OpenClaw ClawRouter 接入指南单密钥多模型路由与配额上报的完整实践【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawClawRouter 是 OpenClaw 内置的托管式多模型提供方路由插件只用一个策略限定的代理密钥proxy key即可访问多个上游模型厂商并由 ClawRouter 侧统一管理上游凭证、转发与月度预算。本文基于 ClawRouter 官方文档 与 clawrouter 插件源码完整介绍其接入配置、模型发现、协议路由、配额上报、就绪探针与排障清单读完可独立完成从领密钥、接入、选模型到运维验证的全流程。ClawRouter 是什么ClawRouter 为 OpenClaw 提供一个策略限定密钥访问多个上游模型提供方的能力。随 OpenClaw 一起分发的clawrouter插件只发现该密钥被授权允许的模型按每个模型声明的协议将其路由到对应传输通道并把密钥的月度预算与聚合用量呈现在 OpenClaw 的用量面上。上游凭证和各厂商的转发逻辑都留在 ClawRouter 侧因此 OpenClaw 主机上不需要安装或认证任何上游提供方插件。插件随 OpenClaw 内置发布enabledByDefault: true你只需要持有管理员签发的 ClawRouter 凭证即可。属性值Providerclawrouter插件bundled随 OpenClaw 内置认证方式CLAWROUTER_API_KEY默认 URLhttps://clawrouter.openclaw.ai模型目录按凭证范围通过/v1/catalog获取配额月度预算与用量通过/v1/usage获取插件清单 openclaw.plugin.json 中可以看到这些声明的落地enabledByDefault: true、providers: [clawrouter]、contracts.usageProviders: [clawrouter]以及名为clawrouter-api-key的 API Key 认证选择项对应 CLI 参数--clawrouter-api-key key。快速接入从领密钥到选模型第一步获取按策略签发的凭证向 ClawRouter 管理员申请一个凭证其策略policy应包含你需要使用的提供方、模型与月度预算。凭证在签发时只展示一次请妥善保存。第二步配置 OpenClawexport CLAWROUTER_API_KEY... openclaw onboard --auth-choice clawrouter-api-key openclaw plugins enable clawrouterclawrouter内置且默认启用。如果你的配置设置了plugins.allow需要先把clawrouter加进该列表再启用。自定义部署时可在models.providers.clawrouter.baseUrl设置 ClawRouter 源地址默认值为https://clawrouter.openclaw.ai。认证项的完整定义见 openclaw.plugin.json 中的providerAuthChoiceschoiceId为clawrouter-api-key环境变量为CLAWROUTER_API_KEY。第三步列出被授权的模型openclaw models list --all --provider clawrouter直接使用返回的模型引用model ref它们保留上游命名空间例如clawrouter/openai/gpt-5.5clawrouter/anthropic/claude-sonnet-4-6clawrouter/google/gemini-3.5-flash如果配置了agents.defaults.modelPolicy.allow需要把选中的 ClawRouter ref 逐条加入该列表。第四步选择模型openclaw models set clawrouter/provider/model也可以针对单次运行临时指定模型openclaw agent --model clawrouter/provider/model --message ...托管式非交互部署在生产环境中建议把代理密钥放在工作负载的密钥注入机制里openclaw.json中只保存一个 SecretRef。核心托管字段如下用途配置或环境字段路由源地址models.providers.clawrouter.baseUrl凭证models.providers.clawrouter.apiKey→ env SecretRef密钥值网关进程环境中的CLAWROUTER_API_KEY默认模型agents.defaults.model.primary→clawrouter/provider/model工作负载标签models.providers.clawrouter.headers.X-ClawRouter-Project-Id可选例如部署控制器可以持有如下 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 --json openclaw config patch --file ./clawrouter.patch.json5dry-run 会解析 SecretRef但绝不会打印其值。轮换凭证时只需更新为CLAWROUTER_API_KEY提供值的外部 Secret 并重启网关工作负载以加载新进程环境配置文件与模型引用无需改动。源码佐证密钥只在实际派发时附加从源码结构看插件刻意把密钥与模型元数据解耦index.ts 中目录发现catalog使用 discovery key 拉取模型stream.ts 中withClawRouterHeaders仅在请求派发时以Authorization: Bearer apiKey形式附加密钥。对应测试 index.test.ts 验证了代理密钥与原生上游 id 仅在请求派发时附加这一行为。Docker 部署说明对于源码构建的独立 Docker 网关ClawRouter 已包含在根运行时中只需要单独打包渠道类插件例如OPENCLAW_EXTENSIONSclickclack、slack或msteams参见 source-built images with selected plugins。归档/设备类部署必须通过自身制品流水线打包同一份落地源码而不是消费 OCI 镜像。就绪检查与线上证明以下检查证明的是不同边界不可互相替代# 仅证明 ClawRouter 进程健康不涉及凭证或上游模型。 curl -fsS https://clawrouter.internal.example/v1/health # 仅证明 OpenClaw 网关启动就绪不发起任何模型调用。 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 # 使用精确的被授权模型 ref 做工作负载金丝雀。 openclaw agent --agent main \ --model clawrouter/openai/gpt-5.5 \ --message Reply exactly: CLAWROUTER_CANARY_OK \ --json请使用凭证目录返回的模型而不是盲目照抄示例模型。/readyz成功只表示网关可以对外服务不代表ClawRouter、其凭证或某个上游提供方已就绪模型探测与 agent 金丝雀才是真正的推理证明。通过日志做在线诊断发起金丝雀后检查网关标准日志。现有的仅元数据模型传输诊断会输出类似下面的行[model-fetch] start providerclawrouter apiopenai-responses modelopenai/gpt-5.5 methodPOST urlhttps://clawrouter.internal.example/v1/responses [model-fetch] response providerclawrouter apiopenai-responses modelopenai/gpt-5.5 status200插件在标识可用时会发送有长度上限的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后缀并附加确定性哈希使不同调用保持有界且可关联。静态部署元数据如X-ClawRouter-Project-Id可放在提供方的headers映射中。agent 与会话归因头保持各自独立的 256 字符上限。自动请求 id 若含 ClawRouter ASCII 标识符集合之外的字符也使用相同的确定性有界形式。显式配置的请求头包括任意大小写变体的X-Request-ID优先于自动值。传输诊断只记录路由与响应元数据不记录凭证、请求 id、提示词或补全内容ClawRouter 自身的审计事件提供所选上游提供方与内容保留状态。源码佐证标识的有界化与净化stream.ts 定义了两套有界标识策略归因 id 上限 256 字符、请求 id 上限 128 字符超过上限或含不安全字符时使用 SHA-256 的 16 位十六进制前缀并保留:model:n后缀见sanitizeBoundedIdstream.ts。测试 index.test.ts 覆盖了超长 id、Unicode 归因、孤立代理对等边界情况并验证new Headers(headers)不会因净化后的值而抛错。模型发现以凭证目录为准GET /v1/catalog返回{ providers: [...] }其中每个提供方条目列出自己的models[]含上游 id、能力与定价及其支持的请求路由。OpenClaw不内置第二份固定的 ClawRouter 模型清单。一个目录模型被公告为 OpenClaw 模型需要同时满足凭证策略授予其提供方目录模型公告了受支持的 LLM 能力llm.responses、llm.chat、llm.messages或带匹配流式路由的llm.stream提供方针对下述传输之一暴露了匹配路由。给受支持的 ClawRouter 提供方新增模型不需要 OpenClaw 发版下一次目录刷新按凭证范围缓存 60 秒即可发现。需要新线上协议的模型则必须先有插件支持。模型的可选displayName是选择器标签没有时 OpenClaw 使用提供方显示名与目录id。标签不会改变模型身份。Responses 与 Chat Completions 原样发送目录id只有原生 Anthropic 与 Gemini 路由在派发时使用upstream。暴露别名的门面facade必须只返回安全的目录元数据把别名放进必填的upstream字段并把私有目标映射留在门面内部。源码佐证路由判定逻辑provider-catalog.ts 的buildRoutedModel是路由判定的核心提供方openaiCompatible且模型具备llm.responses→ 使用openai-responses传输baseUrl 为${rootUrl}/v1提供方openaiCompatible且模型具备llm.chat→ 使用openai-completions传输模型具备llm.messages且存在anthropic.messages原生路由 → 使用anthropic-messages传输并带上upstreamModel否则模型需具备llm.stream且提供方存在google.generate_content流式路由路径含:streamGenerateContent→ 使用google-generative-ai传输。目录缓存 TTL 为 60 秒CATALOG_CACHE_TTL_MS 60_000provider-catalog.ts上下文窗口与最大 token 数分别默认 200,000 与 32,768。发现结果按模型 id 排序并去重且只在providers.length 0时才写入缓存shouldCacheRows避免空目录污染缓存。协议与提供方插件无需安装上游认证ClawRouter 持有上游凭证其目录告诉 OpenClaw 使用哪种传输因此无需安装每个上游厂商的认证插件。目录能力 / 路由OpenClaw 传输llm.responsesOpenAI 兼容提供方openai-responsesllm.chatOpenAI 兼容提供方openai-completionsllm.messagesanthropic.messages路由anthropic-messagesllm.stream 流式google.generate_content路由google-generative-ai插件还会对这些模型族套用匹配的重放replay与工具 schema 策略OpenAI/DeepSeek/Gemini/Perplexity 的工具 schema 兼容以及原生 Anthropic 与 Google Gemini 的重放策略。Perplexity 模型使用严格 schema 重写移除patternProperties和additionalProperties且每个对象 schema 都必须声明properties因为 Perplexity 会拒绝缺少它们的工具 schema。只暴露不支持请求格式的目录提供方会被有意不公告为 OpenClaw 文本模型应在 ClawRouter 侧把这些提供方规整到受支持的契约之一而不是发送不兼容的载荷。源码佐证工具族与重放策略index.ts 为 OpenAI 兼容、原生 Anthropic 与 Google Gemini 族分别构建重放钩子resolveToolFamilyindex.ts按模型 id 前缀deepseek/、google/、perplexity/选择 DeepSeek、Gemini 或 Perplexity 工具规范化器其余默认 OpenAI 工具兼容。tool-schemas.ts 定义了 Perplexity 不支持的 schema 关键字集合与递归遍历键集。测试 index.test.ts 验证了按上游协议族派发重放与工具策略Anthropic 消息保留原生工具调用 id、Gemini 校验回合、OpenAI 兼容族清理工具调用 id。另外插件通过resolveThinkingProfileindex.ts依据目录公告的supportedReasoningEfforts生成思考档位运行时为openclaw/auto时还会追加ultra档档位集合见 provider-catalog.ts 的CLAWROUTER_REASONING_EFFORT_LEVELSnone/minimal/low/medium/high/xhigh/max。对应测试 index.test.ts 验证了思考档位的权威解析与有界化。配额与用量上报ClawRouter 的/v1/usage响应会流入 OpenClaw 常规的提供方用量面请求数、token 数与花费合计以及当密钥设有上限时的月度预算窗口。未计量unmetered密钥仍会展示聚合用量但没有百分比窗口。配额查询与模型发现使用同一个按凭证范围的密钥。配额查询失败不会阻断模型执行。查看实时快照openclaw status --usage openclaw models status同一份提供方快照也出现在聊天内的/status与 OpenClaw 的用量 UI 中。预算是按策略全局的因此使用同一 ClawRouter 策略的其他客户端发起的请求也会改变剩余百分比。源码佐证用量快照的构造usage.ts 的fetchClawRouterUsage负责拉取并构造ProviderUsageSnapshot请求${rootUrl}/v1/usage携带Authorization: Bearer token响应体上限 1 MiBCLAWROUTER_USAGE_RESPONSE_MAX_BYTES超限报错当budget.configured true且 limit/spent 均有效时生成Monthly budget窗口usedPercent min(100, spent/limit*100)与billing预算条目否则回退为spend类型条目通过windowKey如default/test-policy/2026-07解析月度重置时间plan字段区分Managed monthly budget与Unmetered proxy key。测试 usage.test.ts 覆盖了月度预算映射$100 预算已用 $25 → 25%、未计量密钥的聚合展示以及不把数字字符串强转为数值limitMicros: 1000000时窗口为空、billing 未定义等边界。此外 usage.test.ts 验证了生产 SSRF 防护传输、环境代理路由HTTP_PROXY、以及阻止重定向到私网地址等安全行为。常见问题排查症状检查项没有 ClawRouter 模型确认插件已启用且被plugins.allow允许然后确认凭证处于激活状态且至少授予一个就绪提供方。配置的 ClawRouter 模型缺失检查其/v1/catalog能力与路由支持不支持的传输契约会被有意过滤。模型覆盖被策略拒绝在agents.defaults.modelPolicy.allow中加入精确的目录 ref 或clawrouter/*。目录或用量返回401/403重新签发或重设 ClawRouter 凭证范围OpenClaw 不会回退使用上游提供方密钥。发现后模型调用失败检查 ClawRouter 侧的提供方连接与上游健康状态待其就绪恢复后重试。用量有合计但无百分比该策略未计量在 ClawRouter 中配置月度预算即可显示百分比窗口。安全行为要点目录发现按配置的代理密钥限定范围并按凭证范围agent 目录、工作区目录、认证 profile id 与 base URL缓存。代理密钥只在请求派发时附加不存储在模型元数据中。自动归因与请求关联值在派发前会被裁剪并拒绝控制字符归因值上限 256 字符请求 id 上限 128 字符。模型传输诊断只含元数据从不包含代理密钥或模型内容。原生 Anthropic 与 Gemini 模型 id 仅在派发时重写为上游 id。不支持或未授权的目录行失败关闭fail closed不可被选中。从源码看dynamicModelScopeindex.ts正是把 agent 目录、工作区目录、认证 profile id 与规范化后的 root URL 序列化进作用域键prepareDynamicModelindex.ts重建时采用原子发布目录出错时保留上一份快照而凭证缺失是唯一清空快照的失败关闭路径——对应的两个测试index.test.ts分别验证了刷新失败保留旧快照与重建成功但返回空目录时清空。延伸阅读模型提供方Model providers提供方配置与模型选择。用量跟踪Usage trackingOpenClaw 用量与状态面。插件入口实现、路由目录实现、流包装与请求头、用量上报实现、Perplexity 工具 schema 规范化及对应测试目录。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考