codex-mcp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Your role when these tools are available

这些工具可用时你的角色

If the codex MCP tools are available, delegate ALL work through them. Do not read files, search code, or run commands yourself. Pick the right mode for the task:

You do	Codex does (via MCP tools)
Plan what to do next	`codex_run(mode=explore)` — read and navigate codebase
Handle a targeted read-only follow-up	`codex_run(mode=inspect)` — inspect files, config, or injected context without writing
Craft the prompt for each turn	`codex_run(mode=build)` — write, edit, and execute code
Route to the right thread	`codex_run(mode=debug)` — reproduce → diagnose → fix → verify
Report results to user	`codex_run(mode=test)` — write and run tests
Decide when to resume vs start fresh	`codex_review` — independent code review

Incremental prompting: don't dump everything into one call. Send focused turns, use each response to craft the next prompt. Pass

thread_id

to continue a previous run with full context.

Review pattern: after

codex_run(mode=build)

changes code, use

codex_review

in a fresh thread with the original requirement — Codex evaluates independently without self-review bias.

If the tools are NOT available, run the setup below.

如果codex MCP工具可用，所有工作都通过它们来完成。不要自行读取文件、搜索代码或运行命令。为任务选择合适的模式：

你需要做的事	Codex（通过MCP工具）完成的工作
规划下一步行动	`codex_run(mode=explore)` — 读取和导航代码库
处理定向只读后续查询	`codex_run(mode=inspect)` — 无需写入即可检查文件、配置或注入的上下文
为每一轮交互设计提示词	`codex_run(mode=build)` — 编写、编辑和执行代码
路由到正确的线程	`codex_run(mode=debug)` — 复现→诊断→修复→验证
向用户反馈结果	`codex_run(mode=test)` — 编写和运行测试
决定是继续之前的任务还是重新开始	`codex_review` — 独立代码审查

增量提示原则： 不要把所有内容都塞进一次调用里。发送聚焦的单轮请求，根据每轮返回的结果设计下一个提示词。传入

thread_id

即可在保留完整上下文的情况下继续之前的运行任务。

审查模式： 当

codex_run(mode=build)

修改代码后，在新线程中使用

codex_review

并传入原始需求——Codex会进行独立评估，不会出现自我审查的偏差。

如果工具不可用，请执行以下设置流程。

Non-Negotiable Workflow

不可变通的工作流

When this skill is invoked, follow this contract strictly:

Do not proceed with the user's actual task through direct local work.
First check whether
```
codex_run
```
/
```
codex_review
```
are already available.
If the tools are missing, do only the setup workflow in this skill.
During setup, do read-only detection first and stop for explicit user permission before any install, copy, config write, or
```
.gitignore
```
edit.
If the user does not approve setup changes, stop. Do not bypass MCP by reading files, editing code, or running the task directly yourself.
Configure only the invoking agent by default. Do not modify other agent configs unless the user explicitly asks for multi-agent setup.
After setup, tell the user to restart the agent session and wait for the restarted session to use the MCP tools. Do not continue the original task in the same non-MCP turn.

当这个技能被调用时，请严格遵守以下规则：

不要直接在本地执行用户的实际任务。
首先检查
```
codex_run
```
/
```
codex_review
```
是否已经可用。
如果缺少工具，仅执行本技能中的设置工作流。
设置过程中，首先执行只读检测，在进行任何安装、复制、配置写入或
```
.gitignore
```
编辑操作前，必须先获得用户明确授权。
如果用户不批准设置更改，请停止操作。不要通过读取文件、编辑代码或直接运行任务的方式绕过MCP。
默认仅配置发起调用的Agent。除非用户明确要求多Agent设置，否则不要修改其他Agent的配置。
设置完成后，告知用户重启Agent会话，等待会话重启后再使用MCP工具。不要在当前非MCP的会话轮次中继续执行原始任务。

What this does

功能说明

Two MCP tools wrapping Codex app-server. Each call bakes in a role prefix — instructions that guide Codex's behavior for that task type, so quality stays consistent even after many turns.

Tool	Modes	Thread	When to use
`codex_run`	explore	new or resume	Read/navigate codebase — never modifies files
`codex_run`	inspect	new or resume	Targeted read-only checks on files, config, or injected context
`codex_run`	build	new or resume	Write, edit, create, and run code
`codex_run`	debug	new or resume	Reproduce → diagnose → fix → verify a bug
`codex_run`	test	new or resume	Write or run tests, report pass/fail
`codex_run`	research	new or resume	Web search only — no file writes
`codex_review`	—	isolated	Independent code review — fresh thread, no self-bias

