claude-openrouter-delegate-mcp

将来自 Anthropic 支持的 Claude Code 会话中的任务委托给 OpenRouter 支持的 Claude Code 会话——而两者之间永远不会共享环境变量。

将 Claude Code 指向 OpenRouter 意味着要在你的 shell 中导出 ANTHROPIC_* 变量。这些变量是进程级的，因此一个 shell 要么是“Anthropic”，要么是“OpenRouter”，绝不会同时是两者——而一个导出的、持有你 OpenRouter 密钥的 ANTHROPIC_AUTH_TOKEN，只需一个不经意的子进程就可能泄露。

这个 MCP 服务器以显式构造的环境将每个被委托的会话作为子进程启动。你的 Opus 会话保留自己的凭据；被委托的会话获得 OpenRouter 的凭据。它们在同一终端中并排运行。

┌────────────────────────────┐
│  Claude Code (Opus)        │   your session, Anthropic credentials
│                            │
│   └─ mcp: openrouter ──────┼──▶ spawn: claude -p   (fresh env)
└────────────────────────────┘         ANTHROPIC_BASE_URL=https://openrouter.ai/api
                                       ANTHROPIC_AUTH_TOKEN=sk-or-v1-…
                                       → deepseek/deepseek-v4-flash-0731

这是 claude-ollama-delegate-mcp 的姊妹项目，后者为本地 Ollama 服务器做同样的事情。这里决定一切的关键区别是：OpenRouter 需要真金白银，并提供 400+ 模型，因此这个包增加了 API 密钥路径、带价格的模型目录，以及按任务计费报告。

快速开始

# 1. an OpenRouter API key: https://openrouter.ai/keys
export OPENROUTER_API_KEY=sk-or-v1-...

# 2. register the server
claude mcp add openrouter --scope user -- npx -y claude-openrouter-delegate-mcp

# 3. restart your Claude Code session

然后用自然语言请求委托：

把这个委托给 openrouter：总结 src/ 中所有导出的符号

默认情况下，服务器只在你明确要求时才进行委托。要让编排器自行决定，请参阅 委托模式。

Related MCP server: Ollama MCP Server

目录

• 快速开始

• 工作原理

• 前提条件

• 安装

• API 密钥

• 配置

• 委托模式

• 选择模型

• 费用

• 工具参考

• 操作

• 任务产物

• 故障排除

• 平台支持

• 安全模型

• 开发

工作原理

OpenRouter 在 OpenAI 形状的端点之外，还暴露了一个 Anthropic 兼容的 POST /v1/messages 端点，因此 Claude Code 在指向正确的 base URL 时无需修改即可与它通信。每个被委托的任务都以 claude -p 的形式在自己的进程中运行，并带有：

ANTHROPIC_BASE_URL=https://openrouter.ai/api
ANTHROPIC_AUTH_TOKEN=<your OpenRouter key>
ANTHROPIC_DEFAULT_OPUS_MODEL=<model>
ANTHROPIC_DEFAULT_SONNET_MODEL=<model>
ANTHROPIC_DEFAULT_HAIKU_MODEL=<small model>
ANTHROPIC_SMALL_FAST_MODEL=<small model>
CLAUDE_CODE_SUBAGENT_MODEL=<model>
ANTHROPIC_CUSTOM_HEADERS=HTTP-Referer: …⏎X-Title: …
CLAUDE_CODE_MAX_OUTPUT_TOKENS=<clamped per model>

base URL 止于 /api，因为 Claude Code 会自行追加 /v1/messages。使用 ANTHROPIC_AUTH_TOKEN 而不是 ANTHROPIC_API_KEY，是因为它会作为 Authorization: Bearer <key> 发送，这正是 OpenRouter 期望的方案。

子进程环境基于一个小的、按平台划分的允许列表构建。任何匹配 ANTHROPIC_*、CLAUDE_*、AWS_*、GOOGLE_*、AZURE_*、OPENAI_*、BEDROCK_*、VERTEX_* 或 OPENROUTER_* 的变量都会在应用 OpenRouter 值之前被丢弃。最后一个前缀是故意的：被委托的会话只需要以 ANTHROPIC_AUTH_TOKEN 的形式获得密钥，因此它永远不会在另一个名称下收到第二份副本，以免被它运行的其他工具拾取。

