Saltar al contenido principal

Usar InferNode desde Claude Code

Claude Code usa el formato Anthropic Messages. Para trabajar con la API de Chat Completions de InferNode, esta receta utiliza Claude Code Router como traductor local: Claude Code se conecta al router y este llama a InferNode con tu llave. No utiliza LiteLLM.

Se comprobó con Claude Code 2.1.314 y Claude Code Router 3.1.3: generación y lectura de archivos mediante herramientas con Saptiva Turbo, Saptiva Omni y Saptiva Cortex. Son tres alias independientes. La integración con modelos no-Claude no tiene soporte oficial de Anthropic; las pruebas no cubren todas las funciones del agente.

Antes de empezar​

Necesitas Claude Code instalado, Node.js 22 o superior, Python 3, jq, una llave de InferNode y la URL de tu instalación. Los comandos usan Bash; ejecuta bash si tu terminal usa otro intérprete. Instala la versión comprobada del router:

npm install -g @musistudio/claude-code-router@3.1.3
claude --version

Usa una terminal dedicada a esta conexión. Las variables que definirás cambian el proveedor de Claude Code en esa terminal y en los procesos que abras desde ella.

1. Verifica InferNode y los alias​

Reemplaza el dominio de ejemplo. Pega la llave cuando se solicite; no se muestra ni se escribe en el historial:

export INFERNODE_BASE_URL='https://api.<tu-dominio>/infernode/v1'
read -r -s -p 'InferNode API key: ' INFERNODE_API_KEY
printf '\n'
export INFERNODE_API_KEY
curl --fail-with-body -sS "$INFERNODE_BASE_URL/me" \
-H "Authorization: Bearer $INFERNODE_API_KEY"

Consulta el catálogo antes de configurar el router:

curl --fail-with-body -sS "$INFERNODE_BASE_URL/models/aliases" \
-H "Authorization: Bearer $INFERNODE_API_KEY" \
| jq '.data[] | {alias, model: .model.id, context: .model.context_window}'

Copia los alias exactos, con mayúsculas y espacios. El modelo físico y sus límites pueden cambiar detrás de cada alias. Si tu instalación no ofrece alguno de ellos, omítelo de los ejemplos. Para confirmar acceso, la consulta a GET /v1/me debe devolver tu usuario y organización.

2. Configura un router local nuevo​

Este paso es para una instalación nueva de Claude Code Router. Si ya lo usas y existe ~/.claude-code-router/config.sqlite, agrega el proveedor desde su interfaz de administración y conserva tus proveedores actuales. Crea o recupera allí un token de acceso al gateway y guárdalo en ~/.config/saptiva/router-token, con permisos 600. Con el router activo, omite el resto de este paso y continúa en el paso 3; ajusta ANTHROPIC_BASE_URL si tu gateway usa otro puerto. No reemplaces la base de datos ni esperes que editar el archivo inicial cambie una configuración ya importada.

Crea un token privado para la conexión entre Claude Code y el router. Es distinto de tu llave de InferNode:

umask 077
mkdir -p ~/.config/saptiva ~/.claude-code-router
if [ ! -s ~/.config/saptiva/router-token ]; then
python3 -c 'import secrets; print(secrets.token_urlsafe(32))' \
> ~/.config/saptiva/router-token
fi
chmod 600 ~/.config/saptiva/router-token
export SAPTIVA_ROUTER_TOKEN="$(cat ~/.config/saptiva/router-token)"

Crea ~/.claude-code-router/config.json con este contenido, sin reemplazar un archivo que ya uses:

