本文为非官方中文翻译，内容以 OpenAI 官方英文文档为准。
官方来源：https://developers.openai.com/codex/github-action

Codex GitHub Action

从 GitHub 事件触发 Codex 操作

使用 Codex GitHub Action（openai/codex-action@v1）可以在 CI/CD 作业中运行 Codex、应用补丁，或从 GitHub Actions 工作流发布审查结果。该 action 会安装 Codex CLI，在你提供 API key 时启动 Responses API 代理，并在你指定的权限下运行 codex exec。

当你希望执行以下操作时，可以使用这个 action：

自动化处理拉取请求或发布中的 Codex 反馈，而无需自行管理 CLI。
将基于 Codex 的质量检查作为 CI 流水线的一部分，用于变更准入控制。
从工作流文件运行可重复的 Codex 任务（代码审查、发布准备、迁移）。

有关 CI 示例，请参阅非交互模式，并浏览 openai/codex-action 仓库中的源码。

前提条件

将你的 OpenAI key 存储为 GitHub secret（例如 OPENAI_API_KEY），并在工作流中引用它。
在 Linux 或 macOS runner 上运行该作业。对于 Windows，请设置 safety-strategy: unsafe。
在调用该 action 之前先检出你的代码，以便 Codex 可以读取仓库内容。
确定你要运行哪些提示。你可以通过 prompt 提供内联文本，或通过 prompt-file 指向仓库中已提交的文件。

示例工作流

下面的示例工作流会审查新的拉取请求，捕获 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，以供后续检查或上传为 artifact。

配置 `codex exec`

通过设置映射到 codex exec 选项的 action 输入，微调 Codex 的运行方式：

prompt 或 prompt-file（二选一）：内联指令，或指向包含你的任务内容的 Markdown/文本的仓库路径。可考虑将提示存储在 .github/codex/prompts/ 中。
codex-args：额外的 CLI 标志。提供 JSON 数组（例如 ["--json"]）或 shell 字符串（--sandbox workspace-write --json），以允许编辑、流式输出或 MCP 配置。
model 和 effort：选择你想要的 Codex agent 配置；留空则使用默认值。
sandbox：将 sandbox 模式（workspace-write、read-only、danger-full-access）与 Codex 在运行期间所需的权限匹配。
output-file：将 Codex 的最终消息保存到磁盘，以便后续步骤上传或比较差异。
codex-version：固定特定的 CLI 发布版本。留空则使用最新发布版本。
codex-home：如果你希望跨步骤复用配置文件或 MCP 设置，可指向共享的 Codex home 目录。

管理权限

除非你对其进行限制，否则 Codex 在 GitHub 托管的 runner 上拥有广泛访问权限。使用以下输入来控制暴露面：

safety-strategy（默认值为 drop-sudo）会在运行 Codex 之前移除 sudo。这对该作业来说是不可逆的，并且可以保护内存中的 secret。在 Windows 上你必须设置 safety-strategy: unsafe。
unprivileged-user 会将 safety-strategy: unprivileged-user 与 codex-user 搭配使用，以特定账户运行 Codex。请确保该用户可以读写仓库检出目录（参见 .cache/codex-action/examples/unprivileged-user.yml 中的所有权修复方式）。
read-only 会阻止 Codex 更改文件或使用网络，但它仍会以提升后的权限运行。不要仅依赖 read-only 来保护 secret。
sandbox 会在 Codex 内部限制文件系统和网络访问。请选择仍能完成任务的最小权限选项。
allow-users 和 allow-bots 用于限制谁可以触发该工作流。默认情况下，只有具有写权限的用户可以运行该 action；请显式列出其他受信任账户，或将该字段留空以使用默认行为。

捕获输出

该 action 通过 final-message 输出最后一条 Codex 消息。可将其映射为作业输出（如上所示），或在后续步骤中直接处理。如果你更希望从 runner 收集完整转录内容，可将 output-file 与上传 artifacts 功能结合使用。当你需要结构化数据时，可通过 codex-args 传递 --output-schema 来强制 JSON 结构。

安全检查清单

限制谁可以启动该工作流。优先使用受信任事件或显式审批，而不是允许所有人对你的仓库运行 Codex。
清理来自拉取请求、提交消息或 issue 正文的提示输入，以避免提示注入。在将 HTML 注释或隐藏文本提供给 Codex 之前先进行审查。
通过保持 safety-strategy 为 drop-sudo，或将 Codex 移至非特权用户，来保护你的 OPENAI_API_KEY。绝不要在多租户 runner 上让该 action 保持 unsafe 模式。
将 Codex 作为作业中的最后一步运行，以免后续步骤继承任何意外的状态更改。
如果你怀疑代理日志或 action 输出暴露了 secret 内容，请立即轮换 key。

故障排查

你同时设置了 prompt 和 prompt-file：删除重复输入，确保只提供一个来源。
responses-api-proxy 没有写入 server 信息：确认 API key 存在且有效；只有在你提供 openai-api-key 时代理才会启动。
预期已移除 sudo，但 sudo 仍然成功：确认没有更早的步骤恢复 sudo，并且 runner OS 是 Linux 或 macOS。请使用全新作业重新运行。
drop-sudo 后出现权限错误：在 action 运行前授予写权限（例如使用 chmod -R g+rwX "$GITHUB_WORKSPACE"，或使用 unprivileged-user 模式）。
未授权触发被阻止：如果你需要允许默认写协作者之外的服务账户，请调整 allow-users 或 allow-bots 输入。

前提条件​

示例工作流​

配置 codex exec​

管理权限​

捕获输出​

安全检查清单​

故障排查​