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` 获取月度预算和用量

入门指南

获取范围受限的凭证

向 ClawRouter 管理员申请凭证，其策略应包含你需要使用的提供商、模型和月度预算。凭证签发时只会显示一次。

配置 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。

列出获准使用的模型

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 引用添加到其中。

选择模型

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

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

托管式非交互部署

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

用途	配置或环境字段
路由器源站	`models.providers.clawrouter.baseUrl`
凭证	`models.providers.clawrouter.apiKey` -> 环境变量 SecretRef
密钥值	Gateway 网关进程环境中的 `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_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 "仅回复：CLAWROUTER_CANARY_OK" \
  --json

请使用范围受限目录返回的模型，不要直接照搬示例模型。成功的 /readyz 响应表示 Gateway 网关可以处理请求；这并不表示 ClawRouter、其凭证或上游提供商已就绪。模型探测和 Agent 金丝雀测试才是推理验证。进行实时诊断时，请发起金丝雀测试并检查 Gateway 网关的标准日志。现有仅含元数据的模型传输诊断会输出如下形式的行：

[model-fetch] 启动 provider=clawrouter api=openai-responses model=openai/gpt-5.5 method=POST url=https://clawrouter.internal.example/v1/responses
[model-fetch] 响应 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> 后缀和确定性哈希，使不同调用在长度受限的同时仍可关联。静态部署元数据（例如 X-ClawRouter-Project-Id）可以在提供商的 headers 映射中设置。 Agent 和会话归因请求头各自保留 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 使用哪种传输方式，因此无需安装每家上游公司的身份验证插件。

目录能力/路由	OpenClaw 传输方式
`llm.responses`（OpenAI 兼容提供商）	`openai-responses`
`llm.chat`（OpenAI 兼容提供商）	`openai-completions`
`llm.messages` + `anthropic.messages` 路由	`anthropic-messages`
`llm.stream` + 流式 `google.generate_content` 路由	`google-generative-ai`

插件还会为这些系列应用匹配的重放和工具架构策略（OpenAI/DeepSeek/Gemini/Perplexity 工具架构兼容策略；原生 Anthropic 和 Google Gemini 重放策略）。Perplexity 模型会进行严格的架构重写：移除 patternProperties 和 additionalProperties，并且每个对象架构都会声明 properties，因为 Perplexity 会拒绝缺少这些声明的工具架构。如果某个目录提供商仅公开不受支持的请求格式，则有意不将其公布为 OpenClaw 文本模型。应在 ClawRouter 中将这些提供商规范化为受支持的合约之一，而不是发送不兼容的负载。

配额和用量

ClawRouter 的 /v1/usage 响应会填充常规 OpenClaw 提供商用量界面：请求、token 和支出总计；当密钥设置了限制时，还会显示月度预算周期。未计量密钥仍会显示汇总用量，但不会显示百分比周期。配额查询使用与模型发现相同的范围受限密钥。配额查询失败不会阻止模型执行。使用以下命令检查实时快照：

openclaw status --usage
openclaw models status

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

故障排查

症状	检查
没有 ClawRouter 模型	确认插件已启用且获 `plugins.allow` 允许，然后检查凭证是否有效，并且是否授予了至少一个就绪提供商的访问权限。
已配置的 ClawRouter 模型缺失	检查其 `/v1/catalog` 能力和路由支持情况。不受支持的传输合约会被有意过滤。
模型覆盖被策略拒绝	将确切的目录引用或 `clawrouter/*` 添加到 `agents.defaults.modelPolicy.allow`。
目录或用量返回 `401` 或 `403`	重新签发 ClawRouter 凭证或调整其范围；OpenClaw 不会回退到上游提供商密钥。
模型发现后调用失败	检查 ClawRouter 中的提供商连接和上游健康状况，然后在其就绪状态恢复后重试。
用量有总计但没有百分比	该策略未计量；在 ClawRouter 中添加月度预算以显示百分比周期。

安全行为

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

模型提供商

提供商配置和模型选择。

用量跟踪

OpenClaw 用量和状态界面。

概览

模型概念

提供商

入门指南

托管式非交互部署

就绪状态和实时验证

模型发现

协议和提供商插件

配额和用量

故障排查

安全行为

相关内容

模型提供商

用量跟踪

​入门指南

​托管式非交互部署

​就绪状态和实时验证

​模型发现

​协议和提供商插件

​配额和用量

​故障排查

​安全行为

​相关内容

模型提供商

用量跟踪

入门指南

托管式非交互部署

就绪状态和实时验证

模型发现

协议和提供商插件

配额和用量

故障排查

安全行为

相关内容