Pass

thread_id

codex_run

to resume an existing run thread. Omit to start fresh.

codex_review

threads are namespace-isolated — never pass a review

thread_id

codex_run

or vice versa (the server enforces this with a hard error).

Use

explore

for broad discovery and mapping. Use

inspect

for narrow read-only checks, especially when the turn is driven by injected context or a specific config/file target.

Zero external dependencies. Manages app-server lifecycle, thread state, model discovery, approval handling, and timeout transparently.

两个MCP工具封装了Codex app-server。每次调用都内置了角色前缀——针对不同任务类型指导Codex行为的指令，因此即使经过多轮交互，输出质量也能保持稳定。

工具	模式	线程	使用场景
`codex_run`	explore	新建或续接	读取/导航代码库——不会修改任何文件
`codex_run`	inspect	新建或续接	对文件、配置或注入上下文进行定向只读检查
`codex_run`	build	新建或续接	编写、编辑、创建和运行代码
`codex_run`	debug	新建或续接	复现→诊断→修复→验证Bug
`codex_run`	test	新建或续接	编写或运行测试，报告通过/失败结果
`codex_run`	research	新建或续接	仅网页搜索——不会写入文件
`codex_review`	—	隔离	独立代码审查——全新线程，无自我偏差

向

codex_run

传入

thread_id

即可续接已有的运行线程，不传则新建线程。

codex_review

线程是命名空间隔离的——永远不要将审查的

thread_id

传给

codex_run

，反之亦然（服务器会强制校验，违规会直接返回错误）。

explore

模式用于广泛的探索和结构梳理。

inspect

模式用于窄范围的只读检查，特别是当查询由注入上下文或特定配置/文件目标驱动时。

无外部依赖。会透明地管理app-server生命周期、线程状态、模型发现、授权处理和超时逻辑。

Setup (run this automatically when skill triggers)

设置流程（技能触发时自动运行）

npx skills add

already places the server script at a stable project path:

.agents/skills/codex-mcp/scripts/codex-mcp-server.mjs

(symlinked into

.claude/skills/

). No global copy is needed. Setup just wires the MCP entry.

See

references/setup.md

for per-agent config snippets and Windows commands.

Follow these steps in order:

Read-only preflight — gather facts without writing anything:
- Resolve the absolute path to
```
.agents/skills/codex-mcp/scripts/codex-mcp-server.mjs
```
- Check
```
codex
```
  CLI is installed
- Check
```
.codex/config.toml
```
  has a
```
model
```
  line
- Config-drift check: read the
```
args
```
  value for
```
codex-mcp
```
  in the active agent config and compare it to the resolved project-local path above. If they differ (e.g. a stale global path is still registered), flag this as a required fix — the config must be updated before setup is considered done.
- Identify which agent is invoking this skill
Present findings and wait — report what exists, what's missing, what you intend to write. Stop and wait for explicit user approval before any writes.
Configure the invoking agent only — add the MCP entry pointing to the resolved absolute path of the project-local script. Use resolved absolute paths in config values (never
```
~
```
or
```
$HOME
```
). Do not copy the script elsewhere.
Add
memory/codex-threads.json
to project
.gitignore
— per project.
Tell the user to restart — do not continue the original task in the same session unless MCP tools are already loaded.
Post-restart health probe — in the new session, make one lightweight
```
codex_run(mode=inspect, prompt="echo ok")
```
call before starting real work. If this returns
```
Transport closed
```
or fails, setup is not done — go to the "On failure" section. Do not treat tool visibility alone as proof of a healthy transport.

npx skills add

已经将服务器脚本放置到固定的项目路径：

.agents/skills/codex-mcp/scripts/codex-mcp-server.mjs

（软链到

.claude/skills/

目录）。无需全局复制。设置仅需完成MCP入口的配置。

查看

references/setup.md

获取各Agent的配置片段和Windows命令。

请按顺序执行以下步骤：

只读预检——不写入任何内容，收集必要信息：
- 解析
```
.agents/skills/codex-mcp/scripts/codex-mcp-server.mjs
```
  的绝对路径
- 检查
```
codex
```
  CLI是否已安装
- 检查
```
.codex/config.toml
```
  是否包含
```
model
```
  配置项
- 配置漂移检查： 读取活跃Agent配置中
```
codex-mcp
```
  的
```
args
```
  值，与上面解析得到的项目本地路径对比。如果两者不一致（例如仍注册了过期的全局路径），标记为需要修复——配置更新完成后才能视为设置完成。
