Codex GitHub Action

使用 Codex GitHub Action（openai/codex-action@v1）可以在 GitHub Actions 工作流中运行 Codex、应用 patch，或从工作流中发布评审结果。这个 action 会安装 Codex CLI，在你提供 API 密钥时启动 Responses API proxy，并按你指定的权限运行 codex exec。

当你需要下面这些能力时，优先使用这个 action：

在不自行管理 CLI 的前提下，为 pull request 或 release 自动运行 Codex 反馈
将由 Codex 驱动的质量检查纳入 CI 流水线的准入条件
通过工作流文件运行可重复的 Codex 任务，例如代码评审、发布准备或迁移

有关完整的 CI 示例，可结合非交互模式阅读，也可以直接查看 openai/codex-action 仓库。

前提条件

使用前请准备好：

将 OpenAI API 密钥保存为 GitHub Secret，例如 OPENAI_API_KEY，并在工作流中引用它
在 Linux 或 macOS 运行器上运行任务；如果必须在 Windows 上运行，需要显式设置 safety-strategy: unsafe
在执行 action 之前先检出代码，让 Codex 能读取仓库内容
预先确定提示词来源。你可以用 prompt 传内联文本，也可以用 prompt-file 指向仓库中已提交的文件

示例工作流

下面的示例会在新 pull request 打开或更新时触发 Codex 评审，捕获 Codex 的回复，并把结果回贴到 PR：

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

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

      - name: Pre-fetch base and head refs
        run: |
          git fetch --no-tags origin \
            ${{ github.event.pull_request.base.ref }} \
            +refs/pull/${{ github.event.pull_request.number }}/head

      - 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
          safety-strategy: drop-sudo
          sandbox: workspace-write

  post_feedback:
    runs-on: ubuntu-latest
    needs: codex
    if: needs.codex.outputs.final_message != ''
    steps:
      - name: Post Codex feedback
        uses: actions/github-script@v7
        with:
          github-token: ${{ github.token }}
          script: |
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.payload.pull_request.number,
              body: process.env.CODEX_FINAL_MESSAGE,
            });
        env:
          CODEX_FINAL_MESSAGE: ${{ needs.codex.outputs.final_message }}

将 .github/codex/prompts/review.md 换成你自己的提示词文件即可；如果你更喜欢内联文本，也可以直接使用 prompt。这个示例还会把 Codex 的最终消息写入 codex-output.md，方便后续检查或上传为构建产物。

配置 `codex exec`

这个 action 的很多输入项都直接映射到 codex exec：

prompt 或 prompt-file：二选一。可以传内联任务说明，或者引用仓库中的 Markdown / 文本路径；常见做法是把提示词放在 .github/codex/prompts/
codex-args：附加 CLI 参数，可以传 JSON 数组（例如 ["--full-auto"]），也可以传 shell 风格字符串（例如 --full-auto --sandbox danger-full-access），用于开启编辑、流式输出或 MCP 配置
model 和 effort：控制本次运行的 Codex 智能体配置；留空则使用默认值
sandbox：把 workspace-write、read-only、danger-full-access 这类沙箱模式和任务所需权限对齐
output-file：把最终消息写入磁盘，方便后续上传构建产物或比较差异
codex-version：固定某个 CLI 版本；留空则使用最新发布版本
codex-home：如果你要在多个步骤间复用配置文件或 MCP 设置，可以指定共享的 Codex 主目录

管理权限

在 GitHub 托管运行器上，Codex 默认能接触到的环境很广，所以你应显式收紧权限。常见控制项包括：

safety-strategy：默认是 drop-sudo，会在运行 Codex 前移除 sudo。这是对整个 job 不可逆的操作，适合用来保护内存中的敏感信息。在 Windows 上必须改为 unsafe
unprivileged-user：需要与 safety-strategy: unprivileged-user 和 codex-user 搭配使用，让 Codex 以指定账号运行。要确保该用户对仓库 checkout 目录具有读写权限；必要时可参考 openai/codex-action 仓库中的 .cache/codex-action/examples/unprivileged-user.yml
read-only：阻止 Codex 修改文件或使用网络，但它仍然可能以高权限身份运行，所以不要只靠这一项来保护敏感信息
sandbox：限制 Codex 自身的文件系统与网络访问范围，应选择能完成任务的最小权限
allow-users 与 allow-bots：限制哪些用户或机器人可以触发该工作流。默认只有拥有写权限的用户能运行这个 action；如果需要放行额外的受信任账号，请显式列出，留空则保持默认行为

捕获输出

这个 action 会通过 final-message output 输出 Codex 的最后一条消息。你可以像上面的示例一样把它映射成 job output，或者在后续步骤里直接使用。

如果你还想收集运行器上的完整输出，可以把 output-file 与构建产物上传一起使用；如果你需要结构化数据，则可以通过 codex-args 传入 --output-schema，强制最终结果满足指定 JSON 结构。

安全检查清单

在把 Codex 接入 GitHub Actions 前，至少确认以下几点：

限制能够触发工作流的对象。优先使用受信任事件或显式审批，不要让所有人都能对仓库运行 Codex
清洗来自 PR、commit message 或 issue body 的提示词输入，避免提示词注入。尤其要留意 HTML 注释或隐藏文本
用 drop-sudo 或 unprivileged-user 保护 OPENAI_API_KEY；在多租户运行器上不要让 action 停留在 unsafe 模式
尽量把 Codex 放在 job 的最后一步，避免后续步骤继承意外状态
如果怀疑 proxy 日志或 action 输出暴露了敏感信息，立即轮换密钥

故障排查

同时设置了 prompt 和 prompt-file：二者只能二选一
responses-api-proxy 没有写出 server info：确认 API 密钥存在且有效；只有在提供 openai-api-key 时 proxy 才会启动
预期移除了 sudo，但 sudo 仍然成功：确认没有更早的步骤恢复 sudo，并确认运行器是 Linux 或 macOS；必要时用全新 job 重跑
drop-sudo 后出现权限错误：可以在 action 运行前给工作目录补足写权限，例如执行 chmod -R g+rwX "$GITHUB_WORKSPACE"，或者改用 unprivileged-user 模式
触发者未被允许，工作流被阻止：如果你需要放行默认写权限协作者之外的服务账号，请检查 allow-users 和 allow-bots

来源：https://developers.openai.com/codex/github-action

最近搜索

推荐搜索

前提条件

示例工作流

配置 `codex exec`

管理权限

捕获输出

安全检查清单

故障排查

前提条件

示例工作流

配置 codex exec

管理权限

捕获输出

安全检查清单

故障排查

配置 `codex exec`