使用 Codex GitHub Action（openai/codex-action@v1) 在 CI/CD 作业中运行 Codex、应用补丁，或从 GitHub Actions 工作流中发布审查。该操作会安装 Codex CLI，在您提供 API 密钥时启动 Responses API 代理，并在您指定的权限下运行 codex exec 在您指定的权限下。
在以下情况下，请使用此操作：
- 无需自行管理 CLI，即可自动对 Pull Request 或 Release 执行 Codex 反馈。
- 在 CI 流水线中，基于 Codex 驱动的质量检查来管控代码变更。
- 通过工作流文件运行重复性的 Codex 任务（代码审查、发布准备、迁移等）。
有关 CI 示例，请参见 非交互模式 ，并在 openai/codex-action 仓库中.
前提条件
- 将您的 OpenAI 密钥存储为 GitHub 机密（例如
OPENAI_API_KEY)，并在工作流中引用它。 - 在 Linux 或 macOS 运行器上运行作业。对于 Windows，请设置
safety-strategy: unsafe. - 在调用操作之前检出您的代码，以便 Codex 能够读取仓库内容。
- 确定您要运行的提示词。您可以通过
prompt提供内联文本，或者使用prompt-file.
示例工作流
指向仓库中已提交的文件。
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
persist-credentials: false
- name: Pre-fetch base and head refs
env:
PR_BASE_REF: ${{ github.event.pull_request.base.ref }}
PR_NUMBER: ${{ github.event.pull_request.number }}
run: |
git fetch --no-tags origin \
"$PR_BASE_REF" \
"+refs/pull/$PR_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
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 }}下面的示例工作流会审查新的 Pull Request，捕获 Codex 的响应，并将其回复到 PR 上。 .github/codex/prompts/review.md 将 prompt 替换为您自己的提示词文件，或使用 codex-output.md 输入项提供内联文本。该示例还会将最终的 Codex 消息写入
在能够访问您私有 MCP 服务器的网络内部运行。 codex exec
，以便后续检查或作为构件上传。 codex exec options:
promptorprompt-file通过设置映射到以下内容的操作输入项来微调 Codex 的运行方式：.github/codex/prompts/.codex-args: 额外的 CLI 标志。提供一个 JSON 数组（例如["--ephemeral"]（选择一项）：内联指令或包含您任务的 Markdown 或文本的仓库路径。建议将提示词存储在--profile ci) 或 Shell 字符串（modelandeffort: 选择你想要的 Codex 代理配置；留空则使用默认值。sandbox: 匹配沙盒模式（workspace-write,read-only,danger-full-access) 来配置会话、配置文件或 MCP 设置。output-file: 将最终的 Codex 消息保存到磁盘，以便后续步骤上传或进行差异比较。codex-version: 固定特定的 CLI 版本。留空则使用最新发布的版本。codex-home: 如果你想在各个步骤之间复用配置文件或 MCP 设置，请指定一个共享的 Codex 主目录。
) 设置为 Codex 在运行期间所需的权限。
管理权限
safety-strategy除非您进行限制，否则 Codex 在 GitHub 托管的运行器上拥有广泛的访问权限。请使用这些输入项来控制暴露风险：drop-sudo（默认sudo) 会在运行 Codex 之前移除safety-strategy: unsafe.unprivileged-user。这对作业而言是不可逆的，并可以保护内存中的机密。在 Windows 上，您必须设置safety-strategy: unprivileged-userwithcodex-user配对unprivileged-user示例 for an ownership fix).read-only，以便以特定账户身份运行 Codex。请确保该用户可以读写仓库检出内容（参见read-only可阻止 Codex 更改文件或使用网络，但它仍然以提升的权限运行。不要仅依赖sandbox来保护机密。allow-usersandallow-bots用于限制 Codex 自身内部的文件系统和网络访问。请选择既能满足任务完成条件又最狭窄的选项。
用于限制谁可以触发工作流。默认情况下，只有具有写入权限的用户才能运行该操作；您可以显式列出额外的受信任账户，或留空以使用默认行为。
捕获输出 final-message 该操作通过 output-file 输出项发出最后一条 Codex 消息。您可以将其映射为作业输出（如上所示），或在后续步骤中直接处理。如果您倾向于从运行器收集完整的对话记录，可以将 --output-schema 到 codex-args 与构件上传功能结合使用。当您需要结构化数据时，请传入
以强制执行 JSON 结构。
- 安全检查清单
- 限制谁可以启动工作流。首选受信任的事件或显式批准，而不是允许所有人针对您的仓库运行 Codex。
- 对来自 Pull Request、提交消息或 Issue 正文中的提示词输入进行清理，以避免提示词注入。在将其提供给 Codex 之前，请审查 HTML 注释或隐藏文本。
OPENAI_API_KEY通过保持safety-strategyondrop-sudo或将 Codex 迁移到非特权用户来保护您的机密。绝不要在多租户运行器上将操作保持为unsafe模式。 - 将 Codex 作为作业的最后一步运行，以免后续步骤继承任何意外的状态变更。
- 如果您怀疑代理日志或操作输出暴露了机密材料，请立即轮换密钥。
故障排除
- 您同时设置了 prompt 和 prompt-file: 移除重复的输入，确保你只提供了一个来源。
- responses-api-proxy 未写入服务器信息: 确认 API 密钥存在且有效；仅当你提供
openai-api-key. - 预期的
sudo移除，但sudo成功: 确保没有先前的步骤恢复了sudo并且运行器操作系统是 Linux 或 macOS。请使用新作业重新运行。 - 之后的权限错误
drop-sudo: 在 action 运行之前授予写入权限（例如使用chmod -R g+rwX "$GITHUB_WORKSPACE"或通过使用 unprivileged-user 模式实现）。 - 未授权的触发器已被阻止: 调整
allow-usersorallow-bots输入项，如果您需要允许超出默认写入协作者范围的服务账号。