使用说明

Codex MCP桥接精简版

一个本地stdio MCP服务器，为Claude CLI提供两个工具并执行 codex exec 非交互式。

consult_codex
consult_codex_with_stdin

本自述中使用的占位符约定：

<project-root> =此存储库的本地克隆路径（例如， ~/workspace/codex-mcp-bridge).

特性

用途 codex exec - （通过stdin提示）处于非交互模式。
通过以下方式捕获最终输出 --output-last-message 文件第一。
默认沙盒为 read-only.
可通过以下方式选择目录列表 CODEX_ALLOWED_DIRS.
输出截断通过 CODEX_MAX_OUTPUT_CHARS.
对缺少CLI/auth/timeout/非零出口的简洁错误处理。
保持MCP stdout干净（没有调试日志记录到stdout）。

需求

Python 3.10+
Codex CLI已安装并经过身份验证(codex login)

安装

来自PyPI（推荐）

pip install codex-mcp-bridge

或者使用紫外线：

uv pip install codex-mcp-bridge

来源（开发）

cd <project-root>
uv venv
source .venv/bin/activate
uv pip install -e .[dev]

运行（stdio MCP）

从PyPI安装后：

codex-mcp-bridge

或来源：

cd <project-root>
uv run codex-mcp-bridge

Claude CLI注册

pip安装后（推荐）

claude mcp add codex-bridge -- codex-mcp-bridge

来源

claude mcp add codex-bridge -- uv --directory <project-root> run codex-mcp-bridge

验证注册

claude mcp get codex-bridge

次级代理技能

示例技能以两种形式提供：

技能 (examples/claude-skills/)--适当 .claude/skills/ 使用YAML frontmatter格式。支持 context: fork （隔离子代理）， allowed-tools 限制和渐进式披露。 推荐。
自定义命令 (examples/claude-commands/)--遗产 .claude/commands/ 格式。更简单，但缺乏分叉和工具限制等技能特征。

可用技能

完全子代理模式

技能	描述	沙盒
`codex-subagent`	综合编排器 --根据任务自动选择工具、沙盒和格式。支持多步委托。在分叉上下文中运行。	汽车

只读（分析，无文件更改）

技能	描述	沙盒
`codex-review`	代码审查——bug、安全性、性能	`read-only`
`codex-test`	为指定代码生成测试	`read-only`
`codex-explain`	解释代码逻辑和设计决策	`read-only`
`codex-ask`	向食品法典委员会提出的一般技术问题	`read-only`

支持写入（可以修改/创建文件）

技能	描述	沙盒
`codex-fix`	修复代码中的错误和问题	`workspace-write`
`codex-refactor`	重构代码以提高可读性和结构	`workspace-write`
`codex-generate`	根据描述生成新代码/文件	`workspace-write`

安装技能（推荐）

将技能目录复制到项目的 .claude/skills/:

