Codex GitHub Action

在 GitHub Actions 工作流中运行 Codex，同时对 Codex 可用的权限进行严格控制。此操作负责安装 Codex CLI，并将其配置为通过安全代理连接到 Responses API。

用户必须为其选择的提供商（例如 OPENAI_API_KEY 或 使用 Azure 提供 OpenAI 模型时的 AZURE_OPENAI_API_KEY）提供 API 密钥，并将其作为 GitHub Actions 秘密 来使用此操作。

示例：创建您自己的拉取请求机器人

虽然 Codex 云服务已经提供了一个功能强大的代码审查工具，您可以立即使用，但如果您希望对体验有更多控制，以下示例展示了如何使用 openai/codex-action 构建您自己的代码审查工作流。

在下面的示例中，我们定义了一个工作流，该工作流会在用户创建拉取请求时触发，具体步骤如下：

• 创建仓库的浅克隆。
• 确保 PR 的 base 和 head 引用在本地可用。
• 使用包含 PR 特定详细信息的 prompt 运行 Codex。
• 将 Codex 的输出作为评论发布到 PR 中。

有关如何安全使用 openai/codex-action 的提示，请参阅 security.md。

name: 在创建拉取请求时执行代码审查。
on:
  pull_request:
    types: [opened]

jobs:
  codex:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    outputs:
      final_message: ${{ steps.run_codex.outputs.final-message }}
    steps:
      - uses: actions/checkout@v5
        with:
          # 显式检出 PR 的合并提交。
          ref: refs/pull/${{ github.event.pull_request.number }}/merge

      - name: 预先获取 PR 的 base 和 head 引用
        env:
          PR_BASE_REF: ${{ github.event.pull_request.base.ref }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
        run: |
          # 通过环境变量传递 GitHub 表达式，并对 shell 展开部分进行转义。
          git fetch --no-tags origin \
            "$PR_BASE_REF" \
            "+refs/pull/$PR_NUMBER/head"

      # 如果您希望 Codex 构建并运行代码，请在“运行 Codex”步骤之前安装所有需要下载的依赖项，因为 Codex 的默认沙盒会禁用网络访问。

      - name: 运行 Codex
        id: run_codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt: |
            这是 ${{ github.repository }} 的第 ${{ github.event.pull_request.number }} 号拉取请求。

            请仅审查 PR 引入的更改，因此请考虑：
               git log --oneline ${{ github.event.pull_request.base.sha }}...${{ github.event.pull_request.head.sha }}

            请提出任何改进建议、潜在的 bug 或问题。反馈应简洁明了且具体。

            拉取请求标题和正文：
            ----
            ${{ github.event.pull_request.title }}
            ${{ github.event.pull_request.body }}

  post_feedback:
    runs-on: ubuntu-latest
    needs: codex
    if: needs.codex.outputs.final_message != ''
    permissions:
      issues: write
      pull-requests: write
    steps:
      - name: 报告 Codex 的反馈
        uses: actions/github-script@v7
        env:
          CODEX_FINAL_MESSAGE: ${{ needs.codex.outputs.final_message }}
        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,
            });

输入

名称	描述	默认值
openai-api-key	用于在使用 OpenAI 时启动 Responses API 代理的密钥（默认）。请将其存储在 secrets 中。	""
responses-api-endpoint	可选的 Responses API 端点覆盖，例如 https://example.openai.azure.com/openai/v1/responses。留空则使用代理的默认值。	""
prompt	内联提示文本。提供此参数或 prompt-file。	""
prompt-file	包含提示的文件路径（相对于仓库根目录）。提供此参数或 prompt。	""
output-file	最终 Codex 消息将写入的文件。留空则跳过文件写入。	""
working-directory	传递给 codex exec --cd 的目录。默认为仓库根目录。	""
sandbox	Codex 的沙盒模式。可选值为 workspace-write（默认）、read-only 或 danger-full-access。	""
codex-version	要安装的 @openai/codex 版本。	""
codex-args	传递给 codex exec 的额外参数。接受 JSON 数组（["--flag", "value"]）或 shell 样式的字符串。	""
output-schema	写入临时文件并传递给 codex exec --output-schema 的内联模式内容。与 output-schema-file 互斥。	""
output-schema-file	传递给 codex exec --output-schema 的模式文件。留空则跳过该选项。	""
model	代理应使用的模型。留空则由 Codex 自动选择默认值。	""
effort	代理应使用的推理力度。留空则由 Codex 自动选择默认值。	""
codex-home	用作 Codex CLI 主目录（配置/缓存）的目录。留空时使用 CLI 默认值。	""
safety-strategy	控制操作如何限制 Codex 的权限。请参阅 安全策略。	drop-sudo
codex-user	当 safety-strategy 为 unprivileged-user 时，运行 Codex 的用户名。	""
allow-users	除对仓库具有写入权限的人员外，还可以触发该操作的 GitHub 用户名列表。	""
allow-bots	允许由 GitHub Apps/机器人账户触发的运行绕过写入权限检查。	false