被委托的会话还会以 --strict-mcp-config 启动，且不带 MCP 配置，这能加快它们的启动速度，并阻止它们递归调用此服务器。

两个不可省略的细节

输出 token 钳制。 Claude Code 在每个请求中都会要求 max_tokens: 32000。许多 OpenRouter 模型的上限更低——amazon/nova-micro-v1 允许 5120——并会直接拒绝请求。服务器从目录中读取 top_provider.max_completion_tokens，并将 CLAUDE_CODE_MAX_OUTPUT_TOKENS 固定为所选模型实际接受的值。

工具调用是强制性的。 Claude Code 在每个请求中都会发送一个约 110 KB、带有完整工具模式的请求体。一个无法调用工具的模型会在第一轮就失败，而你已经为它付了钱。服务器会使用目录中的 supported_parameters 提前拒绝此类模型。

前提条件

node --version
claude --version
curl -s -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  https://openrouter.ai/api/v1/credits      # {"data":{"total_credits":…}}

安装

从 npm 安装（推荐）

claude mcp add openrouter --scope user \
  --env OPENROUTER_API_KEY=sk-or-v1-... \
  -- npx -y claude-openrouter-delegate-mcp

或者全局安装，这也会把设置 CLI 放到你的 PATH 上：

npm install -g claude-openrouter-delegate-mcp
openrouter-mcp-config --api-key sk-or-v1-...
claude mcp add openrouter --scope user -- claude-openrouter-delegate-mcp

从源码安装

git clone https://github.com/histonedev/claude-openrouter-delegate-mcp.git
cd claude-openrouter-delegate-mcp
npm install          # builds automatically via the prepare script
claude mcp add openrouter --scope user -- node "$(pwd)/dist/index.js"

以 node dist/cli.js … 运行设置 CLI，或者使用 npm link 将 openrouter-mcp-config 放到你的 PATH 上。

确认

claude mcp list        # openrouter: ... - ✔ Connected

然后重启你的 Claude Code 会话——工具列表是在启动时读取的。

API 密钥

从以下第一个已设置的项目中解析：

1. OPENROUTER_API_KEY（最高——生态系统中其他部分使用的名称）

2. OPENROUTER_MCP_API_KEY

3. 配置文件中的 apiKeyFile——指向包含密钥的文件的路径

4. 配置文件中的 apiKey

openrouter-mcp-config --api-key sk-or-v1-...        # writes ~/.openrouter-mcp/config.json, mode 0600
openrouter-mcp-config --api-key-file ~/.secrets/or  # or keep it somewhere else entirely

密钥永远不会通过 MCP 工具暴露。openrouter_models 将其报告为 sk-or-v1-a...7f2e，CLI 打印相同的掩码形式，配置文件以 0600 权限写入。使用 --api-key --scope project 传入的密钥会被重定向到用户配置，因为项目配置会被提交。

如果你希望磁盘上完全没有密钥，可以在 MCP 注册时用 --env OPENROUTER_API_KEY=… 固定它，并跳过配置文件。

配置

设置从四层解析，后者覆盖前者：

1. 内置默认值

2. 用户配置——~/.openrouter-mcp/config.json（用 $OPENROUTER_MCP_CONFIG 覆盖）

3. 项目配置——服务器工作目录中的 ./openrouter-mcp.config.json

4. 环境变量

{
  "delegationMode": "ondemand",
  "defaultModel": "deepseek/deepseek-v4-flash-0731",
  "smallModel": "google/gemini-3.7-flash",
  "allowedModels": ["deepseek/deepseek-v4-flash-0731", "qwen/qwen3.7-flash"],
  "defaultPermissionMode": "auto",
  "maxOutputTokens": 16000,
  "requireToolSupport": true
}

更改设置

设置从终端更改，而不是由模型更改：

openrouter-mcp-config                                   # show current settings + active layers
openrouter-mcp-config --mode auto                       # off | ondemand | auto
openrouter-mcp-config --default-model qwen/qwen3.7-flash
openrouter-mcp-config --small-model google/gemini-3.7-flash
openrouter-mcp-config --allow deepseek/deepseek-v4-flash-0731,qwen/qwen3.7-flash
openrouter-mcp-config --permission-mode acceptEdits
openrouter-mcp-config --scope project                   # write ./openrouter-mcp.config.json

然后重启你的 Claude Code 会话，让服务器重新读取其配置。

