Codex GitHub Action：在 CI 里跑 Codex

这篇适合谁

适合已经把代码放在 GitHub 上、想让 Codex 自动审查 PR 或执行固定任务，又不想在每个 job 里手动安装和调用 CLI 的读者。读完，你能写出一个在 PR 打开或更新时运行 Codex 审查、并把结果回帖到 PR 的工作流。

Codex GitHub Action 是什么

Codex GitHub Action（openai/codex-action@v1）让 Codex 在 GitHub Actions 的 job 里运行。它会安装 Codex CLI；提供了 API key 时还会启动 Responses API 代理；然后按你指定的权限运行 codex exec^[1]。安装、密钥处理和权限设置都由 action 完成，工作流只需要声明输入。

官方列出的三类用途是：在 PR 或发版时自动获得 Codex 反馈；把 Codex 的质量检查作为 CI 的一道关卡；把代码审查、发版准备、迁移这类重复任务写进工作流文件^[1]。

准备工作

把 OpenAI 的 key 存为 GitHub secret，例如 OPENAI_API_KEY，再在工作流里引用它^[1]。
在 Linux 或 macOS runner 上运行。要在 Windows 上运行，必须把 safety-strategy 设为 unsafe^[1]。
调用 action 之前先 checkout 代码，否则 Codex 读不到仓库内容^[1]。
决定任务从哪里来：prompt 接受直接写在工作流里的文字，prompt-file 接受仓库里已提交的文件。两者只能选一个，同时设置时，排错指南要求删掉多余的那个^[1]。

一个 PR 审查工作流

下面是官方示例的第一个 job。它在 PR 被打开、更新或重新打开时触发，从 .github/codex/prompts/review.md 读取提示词，并把 Codex 的最终消息写入 codex-output.md^[1]。示例的第二个 job 用 actions/github-script 把这条消息作为评论发回 PR^[1]。

name: Codex pull request review
on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  codex:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    outputs:
      final_message: ${{ steps.run_codex.outputs.final-message }}
    steps:
      - uses: actions/checkout@v5
        with:
          ref: refs/pull/${{ github.event.pull_request.number }}/merge
          fetch-depth: 0
          persist-credentials: false

      - 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

几处要注意的地方：

types 把触发事件限定为 opened、synchronize 和 reopened^[1]。
output-file 把最终消息保存到磁盘，便于后续步骤上传或对比^[1]。
final-message 输出是最后一条 Codex 消息，示例通过 outputs 把它交给下一个 job^[1]。

正式使用前，把 prompt-file 指向你自己的提示词文件^[1]。其中 ${{ secrets.OPENAI_API_KEY }} 从仓库的 secret 里读取 key，${{ steps.run_codex.outputs.final-message }} 读取 Codex 的最终消息^[1]。

常用输入项

prompt 或 prompt-file：二选一。
codex-args：额外的 CLI 参数。可以写 JSON 数组，如 ["--ephemeral"]，也可以写 shell 字符串，如 --profile ci。需要结构化输出时，通过它传入 --output-schema^[1]。
model 和 effort：选择 Codex 的代理配置，留空则使用默认值^[1]。
sandbox：取值为 workspace-write、read-only 或 danger-full-access，选能让任务完成的最窄那一项^[1]。
output-file：把最终消息保存到磁盘^[1]。
codex-version：固定 CLI 版本，留空则使用最新发布版^[1]。
codex-home：指向共享的 Codex 主目录，让多个步骤复用配置文件或 MCP 设置^[1]。

权限：先收窄再运行

GitHub 托管的 runner 上，Codex 默认拥有较大的访问范围，所以权限相关的输入要认真配置^[1]。

safety-strategy 默认为 drop-sudo，在运行 Codex 之前删除 sudo。官方说明这对当前 job 不可逆，但能保护内存中的密钥^[1]。
要以指定账号运行，用 safety-strategy: unprivileged-user 配合 codex-user。该账号必须能读写仓库检出的目录。官方文档链接了一个示例 examples/unprivileged-user.yml^[1]。
read-only 不允许 Codex 修改文件或访问网络，但它仍以较高权限运行，不能单独依赖它保护密钥^[1]。
allow-users 和 allow-bots 决定谁能触发工作流。默认只有拥有写权限的用户能运行该 action^[1]。

安全底线

来自 PR、commit message 或 issue 正文的内容可能带有提示注入。送给 Codex 之前要先清理，并检查 HTML 注释和隐藏文字^[1]。
不要在多租户 runner 上使用 unsafe 模式^[1]。
如果代理日志或 action 输出可能泄露了密钥，立即轮换该 key^[1]。
把 Codex 步骤放在 job 的最后，避免后续步骤继承意外的状态变化^[1]。

常见报错

**同时设置了 prompt 和 prompt-file**：删掉其中一个^[1]。
responses-api-proxy didn't write server info：代理只在提供 openai-api-key 时启动，检查 key 是否存在、是否有效^[1]。
**用了 drop-sudo 之后出现权限错误**：在 action 运行前授予写权限，例如 chmod -R g+rwX "$GITHUB_WORKSPACE"，或者改用 unprivileged-user 的方式^[1]。
未授权的触发被拦截：调整 allow-users 或 allow-bots^[1]。

上线前的检查

第一次运行当作测试看。确认工作流在你期望的事件上触发，密钥已经配置，runner 是 Linux 或 macOS。然后查看 output-file 保存的文件和 final-message 输出，确认 Codex 的回答符合后面步骤的预期^[1]。

权限要和任务相配。只读代码的审查用不着多大权限，要改文件的迁移或发版准备则需要更多。无论哪种，都应选能完成任务的最窄的 sandbox 选项，并记住 read-only 仍然是以较高权限运行的，不能单靠它保护密钥^[1]。

如果后续步骤依赖 Codex 的消息，就要把依赖关系写清楚。示例通过 outputs 把消息交给下一个 job，下一个 job 才能读到它^[1]。final-message 是 Codex 最后输出的一段文字，不是结构化数据。需要结构化结果时，通过 codex-args 传入 --output-schema，让输出符合指定的 JSON 形状^[1]。

三类典型用法怎么落地

用于 PR 审查时，就是前面那份示例：PR 事件触发，提示词放在仓库里，结果回帖到 PR 上^[1]。用于质量检查时，把 Codex 的输出保存下来，作为检查的一部分，由后续步骤决定如何处理^[1]。用于重复任务，比如发版准备或迁移，可以把提示词写进 prompt-file，并用 codex-version 固定 CLI 版本，让每次运行的环境尽量一致^[1]。

限制和注意事项

运行环境：默认场景是 Linux 或 macOS runner。要在 Windows 上运行，必须把 safety-strategy 设为 unsafe，而官方的安全清单明确提醒不要在多租户 runner 上使用这一模式，所以 Windows 工作流要先评估风险^[1]。
触发者：默认只有拥有写权限的用户能运行 action。想让机器人或服务账号触发，要用 allow-bots 或 allow-users 显式放行^[1]。
提示注入：pull request、commit message 或 issue 正文都可能含有恶意内容。把它们交给 Codex 之前要先清理，并检查 HTML 注释和隐藏文字^[1]。
密钥泄露：如果代理日志或 action 输出可能暴露了密钥，应立即轮换该 key，不要等确认之后再做^[1]。