wehub/openai--codex-plugin-cc
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity

docs: make Chinese README the default

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 10:33:47 +00:00
parent 29f770af4f
commit 7ce08167cb
1 changed files with 115 additions and 110 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+115 -110
View File
@@ -1,70 +1,75 @@
# Codex plugin for Claude Code
<!-- 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 文件为准。
Use Codex from inside Claude Code for code reviews or to delegate tasks to Codex.
# 适用于 Claude Code 的 Codex 插件
This plugin is for Claude Code users who want an easy way to start using Codex from the workflow
they already have.
在 Claude Code 中使用 Codex 进行代码审查（code review），或将任务委派给 Codex。
本插件面向希望在现有工作流中轻松上手 Codex 的 Claude Code 用户。
<video src="./docs/plugin-demo.webm" controls muted playsinline autoplay></video>
## What You Get
## 你能获得什么
- `/codex:review` for a normal read-only Codex review
- `/codex:adversarial-review` for a steerable challenge review
- `/codex:rescue`, `/codex:transfer`, `/codex:status`, `/codex:result`, and `/codex:cancel` to delegate work, hand off sessions, and manage background jobs
- `/codex:review`：用于常规的只读 Codex 审查
- `/codex:adversarial-review`：用于可引导的挑战式审查
- `/codex:rescue`、`/codex:transfer`、`/codex:status`、`/codex:result` 和 `/codex:cancel`：用于委派工作、交接会话及管理后台任务
## Requirements
## 系统要求
- **ChatGPT subscription (incl. Free) or OpenAI API key.**
- Usage will contribute to your Codex usage limits. [Learn more](https://developers.openai.com/codex/pricing).
- **Node.js 18.18 or later**
- **ChatGPT 订阅（含 Free 版）或 OpenAI API 密钥。**
- 使用量将计入你的 Codex 用量限额。[了解更多](https://developers.openai.com/codex/pricing).
- **Node.js 18.18 或更高版本**
## Install
## 安装
Add the marketplace in Claude Code:
在 Claude Code 中添加 marketplace：
```bash
/plugin marketplace add openai/codex-plugin-cc
```
Install the plugin:
安装插件：
```bash
/plugin install codex@openai-codex
```
Reload plugins:
重新加载插件：
```bash
/reload-plugins
```
Then run:
然后运行：
```bash
/codex:setup
```
`/codex:setup` will tell you whether Codex is ready. If Codex is missing and npm is available, it can offer to install Codex for you.
`/codex:setup` 会告诉你 Codex 是否已就绪。如果未安装 Codex 且 npm 可用，它可以为你提供安装 Codex 的选项。
If you prefer to install Codex yourself, use:
如果你想自行安装 Codex，请使用：
```bash
npm install -g @openai/codex
```
If Codex is installed but not logged in yet, run:
如果 Codex 已安装但尚未登录，请运行：
```bash
!codex login
```
After install, you should see:
安装完成后，你应该能看到：
- the slash commands listed below
- the `codex:codex-rescue` subagent in `/agents`
- 下方列出的斜杠命令
- `/agents` 中的 `codex:codex-rescue` 子代理（subagent）
One simple first run is:
一个简单的首次运行示例：
```bash
/codex:review --background
@@ -72,23 +77,23 @@ One simple first run is:
/codex:result
```
## Usage
## 使用方法
### `/codex:review`
Runs a normal Codex review on your current work. It gives you the same quality of code review as running `/review` inside Codex directly.
对你当前的工作运行常规 Codex 审查。其代码审查质量与直接在 Codex 中运行 `/review` 相同。
> [!NOTE]
> Code review especially for multi-file changes might take a while. It's generally recommended to run it in the background.
> 代码审查，尤其是涉及多文件变更时，可能需要较长时间。一般建议在后台运行。
Use it when you want:
适用于以下场景：
- a review of your current uncommitted changes
- a review of your branch compared to a base branch like `main`
- 审查当前未提交的变更
- 将你的分支与 `main` 等基准分支进行对比审查
Use `--base <ref>` for branch review. It also supports `--wait` and `--background`. It is not steerable and does not take custom focus text. Use [`/codex:adversarial-review`](#codexadversarial-review) when you want to challenge a specific decision or risk area.
使用 `--base <ref>` 进行分支审查。它还支持 `--wait` 和 `--background`。该命令不可引导，也不接受自定义聚焦文本。若要质疑特定决策或风险领域，请使用 [`/codex:adversarial-review`](#codexadversarial-review)。
Examples:
示例：
```bash
/codex:review
@@ -96,24 +101,24 @@ Examples:
/codex:review --background
```
This command is read-only and will not perform any changes. When run in the background you can use [`/codex:status`](#codexstatus) to check on the progress and [`/codex:cancel`](#codexcancel) to cancel the ongoing task.
该命令为只读，不会进行任何修改。在后台运行时，可使用 [`/codex:status`](#codexstatus) 查看进度，并使用 [`/codex:cancel`](#codexcancel) 取消正在进行的任务。
### `/codex:adversarial-review`
Runs a **steerable** review that questions the chosen implementation and design.
运行**可引导**的审查，质疑所选的实现方案与设计。
It can be used to pressure-test assumptions, tradeoffs, failure modes, and whether a different approach would have been safer or simpler.
可用于压力测试假设、权衡取舍、故障模式，以及评估其他方案是否会更加安全或简洁。
It uses the same review target selection as `/codex:review`, including `--base <ref>` for branch review.
It also supports `--wait` and `--background`. Unlike `/codex:review`, it can take extra focus text after the flags.
它使用与 `/codex:review` 相同的审查目标选择方式，分支审查可使用 `--base <ref>`。
它还支持 `--wait` 和 `--background`。与 `/codex:review` 不同，它可以在标志（flags）之后接受额外的聚焦文本。
Use it when you want:
适用于以下场景：
- a review before shipping that challenges the direction, not just the code details
- review focused on design choices, tradeoffs, hidden assumptions, and alternative approaches
- pressure-testing around specific risk areas like auth, data loss, rollback, race conditions, or reliability
- 发布前的审查，质疑整体方向，而不仅仅是代码细节
- 聚焦于设计选择、权衡取舍、隐含假设及替代方案的审查
- 针对 auth、数据丢失、回滚、竞态条件或可靠性等特定风险领域的压力测试
Examples:
示例：
```bash
/codex:adversarial-review
@@ -121,25 +126,25 @@ Examples:
/codex:adversarial-review --background look for race conditions and question the chosen approach
```
This command is read-only. It does not fix code.
该命令为只读，不会修复代码。
### `/codex:rescue`
Hands a task to Codex through the `codex:codex-rescue` subagent.
通过 `codex:codex-rescue` 子代理将任务交给 Codex。
Use it when you want Codex to:
适用于希望 Codex 执行以下操作的场景：
- investigate a bug
- try a fix
- continue a previous Codex task
- take a faster or cheaper pass with a smaller model
- 调查 bug
- 尝试修复
- 继续之前的 Codex 任务
- 使用较小的模型进行更快或更经济的处理
> [!NOTE]
> Depending on the task and the model you choose these tasks might take a long time and it's generally recommended to force the task to be in the background or move the agent to the background.
> 根据任务及所选模型，这些任务可能耗时较长，一般建议强制在后台运行任务，或将代理移至后台。
It supports `--background`, `--wait`, `--resume`, and `--fresh`. If you omit `--resume` and `--fresh`, the plugin can offer to continue the latest rescue thread for this repo.
它支持 `--background`、`--wait`、`--resume` 和 `--fresh`。如果省略 `--resume` 和 `--fresh`，插件可以提供继续该仓库最新 rescue 线程的选项。
Examples:
示例：
```bash
/codex:rescue investigate why the tests started failing
@@ -150,56 +155,56 @@ Examples:
/codex:rescue --background investigate the regression
```
You can also just ask for a task to be delegated to Codex:
你也可以直接请求将任务委派给 Codex：
```text
Ask Codex to redesign the database connection to be more resilient.
```
**Notes:**
**说明：**
- if you do not pass `--model` or `--effort`, Codex chooses its own defaults.
- if you say `spark`, the plugin maps that to `gpt-5.3-codex-spark`
- follow-up rescue requests can continue the latest Codex task in the repo
- 如果不传入 `--model` 或 `--effort`，Codex 会使用其默认设置。
- 如果你指定 `spark`，插件会将其映射为 `gpt-5.3-codex-spark`
- 后续的 rescue 请求可以继续该仓库中最新的 Codex 任务
### `/codex:transfer`
Creates a persistent Codex thread from the current Claude Code session and prints a `codex resume <session-id>` command.
从当前 Claude Code 会话创建持久的 Codex 线程，并输出 `codex resume <session-id>` 命令。
Use it when you started a debugging or implementation conversation in Claude Code and want to continue that same context directly in Codex.
适用于你在 Claude Code 中开始了调试或实现对话，并希望在 Codex 中直接延续相同上下文的情况。
Examples:
示例：
```bash
/codex:transfer
/codex:transfer --source ~/.claude/projects/-Users-me-repo/<session-id>.jsonl
```
The plugin's existing `SessionStart` hook supplies the current transcript path automatically; `--source` is available as a manual override. The transfer uses Codex's external-agent session importer, so it follows the same conversion rules as importing Claude history in the Codex App and creates visible turns that can be continued in the App or TUI. The source must be under `~/.claude/projects`, and older Codex versions that do not expose session import must be upgraded before using this command.
插件现有的 `SessionStart` 钩子会自动提供当前 transcript 路径；`--source` 可作为手动覆盖选项。转移使用 Codex 的 external-agent 会话导入器，因此遵循与在 Codex App 中导入 Claude 历史记录相同的转换规则，并创建可在 App 或 TUI 中继续的可见轮次。源文件必须位于 `~/.claude/projects` 下，不支持会话导入的旧版 Codex 必须升级后才能使用此命令。
### `/codex:status`
Shows running and recent Codex jobs for the current repository.
显示当前仓库中正在运行及最近的 Codex 任务。
Examples:
示例：
```bash
/codex:status
/codex:status task-abc123
```
Use it to:
可用于：
- check progress on background work
- see the latest completed job
- confirm whether a task is still running
- 查看后台工作进度
- 查看最新已完成的任务
- 确认任务是否仍在运行
### `/codex:result`
Shows the final stored Codex output for a finished job.
When available, it also includes the Codex session ID so you can reopen that run directly in Codex with `codex resume <session-id>`.
显示已完成任务的最终存储 Codex 输出。
当可用时，还会包含 Codex 会话 ID，以便你使用 `codex resume <session-id>` 直接在 Codex 中重新打开该次运行。
Examples:
示例：
```bash
/codex:result
@@ -208,9 +213,9 @@ Examples:
### `/codex:cancel`
Cancels an active background Codex job.
取消活跃的后台 Codex 任务。
Examples:
示例：
```bash
/codex:cancel
@@ -219,102 +224,102 @@ Examples:
### `/codex:setup`
Checks whether Codex is installed and authenticated.
If Codex is missing and npm is available, it can offer to install Codex for you.
检查 Codex 是否已安装并已认证。
如果未安装 Codex 且 npm 可用，它可以为你提供安装 Codex 的选项。
You can also use `/codex:setup` to manage the optional review gate.
你也可以使用 `/codex:setup` 管理可选的审查闸门（review gate）。
#### Enabling review gate
#### 启用审查闸门
```bash
/codex:setup --enable-review-gate
/codex:setup --disable-review-gate
```
When the review gate is enabled, the plugin uses a `Stop` hook to run a targeted Codex review based on Claude's response. If that review finds issues, the stop is blocked so Claude can address them first.
启用审查闸门后，插件会使用 `Stop` 钩子，根据 Claude 的响应运行有针对性的 Codex 审查。如果该审查发现问题，停止操作会被阻断，以便 Claude 先处理这些问题。
> [!WARNING]
> The review gate can create a long-running Claude/Codex loop and may drain usage limits quickly. Only enable it when you plan to actively monitor the session.
> 审查闸门可能产生长时间运行的 Claude/Codex 循环，并快速消耗用量限额。仅在你计划主动监控会话时启用。
## Typical Flows
## 典型流程
### Review Before Shipping
### 发布前审查
```bash
/codex:review
```
### Hand A Problem To Codex
### 将问题交给 Codex
```bash
/codex:rescue investigate why the build is failing in CI
```
### Start Something Long-Running
### 启动长时间运行的任务
```bash
/codex:adversarial-review --background
/codex:rescue --background investigate the flaky test
```
Then check in with:
然后通过以下方式查看状态：
```bash
/codex:status
/codex:result
```
## Codex Integration
## Codex 集成
The Codex plugin wraps the [Codex app server](https://developers.openai.com/codex/app-server). It uses the global `codex` binary installed in your environment and [applies the same configuration](https://developers.openai.com/codex/config-basic).
Codex 插件封装了 [Codex app server](https://developers.openai.com/codex/app-server). 它会使用环境中安装的全局 `codex` 二进制文件，并[应用相同的配置](https://developers.openai.com/codex/config-basic).
### Common Configurations
### 常见配置
If you want to change the default reasoning effort or the default model that gets used by the plugin, you can define that inside your user-level or project-level `config.toml`. For example to always use `gpt-5.4-mini` on `high` for a specific project you can add the following to a `.codex/config.toml` file at the root of the directory you started Claude in:
如果你想更改插件默认的推理强度（reasoning effort）或默认模型，可以在用户级或项目级的 `config.toml` 中进行配置。例如，若要让某个特定项目在 `high` 上始终使用 `gpt-5.4-mini`，可在启动 Claude 时所在目录根部的 `.codex/config.toml` 文件中添加以下内容：
```toml
model = "gpt-5.4-mini"
model_reasoning_effort = "high"
```
Your configuration will be picked up based on:
你的配置会按以下规则生效：
- user-level config in `~/.codex/config.toml`
- project-level overrides in `.codex/config.toml`
- project-level overrides only load when the [project is trusted](https://developers.openai.com/codex/config-advanced#project-config-files-codexconfigtoml)
- 用户级配置位于 `~/.codex/config.toml`
- 项目级覆盖位于 `.codex/config.toml`
- 项目级覆盖仅在[项目受信任](https://developers.openai.com/codex/config-advanced#project-config-files-codexconfigtoml) 时才会加载
Check out the Codex docs for more [configuration options](https://developers.openai.com/codex/config-reference).
更多[配置选项](https://developers.openai.com/codex/config-reference). 请参阅 Codex 文档。
### Moving The Work Over To Codex
### 将工作迁移到 Codex
Delegated tasks and any [stop gate](#what-does-the-review-gate-do) run can also be directly resumed inside Codex by running `codex resume` either with the specific session ID you received from running `/codex:result` or `/codex:status` or by selecting it from the list.
委派任务以及任何 [stop gate](#what-does-the-review-gate-do) 运行，也可在 Codex 中直接恢复：运行 `codex resume`，并传入运行 `/codex:result` 或 `/codex:status` 时获得的特定会话 ID，或从列表中选择。
This way you can review the Codex work or continue the work there.
这样你就可以在 Codex 中审查相关工作，或在那里继续推进。
## FAQ
## 常见问题
### Do I need a separate Codex account for this plugin?
### 使用此插件是否需要单独的 Codex 账户？
If you are already signed into Codex on this machine, that account should work immediately here too. This plugin uses your local Codex CLI authentication.
如果你已在本机登录 Codex，该账户应可在此插件中直接使用。本插件使用你本地的 Codex CLI 身份验证。
If you only use Claude Code today and have not used Codex yet, you will also need to sign in to Codex with either a ChatGPT account or an API key. [Codex is available with your ChatGPT subscription](https://developers.openai.com/codex/pricing/), and [`codex login`](https://developers.openai.com/codex/cli/reference/#codex-login) supports both ChatGPT and API key sign-in. Run `/codex:setup` to check whether Codex is ready, and use `!codex login` if it is not.
如果你目前只使用 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`。
### Does the plugin use a separate Codex runtime?
### 插件是否使用独立的 Codex 运行时？
No. This plugin delegates through your local [Codex CLI](https://developers.openai.com/codex/cli/) and [Codex app server](https://developers.openai.com/codex/app-server/) on the same machine.
不会。本插件通过你本机上的 [Codex CLI](https://developers.openai.com/codex/cli/) 与 [Codex app server](https://developers.openai.com/codex/app-server/) 进行委派。
That means:
这意味着：
- it uses the same Codex install you would use directly
- it uses the same local authentication state
- it uses the same repository checkout and machine-local environment
- 使用与你直接调用时相同的 Codex 安装
- 使用相同的本地身份验证状态
- 使用相同的仓库检出与机器本地环境
### Will it use the same Codex config I already have?
### 它会使用我已有的 Codex 配置吗？
Yes. If you already use Codex, the plugin picks up the same [configuration](#common-configurations).
会。如果你已在用 Codex，插件会沿用相同的[配置](#common-configurations)。
### Can I keep using my current API key or base URL setup?
### 我还能继续使用当前的 API 密钥或 base URL 设置吗？
Yes. Because the plugin uses your local Codex CLI, your existing sign-in method and config still apply.
可以。由于插件使用你本地的 Codex CLI，你现有的登录方式与配置仍然适用。
If you need to point the built-in OpenAI provider at a different endpoint, set `openai_base_url` in your [Codex config](https://developers.openai.com/codex/config-advanced/#config-and-state-locations).
若需将内置 OpenAI 提供方指向其他端点，请在你的 [Codex 配置](https://developers.openai.com/codex/config-advanced/#config-and-state-locations). 中设置 `openai_base_url`