ClawRouter

ClawRouter 为 OpenClaw 提供一个受策略范围约束的密钥，用于访问多个上游模型提供商。内置的 clawrouter 插件只发现该密钥获准使用的模型，通过每个模型声明的协议进行路由，并在 OpenClaw 的用量界面中报告该密钥的预算和汇总用量。

上游凭据和提供商特定的转发均保留在 ClawRouter 中，因此无需在 OpenClaw 主机上安装或验证每个上游提供商插件。该插件随 OpenClaw 内置提供（enabledByDefault: true）；你只需要一个已签发的 ClawRouter 凭据。

入门指南

export CLAWROUTER_API_KEY="..."openclaw onboard --auth-choice clawrouter-api-keyopenclaw plugins enable clawrouter

openclaw models list --all --provider clawrouter

openclaw models set clawrouter/<provider>/<model>

托管式非交互部署

将代理密钥保留在工作负载的密钥注入机制中，并且只在 openclaw.json 中存储 SecretRef。规范的托管字段如下：

例如，部署控制器可以管理以下 JSON5 补丁：

{  plugins: {    entries: { clawrouter: { enabled: true } },  },  models: {    providers: {      clawrouter: {        baseUrl: "https://clawrouter.internal.example",        apiKey: {          source: "env",          provider: "default",          id: "CLAWROUTER_API_KEY",        },        headers: {          "X-ClawRouter-Project-Id": "fakeco",        },      },    },  },  agents: {    defaults: {      model: { primary: "clawrouter/openai/gpt-5.5" },    },  },}

如果部署设置了 plugins.allow，请保留其现有条目并添加 clawrouter。无需交互式向导即可验证并应用：

openclaw config patch --file ./clawrouter.patch.json5 --dry-run --jsonopenclaw config patch --file ./clawrouter.patch.json5

试运行会解析 SecretRef，但绝不会输出其值。若要轮换凭据，请更新提供 CLAWROUTER_API_KEY 的外部 Secret，并重启 Gateway 网关工作负载，以便加载新的进程环境。配置文件和模型引用无需更改。

对于从源码构建的独立 Docker Gateway 网关，ClawRouter 已包含在根运行时中。仅选择需要单独打包的渠道插件，例如 OPENCLAW_EXTENSIONS=clickclack、slack 或 msteams；请参阅包含所选插件的源码构建镜像。归档/设备部署必须通过自身的制品流水线打包同一份已落地源码，而不能使用 OCI 镜像。

就绪状态和实时验证

这些检查验证不同的边界；请勿互相替代：

# 仅检查 ClawRouter 进程健康状态；不会使用凭据或上游模型。curl -fsS https://clawrouter.internal.example/v1/health # 仅检查 OpenClaw Gateway 网关启动就绪状态；不会调用模型。curl -fsS http://127.0.0.1:18789/readyz # 按凭据范围发现目录。openclaw models list --all --provider clawrouter --json # 通过已配置的 ClawRouter 提供商执行最小真实推理探测。openclaw models status --probe --probe-provider clawrouter --probe-max-tokens 8 --json # 使用精确获准模型引用的工作负载金丝雀测试。openclaw agent --agent main \  --model clawrouter/openai/gpt-5.5 \  --message "Reply exactly: CLAWROUTER_CANARY_OK" \  --json

请使用受限目录返回的模型，而不要盲目复制示例模型。成功的 /readyz 响应表示 Gateway 网关能够处理请求；这并不表示 ClawRouter、其凭据或上游提供商已就绪。模型探测和智能体金丝雀测试才是推理验证。

进行实时诊断时，请发起金丝雀测试并检查 Gateway 网关的标准日志。现有的仅元数据模型传输诊断会输出如下格式的日志行：

[model-fetch] start provider=clawrouter api=openai-responses model=openai/gpt-5.5 method=POST url=https://clawrouter.internal.example/v1/responses[model-fetch] response provider=clawrouter api=openai-responses model=openai/gpt-5.5 status=200

