Codex plugin for Claude Code

在 Claude Code 内部使用 Codex 进行代码审查或将任务委托给 Codex。

此插件适用于希望从现有工作流中轻松开始使用 Codex 的 Claude Code 用户。

功能特点

• /codex:review 用于常规只读 Codex 审查
• /codex:adversarial-review 用于可控的挑战性审查
• /codex:rescue、/codex:transfer、/codex:status、/codex:result 和 /codex:cancel 用于委托工作、移交会话和管理后台任务

系统要求

• ChatGPT 订阅（含免费版）或 OpenAI API 密钥。
  • 使用将计入您的 Codex 使用限额。了解更多。
• Node.js 18.18 或更高版本

安装方法

在 Claude Code 中添加市场：

/plugin marketplace add openai/codex-plugin-cc

安装插件：

/plugin install codex@openai-codex

重新加载插件：

/reload-plugins

然后运行：

/codex:setup

/codex:setup 会告知你 Codex 是否准备就绪。如果 Codex 未安装且 npm 可用，它会主动提出为你安装 Codex。

如果你希望自行安装 Codex，请使用：

npm install -g @openai/codex

如果已安装 Codex 但尚未登录，请运行：

!codex login

安装后，您应该会看到：

• 下方列出的斜杠命令
• /agents 中的 codex:codex-rescue 子智能体

一个简单的首次运行示例如下：

/codex:review --background
/codex:status
/codex:result

使用方法

/codex:review

对您当前的工作执行常规 Codex 审查。其提供的代码审查质量与在 Codex 中直接运行 /review 相同。

当您需要以下情况时使用：

• 审查当前未提交的变更
• 将您的分支与基准分支（如 main）进行比较审查

使用 --base <ref> 进行分支审查。它还支持 --wait 和 --background。此命令不可引导，也不接受自定义焦点文本。如果您想对特定决策或风险领域提出质疑，请使用 /codex:adversarial-review。

示例：

/codex:review
/codex:review --base main
/codex:review --background

此命令为只读模式，不会执行任何更改。在后台运行时，您可以使用 /codex:status 检查进度，并使用 /codex:cancel 取消正在进行的任务。

/codex:adversarial-review

运行可引导式审查，对所选的实现方案和设计提出质疑。

它可用于压力测试假设条件、权衡取舍、故障模式，以及验证不同方案是否更安全或更简洁。

它采用与 /codex:review 相同的审查目标选择方式，包括用于分支审查的 --base <ref>。 它还支持 --wait 和 --background。与 /codex:review 不同的是，它可以在标志后接受额外的焦点文本。

建议在以下场景使用：

• 发布前需要挑战方向而非仅关注代码细节的审查
• 侧重于设计选择、权衡取舍、隐藏假设和替代方案的审查
• 针对特定风险领域（如身份验证、数据丢失、回滚、竞态条件或可靠性）的压力测试

示例：

/codex:adversarial-review
/codex:adversarial-review --base main challenge whether this was the right caching and retry design
/codex:adversarial-review --background look for race conditions and question the chosen approach

此命令为只读模式，不会修改代码。

/codex:rescue

通过 codex:codex-rescue 子代理将任务交给 Codex。

当你希望 Codex 执行以下操作时使用此命令：

• 调查 bug
• 尝试修复
• 继续之前的 Codex 任务
• 使用更小的模型进行更快或更经济的处理

它支持 --background、--wait、--resume 和 --fresh 参数。如果省略 --resume 和 --fresh，插件会主动提示是否继续此仓库的最新 rescue 线程。

示例：

/codex:rescue investigate why the tests started failing
/codex:rescue fix the failing test with the smallest safe patch
/codex:rescue --resume apply the top fix from the last run
/codex:rescue --model gpt-5.4-mini --effort medium investigate the flaky integration test
/codex:rescue --model spark fix the issue quickly
/codex:rescue --background investigate the regression

你也可以直接要求将任务委托给 Codex：

Ask Codex to redesign the database connection to be more resilient.

注意：

• 若未传入 --model 或 --effort，Codex 将自行选择默认值。
• 若输入 spark，插件会将其映射为 gpt-5.3-codex-spark
• 后续恢复请求可继续仓库中最新的 Codex 任务

/codex:transfer

从当前 Claude Code 会话创建一个持久的 Codex 线程，并打印 codex resume <session-id> 命令。

当你已在 Claude Code 中开始调试或实现相关对话，且希望直接在 Codex 中继续使用相同上下文时，可使用此命令。

示例：

