codex-plugin-claude-code

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codex Plugin for Claude Code

适用于Claude Code的Codex插件

Skill by ara.so — Codex Skills collection.

由ara.so提供的技能 — Codex技能合集。

Overview

概述

The

codex-plugin-cc

enables Claude Code users to leverage OpenAI Codex directly from their workflow. You can request code reviews (standard or adversarial), delegate tasks to Codex as a background subagent, and manage long-running Codex jobs—all without leaving Claude Code.

Key capabilities:

```
/codex:review
```
— standard read-only Codex code review
```
/codex:adversarial-review
```
— steerable review that challenges design decisions
```
/codex:rescue
```
— delegate investigation/fix tasks to Codex subagent
```
/codex:status
```
,
```
/codex:result
```
,
```
/codex:cancel
```
— manage background jobs

codex-plugin-cc

让Claude Code用户可以在工作流中直接使用OpenAI Codex。你可以请求代码评审（标准或对抗性）、将任务委托给Codex作为后台子代理，以及管理长时间运行的Codex任务——所有操作无需离开Claude Code。

核心功能：

```
/codex:review
```
— 标准只读Codex代码评审
```
/codex:adversarial-review
```
— 可引导的评审，挑战设计决策
```
/codex:rescue
```
— 将调查/修复任务委托给Codex子代理
```
/codex:status
```
,
```
/codex:result
```
,
```
/codex:cancel
```
— 管理后台任务

Requirements

要求

Node.js 18.18+
ChatGPT subscription (including Free tier) or OpenAI API key
Codex CLI (the plugin can help install it via
```
/codex:setup
```
)

Usage contributes to your Codex usage limits.

Node.js 18.18+
ChatGPT订阅（包括免费版）或OpenAI API密钥
Codex CLI（插件可通过
```
/codex:setup
```
帮助安装）

使用会消耗你的Codex使用额度。

Installation

安装

1. Add the marketplace and install the plugin

1. 添加市场并安装插件

bash

/plugin marketplace add openai/codex-plugin-cc
/plugin install codex@openai-codex
/reload-plugins

bash

/plugin marketplace add openai/codex-plugin-cc
/plugin install codex@openai-codex
/reload-plugins

2. Run setup

2. 运行设置

bash

/codex:setup

This checks if Codex is installed and authenticated. If missing and npm is available, it can offer to install Codex for you.

bash

/codex:setup

这会检查Codex是否已安装并完成认证。如果未安装且npm可用，插件会提供安装Codex的选项。

3. Install Codex CLI (if needed)

3. 安装Codex CLI（如需手动安装）

If you prefer manual installation:

bash

npm install -g @openai/codex

bash

npm install -g @openai/codex

4. Authenticate Codex

4. 认证Codex

If Codex is installed but not logged in:

bash

!codex login

Follow the prompts to sign in with ChatGPT or API key.

如果Codex已安装但未登录：

bash

!codex login

按照提示使用ChatGPT或API密钥登录。

5. Verify

5. 验证

After setup, you should see:

Slash commands:

/codex:review

/codex:adversarial-review

/codex:rescue

/codex:status

/codex:result

/codex:cancel

/codex:setup

Subagent:
```
codex:codex-rescue
```
in
```
/agents
```

Test it:

bash

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

设置完成后，你应该看到：

斜杠命令：

/codex:review

/codex:adversarial-review

/codex:rescue

/codex:status

/codex:result

/codex:cancel

/codex:setup

子代理：
```
codex:codex-rescue
```
在
```
/agents
```
中

测试：

bash

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

Commands

命令

/codex:review

/codex:review

Runs a standard Codex code review on uncommitted changes or branch diff.

Flags:

```
--base <ref>
```
— compare against a base branch (e.g.,
```
main
```
)
```
--wait
```
— wait synchronously for result
```
--background
```
— run asynchronously (recommended for multi-file changes)

Examples:

