Hanako ↔ Codex Local Bridge

一个本地 MCP stdio 桥接器，让 Hanako 与 Codex 可以互相委派文字任务，并把最终结果返回给调用方。

功能

• Hanako 调用 codex_task：启动一次性的本机 Codex 子任务。

• Hanako 调用 codex_new_thread：通过 Codex app-server 创建一个持久的新 Codex 对话，并发送首轮任务。

• Codex 调用 hanako_task：创建一次本机 Hanako detached session。

• 任一侧调用 bridge_status：实际探测 Hanako 本地端口和 Codex 可执行文件，不返回本机路径或令牌。

• 不复制完整对话历史；每次委派只发送调用方提供的任务文字。

• Hanako 全局 WebSocket 事件按 detached session 身份过滤；不会把其他会话的文字、确认或结束事件串进当前任务。

• MCP 支持标准初始化、取消通知和输入流关闭清理；Codex 输出支持跨 chunk 的 JSONL。

• 委派有并发上限、重复任务抑制和下游 Codex 防重入标记，避免无限循环委派。

• 为覆盖多个 MCP 客户端进程，Hanako detached 委派会持有一个本机保护租约；租约期间其他桥接进程的委派会被拒绝，避免 Hanako→桥接器→Hanako 的跨进程循环。

Related MCP server: subway-mcp-server

重要安全说明

本仓库当前配置的是完全访问模式：

• Hanako detached session 使用 operate 权限。

• Codex 子任务使用 --dangerously-bypass-approvals-and-sandbox。

• 委派任务可以读写本机文件、执行命令、安装软件并访问网络。

• codex_new_thread 创建的 Codex 对话使用持久 thread；调用完成后可以在 Codex 桌面端的任务列表中继续查看。

• 桥接器会读取 Hanako 本地服务令牌，但只保存在内存中，不写入日志、不返回给模型。

• bridge_status 只返回 reachable/unconfigured、available/unavailable 等状态，不暴露 executable、工作目录、端口或配置文件路径。

• 默认最多同时运行 4 个委派；传给 Codex 的子进程会带有防重入标记，不能再通过本桥接器发起下一轮委派。

只把它接入你信任的 Hanako/Codex 实例，并只委派可信任务。不要把本服务暴露到局域网或公网，也不要把 server-info.json、访问令牌或个人配置提交到仓库。

系统要求

• Windows、macOS 或 Linux

• Node.js 22 或更新版本

• 已安装并可运行的 Codex CLI

• Codex CLI 需要支持实验性的 app-server（codex_new_thread 使用该接口创建持久对话）

• 正在运行的 Hanako，并且本机可读取 Hanako 的 server-info.json

Node.js 22+ 是为了使用内置 WebSocket；桥接器本身不需要 npm 依赖。

安装

把 bridge.mjs 下载到本机固定目录，例如：

C:\Tools\hanako-codex-bridge\bridge.mjs

不要把个人 Codex 配置、Hanako server-info.json 或访问令牌复制进这个目录。

给其他人使用

这个 GitHub 仓库可以公开分享，但它不是一个在线中转服务。别人克隆后需要在自己的电脑上完成本地安装和配置：

1. 安装 Node.js 22+、Codex CLI 和 Hanako，并分别完成登录。

2. 把 bridge.mjs 放在对方自己的固定目录。

3. 在 Codex 和 Hanako 的 MCP 设置中，把 bridge.mjs 的示例路径替换成对方自己的绝对路径。

4. 确认 Hanako 正在运行，并让桥接器读取对方自己的 %USERPROFILE%\\.hanako\\server-info.json。

5. 委派项目任务时使用对方自己的项目目录，或设置 BRIDGE_DEFAULT_CWD。

仓库没有包含个人账号令牌、server-info.json、Codex 配置或某台电脑的用户目录。代码会根据当前用户的 USERPROFILE/HOME 查找本地配置；README 中的 C:\\Tools、/opt 等只是安装示例。桥接器默认只连接本机 127.0.0.1，不会因为分享 GitHub 链接而替别人连接到你的 Hanako 或 Codex。

配置 Codex

在 Codex 的 config.toml 中添加一个 MCP server。把下面的路径改成 bridge.mjs 的实际路径：

[mcp_servers.hanako-codex-bridge]
command = "node"
args = ["C:\\Tools\\hanako-codex-bridge\\bridge.mjs"]
default_tools_approval_mode = "approve"
tool_timeout_sec = 900.0

macOS/Linux 示例：

[mcp_servers.hanako-codex-bridge]
command = "node"
args = ["/opt/hanako-codex-bridge/bridge.mjs"]
default_tools_approval_mode = "approve"
tool_timeout_sec = 900.0

完全访问模式下，approve 是有意为桥接工具打开自动执行。它只应配置在这个受信任的本地桥接 server 上，不要为了方便把所有 MCP server 都设成同样的策略。

修改后重启 Codex，或在客户端中重新加载 MCP servers。

配置 Hanako

在 Hanako 的 MCP connector 设置中添加一个 stdio server，使用与 Codex 相同的 bridge.mjs：

Transport: stdio
Command: node
Arguments: C:\Tools\hanako-codex-bridge\bridge.mjs
Enabled agents: 需要使用桥接的 Hanako agent，例如 hanako、hakimi

