跳转至

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

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。规范化的托管字段如下:

用途 配置或环境字段
路由器源 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 密钥。配额查询失败不会阻止模型执行。

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

openclaw status --usage
openclaw models status

相同的 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