Codex GitHub Action

身份非官方简体中文镜像

翻译状态 AI 翻译

来源版本官方未提供

同步日期 2026-07-31

如需完整文档索引，请参阅 llms.txt。文档页面的 Markdown 版本可通过在页面后追加 .md 来获取 URL。

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

在以下情况下，可以使用该 Action：

自动化 Codex 对拉取请求或发布的反馈，而无需自行管理 CLI 。
将变更置于 Codex-driven 质量检查门控下，作为你的 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
    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 选项的 action 输入，精细调整 codex exec 的运行方式：

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

管理权限

除非加以限制，Codex 在 GitHub 托管的 runner 上拥有广泛的访问权限。使用以下输入控制暴露范围：

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

捕获输出

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

安全检查清单

限制谁可以启动工作流。优先使用可信事件或显式审批，而不是允许所有人针对你的仓库运行 Codex 。
清理来自拉取请求、提交消息或 issue 正文的提示词输入，以避免提示词注入。在将 HTML 评论或隐藏文本提供给 Codex之前，请先审查它们。
通过保持 OPENAI_API_KEY 开启 safety-strategy 或将 drop-sudo 移至无特权用户，来保护你的 Codex 。切勿在多租户 runner 上让该 action 处于 unsafe 模式。
将 Codex 作为作业中的最后一步运行，这样后续步骤就不会继承任何意外的状态变更。
如果你怀疑代理日志或 action 输出暴露了秘密材料，请立即轮换密钥。

故障排除

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