# From cloned repo
cp -r <project-root>/examples/claude-skills/* .claude/skills/

# Or download a single skill from GitHub
mkdir -p .claude/skills/codex-subagent
curl -sL "https://raw.githubusercontent.com/dante01yoon/codex-mcp-bridge/main/examples/claude-skills/codex-subagent/SKILL.md" \
  -o ".claude/skills/codex-subagent/SKILL.md"

每个技能都是一个目录，其中包含 SKILL.md 文件：

.claude/skills/
├── codex-subagent/
│   └── SKILL.md          # Full orchestrator with fork context
├── codex-review/
│   └── SKILL.md          # Code review (read-only)
├── codex-fix/
│   └── SKILL.md          # Bug fix (workspace-write)
├── codex-generate/
│   └── SKILL.md          # Code generation (workspace-write)
├── codex-test/
│   └── SKILL.md          # Test generation (read-only)
├── codex-explain/
│   └── SKILL.md          # Code explanation (read-only)
├── codex-ask/
│   └── SKILL.md          # Question delegation (read-only)
└── codex-refactor/
    └── SKILL.md          # Refactoring (workspace-write)

SKILL.md格式

每种技能都使用YAML frontmatter作为元数据：

---
name: Codex Sub-Agent
description: Orchestrates task delegation to Codex via MCP bridge.
user-invocable: true
allowed-tools:
  - mcp__codex-bridge__consult_codex
  - mcp__codex-bridge__consult_codex_with_stdin
  - Read
  - Glob
  - Grep
context: fork
argument-hint: Describe the task to delegate to Codex
---

(Skill instructions here...)

关键前沿领域：

user-invocable: true --启用 /skill-name 斜杠命令
allowed-tools --限制技能可以使用的工具
context: fork --在孤立的子代理中运行技能（防止上下文污染）
argument-hint --用户键入斜线命令时显示的提示文本

安装自定义命令（旧版）

如果您更喜欢更简单的传统格式：

mkdir -p .claude/commands
cp <project-root>/examples/claude-commands/*.md .claude/commands/

基本用法

/codex-subagent Review src/config.py, fix any issues, then generate tests
/codex-review src/server.py
/codex-test src/runner.py
/codex-explain src/config.py
/codex-ask "How does MCP stdio transport work?"
/codex-fix src/runner.py "timeout is not applied when value is 0"
/codex-refactor src/config.py
/codex-generate "Create a health check endpoint that returns server status and uptime"

工作流示例

工作流程1：审查→ Fix

/codex-review src/runner.py
  → "3 issues found: [critical] timeout not handled when value is 0..."

/codex-fix src/runner.py "subprocess timeout not handled when value is 0"
  → Codex fixes the issue and applies changes

工作流程2：生成→ Test → 审查

/codex-generate "Add a validate_schema function that checks tool input against JSON Schema"
  → Codex generates src/codex_bridge_mcp/validator.py

/codex-test src/codex_bridge_mcp/validator.py
  → Codex generates tests/test_validator.py

/codex-review src/codex_bridge_mcp/validator.py
  → Codex reviews the generated code for improvements

工作流程3：解释→ 重构

/codex-explain src/codex_bridge_mcp/config.py
  → "Settings class loads config with precedence: tool > env > file > defaults..."

/codex-refactor src/codex_bridge_mcp/config.py
  → Codex refactors with understanding of the design intent preserved

工作流程4：通过子代理进行多步操作

/codex-subagent Analyze the error handling in runner.py, plan improvements, implement them, then verify
  → Step 1: Codex analyzes (read-only)
  → Step 2: Codex plans improvements (read-only)
  → Step 3: Codex applies changes (workspace-write)
  → Step 4: Codex verifies result (read-only)

通过CLAUDE.md进行汽车委派

要使Claude自动更喜欢Codex进行编码任务（无需显式斜线命令），请将提供的代码段添加到项目的 CLAUDE.md:

cat <project-root>/examples/CLAUDE.md.example >> CLAUDE.md

这使得Claude默认情况下将代码审查、测试生成和技术问题委托给Codex。看 examples/CLAUDE.md.example 对于完整配置。

默认启动器命令（推荐）

使用此启动器使Claude更喜欢 codex-bridge 自动用于编码任务，无需每次编写显式模板。

启动器脚本：

<project-root>/scripts/claude_codex_launcher.sh

运行：

<project-root>/scripts/claude_codex_launcher.sh

可选外壳别名：

alias claude-codex='<project-root>/scripts/claude_codex_launcher.sh'

然后使用：

claude-codex

审计启动器（验证是否实际使用了Codex桥接工具）：

<project-root>/scripts/claude_codex_audit.sh "Return exactly BRIDGE_OK"

可选审核别名：

alias claude-codex-audit='<project-root>/scripts/claude_codex_audit.sh'

审计启动器打印：

=== Claude Result === 最终答案文本
tools_used: 观察到所有MCP/工具调用
codex_bridge_used: yes/no 明确的Codex使用信号
codex_bridge_tools: 使用的确切codex桥接工具名称

为什么这个启动器很有用：

一致的行为：始终通过以下方式注入Codex优先指导 --append-system-prompt.
减少摩擦：您不需要为每个技术查询粘贴工具调用模板。
更少的权限拒绝：预设 --allowedTools 对于这两种桥接工具。
更安全的默认设置：指导包括 sandbox=read-only 和 timeout=180 作为基线。

自定义启动器行为：

export CLAUDE_CODEX_APPEND_PROMPT='Your custom codex-first instruction'
export CLAUDE_CODEX_ALLOWED_TOOLS='mcp__codex-bridge__consult_codex,mcp__codex-bridge__consult_codex_with_stdin'

韩语快速提示：

此启动器不删除Claude基本系统提示，而是添加Codex优先说明（append）。
因此，在保留默认行为的同时提高调用Codex工具的概率。

快速指南（英文）

安装并运行：

pip install codex-mcp-bridge
codex-mcp-bridge

或来源：

cd <project-root>
uv venv && source .venv/bin/activate
uv pip install -e .[dev]
uv run codex-mcp-bridge

在Claude CLI中注册MCP服务器：

# After pip install
claude mcp add codex-bridge -- codex-mcp-bridge

# Or from source
claude mcp add codex-bridge -- uv --directory <project-root> run codex-mcp-bridge

验证MCP连接：

claude mcp get codex-bridge

通过Claude验证端到端工具调用：

cd ~
claude -p --output-format text --permission-mode dontAsk --allowedTools mcp__codex-bridge__consult_codex -- "Call mcp__codex-bridge__consult_codex with arguments {\"query\":\"Return exactly BRIDGE_OK\",\"directory\":\"<project-root>\",\"format\":\"text\",\"timeout\":180,\"sandbox\":\"read-only\"}. Return only the tool result."

cd ~
claude -p --output-format text --permission-mode dontAsk --allowedTools mcp__codex-bridge__consult_codex_with_stdin -- "Call mcp__codex-bridge__consult_codex_with_stdin with arguments {\"stdin_content\":\"ping\",\"prompt\":\"Return exactly PONG\",\"directory\":\"<project-root>\",\"format\":\"text\",\"timeout\":180,\"sandbox\":\"read-only\"}. Return only the tool result."

故障排除：

tool denied due to permission restrictions：添加 --allowedTools mcp__codex-bridge__consult_codex 或者使用允许MCP工具的权限模式。
Codex timed out after 90 seconds：增加工具 timeout （例如。 180)并保持提示简短/明确。
codex CLI not found：安装Codex CLI并检查PATH。
Codex authentication appears unavailable：run codex login.

快速指南（KR）

安装和运行：

pip install codex-mcp-bridge
codex-mcp-bridge

或从源：

cd <project-root>
uv venv && source .venv/bin/activate
uv pip install -e .[dev]
uv run codex-mcp-bridge

在Claude CLI中注册MCP服务器：

# pip 설치 후
claude mcp add codex-bridge -- codex-mcp-bridge

# 또는 소스에서
claude mcp add codex-bridge -- uv --directory <project-root> run codex-mcp-bridge

检查MCP连接状态：

claude mcp get codex-bridge

通过Claude验证E2E工具调用：

cd ~
claude -p --output-format text --permission-mode dontAsk --allowedTools mcp__codex-bridge__consult_codex -- "Call mcp__codex-bridge__consult_codex with arguments {\"query\":\"Return exactly BRIDGE_OK\",\"directory\":\"<project-root>\",\"format\":\"text\",\"timeout\":180,\"sandbox\":\"read-only\"}. Return only the tool result."

cd ~
claude -p --output-format text --permission-mode dontAsk --allowedTools mcp__codex-bridge__consult_codex_with_stdin -- "Call mcp__codex-bridge__consult_codex_with_stdin with arguments {\"stdin_content\":\"ping\",\"prompt\":\"Return exactly PONG\",\"directory\":\"<project-root>\",\"format\":\"text\",\"timeout\":180,\"sandbox\":\"read-only\"}. Return only the tool result."

故障排除：

permission restrictions如果拒绝使用工具 --allowedTools在中指定MCP工具或以允许MCP模式运行。
Codex timed out after 90 seconds如果发生，请使用工具参数的 timeout增加并简短、清晰地创建请求。
codex CLI not found 错误是Codex CLI安装或PATH设置问题。
如果看到验证错误 codex login首先执行。

克劳德提示模板（EN/KR）

当您希望Claude首先通过MCP调用Codex时，请使用这些模板。

模板A：Codex第一个简单文本结果（EN）

Call mcp__codex-bridge__consult_codex with arguments {"query":"<YOUR_TASK>","directory":"<project-root>","format":"text","timeout":180,"sandbox":"read-only"}.
Return only the tool result.

例子：

Call mcp__codex-bridge__consult_codex with arguments {"query":"Return exactly BRIDGE_OK","directory":"<project-root>","format":"text","timeout":180,"sandbox":"read-only"}.
Return only the tool result.

模板A:Codex优先纯文本结果（KR）

mcp__codex-bridge__consult_codex 도구를 다음 인자로 호출해줘: {"query":"<작업 지시문>","directory":"<project-root>","format":"text","timeout":180,"sandbox":"read-only"}.
그리고 도구 결과만 그대로 반환해줘.

示例：

mcp__codex-bridge__consult_codex 도구를 다음 인자로 호출해줘: {"query":"정확히 BRIDGE_OK만 반환해","directory":"<project-root>","format":"text","timeout":180,"sandbox":"read-only"}.
그리고 도구 결과만 그대로 반환해줘.

模板B：结构化JSON结果（EN）

Call mcp__codex-bridge__consult_codex with arguments {"query":"<YOUR_TASK: return strict JSON>","directory":"<project-root>","format":"json","timeout":180,"sandbox":"read-only"}.
Return only the tool result without markdown fences.

模板B：结构化的JSON结果（KR）

mcp__codex-bridge__consult_codex 도구를 다음 인자로 호출해줘: {"query":"<JSON으로 응답해야 하는 작업>","directory":"<project-root>","format":"json","timeout":180,"sandbox":"read-only"}.
마크다운 코드블록 없이 도구 결과만 반환해줘.

模板C：通过stdin块进行大输入（EN）

Call mcp__codex-bridge__consult_codex_with_stdin with arguments {"stdin_content":"<LARGE_INPUT>","prompt":"<TASK_PROMPT>","directory":"<project-root>","format":"json","timeout":180,"sandbox":"read-only"}.
Return only the tool result.

模板C：传递大输入（KR）

mcp__codex-bridge__consult_codex_with_stdin 도구를 다음 인자로 호출해줘: {"stdin_content":"<큰 입력 데이터>","prompt":"<작업 지시문>","directory":"<project-root>","format":"json","timeout":180,"sandbox":"read-only"}.
그리고 도구 결과만 반환해줘.

CLI提示（使用时 claude -p):

如果MCP工具调用被拒绝，包括 --allowedTools mcp__codex-bridge__consult_codex （或 _with_stdin).
如果发生超时，请增加 timeout 在工具论证中（例如。 180 或 240).

它是如何工作的（Claude->Codex CLI桥）

sequenceDiagram
    participant U as "User"
    participant C as "Claude CLI"
    participant M as "MCP Server (codex-bridge)"
    participant X as "Codex CLI (codex exec)"
    participant F as "Output File (--output-last-message)"

    U->>C: "요청 입력"
    C->>M: "MCP tool call (consult_codex / consult_codex_with_stdin)"
    M->>M: "입력 검증 (Pydantic), 디렉터리/allowlist 검사"
    M->>X: "subprocess.run(codex exec - ... --sandbox ...)"
    X->>F: "최종 답변 기록"
    X-->>M: "exit code + stdout/stderr"
    M->>M: "output 파일 우선 읽기, 실패 시 stdout fallback"
    M->>M: "출력 길이 제한/오류 표준화"
    M-->>C: "단일 문자열 결과 반환"
    C-->>U: "최종 응답"

关键动作原理：

Claude只充当协调器，代码生成/分析运行通过MCP工具委托给Codex CLI。
桥接 codex exec以非交互式方式运行，为了防止stdout污染，协议通信将分离到stdout，调试/错误将分离到stderr。
Codex结果 --output-last-message 首先从文件读取，然后用读取失败时捕获的stdout替换文件。
基本安全性/可靠性 read-only 通过sandbox、目录allowlist、timeout、stderr剪切和output truncation保证。

关于临时输出文件(`--output-last-message`)

桥接根据每个请求在OS临时目录中创建一个一次性文件。
先从文件中读取Codex的最后一个答案。
处理后删除文件（output_file.unlink(missing_ok=True) 在 src/codex_bridge_mcp/runner.py).
也就是说，在正常流程中，文件不会保留。

为什么文件优先有用（真实示例）

在当前版本中，通常会在stdout中清晰地显示最终答案，但在操作环境中可能会发生以下变化：

CLI选项/模式更改更改stdout格式。：例如 --json 如果启用相同的事件输出模式，stdout可以是JSONL事件流。基于字符串解析的桥接很容易被破坏。
在今后的Codex CLI版本中，将状态消息添加到stdout。：如果横幅/进度/摘要混合到stdout中，“仅返回最终答案”协议可能会被破坏。
如果执行包装器/外壳钩子向stdout注入文本：根据内部策略，在使用包装器将prefix/suffix粘贴到标准输出的环境中，可能会污染输出。

文件优先策略固定了“最终答案来源”，与这些变化无关，从而提高了网桥的稳定性和解析可靠性。

配置

设置可以通过以下方式配置 JSON文件, 环境变量或两者皆有。

优先： 工具输入>环境变量>配置文件>默认值.

JSON配置文件

地方 codex-bridge.json （或 .codex-bridge.json)在您的项目根目录中或 ~/.config/codex-bridge/:

{
  "default_timeout": 180,
  "default_sandbox": "read-only",
  "default_model": null,
  "allowed_dirs": [],
  "max_output_chars": 12000
}

示例见 examples/codex-bridge.json.

环境变量

环境变量覆盖JSON配置值：

CODEX_DEFAULT_MODEL （可选）
CODEX_DEFAULT_TIMEOUT （默认值： 90)
CODEX_DEFAULT_SANDBOX （默认值： read-only)
CODEX_ALLOWED_DIRS （可选CSV绝对/相对目录）
CODEX_MAX_OUTPUT_CHARS （默认值： 12000)

环境变量也可以在MCP注册时设置：

claude mcp add -e CODEX_DEFAULT_TIMEOUT=180 codex-bridge -- codex-mcp-bridge

工具输入

`consult_codex`

query （必填）
directory （默认值 .)
format (text | json | code，默认来自服务器 json)
timeout （秒，可选）
model （可选）
sandbox (read-only | workspace-write | danger-full-access，可选）

`consult_codex_with_stdin`

stdin_content （必填）
prompt （必填）
加上以下所有选项 consult_codex

测试

cd <project-root>
uv run pytest

烟雾/回归脚本

cd <project-root>
./scripts/check_stdout_clean.sh

cd <project-root>
./scripts/it_smoke_codex_bridge.sh