安全策略

safety-strategy 输入决定了 Codex 在运行器上获得的访问权限。选择合适的选项至关重要，尤其是在存在敏感密钥（如您的 OpenAI API 密钥）的情况下。

有关此主题的重要信息，请参阅安全页面上的 保护您的 OPENAI_API_KEY。

• drop-sudo（默认） — 在 Linux 和 macOS 运行器上，该操作会在调用 Codex 之前撤销默认用户的 sudo 权限。随后 Codex 将以该用户身份运行，且不具备超级用户权限。此更改将持续到作业结束，因此后续步骤无法依赖 sudo。这通常是 GitHub 托管运行器上最安全的选择。
• unprivileged-user — 以通过 codex-user 提供的用户身份运行 Codex。如果您管理自己的运行器，并已预先创建无特权账户，则可以使用此选项。请确保该用户能够读取仓库检出内容以及 Codex 所需的任何文件。有关如何在 ubuntu-latest 上配置此类账户的示例，请参阅 unprivileged-user.yml。
• read-only — 在只读沙盒中执行 Codex。Codex 可以查看文件，但无法修改文件系统或直接访问网络。OpenAI API 密钥仍会通过代理传输，因此如果 Codex 能够访问进程内存，仍可能读取该密钥。
• unsafe — 不进行权限降低。Codex 以默认的 runner 用户身份运行（通常具有 sudo 权限）。仅当您完全信任提示内容时才应使用此选项。在 Windows 运行器上，这是唯一支持的选项；如果提供其他选项，该操作将失败。

操作系统支持

• Windows：GitHub 托管的 Windows 运行器缺乏受支持的沙盒环境。请设置 safety-strategy: unsafe。该操作会验证此设置，否则将提前退出。
• Linux/macOS：所有 safety-strategy 选项均受支持。再次提醒，如果您选择 drop-sudo，请记住，作业中后续依赖 sudo 的步骤将会失败。如果您确实在 openai/codex-action 运行后需要执行需要 sudo 的代码，一种方法是将 openai/codex-action 的输出传递给新主机上的新作业，并从那里继续您的工作流。
• GitHub 托管的 Linux 运行器：该操作在设置过程中启用无特权用户命名空间，并在存在时清除 Ubuntu 的 AppArmor 防护。这可以避免在较新的托管镜像中出现的 bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted 错误，包括那些先使用该操作引导 Codex，然后在后续步骤中调用 codex 的工作流。自托管的 Linux 运行器仍需提前配置等效的内核支持。

输出

名称	描述
final-message	codex exec 返回的最终消息。

正如上面的示例所示，我们将 run_codex 步骤的 final-message 输出作为工作流中 codex 作业的输出：

jobs:
  codex:
    # ...
    outputs:
      final_message: ${{ steps.run_codex.outputs.final-message }}

其他提示

• 请在 actions/checkout@v5 之后运行此操作，以便 Codex 能够访问您的仓库内容。
• 若要使用非默认的 Responses API 端点（例如 Azure OpenAI），请将 responses-api-endpoint 设置为提供商的 URL，同时保持 openai-api-key 已填写；代理仍将向上游发送 Authorization: Bearer <key> 请求头。
• 如果您希望 Codex 只能访问有限的一组特权功能，请考虑运行一个本地 MCP 服务器来执行这些操作，并配置 Codex 使用该服务器。
• 如果您需要更精细地控制 CLI 调用，可以通过 codex-args 传递标志，或在 codex-home 目录下创建一个 config.toml 文件。
• 一旦使用 openai-api-key 运行过 openai/codex-action，您也可以在作业中的后续脚本中直接调用 codex。（在这种情况下，您可以省略操作中的 prompt 和 prompt-file 参数。）

Azure

要配置此操作以使用托管在 Azure 上的 OpenAI 模型，请务必注意以下几点：

• responses-api-endpoint 必须设置为完整的 URL（包括任何必需的查询参数），Codex 将向该 URL 发送 POST 请求以获取 Responses API 响应。对于 Azure，这可能类似于 https://YOUR_PROJECT_NAME.openai.azure.com/openai/v1/responses。请注意，与在 Codex 中自定义模型提供商时不同，您必须根据需要自行在 URL 中添加 v1/responses 后缀。
• openai-api-key 输入必须是有效的密钥，可用于在向您的 Responses API 端点发送 POST 请求时附带 Authorization: Bearer <KEY> 请求头。（使用 Codex CLI 设置自定义提供商时，env_key 的值也同样适用。）

