Back to Details

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 doCodex 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:
  1. Do not proceed with the user's actual task through direct local work.
  2. First check whether 
    codex_run
    / 
    codex_review
    are already available.
  3. If the tools are missing, do only the setup workflow in this skill.
  4. During setup, do read-only detection first and stop for explicit user permission before any install, copy, config write, or 
    .gitignore
    edit.
  5. If the user does not approve setup changes, stop. Do not bypass MCP by reading files, editing code, or running the task directly yourself.
  6. Configure only the invoking agent by default. Do not modify other agent configs unless the user explicitly asks for multi-agent setup.
  7. 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.
当这个技能被调用时，请严格遵守以下规则：
  1. 不要直接在本地执行用户的实际任务。
  2. 首先检查
    codex_run
    / 
    codex_review
    是否已经可用。
  3. 如果缺少工具，仅执行本技能中的设置工作流。
  4. 设置过程中，首先执行只读检测，在进行任何安装、复制、配置写入或
    .gitignore
    编辑操作前，必须先获得用户明确授权。
  5. 如果用户不批准设置更改，请停止操作。不要通过读取文件、编辑代码或直接运行任务的方式绕过MCP。
  6. 默认仅配置发起调用的Agent。除非用户明确要求多Agent设置，否则不要修改其他Agent的配置。
  7. 设置完成后，告知用户重启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.
ToolModesThreadWhen to use
codex_run
explorenew or resumeRead/navigate codebase — never modifies files
codex_run
inspectnew or resumeTargeted read-only checks on files, config, or injected context
codex_run
buildnew or resumeWrite, edit, create, and run code
codex_run
debugnew or resumeReproduce → diagnose → fix → verify a bug
codex_run
testnew or resumeWrite or run tests, report pass/fail
codex_run
researchnew or resumeWeb search only — no file writes
codex_review
—isolatedIndependent code review — fresh thread, no self-bias
Pass 
thread_id
to 
codex_run
to resume an existing run thread. Omit to start fresh. 
codex_review
threads are namespace-isolated — never pass a review 
thread_id
to 
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:
  1. 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
  2. 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.
  3. 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.
  4. Add 
    memory/codex-threads.json
    to project 
    .gitignore
     — per project.
  5. Tell the user to restart — do not continue the original task in the same session unless MCP tools are already loaded.
  6. 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命令。
请按顺序执行以下步骤：
  1. 只读预检——不写入任何内容，收集必要信息：
    • 解析
      .agents/skills/codex-mcp/scripts/codex-mcp-server.mjs
      的绝对路径
    • 检查
      codex
      CLI是否已安装
    • 检查
      .codex/config.toml
      是否包含
      model
      配置项
    • 配置漂移检查： 读取活跃Agent配置中
      codex-mcp
      的
      args
      值，与上面解析得到的项目本地路径对比。如果两者不一致（例如仍注册了过期的全局路径），标记为需要修复——配置更新完成后才能视为设置完成。
    • 识别发起调用本技能的Agent
  2. 展示检查结果并等待授权——告知用户已有的内容、缺失的内容以及你打算执行的写入操作。在进行任何写入前停止操作，等待用户明确授权。
  3. 仅配置发起调用的Agent——添加指向已解析的项目本地脚本绝对路径的MCP入口。配置值使用解析后的绝对路径（不要使用
    ~
    或
    $HOME
    ）。不要将脚本复制到其他位置。
  4. 将
    memory/codex-threads.json
    添加到项目的
    .gitignore
    中    ——针对每个项目单独配置。
  5. 告知用户重启——不要在同一会话中继续执行原始任务，除非MCP工具已经加载完成。
  6. 重启后健康检查——在新会话中，开始实际工作前先执行一次轻量调用
    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
or 
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
:
  1. Do not retry blindly. The transport is dead, not slow.
  2. 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.
  3. 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.
  4. Tell the user exactly which step failed and what to check next.
General failure or timeout:
  1. Run a follow-up task to check status (ping "status" to see if it's still running)
  2. If it fails again, do not fall back to direct execution — that defeats context hygiene
  3. 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
：
  1. 不要盲目重试。传输链路已经失效，不是响应慢。
  2. 检查配置路径漂移：发起调用的Agent的配置（不只是
    ~/.codex/config.toml
    ）中注册的
    args
    路径是否与实际的项目本地脚本路径匹配？技能更新后最常见的原因就是使用了过期的全局路径。修复配置后重启。
  3. 如果路径正确，分别验证包装脚本和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输出。
  4. 明确告知用户哪一步失败了，以及下一步需要检查什么。
通用故障或超时：
  1. 执行后续任务检查状态（发送ping "status"查看是否仍在运行）
  2. 如果再次失败，不要回退到直接执行——这会破坏上下文 hygiene
  3. 告知用户失败的内容和原因，让用户决定下一步操作
永远不要静默切换到自行读取文件或运行命令的模式。用户选择MCP委托是有原因的，调用本技能意味着Agent必须严格遵守本工作流。

Troubleshooting

问题排查

ProblemFix
"Codex CLI not found"
npm install -g @openai/codex
Tools don't appear in agentCheck 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 errorsDefault 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 outLikely 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 errorsExpected in containers. The server uses 
danger-full-access
sandbox mode by default.
Thread state lost after restartExpected — server state is in-memory. Registry staleness check (Step 0) handles this automatically.
Wrong thread routedCheck 
memory/codex-threads.json
. Topics are human-readable — correct a wrong entry manually.
Cross-namespace thread_id errorYou 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
错误，避免静默挂起。