wehub-resource-sync
326 lines
11 KiB
Markdown
326 lines
11 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!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 用户。
|
||
|
||
<video src="./docs/plugin-demo.webm" controls muted playsinline autoplay></video>
|
||
|
||
## 你能获得什么
|
||
|
||
- `/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 <ref>` 进行分支审查。它还支持 `--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 <ref>`。
|
||
它还支持 `--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 <session-id>` 命令。
|
||
|
||
适用于你在 Claude Code 中开始了调试或实现对话，并希望在 Codex 中直接延续相同上下文的情况。
|
||
|
||
示例：
|
||
|
||
```bash
|
||
/codex:transfer
|
||
/codex:transfer --source ~/.claude/projects/-Users-me-repo/<session-id>.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 <session-id>` 直接在 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`
|