不同版本的 Hanako 可能使用不同的字段名称；核心配置只有三项：stdio、node、bridge.mjs 的绝对路径。

Hanako 必须处于运行状态，并且本机存在由 Hanako 生成的 server-info.json。默认位置是：

Windows: %USERPROFILE%\.hanako\server-info.json
macOS/Linux: ~/.hanako/server-info.json

可选环境变量

HANAKO_SERVER_INFO       自定义 Hanako server-info.json 路径
CODEX_EXECUTABLE         自定义 Codex 可执行文件路径
BRIDGE_DEFAULT_CWD       Codex 子任务默认工作目录
CODEX_BRIDGE_TIMEOUT_MS  Codex 子任务超时，默认 1200000
CODEX_THREAD_TIMEOUT_MS  持久 Codex 新对话首轮超时，默认跟随 CODEX_BRIDGE_TIMEOUT_MS
HANAKO_BRIDGE_TIMEOUT_MS Hanako 子任务超时，默认 900000
BRIDGE_MAX_CONCURRENT    同一桥接进程最多同时运行的委派数，默认 4；Hanako detached 委派另有本机跨进程保护租约
BRIDGE_MAX_HOPS          允许的委派层数，默认 1；下游 Codex 进程会被硬性禁止再次进入桥接器
HANAKO_CODEX_BRIDGE_HOP  内部使用，不建议手动设置
HANAKO_CODEX_BRIDGE_NO_REENTRY 内部使用；值为 1 时拒绝所有委派

例如在 PowerShell 中：

$env:BRIDGE_DEFAULT_CWD = "C:\Work\my-project"
node C:\Tools\hanako-codex-bridge\bridge.mjs

四个 MCP 工具

自然语言触发

正常使用时不需要输入工具名。在 Hanako 中，只要表达出类似下面的意图即可：

• 把这个任务交给 Codex

• 让 Codex 处理、检查、修复或开发

• 把工作转交给另一个编码助手

• 另开一个独立任务或 Codex 对话

例如：

把这个项目的测试问题转交给 Codex，在 C:\\Work\\my-project 中修复，完成后把结果告诉我。

Hanako 会优先调用 codex_new_thread 创建持久 Codex 对话。只有明确说“只要一次性结果、不要创建新对话”时，才使用 codex_task。

bridge_status

查看桥接器、Hanako 本地服务和 Codex 可执行文件状态。会做本机连通性/版本探测，不会返回令牌、端口或绝对路径。

codex_task

从 Hanako 或其他 MCP 客户端委派给 Codex：

{
  "task": "检查项目当前测试状态，并返回简短结论",
  "cwd": "C:\\Work\\my-project"
}

hanako_task

从 Codex 委派给 Hanako：

{
  "agentId": "hakimi",
  "task": "阅读当前任务背景，给出一份简短的风险检查清单"
}

任务文本会被转交给另一侧；不要在任务文本中放入密码、令牌或其他不必要的敏感信息。

codex_new_thread

从 Hanako 创建一个真正持久的 Codex 新任务：

{
  "task": "检查当前项目的测试状态，并把结论写成简短报告",
  "cwd": "C:\\Work\\my-project"
}

返回结果类似：

{
  "threadId": "...",
  "status": "completed",
  "result": "...",
  "persistent": true
}

这里的 threadId 是 Codex 的持久任务 ID；它和 codex_task 的一次性子进程不同。

验证

安装完成后按这个顺序验证：

1. 调用 bridge_status，确认 hanakoServer 为 reachable、codex 为 available。

2. 从 Codex 调用 hanako_task，让 Hanako 只回复一个固定短语。

3. 从 Hanako 调用 codex_task，让 Codex 只回复另一个固定短语。

4. 确认两边都能收到结果后，再委派真实任务。

测试时先使用“不修改文件、不安装软件、不访问外部服务”的短任务。

故障排查

Hanako 本地服务不可用

确认 Hanako 正在运行，并检查 server-info.json 是否存在、JSON 是否完整。可用 HANAKO_SERVER_INFO 指向自定义位置。

找不到 Codex

确认 Codex CLI 已安装并在 PATH 中。也可以使用 CODEX_EXECUTABLE 指向 codex.exe 或 codex 的绝对路径。

MCP 工具调用需要审批

确认只有 hanako-codex-bridge 的 default_tools_approval_mode 设置为 approve，并重启 Codex 让 config.toml 生效。不要把这个设置扩展到不受信任的 MCP server。

任务超时

首次启动 Codex/Hanako 可能需要较长时间。提高 CODEX_BRIDGE_TIMEOUT_MS 或 HANAKO_BRIDGE_TIMEOUT_MS，并确认 Codex 的 tool_timeout_sec 足够大。

开发

本项目没有第三方 npm 依赖。可以使用下面的命令做语法检查和自动测试：

node --check bridge.mjs
npm test

桥接器使用 JSON-RPC over stdio 与 MCP 客户端通信；Hanako 一侧使用本机 HTTP API 和 WebSocket，Codex 一侧同时支持一次性的 codex exec 子进程和通过 codex app-server 创建持久 thread。仓库包含 GitHub Actions CI，会在 Node.js 22/24 及 Windows、macOS、Linux 上运行语法检查和测试。

许可

当前仓库未附加开源许可证。除非仓库所有者另行添加许可证，否则默认保留所有权利。