ClawRouter

ClawRouter proporciona a OpenClaw una clave con ámbito de política para varios proveedores de modelos ascendentes. El plugin clawrouter incluido descubre únicamente los modelos permitidos para esa clave, enruta cada modelo mediante su protocolo declarado e informa del presupuesto de la clave y del uso agregado en las superficies de uso de OpenClaw.

Las credenciales ascendentes y el reenvío específico de cada proveedor permanecen en ClawRouter, por lo que nunca es necesario instalar ni autenticar cada plugin de proveedor ascendente en el host de OpenClaw. El plugin se incluye con OpenClaw (enabledByDefault: true); solo se necesita una credencial emitida por ClawRouter.

Primeros pasos

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>

Implementación no interactiva administrada

Mantenga la clave del proxy en la inyección de secretos de la carga de trabajo y almacene únicamente una SecretRef en openclaw.json. Los campos administrados canónicos son:

Por ejemplo, un controlador de implementación puede administrar este parche 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" },    },  },}

Si la implementación establece plugins.allow, conserve sus entradas existentes y añada clawrouter. Valide y aplique sin un asistente interactivo:

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

La ejecución de prueba resuelve la SecretRef, pero nunca imprime su valor. Para rotar la credencial, actualice el Secret externo que proporciona CLAWROUTER_API_KEY y reinicie la carga de trabajo del Gateway para que se cargue el nuevo entorno del proceso. El archivo de configuración y la referencia del modelo no cambian.

Para un Gateway de Docker independiente compilado desde el código fuente, ClawRouter ya está incluido en el entorno de ejecución raíz. Seleccione únicamente el plugin de canal que requiera un empaquetado separado, como OPENCLAW_EXTENSIONS=clickclack, slack o msteams; consulte imágenes compiladas desde el código fuente con plugins seleccionados. Las implementaciones de archivo/dispositivo deben empaquetar el mismo código fuente incorporado mediante su propio Pipeline de artefactos en lugar de consumir la imagen OCI.

Preparación y prueba en vivo

Estas comprobaciones demuestran límites distintos; no sustituya una por otra:

# Solo el estado del proceso de ClawRouter; no se ejercita ninguna credencial ni modelo ascendente.curl -fsS https://clawrouter.internal.example/v1/health # Solo la preparación de inicio del Gateway de OpenClaw; no se realiza ninguna llamada de modelo.curl -fsS http://127.0.0.1:18789/readyz # Descubrimiento del catálogo con ámbito de credencial.openclaw models list --all --provider clawrouter --json # Prueba mínima de inferencia real mediante el proveedor ClawRouter configurado.openclaw models status --probe --probe-provider clawrouter --probe-max-tokens 8 --json # Prueba canaria de la carga de trabajo mediante una referencia exacta de modelo concedida.openclaw agent --agent main \  --model clawrouter/openai/gpt-5.5 \  --message "Responde exactamente: CLAWROUTER_CANARY_OK" \  --json

Utilice un modelo devuelto por el catálogo con ámbito en lugar de copiar a ciegas el modelo del ejemplo. Una respuesta correcta de /readyz significa que el Gateway puede atender solicitudes; no afirma que ClawRouter, su credencial o un proveedor ascendente estén preparados. La prueba del modelo y la prueba canaria del agente son las pruebas de inferencia.

Para el diagnóstico en vivo, emita la prueba canaria e inspeccione los registros estándar del Gateway. Los diagnósticos existentes del transporte de modelos, que solo contienen metadatos, emiten líneas con esta forma:

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

El plugin envía las cabeceras acotadas X-ClawRouter-Client, X-ClawRouter-Agent-Id y X-ClawRouter-Session-Id cuando esos identificadores están disponibles. También asigna el callId de diagnóstico de la llamada al modelo (<run-id>:model:<n>) a X-Request-ID, por lo que un evento de llamada de modelo de OpenClaw puede correlacionarse con el registro de auditoría de ClawRouter que solo contiene metadatos. Los valores dentro del límite de 128 caracteres para el identificador de solicitud son idénticos. Los valores más largos conservan el sufijo :model:<n> y un hash determinista, de modo que las distintas llamadas permanezcan acotadas y puedan correlacionarse. Los metadatos estáticos de implementación, como X-ClawRouter-Project-Id, se pueden establecer en el mapa headers del proveedor. Las cabeceras de atribución de agente y sesión conservan su límite independiente de 256 caracteres. Los identificadores de solicitud automáticos que contienen caracteres fuera del conjunto de identificadores ASCII de ClawRouter utilizan la misma forma determinista acotada. Las cabeceras configuradas explícitamente, incluida cualquier variante de mayúsculas y minúsculas de X-Request-ID, prevalecen sobre los valores automáticos. El diagnóstico de transporte registra los metadatos de enrutamiento y respuesta; no registra credenciales, identificadores de solicitud, instrucciones ni respuestas generadas. El propio evento de auditoría de ClawRouter proporciona el proveedor ascendente seleccionado y el estado de retención del contenido.

