> [!NOTE] > 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 > [English](./README.en.md) · [原始项目](https://github.com/openai/codex-plugin-cc) · [上游 README](https://github.com/openai/codex-plugin-cc/blob/HEAD/README.md) > 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 # 适用于 Claude Code 的 Codex 插件 在 Claude Code 中使用 Codex 进行代码审查（code review），或将任务委派给 Codex。 本插件面向希望在现有工作流中轻松上手 Codex 的 Claude Code 用户。 ## 你能获得什么 - `/codex:review`：用于常规的只读 Codex 审查 - `/codex:adversarial-review`：用于可引导的挑战式审查 - `/codex:rescue`、`/codex:transfer`、`/codex:status`、`/codex:result` 和 `/codex:cancel`：用于委派工作、交接会话及管理后台任务 ## 系统要求 - **ChatGPT 订阅（含 Free 版）或 OpenAI API 密钥。** - 使用量将计入你的 Codex 用量限额。[了解更多](https://developers.openai.com/codex/pricing). - **Node.js 18.18 或更高版本** ## 安装 在 Claude Code 中添加 marketplace： ```bash /plugin marketplace add openai/codex-plugin-cc ``` 安装插件： ```bash /plugin install codex@openai-codex ``` 重新加载插件： ```bash /reload-plugins ``` 然后运行： ```bash /codex:setup ``` `/codex:setup` 会告诉你 Codex 是否已就绪。如果未安装 Codex 且 npm 可用，它可以为你提供安装 Codex 的选项。 如果你想自行安装 Codex，请使用： ```bash npm install -g @openai/codex ``` 如果 Codex 已安装但尚未登录，请运行： ```bash !codex login ``` 安装完成后，你应该能看到： - 下方列出的斜杠命令 - `/agents` 中的 `codex:codex-rescue` 子代理（subagent） 一个简单的首次运行示例： ```bash /codex:review --background /codex:status /codex:result ``` ## 使用方法 ### `/codex:review` 对你当前的工作运行常规 Codex 审查。其代码审查质量与直接在 Codex 中运行 `/review` 相同。 > [!NOTE] > 代码审查，尤其是涉及多文件变更时，可能需要较长时间。一般建议在后台运行。 适用于以下场景： - 审查当前未提交的变更 - 将你的分支与 `main` 等基准分支进行对比审查 使用 `--base ` 进行分支审查。它还支持 `--wait` 和 `--background`。该命令不可引导，也不接受自定义聚焦文本。若要质疑特定决策或风险领域，请使用 [`/codex:adversarial-review`](#codexadversarial-review)。 示例： ```bash /codex:review /codex:review --base main /codex:review --background ``` 该命令为只读，不会进行任何修改。在后台运行时，可使用 [`/codex:status`](#codexstatus) 查看进度，并使用 [`/codex:cancel`](#codexcancel) 取消正在进行的任务。 ### `/codex:adversarial-review` 运行**可引导**的审查，质疑所选的实现方案与设计。 可用于压力测试假设、权衡取舍、故障模式，以及评估其他方案是否会更加安全或简洁。 它使用与 `/codex:review` 相同的审查目标选择方式，分支审查可使用 `--base `。 它还支持 `--wait` 和 `--background`。与 `/codex:review` 不同，它可以在标志（flags）之后接受额外的聚焦文本。 适用于以下场景： - 发布前的审查，质疑整体方向，而不仅仅是代码细节 - 聚焦于设计选择、权衡取舍、隐含假设及替代方案的审查 - 针对 auth、数据丢失、回滚、竞态条件或可靠性等特定风险领域的压力测试 示例： ```bash /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 任务 - 使用较小的模型进行更快或更经济的处理 > [!NOTE] > 根据任务及所选模型，这些任务可能耗时较长，一般建议强制在后台运行任务，或将代理移至后台。 它支持 `--background`、`--wait`、`--resume` 和 `--fresh`。如果省略 `--resume` 和 `--fresh`，插件可以提供继续该仓库最新 rescue 线程的选项。 示例： ```bash /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： ```text Ask Codex to redesign the database connection to be more resilient. ``` **说明：** - 如果不传入 `--model` 或 `--effort`，Codex 会使用其默认设置。 - 如果你指定 `spark`，插件会将其映射为 `gpt-5.3-codex-spark` - 后续的 rescue 请求可以继续该仓库中最新的 Codex 任务 ### `/codex:transfer` 从当前 Claude Code 会话创建持久的 Codex 线程，并输出 `codex resume ` 命令。 适用于你在 Claude Code 中开始了调试或实现对话，并希望在 Codex 中直接延续相同上下文的情况。 示例： ```bash /codex:transfer /codex:transfer --source ~/.claude/projects/-Users-me-repo/.jsonl ``` 插件现有的 `SessionStart` 钩子会自动提供当前 transcript 路径；`--source` 可作为手动覆盖选项。转移使用 Codex 的 external-agent 会话导入器，因此遵循与在 Codex App 中导入 Claude 历史记录相同的转换规则，并创建可在 App 或 TUI 中继续的可见轮次。源文件必须位于 `~/.claude/projects` 下，不支持会话导入的旧版 Codex 必须升级后才能使用此命令。 ### `/codex:status` 显示当前仓库中正在运行及最近的 Codex 任务。 示例： ```bash /codex:status /codex:status task-abc123 ``` 可用于： - 查看后台工作进度 - 查看最新已完成的任务 - 确认任务是否仍在运行 ### `/codex:result` 显示已完成任务的最终存储 Codex 输出。 当可用时，还会包含 Codex 会话 ID，以便你使用 `codex resume ` 直接在 Codex 中重新打开该次运行。 示例： ```bash /codex:result /codex:result task-abc123 ``` ### `/codex:cancel` 取消活跃的后台 Codex 任务。 示例： ```bash /codex:cancel /codex:cancel task-abc123 ``` ### `/codex:setup` 检查 Codex 是否已安装并已认证。 如果未安装 Codex 且 npm 可用，它可以为你提供安装 Codex 的选项。 你也可以使用 `/codex:setup` 管理可选的审查闸门（review gate）。 #### 启用审查闸门 ```bash /codex:setup --enable-review-gate /codex:setup --disable-review-gate ``` 启用审查闸门后，插件会使用 `Stop` 钩子，根据 Claude 的响应运行有针对性的 Codex 审查。如果该审查发现问题，停止操作会被阻断，以便 Claude 先处理这些问题。 > [!WARNING] > 审查闸门可能产生长时间运行的 Claude/Codex 循环，并快速消耗用量限额。仅在你计划主动监控会话时启用。 ## 典型流程 ### 发布前审查 ```bash /codex:review ``` ### 将问题交给 Codex ```bash /codex:rescue investigate why the build is failing in CI ``` ### 启动长时间运行的任务 ```bash /codex:adversarial-review --background /codex:rescue --background investigate the flaky test ``` 然后通过以下方式查看状态： ```bash /codex:status /codex:result ``` ## Codex 集成 Codex 插件封装了 [Codex app server](https://developers.openai.com/codex/app-server). 它会使用环境中安装的全局 `codex` 二进制文件，并[应用相同的配置](https://developers.openai.com/codex/config-basic). ### 常见配置 如果你想更改插件默认的推理强度（reasoning effort）或默认模型，可以在用户级或项目级的 `config.toml` 中进行配置。例如，若要让某个特定项目在 `high` 上始终使用 `gpt-5.4-mini`，可在启动 Claude 时所在目录根部的 `.codex/config.toml` 文件中添加以下内容： ```toml model = "gpt-5.4-mini" model_reasoning_effort = "high" ``` 你的配置会按以下规则生效： - 用户级配置位于 `~/.codex/config.toml` - 项目级覆盖位于 `.codex/config.toml` - 项目级覆盖仅在[项目受信任](https://developers.openai.com/codex/config-advanced#project-config-files-codexconfigtoml) 时才会加载 更多[配置选项](https://developers.openai.com/codex/config-reference). 请参阅 Codex 文档。 ### 将工作迁移到 Codex 委派任务以及任何 [stop gate](#what-does-the-review-gate-do) 运行，也可在 Codex 中直接恢复：运行 `codex resume`，并传入运行 `/codex:result` 或 `/codex:status` 时获得的特定会话 ID，或从列表中选择。 这样你就可以在 Codex 中审查相关工作，或在那里继续推进。 ## 常见问题 ### 使用此插件是否需要单独的 Codex 账户？ 如果你已在本机登录 Codex，该账户应可在此插件中直接使用。本插件使用你本地的 Codex CLI 身份验证。 如果你目前只使用 Claude Code、尚未使用过 Codex，还需要使用 ChatGPT 账户或 API 密钥登录 Codex。[Codex 随 ChatGPT 订阅提供](https://developers.openai.com/codex/pricing/),，且 [`codex login`](https://developers.openai.com/codex/cli/reference/#codex-login) 同时支持 ChatGPT 与 API 密钥登录。运行 `/codex:setup` 可检查 Codex 是否就绪；若未就绪，请使用 `!codex login`。 ### 插件是否使用独立的 Codex 运行时？ 不会。本插件通过你本机上的 [Codex CLI](https://developers.openai.com/codex/cli/) 与 [Codex app server](https://developers.openai.com/codex/app-server/) 进行委派。 这意味着： - 使用与你直接调用时相同的 Codex 安装 - 使用相同的本地身份验证状态 - 使用相同的仓库检出与机器本地环境 ### 它会使用我已有的 Codex 配置吗？ 会。如果你已在用 Codex，插件会沿用相同的[配置](#common-configurations)。 ### 我还能继续使用当前的 API 密钥或 base URL 设置吗？ 可以。由于插件使用你本地的 Codex CLI，你现有的登录方式与配置仍然适用。 若需将内置 OpenAI 提供方指向其他端点，请在你的 [Codex 配置](https://developers.openai.com/codex/config-advanced/#config-and-state-locations). 中设置 `openai_base_url`