故意没有提供 MCP 工具来做这件事。 请参阅 安全模型。

委托模式

这控制编排器多积极地使用委托，通过重写模型实际读取的工具描述来实现。更改它需要重启会话，这是设计使然。

两种模式都带有明确的费用警告，因为与本地模型不同，每次被委托的轮次都会计费，而且每个请求都会携带数万输入 token。

选择模型

OpenRouter 提供 400+ 模型。openrouter_models 默认会过滤到支持工具的模型并截断，因为将整个目录转储到编排器的上下文中本身就很昂贵。

openrouter_models({ filter: "gemini", limit: 10 })
openrouter_models({ free_only: true })

默认值是 deepseek/deepseek-v4-flash-0731：支持工具、1.3M 上下文，而且便宜。设置 allowedModels 可以将委托固定到你信任的短名单——允许的集合会嵌入到 delegate_start 的描述中，因此编排器无需额外调用就知道菜单，任何其他模型都会按名称被拒绝，而不是被静默替换。

模型质量参差不齐，这需要你来管理

这些不是 Claude 模型，而 Claude Code 对模型的依赖比聊天界面更重。在构建这个包的过程中，在真实运行中观察到：

• 一个模型可能正确调用其工具，然后不返回任何最终文本。工作完成了；结束语却没有。服务器会检测到这一点，并返回记录的活动轨迹，而不是空结果。

• 一个模型可能将其自身的原生工具调用标记作为纯文本发出——DeepSeek 在推理块内产生 <｜DSML｜tool_calls>——而不是结构化的工具调用。什么都不会执行，token 仍然会被计费。更长、更复杂的提示会使这种情况更可能发生。

• 已完成任务上的 tool calls: 0 注释是为了应对经典失败：一个关于你仓库的自信回答，却没有工具调用作为支撑。

对于较弱的模型，优先使用简短、单一用途的提示，用 max_turns 限制工作量，并在声称重要时检查 delegate_status。

费用

每个已完成的任务都会报告费用，标签会告诉你该在多大程度上信任它：

cost:       $0.00045   (billed by OpenRouter, 1 generation(s))
cost:       >=$0.00045 (billed so far -- 1 of 2 generations recorded)
cost:       $0.00924   (rough list-price estimate; actual routing may differ several-fold)

OpenRouter 会将其生成 ID 作为 Anthropic 消息 ID 返回，因此服务器会收集这些 ID，并向 /v1/generation 查询每个请求的实际费用。这是权威数字。账单记录在生成完成后片刻才会落账，因此某个任务可能会短暂显示部分金额——显示为 >=，绝不会是最终数字，因为费用显示唯一不能出错的方向就是向下。

估算值是在无法获取记录时的回退方案。请仅将其视为数量级参考：在测试中，同一模型上完全相同的 token 数，根据提供商路由和缓存命中的不同，计费可能相差十倍，而按标价计算的一次运行结果甚至高出 20 倍。

关于 token 计数，有两点值得了解：

• Claude Code 将几乎整个提示词报告为 cache_creation_input_tokens，而不是 input_tokens。tokens: in … 行汇总了所有输入类别。一个看起来是"12 个输入 token"的任务实际上约有 42,000 个。

• OpenRouter 路由到的提供商通常不遵守缓存（native_tokens_cached: 0），因此恢复的对话并不像缓存读取数字所显示的那样便宜。

削减账单。 smallModel 是最大的杠杆：Claude Code 的 haiku 槽位用于处理后台工具调用，将其指向便宜的模型，同时保持主模型的能力，几乎不会损失质量。其次是：max_turns 限制代理循环，allowed_tools 阻止委派代理探索超出任务需要的仓库范围。

工具参考

delegate_start

delegate_followup 接受 job_id 或 session_id，以及相同的 prompt/prompt_file 对和可选的 permission_mode、max_turns、wait_seconds。

操作方式

默认异步

delegate_start 以毫秒级返回 job_id；委派代理在后台持续运行。这样长任务不会阻塞你的会话，也不会触发 MCP 客户端超时——大多数客户端在 60 秒后就会放弃单个请求，而这比许多委派任务所需的时间要短。

delegate_start({ prompt: "Audit src/ for unused exports" })
  → job_id A, session_id S, turn 1, state: running

delegate_status({ job_id: "A" })
  → recent activity:
      [tool] Grep: export
      [tool] Read: /repo/src/index.ts

