AgentRouter Setup Guide (Español)

Avanzado: conexión mediante el tipo de proveedor compatible con Claude Code

OmniRoute también admite AgentRouter (y servicios de retransmisión similares) mediante el tipo de proveedor compatible con Claude Code (anthropic-compatible-cc-*), que utiliza la API Messages de Anthropic con el formato de comunicación correcto. Un proveedor genérico openai-compatible-chat que apunte a https://agentrouter.org no funcionará: el WAF del servicio ascendente rechaza las solicitudes que no parecen proceder de Claude Code.

---

Requisitos previos

• Una cuenta y una clave de API de AgentRouter. Los nuevos registros reciben créditos gratuitos mediante el enlace de afiliado incluido en el README del proyecto.
• OmniRoute ejecutándose con la opción de funcionalidad ENABLE_CC_COMPATIBLE_PROVIDER habilitada (consulta la sección siguiente).

1. Habilitar el tipo de proveedor compatible con CC

El tipo de proveedor compatible con Claude Code está protegido por una opción de funcionalidad porque envía tráfico que imita fielmente al cliente oficial de Claude Code. Habilítalo estableciendo una variable de entorno antes de iniciar OmniRoute:

ENABLE_CC_COMPATIBLE_PROVIDER=true

Ejemplo con Docker:

docker run -d --name omniroute \
  --restart unless-stopped \
  -p 20128:20128 \
  -v omniroute-data:/app/data \
  -e ENABLE_CC_COMPATIBLE_PROVIDER=true \
  diegosouzapw/omniroute:latest

Después de reiniciar, el panel de control muestra una opción Añadir compatible con Claude Code además de los flujos existentes compatibles con OpenAI y Anthropic.

2. Crear el proveedor en el panel de control

1. Abre Panel de control → Proveedores → Añadir proveedor.
2. Elige Añadir compatible con Claude Code (solo es visible cuando se ha establecido la opción anterior).
3. Completa los campos:

Campo	Valor
Nombre	AgentRouter (o cualquier etiqueta)
Prefijo	agentrouter (alias descriptivo mostrado en los registros y el panel de control)
URL base	https://agentrouter.org
Ruta de chat	/v1/messages?beta=true (predeterminada; déjala como está)

El identificador canónico del modelo sigue usando el ID completo del nodo del proveedor (anthropic-compatible-cc-{uuid}/{model}). El Prefijo es solo un alias de visualización que src/lib/usage/callLogs.ts resuelve para ofrecer una salida de registro más legible.

4. (Opcional) Pega tu clave de API en el campo Validar y haz clic en Comprobar para confirmar la conectividad antes de guardar.
5. Haz clic en Añadir.

Una vez creado, abre el proveedor y añade una Conexión con tu clave de API de AgentRouter (sk-...). El test_status de la conexión debería cambiar a active.

3. Úsalo mediante un combo o directamente

Haz referencia al modelo utilizando el prefijo de tu proveedor como espacio de nombres:

curl -X POST http://localhost:20128/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agentrouter/claude-opus-4-6",
    "messages": [{"role": "user", "content": "hello"}],
    "max_tokens": 100
  }'

El ID canónico del modelo anthropic-compatible-cc-{uuid}/claude-opus-4-6 también funciona y es el que aparece en la base de datos y en la configuración del combo.

También puedes añadirlo a un combo para gestionar el enrutamiento, la conmutación por error y las cuotas, como con cualquier otro proveedor.

---

Detalles de la imagen de conexión

Como referencia, el puente compatible con cc envía lo siguiente en cada solicitud ascendente (consulta open-sse/services/claudeCodeCompatible.ts):

