内容
# codex-in-claude
[](https://github.com/briandconnelly/codex-in-claude/actions/workflows/ci.yml)
[](LICENSE)
[](pyproject.toml)
[](https://pypi.org/project/codex-in-claude/)
在 **Claude Code** 中调用 **OpenAI Codex** — 独立的第二意见、结构化的代码审查和委托编码任务（**跨模型审查**）— 通过 FastMCP 插件安全地驱动 `codex` 命令行界面。
> **状态：** alpha。代理可见的表面由 `fingerprint` 版本控制；1.0 之前的次要版本可能会更改它。
## 为什么
第二个模型是一种廉价、高价值的检查。`codex-in-claude` 允许 Claude Code 会话向 Codex 提出问题、审查差异或委托任务 — 并获得一个结构化的、**默认为安全**的结果，您可以控制。
| 层级 | Codex 沙盒 | 编辑位置 | 用途 |
|------|---------------|----------------|---------|
| `consult` | `read-only` | 无 — 仅文本/发现 | 问题、第二意见 |
| `review` | `read-only` | 无 — 结构化发现 | 审查您的 git 更改 |
| `propose` | `workspace-write` （临时 git **工作树**） | 隔离工作树 → 返回 **可审查的差异，绝不自动应用** | 委托编码任务 |
计划中的后续里程碑：一个明确选择加入的 `apply` 层级，用于实时树编辑。目前该工具集未公开此功能。
## 快速开始
```sh
# 1. 确认 Codex 已安装并认证。
codex login
# 2. 在 Claude Code 中添加市场插件，然后安装插件：
/plugin marketplace add briandconnelly/codex-in-claude
/plugin install codex-in-claude
```
然后在 Claude Code 中运行 `/codex:status`。它是免费的（无需模型调用），并且检查 `codex` 命令行界面是否找到、认证并且在测试的兼容性范围内。
对于第一次有用的运行：
- `/codex:consult is this approach sound?` 获取只读第二意见。
- `/codex:review` 审查您的当前 git 更改。
- `/codex:delegate add focused tests for this behavior` 在隔离的工作树中获取提议的差异。
MCP 服务器通过 `uvx` 按需启动，因此更新是刻意的。
## 示例
从 Claude Code 会话审查您的未提交更改：
> `/codex:review`
Codex 检查差异 **只读** 并返回结构化的结果信封（摘要）：
```json
{
"ok": true,
"tool": "codex_review_changes",
"verdict": "concerns",
"confidence": "high",
"summary": "重试路径是正确的，但回退延迟在调用之间泄漏，新分支没有测试覆盖。",
"findings": [
{
"severity": "high",
"title": "回退延迟在成功后从未重置",
"file": "src/app/retry.py",
"line": 42,
"evidence": "self._delay 在调用成功后保持其最后一个值",
"risk": "后来的暂时性故障从膨胀的延迟开始，添加延迟。",
"recommendation": "在成功分支中将 self._delay 重置为基本延迟。"
}
],
"next_steps": ["添加一个回归测试，断言延迟在成功后重置"],
"meta": { "scope": "working_tree", "sandbox": "read-only", "elapsed_ms": 8137 }
}
```
`verdict` 是 `pass` / `concerns` / `fail` / `unknown` 之一；`confidence` 是 `low` / `medium` / `high`；每个发现都带有 `severity` （`critical` … `nit`）加上 `evidence`、`risk` 和 `recommendation`。上述信封是摘要的 — `meta`（始终存在，包含 `cwd`、`tier`、`sandbox`、`isolation` 和时间）、`request_id`、`raw_response` 和其他字段被修剪以保持简洁；请参见 [`docs/REFERENCE.md`](docs/REFERENCE.md) 以获取完整结构。像验证声明一样对待输出，而不是盲目遵循指令。
## 要求
- `PATH` 上的 [`codex` 命令行界面](https://developers.openai.com/codex/cli)，已认证（`codex login` — ChatGPT 或 API 密钥）。针对 `codex-cli 0.142` 进行测试；支持的范围位于 [`cli_contract.py`](src/codex_in_claude/cli_contract.py) 中，`/codex:status` 报告您的版本是否在此范围内，并且 [`COMPATIBILITY.md`](COMPATIBILITY.md) 解释了该策略。
- `PATH` 上的 [`uv`](https://docs.astral.sh/uv/) （Claude Code 使用 `uvx` 启动 MCP 服务器）。
- 可用于 `uvx` 的 Python 3.11+。
- `git`（用于审查和委托）。
## 工具
**活动（调用模型并可能消耗代币）：**
- `codex_consult(question, …)` — 只读第二意见/答案。
- `codex_review_changes(scope, base, commit, paths, …)` — 审查 `working_tree` / `branch` / `commit`；返回结构化发现。
- `codex_delegate(task, …)` — 在隔离的工作树中实现任务；返回可审查的 `diff`，**绝不** 应用。
- `codex_consult_async(question, …)`、`codex_review_changes_async(scope, base, commit, paths, …)`、`codex_delegate_async(task, …)` — 三个活动工具的分离变体，采用与同步表单相同的参数；每个立即返回一个 `job_id`。启动作业承诺消耗（它运行到完成或其截止日期）；使用 `codex_job_status` / `codex_job_result` 轮询。
**免费（仅限本地）：**
- `codex_status` — 准备就绪、版本、身份验证、解析的默认值和 `rate_limit` 块（5 小时/每周窗口的剩余 Codex 配额，从您的最后一次付费调用中捕获；`status` 是 `available`/`limited`/`exhausted`/`unknown`）。建议 — 告知是否消耗；`unknown` 只是意味着没有新的读取。
- `codex_dry_run(scope, …)` — 预览审查的范围/差异大小/减少在消耗之前。
- `codex_delegate_dry_run(task, …)` — 预览委托的种子基准（HEAD 提交，加上跟踪的、未提交的和未跟踪的计数和大小）和提示大小在消耗之前；不会创建工作树。
- `codex_capabilities` — 工具清单 + 结果指纹。
- `codex_models` — 有效的 `model` 滑块的建议目录，从 Codex 的磁盘缓存中读取，并带有捆绑的静态备用；也可以作为 `codex://models` 资源浏览。仅发现 — `model` 保持直通，因此未列出的滑块仍然有效，并且 `codex exec` 验证它。
- `codex_job_status(job_id, …)` / `codex_job_result` / `codex_job_consume_result` / `codex_job_cancel` / `codex_job_list` — 后台作业生命周期。状态是磁盘支持的，并且在服务器重启时存活；作业受限于时钟截止日期，带有 TTL + 计数上限驱逐。遵守 `poll_after_ms`（它随着正在运行的作业的运行时增长，有界限，因此您会自动退后）；不要在紧密循环中轮询。结果在作业完成 **后** 保留 `ttl_seconds`，因此 `expires_at` 在作业运行时为空，并在作业完成时设置。
斜杠命令包装这些：`/codex:status`、`/codex:consult`、`/codex:review`、`/codex:delegate`、`/codex:delegate-async`、`/codex:dry-run`。
活动工具通过 `codex` 命令行界面将提示和相关上下文/差异发送到 OpenAI。像验证声明一样对待 Codex 的输出，而不是盲目遵循指令。
## 技能
插件自带两个 Claude Code 技能（从 `skills/` 自动发现）：
- **`collaborating-with-codex`** — 工具参考和防护栏主页：调用哪个工具（咨询/审查/委托）、如何读取信封、后台作业和服务器宕机时的备用。
- **`deliberating-with-codex`** — 如何将这些工具与您自己的工作组合成一个深思熟虑的双模型模式（法官、两名成员的面板、审查-修订循环），带有价值/风险门控，以便单个咨询保留默认值。
## 结果信封
每个工具都返回一个由 `ok` 键控的区分信封。成功带有 `summary`/`findings`/`meta`（加上仅限审查的 `verdict`/`confidence`，或委托的提议 `diff`）；失败是一个统一的、可机器处理的 `error` — 一个稳定的 `code`、`temporary`/`retry_after_ms`、一个符号 `repair{next_step,tool,arguments,alternative}` 和 `details{field,reason,allowed_values}` 以实现自动化恢复（完整的模式在 `codex://error-envelope` 资源中）。形状由 `fingerprint` 版本控制。每个活动调用的 `meta.rate_limit` 携带来自该调用的实时快照（`source: current_run`）；`codex_status` 报告缓存的快照（`source: plugin_cache`）。
直接调用 MCP 工具而不是通过 `/codex:*` 命令？请参见 [`docs/REFERENCE.md`](docs/REFERENCE.md) 以获取完整信封合约和工作空间选择（`workspace_root`）。
## 安全
- `consult` 和 `review` 严格为只读。
- `propose` （委托工具）让 Codex 编写，但仅在从 `HEAD` 播种的临时 git 工作树中。未跟踪的文件不会被复制。您的 working tree 绝不会被插件修改；您审查返回的差异并自己应用它。委托的无网络沙盒（`workspace-write`）仅阻止 Codex 在沙盒中运行的命令的出口 — 它并不意味着没有任何东西离开机器：模型调用仍然会将您的任务和存储库上下文发送到 OpenAI。
- 类似于机密的内容在离开插件之前会被删减（防御深度，而不是保证 — Codex 可以在运行期间自己读取文件；使用隔离和干净的工作空间用于敏感存储库）。这涵盖了收集的差异和 Codex 返回的纯文本返回（`summary`、`findings`、`raw_response.text`）：类似机密的文件块被删除，内联机密值变为 `[redacted: secret value]`。它 **不** 涵盖您提供的输入（`question`、`task`、`extra_context`），它们会原样发送，也不在运行期间 Codex 自己从文件中读取的机密。
- 插件绝不会传递 Codex 的 `--dangerously-bypass-*` 标志。
- 发现漏洞？请私下报告 — 请参见 [`SECURITY.md`](SECURITY.md)。
## 配置（env，`CODEX_IN_CLAUDE_*`）
| 变量 | 默认值 | 含义 |
|-----|---------|---------|
| `CODEX_IN_CLAUDE_MODEL` | 未设置 | Codex 模型覆盖 |
| `CODEX_IN_CLAUDE_TIMEOUT_SECONDS` | 180 | 每次调用超时（夹紧 10–600） |
| `CODEX_IN_CLAUDE_ISOLATION` | `inherit` | `inherit` \| `ignore-config` \| `ignore-rules` |
| `CODEX_IN_CLAUDE_MAX_INPUT_BYTES` | 200000 | 作者输入的字节上限。收集的差异被截断为它；作者文本超过它被拒绝，错误为 `input_too_large` — `codex_consult` 将 `question`+`extra_context` 一起计算，而 `codex_review_changes`/`codex_delegate` 每个输入单独计算 |
| `CODEX_IN_CLAUDE_MAX_DELEGATE_DIFF_BYTES` | 200000 | 委托运行返回的内联差异的上限；较大的差异被截断，带有 `meta.truncated`/`meta.truncation_hint`（最小 1000） |
| `CODEX_IN_CLAUDE_MAX_OUTPUT_BYTES` | 10485760 | 捕获的 stdout 的字节上限（头部+尾部窗口；运行不被杀死）；stderr 绑定到单独的 ~1 MiB 保留 |
| `CODEX_IN_CLAUDE_GIT_TIMEOUT_SECONDS` | 60 | git 命令超时 |
| `CODEX_IN_CLAUDE_STATE_DIR` | `$XDG_CACHE_HOME/codex-in-claude/jobs` 或 `~/.cache/codex-in-claude/jobs` | 磁盘支持的后台作业记录 |
| `CODEX_IN_CLAUDE_JOB_TTL` | 86400 | 已完成作业记录的保存秒数（最小 60） |
| `CODEX_IN_CLAUDE_JOB_MAX_SECONDS` | 1800 | 后台作业的时钟上限（夹紧 60–7200） |
| `CODEX_IN_CLAUDE_JOB_MAX_COUNT` | 50 | 每个工作空间的保留作业（夹紧 1–1000） |
| `CODEX_IN_CLAUDE_SUPPORTED_VERSIONS` | 内置测试集 | 以逗号分隔的 `codex` `major.minor` 版本，视为受支持 |
| `CODEX_IN_CLAUDE_LOG_LEVEL` | `WARNING` | 服务器诊断日志级别（`DEBUG`\|`INFO`\|`WARNING`\|`ERROR`\|`CRITICAL`）；日志输出到 **stderr**（绝不输出到 stdout） |
| `CODEX_IN_CLAUDE_LOG_FILE` | 未设置 | 还将诊断日志镜像到此文件路径 |
## 故障排除
首先运行 `/codex:status` — 它是免费的（无需模型调用），并且可以诊断大多数设置问题。
| 症状 | 原因 | 修复 |
|---------|-------|-----|
| `codex` 未找到 | 命令行界面未安装或不在 `PATH` 上 | 安装 [`codex` 命令行界面](https://developers.openai.com/codex/cli) 并确保它在 `PATH` 上 |
| 未认证 | 无 Codex 登录 | `codex login` （ChatGPT 或 API 密钥） |
| 版本警告 | 您的 `codex` 版本在测试范围之外 | 更新 `codex`，或在验证有效后设置 `CODEX_IN_CLAUDE_SUPPORTED_VERSIONS` |
| 结果中的 `meta.workspace_warning` | 服务器回退到其自己的启动目录 | 从目标存储库运行，或传递 `workspace_root`（请参见 [`docs/REFERENCE.md`](docs/REFERENCE.md#workspace-selection)） |
| `codex_delegate` 需要提交失败 | 临时工作树从 `HEAD` 播种 | 至少进行一次提交 |
| `codex_rate_limited` 错误 | 帐户达到使用/速率限制 | 退后 `retry_after_ms`，然后重试 |
| `Connection closed` / `No such tool available: mcp__codex-in-claude__*` | 标准输入输出 MCP 服务器已关闭 | 使用 `/mcp` 命令重新连接（或重启客户端），然后使用 `codex_status` 确认；请参见下面的备用说明 |
标准输入输出 MCP 服务器无法透明地自动重启（客户端拥有管道和 `initialize` 握手），因此恢复是手动重新连接。在致命崩溃时，服务器将面包屑写入 **stderr** （服务器名称、版本、原因和 `/mcp` 重新连接提示）后退出，并将干净的断开连接（EOF / 破损管道 / `SIGINT` / `SIGTERM`）记录为关闭而不是崩溃 — 因此服务器日志告诉您它是否死了或被停止。
如果 MCP 服务器关闭，您可以直接使用 `codex` 命令行界面进行只读咨询或审查 — `codex exec --sandbox read-only --skip-git-repo-check -` （标准输入提示）— 但这会绕过插件的差异收集、机密删减、输入字节限制和结构化信封，因此请自行净化输入并优先恢复服务器。请参见 `collaborating-with-codex` 技能以获取完整的备用指南。
## 本地开发
```sh
uv sync
uv run pytest # 单元测试（覆盖率下限 95%）
uv run pytest -m integration --no-cov # 现场测试；需要安装并登录 codex
uv run ruff check . && uv run ruff format --check . && uv run ty check
uv run codex-in-claude-mcp # 通过标准输入输出运行 MCP 服务器
```
要从本地检出测试插件，请将 `.mcp.json` 指向 `uv run --project /path/to/codex-in-claude codex-in-claude-mcp` 而不是随附的版本固定 `uvx --from codex-in-claude==<version>` 调用。
请参见 [`CONTRIBUTING.md`](CONTRIBUTING.md) 以获取分支、提交和 PR 约定。
## 相关项目
- [`claude-in-codex`](https://github.com/briandconnelly/claude-in-codex) — 镜像图像：让 **Codex** 调用 **Claude Code**。
- 受 [`openai/codex-plugin-cc`](https://github.com/openai/codex-plugin-cc) 启发，围绕 `codex exec` （不是实验性应用服务器协议）重建以提高鲁棒性。
## 许可证
MIT
