Codex 多轮桥 Miraclemarvel/dsh-codex-bridge

dsh-codex-bridge

把本机 Codex CLI 包成一个 MCP server。 任何 MCP 客户端 —— DeepSeek Harness、Claude Code、Cursor…… —— 装上它就能得到一个能多轮续聊的 Codex 子代理：派活、追问、拿第二意见。

零依赖、单文件、不需要额外的 API key（用的就是你 Codex CLI 已经登录的账号）。

English quickstart ↓

它做什么

两个工具：

| 工具 | 作用 |
| ask | 新开一个 Codex 会话，返回最终答复 + thread id |
| followup | 带 thread id 回去续同一会话，Codex 记得之前所有轮次 |

Codex 在自己的进程里跑，是个完整 agent —— 有自己的工具、自己的工作目录。让它审代码、查一个 bug、独立调研一件事，或者跟你的方案唱反调，都可以。

和官方 Codex subagent 的差别

OpenAI 和 DSH 都提供「把 Codex 当子代理」的通道，但它们都是 one-shot：每次调用是一个全新的、一次性的会话，只回最终答案。

| | 本桥 | 常见官方 one-shot 通道 |
| 多轮续聊 | ✅ followup 带 thread id 回到同一会话 | ❌ 每次全新会话 |
| 中间过程 | 正文 + token 用量 + thread id | 一般只有最终答案 |
| 沙箱策略 | 可逐次指定 read-only / workspace-write / danger-full-access | 由 Codex 原生配置决定 |
| 依赖 | 只要 codex CLI | 需要对应平台的 SDK / bundle |

一句话：只需要一问一答，用官方通道就行；需要跟 Codex 来回迭代，用它。

安装

前置

1. Node.js ≥ 18
2. Codex CLI 已安装并已登录（codex login）
3. 确认能找到 codex：

codex --version

找不到就设 CODEX_BIN 指向它（见「环境变量」）。

拿到代码

git clone https://github.com/Miraclemarvel/dsh-codex-bridge.git
cd dsh-codex-bridge
node test/smoke.mjs # 不需要 Codex、不需要联网，先确认协议层正常

看到 SMOKE PASSED 就说明 server 本身没问题。

注意：在受限沙箱里跑这条会 EPERM（子进程管道被拦），普通 shell 里没问题。

配置

通用 MCP 客户端

大多数客户端（Claude Code、Cursor、Windsurf…）读同一套 JSON，见 examples/mcp.json：

{
"mcpServers": {
"codex": {
"command": "node",
"args": ["/absolute/path/to/dsh-codex-bridge/server.mjs"],
"env": {
"CODEX_BRIDGE_CWD": "/absolute/path/to/your/project",
"CODEX_BRIDGE_SANDBOX": "read-only"
}
}
}
}

Claude Code 也可以直接命令行加：

claude mcp add codex -- node /absolute/path/to/dsh-codex-bridge/server.mjs

DeepSeek Harness

用 DSH 自带的 dsh-mcp-client 挂载。往 <DSH_HOME>/profiles/<profile>/cordis.patch.yml 末尾追加（完整示例见 examples/dsh-profile.yml）：

- insert:
- id: mcp-codex-bridge
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: codex
transport: stdio
command: node
args:
- /absolute/path/to/dsh-codex-bridge/server.mjs
cwd: /absolute/path/to/your/project
toolCallTimeoutMs: 1800000
env:
CODEX_BRIDGE_CWD: /absolute/path/to/your/project
CODEX_BRIDGE_SANDBOX: read-only

工具会以 mcp__codex__ask / mcp__codex__followup 出现在模型侧。

两个必须知道的坑（都是实测踩出来的）

① 新增条目一定要包在 - insert: 里。 cordis.patch.yml 是「id-targeted config overrides, disables, and insert lists」。裸的 - id: X 是按 id 覆盖已有条目；id 在 profile 里不存在就静默丢弃 —— 不报错、不警告，文件看起来完全正常。

② 改已有条目能热重载，新增条目必须重启 Host。 宿主会立刻重写合成后的 cordis.yml，但不会 spawn 新插件的子进程。别误判成配置写错了。

另外 dsh-mcp-client 的 toolCallTimeoutMs 默认只有 60 秒，长任务会被它先掐断，务必调大。

工具参考

ask(prompt, cwd?, sandbox?, model?, timeoutMs?)

新开一个 Codex 会话。

- prompt（必填）—— 指令。Codex 看不到你这边客户端的对话，需要什么上下文都得写进来。
- cwd —— Codex 的工作目录，默认是 server 进程的 cwd。
- sandbox —— read-only（默认）| workspace-write | danger-full-access。
- model —— 覆盖模型，比如 gpt-6.1-sol。省略则用 Codex 默认。
- timeoutMs —— 硬超时，到点杀掉整棵进程树并返回部分输出。

返回正文 + thread id + token 用量。

followup(threadId, prompt, cwd?, model?, timeoutMs?)

续同一会话。threadId 来自上一次 ask 或 followup 的返回。

注意：followup 不能改 sandbox。 codex exec resume 子命令没有 -s，沙箱策略沿用原会话。

环境变量