bash

undefined

对未提交的更改或分支差异运行标准Codex代码评审。

参数：

```
--base <ref>
```
— 与基准分支对比（例如：
```
main
```
）
```
--wait
```
— 同步等待结果
```
--background
```
— 异步运行（推荐用于多文件更改）

示例：

bash

undefined

Review uncommitted changes

评审未提交的更改

/codex:review

Review current branch vs main

评审当前分支与main分支的差异

/codex:review --base main

Run in background

在后台运行

/codex:review --background


**Notes:**
- Read-only, no modifications
- Use `/codex:status` and `/codex:result` for background jobs

---

/codex:review --background


**注意：**
- 只读操作，不会修改代码
- 后台任务使用`/codex:status`和`/codex:result`查看结果

---

/codex:adversarial-review

/codex:adversarial-review

Runs a steerable review that challenges implementation and design choices. Useful for pressure-testing assumptions, tradeoffs, and alternative approaches.

Flags:

Same as
```
/codex:review
```
:
```
--base
```
,
```
--wait
```
,
```
--background
```
Accepts focus text after flags to steer the review

Examples:

bash

undefined

运行可引导的评审，挑战实现和设计选择。适用于压力测试假设、权衡方案和替代方法。

参数：

与
```
/codex:review
```
相同：
```
--base
```
,
```
--wait
```
,
```
--background
```
参数后可添加聚焦文本来引导评审方向

示例：

bash

undefined

General adversarial review

通用对抗性评审

/codex:adversarial-review

Challenge caching and retry design

挑战缓存和重试设计

/codex:adversarial-review --base main challenge whether this was the right caching and retry design

Focus on race conditions

聚焦竞争条件

/codex:adversarial-review --background look for race conditions and question the chosen approach


**Use cases:**
- Pre-ship review challenging direction, not just code details
- Testing design choices, hidden assumptions, alternative approaches
- Pressure-testing auth, data loss, rollback, race conditions, reliability

---

/codex:adversarial-review --background look for race conditions and question the chosen approach


**使用场景：**
- 上线前评审，挑战方向而非仅代码细节
- 测试设计选择、隐藏假设和替代方案
- 压力测试认证、数据丢失、回滚、竞争条件和可靠性

---

/codex:rescue

/codex:rescue

Delegates a task to Codex through the

codex:codex-rescue

subagent. Codex will investigate, fix, or continue work.

Flags:

```
--background
```
— run asynchronously (recommended for long tasks)
```
--wait
```
— wait synchronously
```
--resume
```
— continue latest rescue thread for this repo
```
--fresh
```
— start a new rescue thread
```
--model <model>
```
— specify model (e.g.,
```
gpt-5.4-mini
```
,
```
spark
```
)
```
--effort <level>
```
— reasoning effort:
```
low
```
,
```
medium
```
,
```
high
```

Examples:

bash

undefined

通过

codex:codex-rescue

子代理将任务委托给Codex。Codex会进行调查、修复或继续工作。

参数：

```
--background
```
— 异步运行（推荐用于长时间任务）
```
--wait
```
— 同步等待
```
--resume
```
— 继续当前仓库的最新救援线程
```
--fresh
```
— 启动新的救援线程
```
--model <model>
```
— 指定模型（例如：
```
gpt-5.4-mini
```
,
```
spark
```
）
```
--effort <level>
```
— 推理力度：
```
low
```
,
```
medium
```
,
```
high
```

示例：

bash

undefined

Investigate test failure

调查测试失败原因

/codex:rescue investigate why the tests started failing

Fix with smallest safe patch

用最小安全补丁修复失败的测试

/codex:rescue fix the failing test with the smallest safe patch

Resume latest rescue

继续最新的救援任务

/codex:rescue --resume apply the top fix from the last run

Use specific model and effort

使用特定模型和推理力度

/codex:rescue --model gpt-5.4-mini --effort medium investigate the flaky integration test

