ClawRouter

ClawRouter 为 OpenClaw 提供一个策略范围限定的密钥，用于多个上游模型提供商。内置的 clawrouter 插件仅发现该密钥允许使用的模型，通过其声明的协议路由每个模型，并在 OpenClaw 使用量界面中报告该密钥的预算和聚合使用量。

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

快速入门¶

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. 列出已授权模型

openclaw models list --all --provider clawrouter

请完全按照显示的内容使用返回的模型引用。它们保留上游命名空间，例如 clawrouter/openai/gpt-5.5、clawrouter/anthropic/claude-sonnet-4-6 或 clawrouter/google/gemini-3.5-flash。如果配置了 agents.defaults.modelPolicy.allow，请将每个选定的 ClawRouter 引用添加到其中。

4. 选择模型

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

你也可以使用 openclaw agent --model clawrouter/<provider>/<model> --message "..." 为单次运行选择一个返回的模型。

托管式非交互式部署¶

将 ClawRouter 密钥保留在工作负载的机密注入中，并在 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 --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 probe 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 密钥或上游提供商已就绪。模型探测和代理金丝雀是推理证明。

对于实时诊断，请在网关进程中启用 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 的静态部署元数据可以在提供商 headers 映射中设置。 代理和会话归因请求头保留其独立的 256 字符限制。包含 ClawRouter ASCII 标识符集合之外字符的自动请求 ID 使用相同的确定性有界形式。 显式配置的请求头（包括 X-Request-ID 的任何大小写变体）优先于自动值。传输诊断记录路由和响应元数据；它不会记录凭据、请求 ID、提示词或补全内容。 ClawRouter 自身的审计事件提供所选上游提供商和内容保留状态。

模型发现¶

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

• ClawRouter 密钥的策略授权了其提供商；
• 目录模型宣告了受支持的 LLM 能力（llm.responses、llm.chat、llm.messages，或带有匹配流式路由的 llm.stream）；并且
• 提供商为以下任一传输暴露了匹配的路由。

向受支持的 ClawRouter 提供商添加模型无需 OpenClaw 发布：下一次目录刷新（按 ClawRouter 密钥作用域缓存 60 秒）会发现它。需要新线路协议的模型首先要求插件支持。

模型的可选 displayName 是其选择器标签；如果没有它，OpenClaw 会使用提供商显示名称和目录 id，并从标签中省略重复的 <provider>/ 前缀（例如，Anthropic · claude-sonnet-4-6）。标签从不改变模型身份。Responses 和 Chat Completions 会原样发送目录 id；只有原生 Anthropic 和 Gemini 路由在分发时使用 upstream。暴露别名的门面必须只返回安全的目录元数据，包括在必需的 upstream 字段中包含该别名，并将其私有目标映射保留在门面内部。

协议与提供商插件¶

ClawRouter 拥有上游凭据；其目录会告诉 OpenClaw 使用哪种传输，因此你无需安装每个上游公司的认证插件。

插件还会为这些家族应用匹配的重放和工具 schema 策略（OpenAI/DeepSeek/Gemini/Perplexity 工具 schema 兼容；原生 Anthropic 和 Google Gemini 重放策略）。Perplexity 模型会进行严格的 schema 重写：移除 patternProperties 和 additionalProperties，并且每个对象 schema 都声明 properties，因为 Perplexity 会拒绝没有它们的工具 schema。仅暴露不受支持请求格式的目录提供商有意不会被宣告为 OpenClaw 文本模型。应在 ClawRouter 中将那些提供商规范化为受支持的契约之一，而不是发送不兼容的负载。

配额与用量¶

ClawRouter 的 /v1/usage 响应会填充常规的 OpenClaw 提供商用量界面：请求、token 和支出总计，以及当密钥有限制时的月度预算窗口。未计量密钥仍会显示聚合用量，但没有百分比窗口。

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

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

openclaw status --usage
openclaw models status

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

故障排查¶

安全行为¶

• 目录发现的范围限定为已配置的 ClawRouter 密钥。结果按 ClawRouter 密钥作用域缓存（agent dir、workspace dir、auth profile id 和 base URL）。
• ClawRouter 密钥仅在请求分发时附加；它不会存储在模型元数据中。
• 自动归因和请求关联值在分发前会被修剪并拒绝控制字符。归因值限制为 256 个字符；请求 id 限制为 128 个字符。
• 模型传输诊断仅包含元数据，且从不包含 ClawRouter 密钥或模型内容。
• 原生 Anthropic 和 Gemini 模型 id 仅在分发时重写为其上游 id。
• 不受支持或未授权的目录行会失败关闭，且不可选择。

相关¶

模型提供商

提供商配置和模型选择。

用量跟踪

OpenClaw 用量和状态界面。