~/.claude-code-router/config.json
{
"HOST": "127.0.0.1",
"PORT": 3456,
"APIKEY": "${SAPTIVA_ROUTER_TOKEN}",
"Providers": [
{
"name": "infernode",
"api_base_url": "${INFERNODE_BASE_URL}",
"api_key": "${INFERNODE_API_KEY}",
"models": [
"Saptiva Turbo",
"Saptiva Omni",
"Saptiva Cortex"
],
"autoFetchModels": false,
"capabilities": [
{
"type": "openai_chat_completions",
"baseUrl": "${INFERNODE_BASE_URL}"
}
],
"account": {
"enabled": false
}
}
],
"preferredProvider": "infernode",
"Router": {
"builtInRules": {
"claude-code": {
"enabled": false
},
"codex": {
"enabled": false
}
},
"fallback": {
"mode": "off",
"models": [],
"retryCount": 0
},
"rules": []
},
"profile": {
"enabled": false,
"profiles": []
},
"observability": {
"requestLogs": false,
"agentAnalysis": false
}
}

En su primer arranque, la versión 3.1.3 importa este archivo, resuelve las variables de entorno y guarda la configuración en SQLite. Los tres valores deben estar exportados en esa terminal: INFERNODE_BASE_URL, INFERNODE_API_KEY y SAPTIVA_ROUTER_TOKEN. El router guarda las credenciales localmente; trata su carpeta como privada.

La configuración declara un solo proveedor, mantiene los alias separados, desactiva reglas automáticas y alternativas de respaldo, y evita que el router modifique la configuración global de tus agentes. Escucha solo en 127.0.0.1.

Arráncalo desde esa misma terminal:

ccr start --no-open

La dirección del gateway es http://127.0.0.1:3456. La administración usa http://127.0.0.1:3458 por defecto. El comando muestra una URL administrativa que contiene un token: no la compartas. Si modificas la llave o la URL de InferNode después de la importación, actualiza el proveedor en la administración del router.

3. Muestra los alias en Claude Code​

Crea ~/.config/saptiva/claude-models.json para que /model muestre los tres nombres exactos:

~/.config/saptiva/claude-models.json
{
"modelPicker": {
"replaceBuiltInOptions": true,
"options": [
{
"model": "Saptiva Turbo",
"label": "Saptiva Turbo"
},
{
"model": "Saptiva Omni",
"label": "Saptiva Omni"
},
{
"model": "Saptiva Cortex",
"label": "Saptiva Cortex"
}
]
}
}

Desde la carpeta del proyecto, configura la conexión y abre una sesión:

unset ANTHROPIC_API_KEY ANTHROPIC_MODEL ANTHROPIC_DEFAULT_FABLE_MODEL
export ANTHROPIC_BASE_URL='http://127.0.0.1:3456'
export ANTHROPIC_AUTH_TOKEN="$(cat ~/.config/saptiva/router-token)"
export ANTHROPIC_DEFAULT_HAIKU_MODEL='Saptiva Turbo'
export ANTHROPIC_DEFAULT_SONNET_MODEL='Saptiva Omni'
export ANTHROPIC_DEFAULT_OPUS_MODEL='Saptiva Cortex'
export ANTHROPIC_SMALL_FAST_MODEL='Saptiva Turbo'
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
export DISABLE_PROMPT_CACHING=1
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=8192
export CLAUDE_CODE_MAX_CONTEXT_TOKENS=131072

claude --settings ~/.config/saptiva/claude-models.json --model 'Saptiva Turbo'

Puedes sustituir Saptiva Turbo por Saptiva Omni o Saptiva Cortex. En la sesión, /model permite cambiar entre ellos. Las variables de familia solo eligen qué alias usar cuando Claude Code solicita internamente Haiku, Sonnet u Opus; no convierten los modelos de InferNode en modelos de Anthropic.

No definas ANTHROPIC_MODEL de forma permanente. Puede hacer que una sesión nueva vuelva a un modelo distinto del que guardaste con /model. En este ejemplo, --model elige el modelo de ese arranque; si lo omites, Claude Code consulta su configuración guardada. No configures equivalencias con Fable para estos alias.

El límite de contexto de 131072 es conservador para cambiar entre los tres alias de este ejemplo. Comprueba el catálogo antes de ajustarlo. El máximo de salida de 8192 también ocupa espacio dentro de esa ventana. Desactivar el caché de prompts evita depender de compatibilidad con el caché de Anthropic; el aviso Prompt caching off es esperado y no indica que se esté usando otro proveedor.