delegate_result({ job_id: "A" })
  → the final text

在这些参数上传递 wait_seconds 可改为阻塞模式——适用于短任务，但请确保低于客户端的请求超时时间。

双向对话

每个任务都带有 session_id。将其 job_id 传递给 delegate_followup 即可恢复包含完整历史的会话；session_id 在各轮之间保持稳定，而每轮都会获得新的 job_id。

delegate_start({ prompt: "Summarise the auth flow in this repo" })
  → job A, session S, turn 1
delegate_followup({ job_id: "A", prompt: "Now list every place it can fail" })
  → job B, session S, turn 2   (delegate still remembers turn 1)

恢复会话会将对话作为输入 token 重放，因此长线程每轮的成本高于新线程——但仍比重建相同上下文便宜得多。

长提示词

每个 prompt 参数都有对应的 prompt_file 版本。在内部，提示词始终写入磁盘，并通过 stdin 输入 CLI——绝不会作为 argv 条目或通过 shell 传递。反引号、$(...)、引号、换行符和通配符字符都会原样传递，且没有 argv 长度限制。

权限

// read-only review
delegate_start({ prompt: "...", disallowed_tools: ["Write", "Edit", "NotebookEdit"] })

// tightly scoped
delegate_start({ prompt: "...", allowed_tools: ["Read", "Grep", "Glob"] })

取消

delegate_cancel({ job_id: "A" })

终止委派代理及其启动的所有内容，并停止其消耗更多积分。服务器关闭时也会终止正在运行的委派代理。

任务产物

每个任务都会写入 ~/.openrouter-mcp/jobs/<job_id>/：

当委派代理的摘要不可信时，应查看 stream.jsonl：它包含实际的工具结果，而非模型对这些结果的转述。系统不会自动清理任何内容——你可以随时删除该目录。

故障排查

No OpenRouter API key configured 设置 OPENROUTER_API_KEY，或运行 openrouter-mcp-config --api-key sk-or-v1-...，然后重启会话。

OpenRouter rejected the API key (HTTP 401) 在 openrouter.ai/keys 检查。请注意，密钥在服务器启动时读取，因此新密钥需要重启会话。

Model "x" does not support tool calling 符合预期——Claude Code 会在每个请求中发送工具模式。请选择其他模型，或设置 requireToolSupport: false 尝试继续。

Model "x" is not in the allowed list 符合预期。运行 openrouter-mcp-config --allow <models>，然后重启。

委派代理不返回文本，或其工具调用无效果 这是模型质量问题，而非连接问题——请参阅模型质量参差不齐，这是你需要管理的问题。尝试更短的提示词或更强的模型，并阅读 stream.jsonl 查看实际发生的情况。

MCP 客户端报 Request timed out wait_seconds 超过了客户端的单次请求超时时间（通常为 60 秒）。请移除该参数，改用 delegate_status 轮询——这正是异步设计的目的。

关于 max_tokens 的 HTTP 400 错误 模型的输出上限低于请求值。服务器会自动将其限制为目录中的值；如果目录有误，请降低 maxOutputTokens。

工具未出现在 Claude Code 中 工具列表在会话启动时读取。请重启，或检查 claude mcp list。

委派代理立即以启动错误失败 未找到 CLI。请将 OPENROUTER_MCP_CLAUDE_BIN 设置为 claude 的绝对路径。

平台支持

平台差异隔离在 src/platform.ts 中：

二进制解析。 在 POSIX 上，spawn 会搜索 PATH。在 Windows 上，原生安装提供 claude.exe，而 npm 安装提供 claude.cmd，CreateProcess 无法直接执行后者——因此服务器会遍历 PATH × PATHEXT，优先使用 .exe，并回退到通过 cmd.exe 路由 .cmd 垫片。

参数转义。 该回退机制应用了两层：MSVCRT argv 引用，然后对 cmd 自身的元字符（& | < > ^ " ( ) % !）进行脱字符转义。跳过第二层是经典的 .cmd 命令注入漏洞。提示词永远不会经过此路径——它们通过 stdin 传输。一个限制：多行 append_system_prompt 无法跨 cmd.exe 命令行，因此服务器会抛出明确错误，指向 OPENROUTER_MCP_CLAUDE_BIN，而不是静默地破坏内容。

