openai/codex-action@v1 是官方的 Codex GitHub Action，解决了在 CI 中手动安装和配置 Codex CLI 的麻烦——Action 自动完成安装、API 代理启动和 codex exec 调用。适合 PR 自动审查、发布质量门控和定时代码分析等场景。

Codex GitHub Action

使用 openai/codex-action@v1 可以在 CI/CD 工作流中运行 Codex：自动安装 CLI、启动 Responses API 代理，并在你指定的权限下运行 codex exec。

适合以下场景：

• 在 PR 上自动运行 Codex 反馈，无需手动管理 CLI
• 将 Codex 驱动的质量检查作为 CI 门控
• 从工作流文件定期执行 Codex 任务（代码审查、发布准备、迁移等）

非交互模式示例见 非交互模式文档，源码见 openai/codex-action。

---

前置条件

• 将 OpenAI API Key 存为 GitHub Secret（如 OPENAI_API_KEY）并在工作流中引用
• 使用 Linux 或 macOS runner；Windows 需设置 safety-strategy: unsafe
• 在调用 Action 之前先 checkout 代码，确保 Codex 能读取仓库内容
• 准备好 prompt：可以内联写在 prompt 参数里，也可以指向仓库中的 Markdown/文本文件（prompt-file）

---

示例工作流

以下示例在 PR 上运行 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 文件。

---

Action 参数说明

参数	说明
prompt / prompt-file	二选一：内联 prompt 或仓库内文件路径
codex-args	额外 CLI flag，JSON 数组或 shell 字符串（如 ["--full-auto"]）
model / effort	模型和推理强度，留空使用默认值
sandbox	沙箱模式：workspace-write、read-only、danger-full-access
output-file	将最终 Codex 消息保存到文件
codex-version	固定 CLI 版本，留空使用最新版
codex-home	指向共享 Codex 主目录（跨步骤复用配置）

---

权限控制

• safety-strategy（默认 drop-sudo）：在运行 Codex 前移除 sudo，保护内存中的 secret。Windows 必须设为 unsafe
• unprivileged-user + codex-user：以指定账号运行 Codex，需确保该账号对仓库 checkout 有读写权限
• read-only：禁止 Codex 修改文件或使用网络，但仍以高权限运行——不能单独依赖它保护 secret
• sandbox：限制 Codex 内部的文件系统和网络访问，选择能完成任务的最窄选项
• allow-users / allow-bots：限制哪些账号可以触发工作流

---

捕获输出

Action 通过 final-message 输出最后一条 Codex 消息。配合 output-file 可保存完整文本，上传为 artifact。需要结构化数据时，在 codex-args 里传入 --output-schema。

---

安全注意事项

• 限制谁能触发工作流，优先使用可信事件或显式审批
• 对来自 PR 的 prompt 输入（标题、正文、commit message）做过滤，防止 prompt 注入
• safety-strategy 保持 drop-sudo 或移到非特权用户，避免在多租户 runner 上使用 unsafe 模式
• 将 Codex Action 放在 job 最后一步，防止后续步骤继承意外状态变更
• 怀疑代理日志或输出泄露了 secret 时，立即轮换 API Key

---

常见问题

Q: prompt 和 prompt-file 同时设置了怎么办？

A: 只能提供一个，同时设置会报错，删掉其中一个即可。

Q: responses-api-proxy 没有写入 server info 是什么原因？

A: 确认 openai-api-key 已提供且有效，代理只有在提供 API Key 的情况下才会启动。

Q: 使用 drop-sudo 后出现权限错误怎么处理？

A: 在 Action 运行前授予写权限（如 chmod -R g+rwX "$GITHUB_WORKSPACE"），或使用 unprivileged-user 模式并预先设置好所有权。