Quick fix with spark

用spark模型快速修复

/codex:rescue --model spark fix the issue quickly

Background investigation

后台调查

/codex:rescue --background investigate the regression


**Natural delegation:**

You can also ask naturally:

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

Notes:

If
```
--model
```
or
```
--effort
```
omitted, Codex uses its own defaults
```
spark
```
maps to
```
gpt-5.3-codex-spark
```
Follow-up rescues can continue the latest task

/codex:rescue --background investigate the regression


**自然委托：**

你也可以用自然语言请求：

```text
让Codex重新设计数据库连接以提高弹性。

注意：

如果省略
```
--model
```
或
```
--effort
```
，Codex会使用自身默认值
```
spark
```
对应
```
gpt-5.3-codex-spark
```
后续救援任务可继续最新的任务线程

/codex:status

/codex:status

Shows running and recent Codex jobs for the current repository.

Examples:

bash

undefined

显示当前仓库中正在运行和最近的Codex任务。

示例：

bash

undefined

Show all jobs

显示所有任务

/codex:status

Show specific job

显示特定任务

/codex:status task-abc123


**Use cases:**
- Check background work progress
- See latest completed job
- Confirm if task still running

---

/codex:status task-abc123


**使用场景：**
- 检查后台任务进度
- 查看最新完成的任务
- 确认任务是否仍在运行

---

/codex:result

/codex:result

Shows final output for a finished job. Includes Codex session ID for resuming in Codex CLI.

Examples:

bash

undefined

显示已完成任务的最终输出。包含Codex会话ID，可用于在Codex CLI中恢复任务。

示例：

bash

undefined

Show latest result

显示最新结果

/codex:result

Show specific result

显示特定结果

/codex:result task-abc123


**Resume in Codex CLI:**

```bash
codex resume <session-id>

/codex:result task-abc123


**在Codex CLI中恢复任务：**