最终，您配置的操作可能如下所示：

- name: 启动 Codex 代理
  uses: openai/codex-action@v1
  with:
    openai-api-key: ${{ secrets.AZURE_OPENAI_API_KEY }}
    responses-api-endpoint: "https://bolinfest-7804-resource.cognitiveservices.azure.com/openai/v1/responses"
    prompt: "调试所有内容。"

版本历史

有关详细信息，请参阅 CHANGELOG。

许可证

本项目采用 Apache License 2.0 许可证授权。

Codex GitHub Action 快速上手指南

codex-action 是一个 GitHub Action，允许你在 GitHub Actions 工作流中安全地运行 OpenAI Codex CLI。它通过安全代理连接 Responses API，并严格控制 Codex 的运行权限，非常适合构建自动化的代码审查机器人或开发辅助流程。

环境准备

系统要求

• 运行平台：GitHub Actions (推荐 ubuntu-latest)。
  • Linux/macOS：支持所有安全策略模式（drop-sudo, unprivileged-user, read-only）。
  • Windows：仅支持 unsafe 模式（无权限缩减），因为 GitHub 托管的 Windows Runner 缺乏沙盒支持。
• 内核支持：自托管 Linux Runner 需启用非特权用户命名空间（unprivileged user namespaces）并配置 AppArmor，以避免沙盒启动失败。GitHub 托管的 Linux Runner 已默认处理此配置。

前置依赖

1. OpenAI API Key：你需要一个有效的 OpenAI API Key（或 Azure OpenAI Key）。
2. GitHub Secrets：必须将 API Key 存储为 GitHub Repository 的 Secret，变量名建议设为 OPENAI_API_KEY。
   • 设置路径：Repository Settings -> Secrets and variables -> Actions -> New repository secret。

安装步骤

无需在本地安装任何软件。该工具直接作为 GitHub Action 在工作流中调用。

1. 在你的仓库根目录下创建或编辑 .github/workflows/codex-review.yml 文件。
2. 确保工作流中先执行了代码检出（actions/checkout），以便 Codex 能读取代码。
3. 引用 openai/codex-action@v1。

基本使用

以下是一个最简示例：当有人创建 Pull Request 时，自动触发 Codex 进行代码审查，并将审查结果作为评论发布到 PR 中。

工作流配置示例

name: Codex Code Review

on:
  pull_request:
    types: [opened]

jobs:
  codex-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write # 需要写入权限以发表评论
    outputs:
      review-comment: ${{ steps.run_codex.outputs.final-message }}
    
    steps:
      # 1. 检出代码
      - uses: actions/checkout@v4
        with:
          ref: refs/pull/${{ github.event.pull_request.number }}/merge

      # 2. 运行 Codex
      - name: Run Codex Review
        id: run_codex
        uses: openai/codex-action@v1
        with:
          # 从 GitHub Secrets 获取 API Key
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          
          # 设置安全策略：移除 sudo 权限（Linux/macOS 推荐）
          safety-strategy: drop-sudo
          
          # 编写提示词
          prompt: |
            请审查此 Pull Request 的代码变更。
            关注潜在的 Bug、性能问题及代码规范。
            请保持回答简洁明了。
            
            变更范围：
            git log --oneline ${{ github.event.pull_request.base.sha }}...${{ github.event.pull_request.head.sha }}

  post-comment:
    runs-on: ubuntu-latest
    needs: codex-review
    if: needs.codex-review.outputs.review-comment != ''
    permissions:
      pull-requests: write
    steps:
      - name: Post Review Comment
        uses: actions/github-script@v7
        env:
          COMMENT_BODY: ${{ needs.codex-review.outputs.review-comment }}
        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.COMMENT_BODY,
            });

关键参数说明

参数名	说明	推荐值
openai-api-key	OpenAI API 密钥（引用 Secrets）	${{ secrets.OPENAI_API_KEY }}
prompt	发送给 Codex 的指令文本	见上方示例
safety-strategy	安全沙盒模式	drop-sudo (Linux/Mac), unsafe (Windows)
model	指定使用的模型	留空则使用默认模型

注意事项

• 权限控制：使用 safety-strategy: drop-sudo 后，当前 Job 后续步骤将无法使用 sudo 命令。如需提权操作，请在新的 Job 中执行。
• 网络访问：Codex 默认沙盒禁止网络访问。若需安装依赖，请在运行 Codex 步骤之前完成。
• Azure 支持：若使用 Azure OpenAI，需额外设置 responses-api-endpoint 为你的 Azure 端点 URL。