当这些标识符可用时，插件会发送长度受限的 X-ClawRouter-Client、X-ClawRouter-Agent-Id 和 X-ClawRouter-Session-Id 标头。它还会将模型调用的诊断 callId（<run-id>:model:<n>）映射到 X-Request-ID，从而能够将 OpenClaw 模型调用事件与 ClawRouter 的仅元数据审计轨迹关联起来。未超过 128 字符请求 ID 限制的值保持完全一致。较长的值会保留 :model:<n> 后缀并附加确定性哈希，以确保不同调用的长度受限且仍可关联。可以在提供商的 headers 映射中设置 X-ClawRouter-Project-Id 等静态部署元数据。智能体和会话归因标头各自保留 256 字符的限制。自动生成且包含 ClawRouter ASCII 标识符集合之外字符的请求 ID，也会使用相同的确定性长度限制形式。 显式配置的标头（包括 X-Request-ID 的任何大小写变体）优先于自动值。传输诊断记录路由和响应元数据；它不会记录凭据、请求 ID、提示词或补全内容。ClawRouter 自身的审计事件会提供所选的上游提供商和内容保留状态。

模型发现

GET /v1/catalog 返回 { providers: [...] }，其中每个提供商条目都会列出自身的 models[]（包含上游 ID、能力和定价）以及支持的请求路由。OpenClaw 不会附带第二份固定的 ClawRouter 模型列表。满足以下条件时，目录模型会作为 OpenClaw 模型提供：

• 凭据策略允许使用其提供商；
• 目录模型声明了受支持的 LLM 能力（llm.responses、llm.chat、llm.messages，或具有匹配流式路由的 llm.stream）；以及
• 提供商为下列传输协议之一公开了匹配路由。

向受支持的 ClawRouter 提供商添加模型无需发布新版 OpenClaw：下一次目录刷新（按凭据范围缓存 60 秒）即可发现该模型。需要新线路协议的模型则必须先获得插件支持。

协议和提供商插件

ClawRouter 负责管理上游凭据；其目录会告知 OpenClaw 应使用哪种传输协议，因此无需安装每个上游公司的身份验证插件。

该插件还会为这些系列应用匹配的重放和工具模式策略（OpenAI/DeepSeek/Gemini 工具模式兼容策略，以及原生 Anthropic 和 Google Gemini 重放策略）。如果目录提供商仅公开不受支持的请求格式，则有意不会将其作为 OpenClaw 文本模型提供。应在 ClawRouter 中将这些提供商规范化为受支持的契约之一，而不是发送不兼容的载荷。

配额和用量

ClawRouter 的 /v1/usage 响应会填充常规 OpenClaw 提供商用量界面：请求数、Token 数和支出总额；如果密钥设置了限制，还会显示每月预算周期。不限额密钥仍会显示汇总用量，但不显示百分比周期。

配额查询使用与模型发现相同的受限范围密钥。配额查询失败不会阻止模型执行。

使用以下命令检查实时快照：

openclaw status --usageopenclaw models status

聊天中的 /status 和 OpenClaw 用量 UI 也会提供相同的提供商快照。预算适用于整个策略，因此使用相同 ClawRouter 策略的其他客户端所发出的请求可能会改变剩余百分比。

故障排查

安全行为

• 目录发现范围限定于已配置的代理密钥，并按凭据作用域（Agent 目录、工作区目录、身份验证配置文件 ID 和基础 URL）分别缓存。
• 代理密钥仅在分派请求时附加；不会存储在模型元数据中。
• 自动归属信息和请求关联值在分派前会去除首尾空白并拒绝控制字符。归属信息值上限为 256 个字符；请求 ID 上限为 128 个字符。
• 模型传输诊断仅包含元数据，绝不包含代理密钥或模型内容。
• 原生 Anthropic 和 Gemini 模型 ID 仅在分派时重写为其上游 ID。
• 不受支持或未获授权的目录条目会以关闭方式失败，且不可选择。

相关内容