- 识别发起调用本技能的Agent
展示检查结果并等待授权——告知用户已有的内容、缺失的内容以及你打算执行的写入操作。在进行任何写入前停止操作，等待用户明确授权。
仅配置发起调用的Agent——添加指向已解析的项目本地脚本绝对路径的MCP入口。配置值使用解析后的绝对路径（不要使用
```
~
```
或
```
$HOME
```
）。不要将脚本复制到其他位置。
将
memory/codex-threads.json
添加到项目的
.gitignore
中——针对每个项目单独配置。
告知用户重启——不要在同一会话中继续执行原始任务，除非MCP工具已经加载完成。
重启后健康检查——在新会话中，开始实际工作前先执行一次轻量调用
```
codex_run(mode=inspect, prompt="echo ok")
```
。如果返回
```
Transport closed
```
或调用失败，说明设置未完成——请前往「故障处理」章节。不要仅以工具可见作为传输链路正常的证明。

Thread registry

线程注册表

The server tracks threads in

memory/codex-threads.json

— mapping thread IDs to topics so the agent routes to the right thread by topic, not by recency. Threads persist across server restarts via

thread/resume

See

references/thread-registry.md

for the full schema, maintenance rules (when to add/update/close rows), and the routing decision tree (how to pick the right

thread_id

before each call).

服务器在

memory/codex-threads.json

中跟踪线程信息——将线程ID映射到主题，这样Agent可以按主题而不是按最近使用时间路由到正确的线程。线程可以通过

thread/resume

在服务器重启后继续使用。

查看

references/thread-registry.md

获取完整的schema、维护规则（何时添加/更新/关闭条目）和路由决策树（每次调用前如何选择正确的

thread_id

）。

Prompting Codex well

向Codex发送高效提示词

Every prompt should contain: what to do + where (file paths) + expected outcome + constraints. Pick the right mode — its baked-in role prefix handles the rest.

Scoping prompts: One focused task per call, pass

thread_id

to continue. Codex accumulates context across calls — the second call already knows what the first found. This gives better results than broad prompts, and prevents inactivity timeouts on very large scopes (

explore

on deep directory trees is most at risk). Use the routing decision tree in

references/thread-registry.md

to pick the right thread.

codex_run(explore, prompt="Map skills/project-memory/")          → T1
codex_run(explore, thread_id=T1, prompt="Now map skills/agent-handoff/")

Each mode's role prefix instructs Codex to use subagents for parallelism (file reading, multi-file edits, test execution, etc.). This produces a denser event stream that reduces timeout risk, but focused prompts still give higher quality results than broad ones.

If a single call is legitimately large, pass

timeout=120

timeout=180

(per-call override, not global).

codex_run(explore): "List all exported functions in src/auth/ and their error handling patterns."
codex_run(inspect): "Use the injected `pwd` output and report the exact project root. Do not modify any files."
codex_run(build):   "Add null checks to all auth functions that access user.email."
codex_run(build, thread_id=T1): "Also add the same null checks in src/payment/."
codex_run(test):    "Write tests for the null-check cases in src/auth/. Cover: null, undefined, empty string."
codex_review:       "Read src/auth/. Requirement: every user.email access has a null check. List any gaps."
codex_run(debug):   "Login fails with TypeError on line 42 of src/auth.ts when email is null. Fix it."

每个提示词都应该包含：要做什么 + 在哪里（文件路径） + 预期结果 + 约束条件。选择正确的模式——其内置的角色前缀会处理其余逻辑。

提示词范围原则： 每次调用仅处理一个聚焦的任务，续接任务时传入

thread_id

。Codex会在多次调用中累积上下文——第二次调用已经知道第一次调用的结果。这种方式比宽泛的提示词效果更好，还能避免超大范围任务导致的非活动超时（深度目录树的

explore

操作最容易触发超时）。使用

references/thread-registry.md

中的路由决策树选择正确的线程。

codex_run(explore, prompt="Map skills/project-memory/")          → T1
codex_run(explore, thread_id=T1, prompt="Now map skills/agent-handoff/")

每种模式的角色前缀都会指导Codex使用子Agent实现并行处理（文件读取、多文件编辑、测试执行等）。这会生成更密集的事件流，降低超时风险，但聚焦的提示词仍然比宽泛的提示词输出质量更高。

如果单次调用的任务确实很大，可以传入

timeout=120

或

timeout=180

（单次调用超时覆盖，不是全局配置）。