环境变量白名单。 Windows 保留的集合远大于 POSIX。SystemRoot 和 windir 不可省略——移除它们会导致 Winsock 初始化失败，子进程将完全无法打开套接字。

取消。 POSIX 子进程以 detached 方式生成，作为进程组组长，并使用 process.kill(-pid) 取消；Windows 使用 taskkill /T /F。

安全模型

凭据隔离是关键。 子进程环境是从零构建的，而非继承，提供商变量会在应用 OpenRouter 值之前被剥离。test/env-unit.mjs 断言密钥仅通过一个变量到达子进程，且父进程的机密不会残留；test/e2e.mjs 使用伪造的 ANTHROPIC_API_KEY 和真实的 ANTHROPIC_BASE_URL=https://api.anthropic.com 污染父进程，并确认委派代理两者都看不到。

密钥永远无法通过工具读取。 所有诊断路径都会对其进行掩码处理，test/readonly.mjs 断言任何工具输出和 CLI 输出都不包含密钥。这比 Ollama 兄弟项目更为重要，因为后者的 token 就是字面字符串 ollama。

委派策略不可被模型写入。 没有任何 MCP 工具可以更改 delegationMode、allowedModels 或 API 密钥。发现 ondemand 不便的模型无法自行切换到 auto 并开始消费。设置仅在启动时加载一次，运行时从不变异，工具描述也明确指出该策略不由模型更改。

这是护栏，而非安全边界。 拥有 shell 访问权限的代理仍然可以编辑配置文件。移除该工具的意义在于，此类更改是可见的文件编辑，且仅在下一次重启时生效，而不是任务中途一次静默的工具调用。要使其万无一失，请在 MCP 注册时通过 --env 固定这些值，这将覆盖配置文件：

claude mcp add openrouter --scope user \
  --env OPENROUTER_API_KEY=sk-or-v1-... \
  --env OPENROUTER_MCP_DELEGATION_MODE=ondemand \
  --env OPENROUTER_MCP_ALLOWED_MODELS=deepseek/deepseek-v4-flash-0731 \
  -- node /path/to/claude-openrouter-delegate-mcp/dist/index.js

消费是真实的。 失控的 auto 模式编排器消耗的是你的积分，而不是你的耐心。请为你提供给此服务器的密钥设置 OpenRouter 密钥限额——这是模型无法辩驳的上限。

委派代理继承你的文件系统。 它们以你的用户身份在你指定的 cwd 中运行，并使用 defaultPermissionMode。请像对待任何 Claude Code 会话一样对待委派会话——在将工作交给信任度较低的模型时，请使用 disallowed_tools 或只读权限模式。

开发

npm install        # installs and builds
npm run build      # tsc
npm run dev        # tsc --watch

测试

node test/env-unit.mjs       # env isolation, key handling, model slot wiring
node test/pricing-unit.mjs   # cost arithmetic, catalog filtering, URL normalisation
node test/quoting.mjs        # Windows argv/cmd escaping, incl. an injection probe
node test/killtree-unit.mjs  # process-tree termination (cross-platform)
OPENROUTER_API_KEY=... node test/e2e.mjs     # full MCP round trip         (costs ~$0.01)
OPENROUTER_API_KEY=... node test/async.mjs   # async polling, prompt_file, cancel
CFG_PATH=/tmp/c.json CFG_CWD=/tmp node test/readonly.mjs   # config is read-only to the model

npm test 运行四个无需网络的测试。它们在 Windows 和 POSIX 上均能通过——进程树测试使用 node 进程而非 shell 内建命令来构建其树，因此它并非仅限 POSIX。

发布版本

npm login                       # interactive, once per machine
npm version patch               # or minor / major -- tags and bumps
npm publish                     # prepare script builds first
git push --follow-tags

请从真实终端运行 npm publish，而不是脚本或非交互式 shell。使用 WebAuthn/安全密钥 2FA 时，CLI 通过打开浏览器来完成挑战；没有 TTY 则无法做到，并会退而要求输入安全密钥无法生成的 TOTP 验证码（npm error code EOTP）。对于 CI，请改用具有 Bypass 2FA 权限的细粒度访问令牌。

该包仅发布 dist/、README.md 和 LICENSE。publishConfig.access 为 public，且 prepare 在打包前运行 tsc，因此过期的 dist/ 永远不会被发布。

文件布局

许可证

MIT — 参见 LICENSE。