| 变量 | 默认 | 说明 |
| CODEX_BIN | 自动探测 | codex 可执行文件路径。不设则依次找 PATH → ~/.codex/bin/codex.exe、~/.codex/.sandbox-bin/codex.exe（Windows）/ ~/.local/bin/codex、/usr/local/bin/codex、/opt/homebrew/bin/codex（POSIX） |
| CODEX_BRIDGE_CWD | 进程 cwd | 默认工作目录 |
| CODEX_BRIDGE_SANDBOX | read-only | 默认沙箱策略 |
| CODEX_BRIDGE_TIMEOUT_MS | 900000 | 默认超时（15 分钟） |
| CODEX_BRIDGE_MAX_TIMEOUT_MS | 3600000 | 调用方可传的超时上限（1 小时） |

设计要点

改代码前值得先知道这几条 —— 每一条都是踩坑之后定下来的。

零依赖，手写 JSON-RPC。 不引入 @modelcontextprotocol/sdk：clone 下来直接 node server.mjs 就能跑，没有 npm install、没有版本冲突。

全程不碰管道。 stdin 用临时文件 fd，stdout/stderr 直接重定向到临时文件 fd，spawn(bin, args, { stdio: [inFd, outFd, errFd] })，父进程立刻放掉句柄，等 close 事件再读文件。原因：受限沙箱（比如 DSH 自己的文件沙箱）下 piped stdio 会 EPERM，而文件重定向两边都能跑。顺带好处是完全绕开 argv 长度上限，prompt 想多长都行。

initialize 原样回显客户端请求的 protocolVersion。 客户端只会请求自己支持的版本，回显就一定落在它的支持集内 —— 省掉一份会过期的协议版本白名单。

生命周期不能图省事。 写成 process.stdin.on('end', () => process.exit(0)) 会把还在飞的 Codex 调用直接掐死（症状：只回了 initialize，tools/call 毫无输出）。正确做法是 pending 计数 + stdinEnded 标志，两者都满足才退出。

followup 的 threadId 必须显式校验。 spawn 会把 undefined 参数悄悄字符串化成 "undefined"：Codex 找不到那个会话，就静默新建一个 —— 不报错、退出码 0，只是「完全没有上文」。所以 buildArgs 里宁可 throw。

Windows 的 .cmd 要转手。 npm 全局安装只留 codex.cmd，而 spawn 不能直接执行 .cmd/.bat，必须交给 cmd.exe /c。我们的 argv 里没有用户自由文本（prompt 走 stdin），只有 cwd / model 可能含空格，逐个加引号即可。

噪音降级。 Code Mode 缺失、WebSocket 回落 HTTPS、Reconnecting... N/5 这些每次调用都出现，但不是真错误，归到 notes 而不是 error。

故障排查

| 现象 | 原因 / 处理 |
| 客户端里看不到工具 | server 起不来。终端直接跑 node server.mjs，看 stderr 的 [codex-bridge] ready — codex=... 那行 |
| Could not locate the codex executable | 设 CODEX_BIN 指向完整的可执行文件路径 |
| 工具调用老是超时 | 客户端侧超时可能比 Codex 实际耗时短。DSH 的 dsh-mcp-client 默认只有 60 秒，必须调大 toolCallTimeoutMs |
| 改了配置没反应（DSH） | 新增条目必须重启 Host，且必须包在 - insert: 里（见上文） |
| followup 说不知道上文 | 你传的 threadId 不是这个会话的。ask 的返回里会明确写出该用哪个 id |

已知限制

- Codex 看不到调用方的对话。 它是独立进程，不是旁听者。上下文得由调用方写进 prompt。
- followup 不能改 sandbox。 见上文。
- 首次调用可能很慢。 如果 Codex 先试 WebSocket 传输再超时回落 HTTPS，每次会白等一段时间（会看到 Reconnecting... N/5、Falling back from WebSockets to HTTPS transport）。这些已归为 notes，不影响结果，但确实拖时间。
- 只暴露 tools。 MCP 的 Resources 和 Prompts 返回空列表。
- 无进度流。 一次调用要么等到最终答案，要么等到超时。

English quickstart

dsh-codex-bridge 把本地 Codex CLI 包装成 MCP 服务器，让任何 MCP 客户端都能拿到一个 Codex 子代理，而且能真正反复迭代——不是只能调用一次。

git clone https://github.com/Miraclemarvel/dsh-codex-bridge.git
cd dsh-codex-bridge
node test/smoke.mjs # protocol-level check; needs no Codex, no network

把它加进你的客户端（见 examples/mcp.json）：

{
"mcpServers": {
"codex": {
"command": "node",
"args": ["/absolute/path/to/dsh-codex-bridge/server.mjs"]
}
}
}

你会得到两个工具：

- ask(prompt, cwd?, sandbox?, model?, timeoutMs?) —— 新建一个 Codex 会话。默认 read-only，所以 Codex 只能查看，不能修改。返回答案和一个 thread id。Codex 看不到你的对话，所以需要的上下文都写进 prompt。
- followup(threadId, prompt, ...) —— 继续同一个会话。Codex 记得之前每一轮。沙箱策略会继承（codex exec resume 没有 -s）。

需要 Node ≥ 18，以及已登录的 Codex CLI。如果 codex 不在你的 PATH 里，就设置 CODEX_BIN。

MIT 协议。

License

MIT