codex_run(explore): "List all exported functions in src/auth/ and their error handling patterns."
codex_run(inspect): "Use the injected `pwd` output and report the exact project root. Do not modify any files."
codex_run(build):   "Add null checks to all auth functions that access user.email."
codex_run(build, thread_id=T1): "Also add the same null checks in src/payment/."
codex_run(test):    "Write tests for the null-check cases in src/auth/. Cover: null, undefined, empty string."
codex_review:       "Read src/auth/. Requirement: every user.email access has a null check. List any gaps."
codex_run(debug):   "Login fails with TypeError on line 42 of src/auth.ts when email is null. Fix it."

On failure

故障处理

Tools visible but transport immediately closed — if the MCP tools appear in the agent but the very first

codex_run

call (or the follow-up status ping) returns

Transport closed

Do not retry blindly. The transport is dead, not slow.
Check for config-path drift: does the registered
```
args
```
path in the invoking agent's config (not just
```
~/.codex/config.toml
```
) match the actual project-local script path? A stale global path is the most common cause after a skills update. Fix the config and restart.
If the path is correct, verify the wrapper and app-server independently:
- Windows: see
```
references/troubleshooting-windows.md
```
  for PowerShell commands and diagnosis sequence.
- Unix / macOS: run the wrapper directly (
```
node "$(realpath .agents/skills/codex-mcp/scripts/codex-mcp-server.mjs)"
```
  ); then run
```
codex app-server
```
  standalone. If both start cleanly, inspect stderr from the wrapper's
```
spawn()
```
  call.
Tell the user exactly which step failed and what to check next.

General failure or timeout:

Run a follow-up task to check status (ping "status" to see if it's still running)
If it fails again, do not fall back to direct execution — that defeats context hygiene
Tell the user what failed and why, so they can decide next steps

Never silently switch to reading files or running commands yourself. The user chose MCP delegation for a reason, and invoking this skill means the agent must stay inside this workflow.

工具可见但传输链路立即关闭——如果Agent中显示MCP工具可用，但第一次

codex_run

调用（或后续的状态 ping）返回

Transport closed

：

不要盲目重试。传输链路已经失效，不是响应慢。
检查配置路径漂移：发起调用的Agent的配置（不只是
```
~/.codex/config.toml
```
）中注册的
```
args
```
路径是否与实际的项目本地脚本路径匹配？技能更新后最常见的原因就是使用了过期的全局路径。修复配置后重启。
如果路径正确，分别验证包装脚本和app-server：
- Windows：查看
```
references/troubleshooting-windows.md
```
  获取PowerShell命令和诊断流程。
- Unix / macOS：直接运行包装脚本（
```
node "$(realpath .agents/skills/codex-mcp/scripts/codex-mcp-server.mjs)"
```
  ）；然后单独运行
```
codex app-server
```
  。如果两者都能正常启动，检查包装脚本
```
spawn()
```
  调用的stderr输出。
明确告知用户哪一步失败了，以及下一步需要检查什么。

通用故障或超时：

执行后续任务检查状态（发送ping "status"查看是否仍在运行）
如果再次失败，不要回退到直接执行——这会破坏上下文 hygiene
告知用户失败的内容和原因，让用户决定下一步操作

永远不要静默切换到自行读取文件或运行命令的模式。用户选择MCP委托是有原因的，调用本技能意味着Agent必须严格遵守本工作流。

Troubleshooting

问题排查

Problem	Fix
"Codex CLI not found"	`npm install -g @openai/codex`
Tools don't appear in agent	Check config path is absolute. Restart agent session.
Wrong project used for `memory/`	Always pass `project_dir` explicitly in tool calls. Do not rely on `process.cwd()` .
Timeout errors	Default is 60s inactivity. Pass `timeout=120` or `180` for large tasks. Break work into resumable `thread_id` steps — see prompting section.
"app-server exited"	Check `.codex/config.toml` has a valid model. If needed, run `codex` once interactively to verify the CLI itself works, but do not assume interactive setup is the only valid fix.
`Transport closed` (any platform)	Check config-path drift first (most common cause). Then see `references/troubleshooting-windows.md` (Windows) or run wrapper + app-server standalone (Unix).
Turn hangs then times out	Likely an unhandled approval request. Update wrapper to latest version. Check stderr for unhandled method names.
"Codex completed with no output"	Check the `errors` field in the response — rate limits and model errors are now surfaced there. If no errors, the model genuinely returned nothing.
bwrap/sandbox errors	Expected in containers. The server uses `danger-full-access` sandbox mode by default.
Thread state lost after restart	Expected — server state is in-memory. Registry staleness check (Step 0) handles this automatically.
Wrong thread routed	Check `memory/codex-threads.json` . Topics are human-readable — correct a wrong entry manually.
Cross-namespace thread_id error	You passed a review thread_id to codex_run or vice versa. Check registry status column.

问题	修复方案
"Codex CLI not found"	`npm install -g @openai/codex`
工具未在Agent中显示	检查配置路径为绝对路径。重启Agent会话。
`memory/` 使用了错误的项目	总是在工具调用中明确传入 `project_dir` 。不要依赖 `process.cwd()` 。
超时错误	默认非活动超时为60秒。大型任务可以传入 `timeout=120` 或 `180` 。将工作拆分为可续接的 `thread_id` 步骤——参考提示词章节。
"app-server exited"	检查 `.codex/config.toml` 有有效的模型配置。如果需要，交互运行一次 `codex` 验证CLI本身可用，但不要假设交互设置是唯一的有效修复方案。
`Transport closed` （任意平台）	首先检查配置路径漂移（最常见原因）。然后参考 `references/troubleshooting-windows.md` （Windows）或单独运行包装脚本+app-server（Unix）。
轮次挂起然后超时	很可能是未处理的授权请求。将包装脚本更新到最新版本。检查stderr中未处理的方法名。
"Codex completed with no output"	检查响应中的 `errors` 字段——限流和模型错误现在会在该字段中暴露。如果没有错误，说明模型确实没有返回内容。
bwrap/sandbox错误	容器中属于预期行为。服务器默认使用 `danger-full-access` 沙箱模式。
重启后线程状态丢失	属于预期行为——服务器状态存储在内存中。注册表过期检查（步骤0）会自动处理这个问题。
路由到错误的线程	检查 `memory/codex-threads.json` 。主题是人类可读的——可以手动修正错误条目。
跨命名空间thread_id错误	你将审查线程的thread_id传给了codex_run，反之亦然。检查注册表的状态列。

Architecture

架构

Agent (Claude Code / Gemini CLI / Cursor / Codex CLI / Antigravity / Augment)
  └─ MCP protocol (stdio)
      └─ codex-mcp-server.mjs  (.agents/skills/codex-mcp/scripts/)
          ├─ runServers map    (per projectDir, codex_run threads)
          ├─ reviewServers map (per projectDir, codex_review threads, isolated)
          └─ Codex app-server (JSON-RPC over stdio)
              └─ GPT model (reads, writes, executes)

<project-root>/memory/codex-threads.json
  └─ thread registry (topic-based routing, managed by the orchestrating agent)
     created automatically on first tool call, isolated per project

The MCP server spawns one app-server process per namespace per project directory and keeps it alive across tool calls. Thread state is maintained in memory — registry in

memory/codex-threads.json

maps thread IDs to topics so routing survives context growth. On shutdown (SIGINT/SIGTERM), all app-server processes are cleaned up.

The wrapper handles the core protocol surface: turn lifecycle, text output, diffs, file writes, command/file/permissions approvals, and token usage. Some newer methods (

thread/fork

turn/steer

, tool forwarding via

item/tool/call

) are not yet supported — unhandled server requests receive a JSON-RPC

-32601

error to prevent silent hangs.

Agent (Claude Code / Gemini CLI / Cursor / Codex CLI / Antigravity / Augment)
  └─ MCP protocol (stdio)
      └─ codex-mcp-server.mjs  (.agents/skills/codex-mcp/scripts/)
          ├─ runServers map    (per projectDir, codex_run threads)
          ├─ reviewServers map (per projectDir, codex_review threads, isolated)
          └─ Codex app-server (JSON-RPC over stdio)
              └─ GPT model (reads, writes, executes)

<project-root>/memory/codex-threads.json
  └─ thread registry (topic-based routing, managed by the orchestrating agent)
     created automatically on first tool call, isolated per project

MCP服务器为每个项目目录的每个命名空间生成一个app-server进程，并在多次工具调用中保持进程存活。线程状态存储在内存中——

memory/codex-threads.json

中的注册表将线程ID映射到主题，因此路由不会受上下文增长影响。收到关闭信号（SIGINT/SIGTERM）时，所有app-server进程都会被清理。

包装脚本处理核心协议逻辑：轮次生命周期、文本输出、diff、文件写入、命令/文件/权限授权，以及token用量统计。部分较新的方法（

thread/fork

、

turn/steer

、通过

item/tool/call

进行工具转发）暂不支持——未处理的服务器请求会返回JSON-RPC

-32601

错误，避免静默挂起。