Los comandos claude-saptiva, pi-saptiva y opencode-saptiva no son parte de estas herramientas: solo existen si tu equipo instaló lanzadores personalizados. Esta guía usa los comandos estándar.

4. Prueba texto y herramientas​

Haz una petición breve con las variables del paso anterior cargadas:

claude --settings ~/.config/saptiva/claude-models.json \
--model 'Saptiva Turbo' --print 'Responde solamente OK.' \
--max-turns 1 --tools ''

Después, en la sesión interactiva, pide leer un archivo pequeño que exista por su ruta exacta y resumirlo sin modificarlo. Mantén las confirmaciones normales de herramientas. Una respuesta de texto por sí sola no comprueba que el agente pueda usar herramientas.

Comprobar qué modelo respondió​

El nombre que aparece en /model es el modelo solicitado. La respuesta a «¿qué modelo eres?» no es evidencia del modelo que atendió la llamada: Claude Code incluye instrucciones que lo presentan como el asistente de Anthropic y el modelo puede repetirlas o inventar una familia.

Para consultar la resolución actual de un alias, usa GET /v1/models/aliases. Para comprobar una inferencia, revisa el campo model de la respuesta de InferNode:

curl --fail-with-body -sS "$INFERNODE_BASE_URL/chat/completions" \
-H "Authorization: Bearer $INFERNODE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"model":"Saptiva Turbo","messages":[{"role":"user","content":"Responde OK."}],"max_tokens":512}' \
| jq '{model, finish_reason: .choices[0].finish_reason, content: .choices[0].message.content}'

Esa prueba directa comprueba InferNode, pero no la ruta de una sesión de Claude Code. Para esa sesión, compara la hora de tus mensajes con el proveedor, modelo y estado HTTP del registro de uso del router. En la versión 3.1.3 puedes consultar solo esos metadatos, sin abrir credenciales ni contenido de conversaciones:

python3 - <<'PYTHON'
from pathlib import Path
import sqlite3
path = Path.home() / ".claude-code-router/app-data/usage.sqlite"
with sqlite3.connect(path.as_uri() + "?mode=ro", uri=True) as db:
for row in db.execute(
"SELECT created_at, provider, model, status_code "
"FROM usage_events ORDER BY id DESC LIMIT 5"
):
print(*row, sep=" | ")
PYTHON

Las horas de created_at están en UTC. Espera el proveedor infernode, el modelo físico al que apunta el alias y status_code igual a 200. Si el proveedor o el modelo no coincide, revisa la configuración del router antes de seguir. Si cambiaste variables en la terminal, cierra Claude Code y abre otra sesión: una sesión ya abierta conserva el entorno anterior.

Errores frecuentes​

SíntomaQué revisar
401 desde el router localANTHROPIC_AUTH_TOKEN debe contener el token del router, no la llave de InferNode.
Error de autenticación del proveedorActualiza la llave de InferNode guardada en el proveedor del router.
Conexión rechazada en 127.0.0.1:3456Ejecuta ccr start --no-open y comprueba que el puerto esté disponible.
model_not_foundUsa el alias exacto y verifica que exista para tu llave. No agregues prefijos de proveedor al nombre enviado a InferNode.
ANTHROPIC_MODEL is setQuita esa variable del lanzador o terminal y abre una sesión nueva. Revisa también el argumento --model.
El modelo dice que es Claude o FableComprueba los registros y el campo model, no su descripción de sí mismo.
Se deshabilitan los conectores de la cuenta de ClaudeEsta sesión usa autenticación del gateway, que prevalece sobre el inicio de sesión de la cuenta.
La respuesta se corta o agota el tiempoRevisa el límite de salida y el contexto; prueba Saptiva Turbo y consulta InferNode no responde.

Para detener el router cuando termines:

ccr stop

Siguiente paso​