GitHub Actions 集成

配置官方 codex-action 的输入、权限和输出，并定位常见 CI 启动问题。

openai/codex-action@v1 在 GitHub Actions 中安装 Codex CLI，并按指定权限运行 codex exec。提供 API key 时会启动 Responses API proxy，适合重复执行评审、发布准备或迁移任务。

运行前准备

先 checkout 仓库；把 API key 存在 GitHub secret，例如 OPENAI_API_KEY。使用 Linux 或 macOS runner 时可保留官方默认的 drop-sudo 策略。官方 Windows 路径要求 safety-strategy: unsafe，应结合 runner 隔离条件评估，不宜直接迁移默认 Linux 配置。

已准备 checkout 的 job 可以使用以下 step：

- name: Run Codex
  id: run_codex
  uses: openai/codex-action@v1
  with:
    openai-api-key: ${{ secrets.OPENAI_API_KEY }}
    prompt-file: .github/codex/prompts/review.md
    output-file: codex-output.md

示例中的提示词文件必须存在，也可改用 prompt 传内联内容；二者只能选一个。

常用输入

输入	作用
`codex-args`	CLI 参数，可用 JSON 数组或 shell 字符串
`model`、`effort`	指定模型与推理强度；留空使用默认值
`sandbox`	选择 `read-only`、`workspace-write` 或 `danger-full-access`
`codex-version`	固定 CLI 版本；留空使用最新发布版
`codex-home`	复用配置、MCP 等所在的 Codex 目录
`output-file`	保存最后一条消息到文件

需要结构化输出时，可通过 codex-args 传 --output-schema。最后消息也出现在 steps.run_codex.outputs.final-message，可映射为 job output 给后续任务使用。

权限策略

safety-strategy 默认 drop-sudo，会在 job 内不可逆地移除 sudo；需要调整 checkout 所有权或写权限，应在运行 action 前完成。也可使用 unprivileged-user 策略配合 codex-user 指定账号。

allow-users 与 allow-bots 限制触发者，默认允许有写权限的用户。read-only 沙箱并不单独解决 runner 中的凭据暴露；官方建议 Codex 作为 job 的最后一步，并限制不受信任提示词和触发来源。

排障

同时设置 prompt 和 prompt-file 时移除其中一个；proxy 未写出服务信息时检查 API key 是否已提供且有效；drop-sudo 后写入失败时在前置步骤修正权限；触发者被拒绝时核对 allow-users 或 allow-bots。只有明确准备了发布步骤时才向 PR 发送评审，运行 Codex 本身不等于已经发布评论。