Descubrimiento de modelos

GET /v1/catalog devuelve { providers: [...] }, donde cada entrada de proveedor enumera su propio models[] (con identificador ascendente, capacidades y precios) y sus rutas de solicitud compatibles. OpenClaw no incluye una segunda lista fija de modelos de ClawRouter. Un modelo del catálogo se anuncia como modelo de OpenClaw cuando:

• la política de la credencial concede su proveedor;
• el modelo del catálogo anuncia una capacidad LLM compatible (llm.responses, llm.chat, llm.messages o llm.stream con una ruta de transmisión coincidente); y
• el proveedor expone una ruta coincidente para uno de los transportes siguientes.

Añadir un modelo a un proveedor de ClawRouter compatible no requiere una versión nueva de OpenClaw: la siguiente actualización del catálogo (almacenada en caché durante 60 segundos por ámbito de credencial) lo descubre. Un modelo que necesite un nuevo protocolo de comunicación requiere primero compatibilidad en el plugin.

Plugins de protocolo y proveedor

ClawRouter administra las credenciales ascendentes; su catálogo indica a OpenClaw qué transporte utilizar, por lo que nunca es necesario instalar el plugin de autenticación de cada empresa ascendente.

El plugin también aplica las políticas correspondientes de repetición y esquema de herramientas para esas familias (compatibilidad de esquemas de herramientas de OpenAI/DeepSeek/Gemini/Perplexity; políticas de repetición nativas de Anthropic y Google Gemini). Los modelos de Perplexity reciben una reescritura estricta del esquema: se eliminan patternProperties y additionalProperties, y cada esquema de objeto declara properties, porque Perplexity rechaza los esquemas de herramientas que no los incluyen. Un proveedor del catálogo que exponga únicamente un formato de solicitud no compatible no se anuncia intencionadamente como modelo de texto de OpenClaw. Normalice esos proveedores a uno de los contratos compatibles en ClawRouter en lugar de enviar una carga incompatible.

Cuotas y uso

La respuesta /v1/usage de ClawRouter alimenta las superficies normales de uso de proveedores de OpenClaw: totales de solicitudes, tokens y gasto, además de un periodo de presupuesto mensual cuando la clave tiene un límite. Las claves sin medición siguen mostrando el uso agregado sin un periodo porcentual.

La consulta de cuotas utiliza la misma clave con ámbito que el descubrimiento de modelos. Un fallo en la consulta de cuotas no bloquea la ejecución del modelo.

Compruebe la instantánea en vivo con:

openclaw status --usageopenclaw models status

La misma instantánea del proveedor está disponible para /status en el chat y en la interfaz de uso de OpenClaw. El presupuesto se aplica a toda la política, por lo que las solicitudes realizadas por otro cliente que utilice la misma política de ClawRouter pueden cambiar el porcentaje restante.

Solución de problemas

Comportamiento de seguridad

• La detección del catálogo se limita a la clave de proxy configurada y se almacena en caché por ámbito de credenciales (directorio del agente, directorio del espacio de trabajo, id del perfil de autenticación y URL base).
• La clave de proxy se adjunta únicamente al enviar la solicitud; no se almacena en los metadatos del modelo.
• Los valores de atribución automática y correlación de solicitudes se recortan y se rechazan si contienen caracteres de control antes del envío. Los valores de atribución están limitados a 256 caracteres; los ids de solicitud, a 128.
• Los diagnósticos de transporte del modelo solo contienen metadatos y nunca incluyen la clave de proxy ni el contenido del modelo.
• Los ids de modelos nativos de Anthropic y Gemini se reescriben como sus ids de origen únicamente al enviar la solicitud.
• Las filas del catálogo no compatibles o no autorizadas se rechazan de forma segura y no se pueden seleccionar.

Contenido relacionado