内容
# 技能代码库
[](https://www.npmjs.com/package/skill-codex)
[](https://www.npmjs.com/package/skill-codex)
[](https://ko-fi.com/arystos)
使用 [OpenAI Codex](https://github.com/openai/codex) 进行代码审查、任务委托和第二意见 —— 通过 MCP，使用您现有的 Codex 订阅。无需 API 密钥。
> **两个模型很少犯相同的错误。** skill-codex 让 Claude 和 Codex 相互检查对方的工作 —— Claude 计划和构建速度快，Codex 以新鲜的眼光审查 —— 从单个终端。无需 API 密钥，无需第二个窗口，无需复制粘贴。
```shell
npx skill-codex setup # 然后重启 Claude Code
```
<details>
<summary><b>目录</b></summary>
- [为什么？](#为什么？)
- [为什么不直接使用 Claude 自己的子代理？](#为什么不直接使用-claude-自己的子代理？)
- [比较](#比较)
- [实际演示](#实际演示)
- [安装](#安装)
- [用法](#用法)
- [配置](#配置)
- [故障排除](#故障排除)
- [开发](#开发)
- [贡献](#贡献)
- [许可证](#许可证)
</details>
## 为什么？
Claude Code 和 Codex CLI 有不同的优势。Claude 在推理、架构和复杂重构方面表现出色。Codex 速度快、彻底，擅长专注的执行和审查。**skill-codex** 让它们在单个终端中协同工作 —— 无需第二个窗口，无需复制粘贴，无需上下文丢失。
* **`/codex-review`** — 让 Codex 审查您当前的更改，作为第二个审查者
* **`/codex-do`** — 将明确范围的实施任务委托给 Codex
* **`/codex-consult`** — 获取架构或设计决策的第二意见
* **`codex-bridge` 代理技能** — 在实施/审查/咨询请求时自动触发，无需命令
* **自动审查钩子** — 智能 PostToolUse 钩子在重大更改后建议审查
* **实时进度** — 将 Codex 的活动流式传输为 MCP 进度，以便长时间运行永远不会看起来冻结（镜像到 OS 临时目录下的可尾随日志 —— 永远不会污染您的存储库）
* **订阅优先** — 与 `codex login` 一起工作，无需 `OPENAI_API_KEY`
* **防护措施** — 重试、超时、反递归、锁定文件、预飞行检查
### 为什么不直接使用 Claude 自己的子代理？
因为子代理是 **相同的模型**。当 Claude 审查 Claude 时，您会继承相同的盲点 —— 它正在评估自己的作业。一个 *不同的* 模型系列经过不同的训练，因此其错误与 Claude 的错误不相关：它可以检查 Claude 自信错误的内容，而 Claude 可以检查 Codex 错误的内容。这种不相关的跨模型检查是整个要点 —— 而 skill-codex 将 Claude 作为最终裁判，从不盲目转发 Codex 的裁决。
### 比较
| | skill-codex | 大多数 Codex MCP 桥接器 |
|---|---|---|
| Codex **订阅** 认证（无 `OPENAI_API_KEY`） | ✅ | ⚠️ 通常需要 API 密钥 |
| **Windows** 在 CI 中验证（不仅仅是“应该有效”） | ✅ 9 种矩阵（Windows/macOS/Linux × Node 18/20/22） | ❌ 通常仅限 Linux CI |
| **实时进度**，让长时间运行永远不会看起来冻结 | ✅ MCP 进度 + 可尾随日志 | ⚠️ 取决于具体实现 |
| **斜杠命令**（`/codex-review`，`/codex-do`，`/codex-consult`） | ✅ | ⚠️ 部分支持 |
| **自动审查钩子**（PostToolUse） | ✅ | ❌ |
| **代理技能**（自动触发，无需命令） | ✅ | ❌ |
| **防护措施**：重试、超时、反递归、锁定文件 | ✅ | ⚠️ 部分支持 |
*快照，而非排行榜 —— Codex MCP 空间发展迅速，请检查每个工具的当前状态。重点不在“skill-codex 赢得一切”，而在于操作细节（订阅认证、真正的 Windows 支持、永不冻结的运行、防护措施）是它的关注点。*
## 实际演示
上面的 20 秒演示。每个功能都在运动中：
<details>
<summary><b>▶ 功能演示</b> — 审查 · 委托 · 咨询 · 模型 & 努力 · 内存 · 防护措施 · 钩子</summary>
### `/codex-review` — 不同的模型审查您的差异并返回裁决，具有有界的修复 → 重新审查循环
### `/codex-do` — 委托一个有界任务；Codex 编写它，Claude 审查差异
### `/codex-consult` — 对设计决策的第二意见（您保留决策权）
### 模型 & 推理努力，按任务 — 廉价模型用于繁琐工作，高努力用于艰难审查
### 会话内存 — 将线程 ID 传回，Codex 在调用之间记住
### 永不冻结、永不失控 — 实时进度加上超时 / 反递归 / 锁定文件防护，适用于 Windows
### 自动审查钩子 — 在重大更改后提示运行 `/codex-review`（跳过琐碎差异）
</details>
## 安装
**先决条件**
* [Node.js](https://nodejs.org) ≥ 18
* [Claude Code](https://code.claude.com) 已安装并认证
* [Codex CLI](https://github.com/openai/codex) 已安装并登录 (`codex login`)
**快速开始**
```shell
# 选项 A：直接运行（无需全局安装）
npx skill-codex setup
# 选项 B：全局安装，然后设置
npm i -g skill-codex
skill-codex setup
# 重启 Claude Code 以加载 MCP 服务器，然后使用：
/codex-review # 审查未提交的更改
/codex-do "编写测试" # 将任务委托给 Codex
/codex-consult "方法？" # 获取第二意见
```
`setup` 注册 MCP 服务器（`~/.claude.json`），安装斜杠命令（`~/.claude/commands/`），配置自动审查钩子，安装 `codex-bridge` 代理技能（`~/.claude/skills/`），并验证所有内容。
> **提示：** 将 `.skill-codex.lock` 添加到您的 `.gitignore` 中。
**作为插件安装**
```shell
/plugin marketplace add Arystos/skill-codex
/plugin install skill-codex@skill-codex
```
插件捆绑了 MCP 服务器（通过 `npx -y skill-codex mcp` 启动），斜杠命令，代理技能和自动审查钩子。安装后重启 Claude Code。
## 用法
```
您在 Claude Code 中
|
|-- /codex-review --> MCP 工具 --> codex exec --sandbox read-only --> 审查结果
|-- /codex-do "任务" --> MCP 工具 --> codex exec --sandbox workspace-write --> 审查输出
+-- /codex-consult "问题" --> MCP 工具 --> codex exec --sandbox read-only --> 综合意见
```
MCP 服务器使用您登录的 Codex 会话将 `codex exec` 作为子进程启动。Claude 看到了输出并批判性地评估它 —— **Codex 被视为同行，而不是权威**。
斜杠命令是明确的入口点；`codex-bridge` **代理技能** 是隐含的入口点 —— 当您的请求与委托、审查或咨询模式匹配时，Claude 会自动加载它（“实现 X”，“审查此差异”，“第二意见关于…”）。琐碎任务（< 50 行，直接完成更快）不在范围内。
<details>
<summary><b>高级：模型、努力、沙盒、会话 & 原生审查</b></summary>
这些 `codex_exec` 参数都是可选的 —— 省略它们，Codex 将使用其默认值：
* **`model`** — 选择 Codex 模型（例如 `gpt-5.5`，`gpt-5.4`，`gpt-5.4-mini`）。将廉价任务路由到较小的模型，并将艰难任务升级。
* **`reasoningEffort`** — Codex 的思考程度：`minimal` | `low` | `medium` | `high` | `xhigh`。
* **`sandbox`** — 显式策略（`read-only`，`workspace-write`，`danger-full-access`），覆盖 `mode`。仅当您了解风险时，才使用 `danger-full-access`。
* **`sessionId`** — 恢复以前的 Codex 会话以进行多轮内存。每个响应都包含会话的线程 ID；将其传回，以便 Codex 保留上下文 —— 例如，继续审查以前标记的问题是否已修复。
* **`review`** — 运行 Codex 的原生差异范围审查器（`codex exec review`），可选地针对分支（`reviewBase`）或提交（`reviewCommit`）。
完整参数列表：[docs/CONFIGURATION.md](docs/CONFIGURATION.md#codex_exec-工具参数)。
</details>
<details>
<summary><b>示例输出</b></summary>
```
[只读 │ D:\myproject │ 21538 tok in (15744 cached) → 129 out]
✔ exec: powershell -Command 'git diff --cached' (ok)
严重 — src/auth/login.ts:42
密码比较使用 == 而不是时间安全的比较。
中等 — src/api/routes.ts:18
登录端点上缺少速率限制。
```
第一行显示模式、工作目录和令牌使用情况。活动行显示 Codex 执行的命令（✔ ok，✘ 阻止/失败）。响应内容在空白行后出现。
</details>
## 配置
所有内容都是可选的。最常见的旋钮：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `SKILL_CODEX_TIMEOUT_MS` | `300000`（5 分钟） | 子进程超时 |
| `SKILL_CODEX_MAX_RETRIES` | `3` | 暂时性错误的重试次数 |
| `SKILL_CODEX_WINDOWS_SANDBOX` | `unelevated` | 仅限 Windows 的 Codex 沙盒模式 |
自动审查钩子跳过琐碎的差异（仅文档、< 5 行、空白），并强制审查安全路径或大型/跨越更改，以保留您的 Codex 配额。
**完整参考** — 所有环境变量、完整的智能过滤器规则、边缘情况行为和所有 `codex_exec` 参数： **[docs/CONFIGURATION.md](docs/CONFIGURATION.md)**。
## 故障排除
**设置提示“钩子脚本未找到”** — 先运行 `npm run build`，然后再运行 `npx skill-codex setup`。钩子脚本位于包根目录，而非 `dist/`。
**`/codex-review` 提示“未知工具：codex_exec”** — 在设置后重启 Claude Code。MCP 服务器仅在启动时加载。
**Codex 一直超时** — 增加它：`export SKILL_CODEX_TIMEOUT_MS=1200000`（20 分钟）。大型代码库需要更长时间。
**“身份验证过期”但 Codex 在另一个终端中有效** — MCP 服务器在其自己的进程中运行。运行 `codex login` 并重启 Claude Code。在 Windows 上，身份验证预检查自动跳过（PowerShell 配置文件错误导致假阴性）；身份验证仍在 Codex 实际运行时得到验证。
**锁定文件阻止运行** — 崩溃的运行可能会留下陈旧的 `.skill-codex.lock`。它在 15 分钟后自动清理，或手动删除。
**Windows： “windows sandbox failed: spawn setup refresh” / Codex 命令全部被阻止** — Codex 的默认 *提升* Windows 沙盒在许多设置中无法启动 ([openai/codex#24098](https://github.com/openai/codex/issues/24098)，[#24259](https://github.com/openai/codex/issues/24259))。skill-codex 固定 `windows.sandbox=unelevated`，它可以可靠地启动。如果您的机器需要提升的沙盒，请设置 `SKILL_CODEX_WINDOWS_SANDBOX=elevated`。
## 开发
```shell
git clone https://github.com/Arystos/skill-codex.git
cd skill-codex
npm install
npm run build
npm test
npm run test:coverage # 强制执行与 CI 相同的 80%+ 门槛
```
安全策略： [SECURITY.md](SECURITY.md)。卸载：`npx skill-codex uninstall`.
## 灵感来源
* [Dunqing/claude-codex-bridge](https://github.com/Dunqing/claude-codex-bridge) — 重试逻辑、反递归、输出解析
* [EpocheDrift/claude-codex-skill](https://github.com/EpocheDrift/claude-codex-skill) — 订阅优先、委托启发式
* [incadawr/claude-codex-skill](https://github.com/incadawr/claude-codex-skill) — MCP 服务器方法、自动触发
## 贡献
欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)、 [路线图](ROADMAP.md) 和 [项目板](https://github.com/users/Arystos/projects/2) — 标记为 **good first issue** 和 **help wanted** 的问题是开始贡献的好地方。问题和想法请在 [讨论](https://github.com/Arystos/skill-codex/discussions) 中提出。如果您觉得这很有用，可以 [在 Ko-fi 上支持该项目](https://ko-fi.com/arystos)。
## 许可证
[MIT](LICENSE)
