ClawRouter
ClawRouter 为 OpenClaw 提供一个策略作用域的密钥,用于多个上游模型提供商。捆绑的 clawrouter 插件仅发现该密钥允许使用的模型,通过每个模型声明的协议路由请求,并在 OpenClaw 用量界面上报告该密钥的预算和聚合用量。
上游凭据和特定提供商的转发保留在 ClawRouter 中,因此你无需在 OpenClaw 主机上安装或认证每个上游提供商插件。该插件随 OpenClaw 捆绑提供(enabledByDefault: true);你只需要一个已签发的 ClawRouter 密钥。
| 属性 | 值 |
|---|---|
| 提供商 | clawrouter |
| 插件 | 捆绑(包含在 OpenClaw 中) |
| 认证 | CLAWROUTER_API_KEY |
| 默认 URL | https://clawrouter.openclaw.ai |
| 模型目录 | 通过 /v1/catalog 按凭据作用域 |
| 配额 | 通过 /v1/usage 获取月度预算和用量 |
快速开始¶
1. 获取作用域凭据
向你的 ClawRouter 管理员申请一个 ClawRouter 密钥,其策略应包含你应使用的提供商、模型和月度预算。ClawRouter 密钥在签发时仅显示一次。
2. 配置 OpenClaw
export CLAWROUTER_API_KEY="..."
openclaw onboard --auth-choice clawrouter-api-key
openclaw plugins enable clawrouter
clawrouter 已捆绑并默认启用。如果你的配置设置了 plugins.allow,请在启用它之前将 clawrouter 添加到该列表中。对于自定义部署,请将 models.providers.clawrouter.baseUrl 设置为 ClawRouter 源地址;默认值为 https://clawrouter.openclaw.ai。
3. 列出已授权的模型
请完全按照显示的方式使用返回的模型引用。它们保留上游命名空间,例如 clawrouter/openai/gpt-5.5、clawrouter/anthropic/claude-sonnet-4-6 或 clawrouter/google/gemini-3.5-flash。如果配置了 agents.defaults.modelPolicy.allow,请将每个选定的 ClawRouter 引用添加到其中。
4. 选择模型
你也可以通过 openclaw agent --model clawrouter/<provider>/<model> --message "..." 为单次运行选择一个返回的模型。
托管的非交互式部署¶
将 ClawRouter 密钥保留在工作负载的密钥注入中,并在 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.json5
试运行会解析 SecretRef,但绝不会打印其值。若要轮换 ClawRouter 密钥,请更新提供 CLAWROUTER_API_KEY 的外部 Secret,并重启网关工作负载,以加载新的进程环境。配置文件和模型引用不会改变。
对于源码构建的独立 Docker 网关,ClawRouter 已包含在根运行时中。仅选择需要单独打包的通道插件,例如 OPENCLAW_EXTENSIONS=clickclack、slack 或 msteams;参见带所选插件的源码构建镜像。归档/设备部署必须通过其自身的制品流水线打包相同的已落地源码,而不是使用 OCI 镜像。
就绪状态与实时验证¶
这些检查证明不同的边界;不要用一个替代另一个:
# ClawRouter process health only; no credential or upstream model is exercised.
curl -fsS https://clawrouter.internal.example/v1/health
# OpenClaw gateway startup readiness only; no model call is made.
curl -fsS http://127.0.0.1:18789/readyz
# Credential-scoped catalog discovery.
openclaw models list --all --provider clawrouter --json
# Minimal real inference test through the configured ClawRouter provider.
openclaw models status --probe --probe-provider clawrouter --probe-max-tokens 8 --json
# Workload canary using an exact granted model ref.
openclaw agent --agent main \
--model clawrouter/openai/gpt-5.5 \
--message "Reply exactly: CLAWROUTER_CANARY_OK" \
--json
请使用作用域目录返回的模型,而不是盲目复制示例模型。成功的 /readyz 响应表示网关可以处理请求;它并不表示 ClawRouter、ClawRouter 密钥或上游提供商已就绪。模型检查和 agent 金丝雀是推理证明。
对于实时诊断,请在网关进程中启用 OPENCLAW_DEBUG_MODEL_TRANSPORT=1,发出金丝雀请求,并检查网关日志。仅包含元数据的模型传输诊断会输出如下形式的行:
[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
在没有定向调试标志的情况下,开始记录和快速成功响应记录使用
debug;非 2xx 响应以及耗时至少一秒的响应保持为
info。参见 模型传输诊断。
当这些标识符可用时,插件会发送有界的 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 之类的静态部署元数据
可以在 provider 的 headers 映射中设置。
Agent 和 session 归因请求头保留其独立的 256 字符
限制。包含 ClawRouter ASCII 标识符集合之外字符的自动请求 ID 使用相同的确定性有界形式。
显式配置的请求头(包括 X-Request-ID 的任何大小写变体)优先于自动值。传输诊断记录路由和响应
元数据;它不会记录凭据、请求 ID、提示词或补全内容。
ClawRouter 自身的审计事件提供所选上游 provider 和
内容保留状态。
模型发现¶
GET /v1/catalog 返回 { providers: [...] },其中每个 provider 条目
列出其自身的 models[](包含上游 id、能力和定价)及其
支持的请求路由。OpenClaw 不会附带第二份固定的
ClawRouter 模型列表。当满足以下条件时,目录模型会被作为 OpenClaw 模型发布:
- ClawRouter 密钥的策略授予其 provider;
- 目录模型发布受支持的 LLM 能力(
llm.responses、llm.chat、llm.messages,或带有匹配流式路由的llm.stream);并且 - provider 为以下传输之一暴露了匹配的路由。
向受支持的 ClawRouter provider 添加模型无需发布 OpenClaw。 成功的目录响应(包括空的已授权模型列表)会按每个 endpoint 和已解析凭据复用一小时。常规模型列表读取 会提供保留的库存,同时过期数据在后台刷新。在 Models 中使用 Refresh 可立即发现变更;显式刷新会绕过 响应缓存。需要新 wire protocol 的模型首先要求插件 支持。缓存库存不是授权:当模型请求被分发时,ClawRouter 会检查当前 授权和预算。
模型的可选 displayName 是其选择器标签;如果没有它,OpenClaw 会使用
provider 显示名称和目录 id,并从标签中省略重复的 <provider>/
前缀(例如 Anthropic · claude-sonnet-4-6)。标签从不改变模型
身份。Responses 和 Chat Completions 会原样发送目录 id;
只有原生 Anthropic 和 Gemini 路由在分发时使用 upstream。暴露
别名的 facade 必须只返回安全的目录元数据,包括在必需的 upstream 字段中包含该
别名,并将其私有目标映射保留在 facade 内部。
协议和 provider 插件¶
ClawRouter 拥有上游凭据;其目录告诉 OpenClaw 使用哪种 传输,因此你无需安装每个上游公司的 auth 插件。
| 目录能力 / 路由 | OpenClaw 传输 |
|---|---|
llm.responses(OpenAI 兼容 provider) |
openai-responses |
llm.chat(OpenAI 兼容 provider) |
openai-completions |
llm.messages + anthropic.messages 路由 |
anthropic-messages |
llm.stream + 流式 google.generate_content 路由 |
google-generative-ai |
该插件还会为这些家族应用匹配的 replay 和 tool-schema 策略
(OpenAI/DeepSeek/Gemini/Perplexity 的 tool-schema 兼容;原生
Anthropic 和 Google Gemini 的 replay 策略)。Perplexity 模型会进行严格的
schema 重写:移除 patternProperties 和 additionalProperties,并且
每个 object schema 都声明 properties,因为 Perplexity 会拒绝缺少 properties 的 tool
schema。仅暴露不受支持请求格式的目录 provider 有意不会被作为 OpenClaw
文本模型发布。在 ClawRouter 中将这些 provider 规范化为受支持的契约之一,
而不是发送不兼容的 payload。
配额和用量¶
ClawRouter 的 /v1/usage 响应会填充常规 OpenClaw provider 用量
界面:请求、token 和支出总计,以及当密钥有限制时的月度预算窗口。未计量密钥仍会显示聚合用量,但没有
百分比窗口。
配额查询使用与模型发现相同的 ClawRouter 密钥。配额查询失败不会阻止模型执行。
使用以下命令检查实时快照:
相同的 provider 快照可用于聊天中的 /status 和 OpenClaw 的
用量 UI。预算是策略范围的,因此使用相同 ClawRouter 策略的其他客户端发出的请求可能会改变剩余百分比。
故障排查¶
| 症状 | 检查项 |
|---|---|
| 没有 ClawRouter 模型 | 确认插件已启用并被 plugins.allow 允许,然后检查 ClawRouter 密钥处于活动状态,并授予至少一个就绪 provider。 |
| 现象 | 检查 |
|---|---|
| 已配置的 ClawRouter 模型缺失 | 检查其 /v1/catalog 能力和路由支持。不受支持的传输契约会被有意过滤。 |
| 模型覆盖被策略拒绝 | 将精确的目录引用或 clawrouter/* 添加到 agents.defaults.modelPolicy.allow。 |
401 或 403 来自目录或用量 |
重新签发或重新限定 ClawRouter 密钥的作用范围;OpenClaw 不会回退到上游提供商密钥。 |
| 发现后模型调用失败 | 检查 ClawRouter 中的提供商连接和上游健康状况,然后在其就绪状态恢复后重试。 |
| 用量有总计但没有百分比 | 该策略未计量;在 ClawRouter 中添加月度预算以显示百分比窗口。 |
安全行为¶
- 目录发现的范围限定为已配置的 ClawRouter 密钥。HTTP 响应按端点和已解析凭据缓存;更改其中任一项都不会复用之前的响应。预置清单和动态模型查找保留各自的 agent、workspace 和 auth 范围。
- ClawRouter 密钥仅在请求分发时附加;不会存储在模型元数据中。
- 自动归因和请求关联值在分发前会被修剪并拒绝控制字符。归因值限制为 256 个字符;请求 ID 限制为 128 个字符。
- 模型传输诊断仅包含元数据,绝不包含 ClawRouter 密钥或模型内容。
- 原生 Anthropic 和 Gemini 模型 ID 仅在分发时重写为其上游 ID。
- 不受支持或未授权的目录行会失败关闭且不可选择。
相关¶
提供商配置和模型选择。
OpenClaw 用量和状态界面。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw