ClawRouter

O ClawRouter fornece ao OpenClaw uma chave com escopo de política para vários provedores de modelos upstream. O plugin clawrouter incluído descobre apenas os modelos permitidos para essa chave, encaminha cada modelo por meio do protocolo declarado e informa o orçamento da chave e o uso agregado nas superfícies de uso do OpenClaw.

As credenciais upstream e o encaminhamento específico de cada provedor permanecem no ClawRouter, portanto nunca é necessário instalar nem autenticar o plugin de cada provedor upstream no host do OpenClaw. O plugin é fornecido com o OpenClaw (enabledByDefault: true); é necessária apenas uma credencial emitida pelo ClawRouter.

Primeiros passos

export CLAWROUTER_API_KEY="..."openclaw onboard --auth-choice clawrouter-api-keyopenclaw plugins enable clawrouter

openclaw models list --all --provider clawrouter

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

Implantação não interativa gerenciada

Mantenha a chave do proxy na injeção de segredos da carga de trabalho e armazene apenas uma SecretRef em openclaw.json. Os campos gerenciados canônicos são:

Por exemplo, um controlador de implantação pode gerenciar este patch 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" },    },  },}

Se a implantação definir plugins.allow, preserve as entradas existentes e adicione clawrouter. Valide e aplique sem um assistente interativo:

openclaw config patch --file ./clawrouter.patch.json5 --dry-run --jsonopenclaw config patch --file ./clawrouter.patch.json5

A simulação resolve a SecretRef, mas nunca imprime seu valor. Para alternar a credencial, atualize o Secret externo que fornece CLAWROUTER_API_KEY e reinicie a carga de trabalho do Gateway para que o novo ambiente do processo seja carregado. O arquivo de configuração e a referência do modelo não são alterados.

Para um Gateway Docker independente compilado a partir do código-fonte, o ClawRouter já está incluído no runtime raiz. Selecione apenas o plugin de canal que precisa de empacotamento separado, como OPENCLAW_EXTENSIONS=clickclack, slack ou msteams; consulte imagens compiladas a partir do código-fonte com plugins selecionados. Implantações de arquivo/appliance devem empacotar o mesmo código-fonte integrado por meio de seu próprio pipeline de artefatos, em vez de consumir a imagem OCI.

Prontidão e comprovação em produção

Estas verificações comprovam limites diferentes; não substitua uma por outra:

# Apenas a integridade do processo do ClawRouter; nenhuma credencial ou modelo upstream é exercitado.curl -fsS https://clawrouter.internal.example/v1/health # Apenas a prontidão de inicialização do Gateway do OpenClaw; nenhuma chamada de modelo é feita.curl -fsS http://127.0.0.1:18789/readyz # Descoberta do catálogo com escopo de credencial.openclaw models list --all --provider clawrouter --json # Sondagem mínima de inferência real por meio do provedor ClawRouter configurado.openclaw models status --probe --probe-provider clawrouter --probe-max-tokens 8 --json # Canary da carga de trabalho usando uma referência exata de modelo concedido.openclaw agent --agent main \  --model clawrouter/openai/gpt-5.5 \  --message "Responda exatamente: CLAWROUTER_CANARY_OK" \  --json

Use um modelo retornado pelo catálogo com escopo, em vez de copiar o modelo de exemplo sem verificar. Uma resposta /readyz bem-sucedida significa que o Gateway pode atender a solicitações; ela não afirma que o ClawRouter, sua credencial ou um provedor upstream esteja pronto. A sondagem do modelo e o canary do agente são as comprovações de inferência.

Para diagnóstico em produção, execute o canary e inspecione os logs padrão do Gateway. Os diagnósticos existentes de transporte de modelo somente com metadados emitem linhas com o seguinte formato:

[model-fetch] início provider=clawrouter api=openai-responses model=openai/gpt-5.5 method=POST url=https://clawrouter.internal.example/v1/responses[model-fetch] resposta provider=clawrouter api=openai-responses model=openai/gpt-5.5 status=200

O plugin envia os cabeçalhos limitados X-ClawRouter-Client, X-ClawRouter-Agent-Id e X-ClawRouter-Session-Id quando esses identificadores estão disponíveis. Ele também mapeia o callId de diagnóstico da chamada do modelo (<run-id>:model:<n>) para X-Request-ID, para que um evento de chamada de modelo do OpenClaw possa ser correlacionado com a trilha de auditoria somente com metadados do ClawRouter. Valores dentro do limite de 128 caracteres do ID da solicitação são idênticos. Valores mais longos mantêm o sufixo :model:<n> e um hash determinístico, para que chamadas distintas permaneçam limitadas e correlacionáveis. Metadados estáticos da implantação, como X-ClawRouter-Project-Id, podem ser definidos no mapa headers do provedor. Os cabeçalhos de atribuição de agente e sessão mantêm seu limite separado de 256 caracteres. IDs de solicitação automáticos que contêm caracteres fora do conjunto de identificadores ASCII do ClawRouter usam a mesma forma determinística e limitada. Cabeçalhos configurados explicitamente, incluindo qualquer variação de maiúsculas e minúsculas de X-Request-ID, têm precedência sobre os valores automáticos. O diagnóstico de transporte registra metadados de roteamento e resposta; ele não registra credenciais, IDs de solicitação, prompts nem conclusões. O próprio evento de auditoria do ClawRouter fornece o provedor upstream selecionado e o estado de retenção de conteúdo.

Descoberta de modelos

GET /v1/catalog retorna { providers: [...] }, em que cada entrada de provedor lista seus próprios models[] (com ID upstream, recursos e preços) e suas rotas de solicitação compatíveis. O OpenClaw não fornece uma segunda lista fixa de modelos do ClawRouter. Um modelo do catálogo é anunciado como modelo do OpenClaw quando:

• a política da credencial concede acesso ao provedor;
• o modelo do catálogo anuncia um recurso de LLM compatível (llm.responses, llm.chat, llm.messages ou llm.stream com uma rota de streaming correspondente); e
• o provedor expõe uma rota correspondente para um dos transportes abaixo.

Adicionar um modelo a um provedor ClawRouter compatível não requer uma versão do OpenClaw: a próxima atualização do catálogo (armazenada em cache por 60 segundos por escopo de credencial) o descobre. Um modelo que precisa de um novo protocolo de comunicação requer primeiro suporte do plugin.

Plugins de protocolo e provedor

O ClawRouter gerencia as credenciais upstream; seu catálogo informa ao OpenClaw qual transporte usar, portanto nunca é necessário instalar o plugin de autenticação de cada empresa upstream.

O plugin também aplica as políticas correspondentes de repetição e esquema de ferramentas para essas famílias (compatibilidade de esquema de ferramentas do OpenAI/DeepSeek/Gemini/Perplexity; políticas nativas de repetição do Anthropic e Google Gemini). Os modelos do Perplexity recebem uma reescrita rigorosa do esquema: patternProperties e additionalProperties são removidos, e cada esquema de objeto declara properties, pois o Perplexity rejeita esquemas de ferramentas sem eles. Um provedor do catálogo que expõe apenas um formato de solicitação incompatível não é anunciado intencionalmente como um modelo de texto do OpenClaw. Normalize esses provedores para um dos contratos compatíveis no ClawRouter, em vez de enviar uma carga incompatível.

Cotas e uso

A resposta /v1/usage do ClawRouter alimenta as superfícies normais de uso do provedor no OpenClaw: totais de solicitações, tokens e gastos, além de uma janela de orçamento mensal quando a chave tem um limite. Chaves sem medição ainda exibem o uso agregado sem uma janela percentual.

A consulta de cotas usa a mesma chave com escopo que a descoberta de modelos. Uma falha na consulta de cotas não bloqueia a execução do modelo.

Verifique o instantâneo em produção com:

openclaw status --usageopenclaw models status

O mesmo instantâneo do provedor está disponível para /status no chat e na interface de uso do OpenClaw. O orçamento abrange toda a política, portanto solicitações feitas por outro cliente usando a mesma política do ClawRouter podem alterar o percentual restante.

Solução de problemas

Comportamento de segurança

• A descoberta do catálogo é limitada à chave de proxy configurada e armazenada em cache por escopo de credencial (diretório do agente, diretório do espaço de trabalho, id do perfil de autenticação e URL base).
• A chave de proxy é anexada somente no envio da solicitação; ela não é armazenada nos metadados do modelo.
• Os valores automáticos de atribuição e correlação de solicitações têm os espaços em branco removidos das extremidades e são rejeitados se contiverem caracteres de controle antes do envio. Os valores de atribuição são limitados a 256 caracteres; os ids de solicitação são limitados a 128.
• Os diagnósticos de transporte do modelo contêm apenas metadados e nunca incluem a chave de proxy nem o conteúdo do modelo.
• Os ids de modelos nativos da Anthropic e do Gemini são reescritos para seus ids de upstream somente no envio.
• As linhas do catálogo sem suporte ou sem permissão falham de forma segura e não podem ser selecionadas.

Relacionados