Codex GitHub Action

身份非官方简体中文镜像

翻译状态 AI 翻译 / AI 审校

来源版本官方未提供

同步日期 2026-07-26

官方原文 learn.chatgpt.com

使用 Codex GitHub Action（openai/codex-action@v1）在 CI/CD 作业中运行 Codex、应用补丁，或通过 GitHub Actions 工作流发布审查意见。

该操作会安装 Codex CLI；提供 API key 时，会启动 Responses API 代理，并在你指定的权限下运行 codex exec。

在以下情况下，可以使用该操作：

自动化 Codex 对拉取请求或发布版本的反馈，无需自行管理 CLI。
将 Codex 驱动的质量检查作为 CI 流水线的一部分，用于阻止不符合要求的更改。
从工作流文件中运行可重复的 Codex 任务（代码审查、发布准备、迁移）。

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

前置条件

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

示例工作流

下面的示例工作流会审查新的拉取请求，捕获 Codex 的响应，并将其发布回该拉取请求。

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
          output-file: codex-output.md

  post_feedback:
    runs-on: ubuntu-latest
    needs: codex
    if: needs.codex.outputs.final_message != ''
    permissions:
      issues: write
      pull-requests: write
    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`

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

prompt 或 prompt-file（二选一）：内联指令，或包含任务说明的 Markdown 或文本文件的仓库路径。可以考虑将提示词存储在 .github/codex/prompts/ 中。
codex-args：额外的 CLI 标志。提供 JSON 数组（例如 ["--ephemeral"]）或 shell 字符串（--profile ci），用于配置会话、配置文件或 MCP 设置。
model 和 effort：选择所需的 Codex Agent 配置；留空则使用默认值。
sandbox：根据 Codex 运行期间所需的权限，匹配沙箱模式（workspace-write、read-only、danger-full-access）。
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。请确保该用户能够读取和写入仓库检出内容（有关所有权修复，请参阅 unprivileged-user 示例）。
read-only 可阻止 Codex 修改文件或使用网络，但它仍会以提升的权限运行。不要仅依靠 read-only 来保护 secret。
sandbox 会限制 Codex 自身的文件系统和网络访问。选择仍能完成任务的最窄权限选项。
allow-users 和 allow-bots 会限制可以触发工作流的用户。默认情况下，只有拥有写入权限的用户才能运行该操作；如需允许其他受信任账户，请明确列出，或将字段留空以使用默认行为。

捕获输出

该操作会通过 final-message 输出最后一条 Codex 消息。可以像上面的示例一样，将其映射为作业输出，或在后续步骤中直接处理。若希望收集 runner 中的完整记录，可将 output-file 与上传构件功能结合使用。需要结构化数据时，可通过 codex-args 传递 --output-schema，以强制使用特定的 JSON 结构。

安全检查清单

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

故障排除

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