```bash
codex resume <session-id>

/codex:cancel

/codex:cancel

Cancels an active background Codex job.

Examples:

bash

undefined

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

示例：

bash

undefined

Cancel latest job

取消最新任务

/codex:cancel

Cancel specific job

取消特定任务

/codex:cancel task-abc123

---

/codex:cancel task-abc123

---

/codex:setup

/codex:setup

Checks if Codex is installed and authenticated. Can install Codex if npm is available. Also manages optional review gate.

Examples:

bash

undefined

检查Codex是否已安装并完成认证。如果npm可用，可安装Codex。还可管理可选的评审闸门。

示例：

bash

undefined

Check setup

检查设置

/codex:setup

Enable review gate (advanced)

启用评审闸门（高级功能）

/codex:setup --enable-review-gate

Disable review gate

禁用评审闸门

/codex:setup --disable-review-gate


**Review gate:**
- Uses a `Stop` hook to run targeted Codex review based on Claude's response
- Blocks stop if issues found, so Claude can address them
- **Warning:** Can create long Claude/Codex loops and drain usage limits quickly

---

/codex:setup --disable-review-gate


**评审闸门：**
- 使用`Stop`钩子根据Claude的响应运行针对性Codex评审
- 如果发现问题会阻止停止，以便Claude解决问题
- **警告：** 可能会创建Claude/Codex的长时间循环，快速消耗使用额度

---

Configuration

配置

The plugin uses your local Codex CLI configuration. Config is picked up from:

User-level:
```
~/.codex/config.toml
```
Project-level:
```
.codex/config.toml
```
(must be trusted)

插件使用本地Codex CLI配置。配置从以下位置读取：

用户级：
```
~/.codex/config.toml
```
项目级：
```
.codex/config.toml
```
（必须是受信任的）

Common Configurations

常见配置

Set default model and reasoning effort:

Create

.codex/config.toml

at the root of your project:

toml

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

Custom OpenAI base URL:

In your Codex config:

toml

openai_base_url = "https://your-custom-endpoint.example.com"

Use environment variables for API keys:

Codex respects

OPENAI_API_KEY

if you're using API key authentication:

bash

export OPENAI_API_KEY=your-api-key-here
codex login

See Codex config reference for full options.

设置默认模型和推理力度：

在项目根目录创建

.codex/config.toml

：

toml

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

自定义OpenAI基础URL：

在Codex配置中：

toml

openai_base_url = "https://your-custom-endpoint.example.com"

使用环境变量存储API密钥：

如果使用API密钥认证，Codex会读取

OPENAI_API_KEY

环境变量：

bash

export OPENAI_API_KEY=your-api-key-here
codex login

查看Codex配置参考获取完整选项。

Workflow Patterns

工作流模式

Review Before Shipping

上线前评审

bash

/codex:review

Wait for output, address feedback, commit.

bash

/codex:review

等待输出，处理反馈，提交代码。

Adversarial Pre-Ship Review

上线前对抗性评审

bash

/codex:adversarial-review --base main challenge the retry and timeout strategy

Use this to pressure-test critical design decisions.

bash

/codex:adversarial-review --base main challenge the retry and timeout strategy

用于压力测试关键设计决策。

Delegate Bug Investigation

委托Bug调查

bash

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

Check in later:

bash

/codex:status
/codex:result

bash

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

稍后检查：

bash

/codex:status
/codex:result

Quick Fix with Spark Model

使用Spark模型快速修复

bash

/codex:rescue --model spark fix the linter error quickly

bash

/codex:rescue --model spark fix the linter error quickly

Resume Previous Rescue

恢复之前的救援任务

bash

/codex:rescue --resume apply the suggested fix from the last run

bash

/codex:rescue --resume apply the suggested fix from the last run

Long-Running Background Task

长时间运行的后台任务

bash

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

Monitor:

bash

/codex:status

Retrieve:

bash

/codex:result

Cancel if needed:

bash

/codex:cancel

bash

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

监控：

bash

/codex:status

获取结果：

bash

/codex:result

必要时取消：

bash

/codex:cancel

Continue Work in Codex CLI

在Codex CLI中继续工作

After

/codex:result

, copy the session ID and resume directly in Codex:

bash

codex resume abc123-session-id

This lets you review Codex's work or continue it there.

运行

/codex:result

后，复制会话ID并在Codex中直接恢复：

bash

/codex:result

Code Examples

复制会话ID：abc123-session-id

JavaScript: Triggering Codex Review from a Script

在终端中

While the plugin is used via Claude Code slash commands, you can programmatically trigger Codex CLI tasks in Node.js:

javascript

const { execSync } = require('child_process');

function runCodexReview(baseBranch = null) {
  let cmd = 'codex review';
  if (baseBranch) {
    cmd += ` --base ${baseBranch}`;
  }
  try {
    const output = execSync(cmd, { encoding: 'utf-8' });
    console.log(output);
  } catch (error) {
    console.error('Codex review failed:', error.message);
  }
}

runCodexReview('main');

codex resume abc123-xyz


这让你可以在Codex中评审工作或继续任务。

---

JavaScript: Checking Codex Job Status

代码示例

—

JavaScript：从脚本触发Codex评审

javascript

const { execSync } = require('child_process');

function getCodexStatus(taskId = null) {
  let cmd = 'codex status';
  if (taskId) {
    cmd += ` ${taskId}`;
  }
  try {
    const output = execSync(cmd, { encoding: 'utf-8' });
    return JSON.parse(output); // Adjust based on actual Codex CLI output format
  } catch (error) {
    console.error('Failed to get Codex status:', error.message);
    return null;
  }
}

const status = getCodexStatus();
console.log(status);

虽然插件通过Claude Code的斜杠命令使用，但你也可以在Node.js中以编程方式触发Codex CLI任务：

javascript

const { execSync } = require('child_process');

function runCodexReview(baseBranch = null) {
  let cmd = 'codex review';
  if (baseBranch) {
    cmd += ` --base ${baseBranch}`;
  }
  try {
    const output = execSync(cmd, { encoding: 'utf-8' });
    console.log(output);
  } catch (error) {
    console.error('Codex review failed:', error.message);
  }
}

runCodexReview('main');

JavaScript: Delegating Task with Environment Config

JavaScript：检查Codex任务状态

javascript

const { execSync } = require('child_process');

function delegateToCodex(task, model = 'gpt-5.4-mini', effort = 'medium') {
  // Ensure Codex uses the right config
  process.env.CODEX_MODEL = model;
  process.env.CODEX_REASONING_EFFORT = effort;

  const cmd = `codex rescue "${task}"`;
  try {
    const output = execSync(cmd, { encoding: 'utf-8' });
    console.log('Codex rescue output:', output);
  } catch (error) {
    console.error('Codex rescue failed:', error.message);
  }
}

delegateToCodex('investigate the failing integration test');

javascript

const { execSync } = require('child_process');

function getCodexStatus(taskId = null) {
  let cmd = 'codex status';
  if (taskId) {
    cmd += ` ${taskId}`;
  }
  try {
    const output = execSync(cmd, { encoding: 'utf-8' });
    return JSON.parse(output); // 根据Codex CLI实际输出格式调整
  } catch (error) {
    console.error('Failed to get Codex status:', error.message);
    return null;
  }
}

const status = getCodexStatus();
console.log(status);

Troubleshooting

JavaScript：使用环境配置委托任务

Codex Not Found

—

Symptom:

/codex:setup

reports Codex is not installed.

Solution:

bash

npm install -g @openai/codex

Then re-run:

bash

/codex:setup

javascript

const { execSync } = require('child_process');

function delegateToCodex(task, model = 'gpt-5.4-mini', effort = 'medium') {
  // 确保Codex使用正确配置
  process.env.CODEX_MODEL = model;
  process.env.CODEX_REASONING_EFFORT = effort;

  const cmd = `codex rescue "${task}"`;
  try {
    const output = execSync(cmd, { encoding: 'utf-8' });
    console.log('Codex rescue output:', output);
  } catch (error) {
    console.error('Codex rescue failed:', error.message);
  }
}

delegateToCodex('investigate the failing integration test');

Authentication Failed

故障排除

—

Codex未找到

Symptom: Codex commands fail with authentication error.

Solution:

bash

!codex login

Follow the prompts to sign in with ChatGPT or API key.

症状：

/codex:setup

报告Codex未安装。

解决方案：

bash

npm install -g @openai/codex

然后重新运行：

bash

/codex:setup

Background Job Stuck

认证失败

Symptom:

/codex:status

shows job running for too long.

Solution:

bash

/codex:cancel

Then retry or investigate Codex logs.

症状： Codex命令因认证错误失败。

解决方案：

bash

!codex login

按照提示使用ChatGPT或API密钥登录。

Review Gate Draining Usage

后台任务卡住

Symptom: Review gate creates long Claude/Codex loops.

Solution:

Disable the review gate:

bash

/codex:setup --disable-review-gate

Only enable when actively monitoring.

症状：

/codex:status

显示任务运行时间过长。

解决方案：

bash

/codex:cancel

然后重试或调查Codex日志。

Custom Base URL Not Picked Up

评审闸门消耗额度过快

Symptom: Codex ignores

openai_base_url

config.

Solution:

Ensure

.codex/config.toml

is in the project root and the project is trusted. See Codex config docs.

症状： 评审闸门创建Claude/Codex的长时间循环。

解决方案：

禁用评审闸门：

bash

/codex:setup --disable-review-gate

仅在主动监控时启用。

Node.js Version Too Old

自定义基础URL未生效

Symptom: Plugin fails to load or Codex CLI errors.

Solution:

Upgrade to Node.js 18.18+:

bash

nvm install 18
nvm use 18

Or use your system's package manager.

症状： Codex忽略

openai_base_url

配置。

解决方案：

确保

.codex/config.toml

在项目根目录且项目是受信任的。查看Codex配置文档。

Advanced Usage

Node.js版本过旧

Combining with Claude Code Native Commands

—

You can alternate between Claude Code's native review and Codex's review:

bash

undefined

症状： 插件加载失败或Codex CLI报错。

解决方案：

升级到Node.js 18.18+：

bash

nvm install 18
nvm use 18

或使用系统包管理器升级。

Claude review

高级用法

—

与Claude Code原生命令结合使用

/review

你可以在Claude Code的原生评审和Codex评审之间切换：

bash

undefined

Codex adversarial review

Claude评审

/codex:adversarial-review --base main challenge the error handling strategy

undefined

/review

Using Codex Config Profiles

Codex对抗性评审

Define multiple configs and switch via environment:

.codex/config.toml
(default):

toml

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

.codex/config-high.toml
:

toml

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

Switch in shell before running commands:

bash

export CODEX_CONFIG=.codex/config-high.toml
/codex:rescue investigate the race condition thoroughly

(Exact mechanism depends on Codex CLI support; adjust as needed.)

/codex:adversarial-review --base main challenge the error handling strategy

undefined

Resuming Codex Sessions

使用Codex配置文件

After a rescue or review, grab the session ID from

/codex:result

and resume in Codex CLI for deeper investigation:

bash

/codex:result

定义多个配置文件并通过环境变量切换：

.codex/config.toml
（默认）：

toml

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

.codex/config-high.toml
：

toml

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

运行命令前在shell中切换：

bash

export CODEX_CONFIG=.codex/config-high.toml
/codex:rescue investigate the race condition thoroughly

（具体机制取决于Codex CLI支持，请按需调整。）

Copy session ID: abc123-xyz

恢复Codex会话

In terminal

—

codex resume abc123-xyz

---

救援或评审完成后，从

/codex:result

中获取会话ID，在Codex CLI中恢复以进行深入调查：

bash

/codex:result

Summary

复制会话ID：abc123-xyz

—

在终端中

The Codex plugin for Claude Code bridges two powerful AI coding tools:

Standard reviews:
```
/codex:review
```
Adversarial reviews:
```
/codex:adversarial-review
```
Task delegation:
```
/codex:rescue
```
Job management:
```
/codex:status
```
,
```
/codex:result
```
,
```
/codex:cancel
```

Install, authenticate, and leverage Codex's deep code understanding alongside Claude Code's agent workflow. Use background jobs for long tasks, adversarial reviews for design challenges, and rescue for delegating investigations and fixes.

Configuration: Uses your local Codex CLI config (

~/.codex/config.toml

.codex/config.toml

Authentication: Same as Codex CLI (

codex login

Workflow: Delegate to Codex, check status, retrieve results, or resume in Codex CLI for deeper work.

Resources:

codex resume abc123-xyz

---

—

总结

—

适用于Claude Code的Codex插件连接了两个强大的AI编码工具：

标准评审：
```
/codex:review
```
对抗性评审：
```
/codex:adversarial-review
```
任务委托：
```
/codex:rescue
```
任务管理：
```
/codex:status
```
,
```
/codex:result
```
,
```
/codex:cancel
```

安装、认证后，即可在Claude Code的代理工作流中利用Codex的深度代码理解能力。对长时间任务使用后台任务，对设计挑战使用对抗性评审，对调查和修复工作使用救援功能。

配置： 使用本地Codex CLI配置（

~/.codex/config.toml

或

.codex/config.toml

）。

认证： 与Codex CLI相同（

codex login

）。

工作流： 委托任务给Codex，检查状态，获取结果，或在Codex CLI中恢复以进行深入工作。

资源：