Esta página es una traducción de la documentación en inglés. Los comandos, identificadores y ejemplos no cambian. Runtime 7.24.4 · SDK 2.6.7. Original en inglés

Proveedores personalizados y de puerta de enlace

Estado: Activo Alcance: estado actual Última revisión: 2026-09-06 Responsable: entorno de ejecución de ax-code

AX Code habla con los modelos mediante protocolos estándar de proveedor. Cualquier endpoint que hable una API compatible con OpenAI (/v1/chat/completions) o compatible con Anthropic (/v1/messages) puede añadirse como proveedor personalizado apuntando baseURL hacia él: sin cambios de código y sin esperar un ajuste predefinido integrado.

Esto cubre agregadores autoalojados y puertas de enlace de retransmisión como LiteLLM, one-api, new-api y Vercel AI Gateway, además de proxies corporativos privados y cualquier otro servicio compatible. AX Code los trata de forma uniforme: habla el protocolo de cable y tú aportas la URL y la clave.

Nota de responsabilidad. Una puerta de enlace se sitúa entre AX Code y el modelo de origen, así que tus prompts, tu código y tus credenciales pasan por ella. Cuando apuntas AX Code a una retransmisión de terceros o de agrupación de cuentas, eres responsable de confiar a ese operador tus datos y de permanecer dentro de las condiciones de servicio de cada proveedor de origen al que enruta. Los ajustes predefinidos integrados de puerta de enlace, como OpenRouter, usan la misma ruta de protocolo estándar; la configuración personalizada de una puerta de enlace no implica respaldo de ningún operador de retransmisión.

Configuración interactiva

Usa /connect -> API Cloud Provider -> Custom API provider para una puerta de enlace compatible, o /connect -> AX Trust -> Connect AX Trust para una puerta de enlace AX Trust. Introduce su URL base (incluido /v1 para AX Trust) y la clave de API del cliente. El editor descubre los ID de modelo y los metadatos, y guarda las credenciales en el almacenamiento de autenticación cifrado. También puede aceptar ID de modelo explícitos si el descubrimiento no está disponible. Reconectar una URL guardada conserva su ID de proveedor y su clave cuando el token se deja en blanco. Las conexiones de AX Trust conservan su categoría después de las ediciones y de las actualizaciones de modelos. AX Code envía X-AX-Prompt-Cache-Key con el ID de sesión en esas conexiones para que la puerta de enlace pueda mantener una sesión en una cuenta apta; establece provider.<id>.options.axTrust en false para desactivarlo. Esta cabecera no se reenvía al origen y no es un prompt_cache_key del cuerpo.

Los proveedores de AX Trust conectados actualizan sus listas de modelos en segundo plano al arrancar. AX Code llama a GET /models del endpoint configurado con la credencial existente y actualiza nombres de modelo, límites de contexto y salida, razonamiento, llamada a herramientas, soporte de temperatura y soporte de imagen. Los modelos capaces de imagen muestran el marcador de visión en /models, incluidos los alias de puerta de enlace cuando AX Trust anuncia su soporte de imagen. La TUI se actualiza cuando termina el descubrimiento. Para los ID exactos de modelos DeepSeek de primera parte, los metadatos ausentes se rellenan desde el catálogo models.dev incluido. Las marcas de capacidad y los límites explícitos de la puerta de enlace tienen precedencia; los alias desconocidos no heredan capacidades por similitud de nombre.

Una actualización exitosa sustituye la lista del entorno de ejecución, elimina los modelos que la puerta de enlace ya no anuncia y sigue aplicando las listas de permiso y bloqueo configuradas. Los tiempos de espera, los errores y las respuestas vacías o no válidas conservan la lista guardada y registran un fallo de descubrimiento. El arranque no espera a la red. Esta actualización no reescribe la configuración del proveedor ni las credenciales; la configuración guardada sigue siendo el respaldo de arranque. Los proveedores de API personalizados ordinarios conservan la actualización manual.

Cómo se resuelve un proveedor

Para cada solicitud, AX Code necesita tres cosas de una entrada de proveedor:

npm — el adaptador del SDK de IA que habla el protocolo de cable. Usa @ai-sdk/openai-compatible para endpoints de estilo OpenAI y @ai-sdk/anthropic para endpoints de estilo Anthropic. Solo los adaptadores @ai-sdk/* están incluidos o se pueden instalar.
options.baseURL — la URL de la puerta de enlace. Recurre al campo api del proveedor y luego al api.url propio del modelo. Admite la sustitución ${ENV_VAR}.
Una credencial — se resuelve en orden desde options.apiKey, luego el almacén de autenticación persistente y luego las variables env del proveedor.

La configuración manual también necesita un mapa models explícito. El editor interactivo rellena este mapa desde el endpoint o desde los ID de modelo que aportes.

Las nubes GPU privadas dedicadas son proveedores de primera clase bajo /connect → Private GPU cloud. Pega la URL compatible con OpenAI y el token (alibaba-pai, runpod, huggingface-endpoints, sagemaker, volcengine-ark, modelarts, tencent-ti o custom-private-gpu); AX Code llama a GET …/models y usa de forma automática los ID del modelo desplegado.

Los catálogos GPU alojados (nebius, fireworks-ai, togetherai, baseten, nvidia, deepinfra) usan una clave de API y la instantánea de modelos incluida, el mismo patrón que usa OpenCode.

Puerta de enlace compatible con OpenAI

La mayoría de los agregadores (LiteLLM, one-api, new-api, puertas de enlace gratuitas o autoalojadas) exponen una superficie compatible con OpenAI. Añade esto a tu ax-code.json (global en ~/.config/ax-code/ax-code.json, o por proyecto en la raíz del repositorio):

{
  "$schema": "https://ax-code.app/docs-assets/schema/config.schema.json",
  "provider": {
    "my-gateway": {
      "name": "My Gateway",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://gateway.example.com/v1",
        "apiKey": "${MY_GATEWAY_API_KEY}",
      },
      "models": {
        "gpt-4o": {
          "name": "GPT-4o (via gateway)",
          "tool_call": true,
          "reasoning": false,
          "attachment": true,
          "limit": { "context": 128000, "output": 16384 },
        },
      },
    },
  },
}

La clave "my-gateway" es el id de proveedor que seleccionas en /connect y ax-code models.
Cada clave bajo models es el ID de selección local. Establece el id de la entrada en el ID exacto de modelo que espera la puerta de enlace cuando difiere de esa clave; si no, la clave se usa para los modelos declarados a mano sin una correspondencia de catálogo existente.
Prefiere ${ENV_VAR} a una clave literal para que el secreto quede fuera de la configuración confirmada en el repositorio.

Alias de modelo de la puerta de enlace tras cambiar endpoints

Cambiar options.baseURL no traduce los ID de modelo configurados a mano. Por ejemplo, un endpoint de AX Trust puede anunciar deepseek-flash mientras una selección local existente es ax-trust/deepseek-v4-flash. Conserva la clave local y establece provider.ax-trust.models.deepseek-v4-flash.id en deepseek-flash. AX Code envía entonces el ID de la puerta de enlace en las solicitudes de API.

Consulta el ejemplo de configuración de AX Trust para DeepSeek Flash. Fusiona los campos de proveedor pertinentes en tu configuración existente, conservando los demás modelos y sus ajustes de capacidad. El ejemplo usa {env:AX_TRUST_API_KEY}; establece esa variable de entorno antes de iniciar AX Code, o conserva tu configuración de credenciales existente. Reinicia AX Code después de editar.

Al diagnosticar 403 model is not allowed, compara el ID de modelo de la solicitud con la respuesta autenticada GET /models del endpoint. Una solicitud exitosa de lista de modelos por sí sola no establece permiso para ejecutar un modelo. Si el ID exacto sigue fallando, comprueba los permisos de clave y modelo de la puerta de enlace.

Puerta de enlace compatible con Anthropic

Las retransmisiones que exponen /v1/messages (la forma de la API de Claude) usan el adaptador de Anthropic:

{
  "$schema": "https://ax-code.app/docs-assets/schema/config.schema.json",
  "provider": {
    "my-claude-gateway": {
      "name": "My Claude Gateway",
      "npm": "@ai-sdk/anthropic",
      "options": {
        "baseURL": "https://gateway.example.com",
        "apiKey": "${MY_GATEWAY_API_KEY}",
      },
      "models": {
        "claude-sonnet-4-6": {
          "name": "Claude Sonnet (via gateway)",
          "tool_call": true,
          "reasoning": true,
          "attachment": true,
          "limit": { "context": 200000, "output": 64000 },
        },
      },
    },
  },
}

Algunas retransmisiones con forma de Anthropic también respetan directamente las variables de entorno de Claude. Para una ejecución headless rápida sin editar la configuración puedes establecer:

export ANTHROPIC_BASE_URL="https://gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="sk-..."

Sigue siendo recomendable una entrada de configuración cuando quieras que la puerta de enlace aparezca como su propio proveedor seleccionable, con una lista de modelos curada.

Campos del modelo

Las entradas de modelo reutilizan el esquema del registro; para un endpoint personalizado, los campos útiles son:

Campo	Significado
`name`	Etiqueta visible en el selector de modelos
`tool_call`	Si el modelo admite llamadas a herramientas o funciones (necesario para las herramientas)
`reasoning`	Si el modelo emite razonamiento extendido
`attachment`	Si el modelo acepta adjuntos de imagen o archivo
`limit`	Límites de tokens `{ context, output }` usados para el presupuesto
`modalities`	Arrays `{ input, output }` opcionales (`text`, `image`, `pdf`, …)

Establece las marcas de capacidad de acuerdo con lo que el modelo de origen admite de verdad; AX Code las usa para condicionar las llamadas a herramientas, los adjuntos y el presupuesto de contexto.

Verificación

Después de guardar la configuración:

ax-code models lista cada modelo que expone tu proveedor.
/connect dentro de la TUI muestra el proveedor y te permite autenticarte si usaste una clave env en lugar de options.apiKey.

Si falta un modelo, confirma el id del proveedor, la clave del modelo y que la puerta de enlace es alcanzable en baseURL.

Resolución de problemas

Errores de autenticación — confirma el orden de resolución de la credencial: gana options.apiKey; si no, se usa una clave de env o del almacén de autenticación.
Flujos detenidos — las puertas de enlace a veces almacenan SSE en búfer. Ajusta options.chunkTimeout (por fragmento) y options.timeout (solicitud completa) en el proveedor.
Llamadas a herramientas rechazadas — establece "tool_call": true en el modelo y confirma que el modelo de origen detrás de la puerta de enlace admite herramientas de verdad.