ClawRouter

ClawRouter proporciona a OpenClaw una clave con ámbito de política para varios proveedores de modelos ascendentes. El plugin clawrouter incluido detecta ú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 necesita una credencial de ClawRouter emitida.

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>

Despliegue administrado no interactivo

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 despliegue puede ser propietario de 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 el despliegue define 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 secreto 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 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. Los despliegues de archivo o dispositivo deben empaquetar el mismo código fuente incorporado mediante su propia canalización de artefactos, en lugar de consumir la imagen OCI.

Preparación y prueba en vivo

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

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

Utilice un modelo devuelto por el catálogo con ámbito definido en lugar de copiar ciegamente 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 de disponibilidad del agente constituyen las pruebas de inferencia.

Para realizar un diagnóstico en vivo, ejecute la prueba de disponibilidad e inspeccione los registros estándar del Gateway. Los diagnósticos existentes del transporte de modelos, que solo incluyen metadatos, emiten líneas con este formato:

[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

El plugin envía las cabeceras delimitadas 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, de modo que un evento de llamada a un modelo de OpenClaw pueda vincularse con el registro de auditoría de ClawRouter que solo contiene metadatos. Los valores dentro del límite de 128 caracteres del identificador de solicitud son idénticos. Los valores más largos conservan el sufijo :model:<n> y un hash determinista para que las llamadas distintas permanezcan delimitadas y puedan vincularse. Los metadatos estáticos del despliegue, como X-ClawRouter-Project-Id, pueden establecerse en el mapa headers del proveedor. Las cabeceras de atribución del agente y de la 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 y delimitada. Las cabeceras configuradas explícitamente, incluida cualquier variante de mayúsculas y minúsculas de X-Request-ID, tienen prioridad sobre los valores automáticos. El diagnóstico del 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 conservación del contenido.

Detección de modelos

GET /v1/catalog devuelve { providers: [...] }, donde cada entrada de proveedor enumera sus propios 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 acceso a su proveedor;
• el modelo del catálogo anuncia una capacidad de 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 compatible de ClawRouter 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 detecta. 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 debe 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 coincidentes de reproducción y esquema de herramientas para esas familias (compatibilidad de esquemas de herramientas de OpenAI/DeepSeek/Gemini; políticas nativas de reproducción de Anthropic y Google Gemini). 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 de /v1/usage de ClawRouter alimenta las superficies normales de uso de proveedores de OpenClaw: totales de solicitudes, tokens y gasto, además de una ventana de presupuesto mensual cuando la clave tiene un límite. Las claves sin medición siguen mostrando el uso agregado sin una ventana porcentual.

La consulta de cuotas utiliza la misma clave con ámbito definido que la detección de modelos. Un fallo en la consulta de cuotas no bloquea la ejecución de modelos.

Consulte 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 del 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 del 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 identificadores de solicitud, a 128.
• Los diagnósticos de transporte del modelo solo contienen metadatos y nunca incluyen la clave del proxy ni el contenido del modelo.
• Los identificadores de modelos nativos de Anthropic y Gemini se reescriben con sus identificadores de origen únicamente al enviarse.
• Las filas del catálogo no compatibles o no autorizadas se bloquean de forma segura y no se pueden seleccionar.

Relacionado