Encabezado	Valor
Authorization	Bearer <api-key>
User-Agent	claude-cli/2.1.258 (external, sdk-cli)
anthropic-version	2023-06-01
anthropic-beta	claude-code-20250219,interleaved-thinking-2025-05-14,effort-2025-11-24
Opción beta por conexión para ocultar el razonamiento	Añade redact-thinking-2026-02-12 para los servicios ascendentes que requieren específicamente flujos de razonamiento ocultos
Opción por conexión para resumir el razonamiento	Añade display: "summarized" a las solicitudes de razonamiento de CC Compatible que aún no hayan establecido un modo de visualización
anthropic-dangerous-direct-browser-access	true
x-app	cli
X-Stainless-*	Diversos encabezados del SDK de Stainless (lenguaje, versión del paquete, SO, arquitectura, etc.)

Esto es lo que permite que las solicitudes superen el WAF ascendente y la lista de clientes permitidos.

---

Solución de problemas

{"error":{"message":"unauthorized client detected, ..."}} — Tu solicitud no coincidió con la imagen de conexión de Claude Code. Esto sucede cuando el proveedor está configurado como openai-compatible-chat en lugar de anthropic-compatible-cc, o cuando la opción ENABLE_CC_COMPATIBLE_PROVIDER=true no se estableció al iniciar.

{"error":{"message":"无效的令牌","type":"new_api_error"}} (HTTP 401) — «Token no válido». La imagen de conexión es correcta, pero la clave de API ha sido rechazada. Genera una clave nueva en el panel de AgentRouter y actualiza la conexión.

{"error":{"code":"content-blocked","type":"agent_router_api_error"}} (HTTP 400) — El mecanismo de moderación de AgentRouter rechazó el contenido de la solicitud, o el plan de la clave no permite usar el modelo solicitado. Prueba con otro prompt o modelo; contacta con el soporte de AgentRouter si un prompt inocuo se bloquea sistemáticamente.

[400]: content-blocked solo en modelos específicos — La mayoría de los planes de AgentRouter solo permiten un subconjunto de modelos (p. ej., claude-opus-4-6). Otros ID de modelo devuelven unauthorized_client_error aunque la clave sea válida. Comprueba qué modelos cubre tu plan en el panel de AgentRouter.

Invalid JSON response from provider (reset after Ns) en los registros de omniroute — El servicio ascendente devolvió un cuerpo que no era JSON (normalmente, una página de error HTML del WAF). Esto suele significar que la solicitud nunca llegó al backend de AgentRouter; vuelve a comprobar que el ID del proveedor comience por anthropic-compatible-cc- (ten en cuenta el guion final; consulta CLAUDE_CODE_COMPATIBLE_PREFIX en open-sse/services/claudeCodeCompatible.ts) y que la opción de funcionalidad esté habilitada.

unauthorized client detected / página de error HTML aunque ya exista un proveedor de AgentRouter — Probablemente tienes más de un proveedor de AgentRouter y tu solicitud está llegando al incorrecto. Si se creó previamente un proveedor manual anthropic-compatible-* (sin cc) u openai-compatible-chat-* con el prefijo agentrouter, este puede apropiarse de los ID de modelo agentrouter/<model> (y los combos pueden hacer referencia a él mediante el ID de nodo), por lo que el tráfico se enruta a ese proveedor, que envía un User-Agent genérico y es rechazado, en lugar de al proveedor integrado agentrouter, que ya incluye la imagen de conexión correcta. Comprueba dónde se resuelve realmente el modelo en los registros de omniroute (la etiqueta ROUTING muestra agentrouter/<model> → <providerId>/<model>); si <providerId> no es agentrouter, consolida la configuración en el proveedor nativo: haz que los combos apunten a agentrouter/<model> (providerId agentrouter) y elimina los proveedores compatibles duplicados. El proveedor nativo no necesita configurar la imagen de conexión ni customUserAgent.

---

Véase también

• docs/providers/CLAUDE_WEB.md — Notas sobre la integración del proveedor Claude Web
• docs/reference/FREE_TIERS.md — Catálogo de proveedores con nivel gratuito
• open-sse/services/claudeCodeCompatible.ts — Implementación de imágenes mediante protocolo de comunicación

---

Código fuente de OmniRoute (a58000c7685f)