/codex:transfer
/codex:transfer --source ~/.claude/projects/-Users-me-repo/<session-id>.jsonl

该插件现有的 SessionStart 钩子会自动提供当前的会话记录路径；--source 可用作手动覆盖选项。传输过程使用 Codex 的 external-agent 会话导入器，因此它遵循与在 Codex 应用中导入 Claude 历史记录相同的转换规则，并创建可在应用或 TUI 中继续的可见对话轮次。源文件必须位于 ~/.claude/projects 目录下，并且在使用此命令前，必须升级不支持会话导入功能的旧版 Codex。

/codex:status

显示当前仓库的运行中及近期 Codex 任务。

示例：

/codex:status
/codex:status task-abc123

使用它来：

• 检查后台工作的进度
• 查看最新完成的任务
• 确认任务是否仍在运行

/codex:result

显示已完成任务的最终存储 Codex 输出。 如果可用，它还会包含 Codex 会话 ID，以便你可以使用 codex resume <session-id> 在 Codex 中直接重新打开该运行。

示例：

/codex:result
/codex:result task-abc123

/codex:cancel

取消正在进行的后台 Codex 任务。

示例：

/codex:cancel
/codex:cancel task-abc123

/codex:setup

检查 Codex 是否已安装并通过身份验证。 如果 Codex 未安装且 npm 可用，它可以为你提供安装 Codex 的选项。

你也可以使用 /codex:setup 来管理可选的审查关卡。

启用审查关卡

/codex:setup --enable-review-gate
/codex:setup --disable-review-gate

当审查门启用时，插件会使用 Stop 钩子，基于 Claude 的响应运行有针对性的 Codex 审查。如果该审查发现问题，会阻止停止操作，以便 Claude 先解决这些问题。

典型流程

发布前审查

/codex:review

将问题交给 Codex

/codex:rescue investigate why the build is failing in CI

启动长时间运行的任务

/codex:adversarial-review --background
/codex:rescue --background investigate the flaky test

然后通过以下方式进行检查：

/codex:status
/codex:result

Codex 集成

Codex 插件封装了 Codex 应用服务器。它使用环境中安装的全局 codex 二进制文件，并应用相同的配置。

常见配置

如果您想更改插件使用的默认推理力度或默认模型，可以在用户级或项目级的 config.toml 中进行定义。例如，要在特定项目中始终将 gpt-5.4-mini 设置为 high 推理力度，您可以在启动 Claude 时所在目录的根目录下的 .codex/config.toml 文件中添加以下内容：

model = "gpt-5.4-mini"
model_reasoning_effort = "high"

您的配置将根据以下方式被获取：

• 用户级配置位于 ~/.codex/config.toml
• 项目级覆盖配置位于 .codex/config.toml
• 项目级覆盖配置仅在项目受信任时加载

有关更多配置选项，请查阅 Codex 文档。

将工作转移到 Codex

委托的任务以及任何停止检查点运行也可以通过运行 codex resume 在 Codex 内直接恢复，您可以使用从运行 /codex:result 或 /codex:status 获得的特定会话 ID，或者从列表中选择会话。

通过这种方式，您可以在 Codex 中查看工作成果或继续开展工作。

常见问题

我是否需要为这个插件单独创建一个 Codex 账户？

如果您已在此机器上登录 Codex，该账户应可立即在此处使用。此插件使用您本地的 Codex CLI 身份验证。

如果您目前仅使用 Claude Code 且尚未使用过 Codex，则还需要使用 ChatGPT 账户或 API 密钥登录 Codex。您的 ChatGPT 订阅已包含 Codex 使用权限，并且 codex login 支持 ChatGPT 和 API 密钥两种登录方式。运行 /codex:setup 可检查 Codex 是否准备就绪，若未就绪，请使用 !codex login 进行登录。

该插件是否使用单独的 Codex 运行时？

否。此插件通过同一台机器上的本地 Codex CLI 和 Codex 应用服务器 进行任务委托。

这意味着：

• 它使用与您直接使用时相同的 Codex 安装
• 它使用相同的本地身份验证状态
• 它使用相同的代码库检出和机器本地环境

它会使用我已有的 Codex 配置吗？

是的。如果您已在使用 Codex，该插件将获取相同的配置。

我可以继续使用当前的 API 密钥或基础 URL 设置吗？

可以。由于该插件使用您本地的 Codex CLI，您现有的登录方式和配置仍然适用。

如果需要将内置的 OpenAI 提供程序指向其他端点，请在您的 Codex 配置 中设置 openai_base_url。