Esta página é uma tradução da documentação em inglês. Comandos, identificadores e exemplos permanecem iguais. Runtime 7.24.4 · SDK 2.6.7. Original em inglês

Provedores personalizados e de gateway

Status: Ativo Escopo: estado atual Última revisão: 2026-09-06 Responsável: runtime do ax-code

O AX Code conversa com os modelos por protocolos padrão de provedor. Qualquer endpoint que fale uma API compatível com OpenAI (/v1/chat/completions) ou compatível com Anthropic (/v1/messages) pode ser acrescentado como provedor personalizado ao apontar baseURL para ele — sem mudanças de código e sem esperar uma predefinição integrada.

Isso cobre agregadores auto-hospedados e gateways de retransmissão, como LiteLLM, one-api, new-api e o Vercel AI Gateway, além de proxies corporativos privados e qualquer outro serviço compatível. O AX Code trata todos da mesma forma: ele fala o protocolo de comunicação, e você informa a URL e a chave.

Nota de responsabilidade. Um gateway fica entre o AX Code e o modelo upstream, então os prompts, o código e as credenciais passam por ele. Ao apontar o AX Code para um retransmissor de terceiros ou que agrupa contas, você é responsável por confiar a esse operador os seus dados e por permanecer dentro dos termos de serviço de cada provedor upstream para o qual ele encaminha. Predefinições integradas de gateway, como o OpenRouter, usam o mesmo caminho de protocolo padrão; configurar um gateway personalizado não implica endosso de nenhum operador de retransmissão.

Configuração interativa

Use /connect -> Provedor de API na nuvem -> Provedor de API personalizado para um gateway compatível, ou /connect -> AX Trust -> Conectar o AX Trust para um gateway AX Trust. Informe a URL base (incluindo /v1 no caso do AX Trust) e a chave de API do cliente. O editor descobre IDs e metadados de modelo e guarda as credenciais em armazenamento de autenticação criptografado. Ele também aceita IDs de modelo explícitos se a descoberta não estiver disponível. Reconectar uma URL salva conserva o ID do provedor e a chave quando o token é deixado em branco. Conexões do AX Trust mantêm a categoria depois de edições e de atualizações da lista de modelos. O AX Code envia X-AX-Prompt-Cache-Key com o ID da sessão nessas conexões, para que o gateway possa manter a sessão em uma conta elegível; defina provider.<id>.options.axTrust como false para desativar isso. Este cabeçalho não é encaminhado upstream e não é um corpo prompt_cache_key.

Provedores AX Trust conectados atualizam as listas de modelos em segundo plano na inicialização. O AX Code chama GET /models do endpoint configurado com a credencial existente e atualiza nomes de modelo, limites de contexto e de saída, raciocínio, chamada de ferramentas, suporte a temperatura e suporte a imagem. Modelos capazes de imagem mostram o marcador de visão em /models, inclusive aliases de gateway quando o AX Trust anuncia o suporte a imagem deles. A TUI é atualizada quando a descoberta termina. Para IDs exatos de modelo DeepSeek de primeira parte, metadados ausentes são preenchidos a partir do catálogo models.dev incluído. Sinalizadores explícitos de capacidade do gateway e limites têm precedência; aliases desconhecidos não herdam capacidades por semelhança de nome.

Uma atualização bem-sucedida substitui a lista do runtime, remove modelos que o gateway deixou de anunciar e ainda aplica as listas configuradas de permissão e de bloqueio. Tempos esgotados, erros e respostas vazias ou inválidas conservam a lista salva e registram uma falha de descoberta. A inicialização não espera a rede. Esta atualização não reescreve a configuração nem as credenciais do provedor; a configuração salva continua sendo a reserva na inicialização. Provedores comuns de API personalizada conservam a atualização manual.

Como um provedor é resolvido

Para cada requisição, o AX Code precisa de três itens de uma entrada de provedor:

npm — o adaptador do SDK de IA que fala o protocolo de comunicação. Use @ai-sdk/openai-compatible para endpoints no estilo OpenAI e @ai-sdk/anthropic para endpoints no estilo Anthropic. Somente adaptadores @ai-sdk/* vêm incluídos ou podem ser instalados.
options.baseURL — a URL do gateway. Recorre ao campo api do provedor e, depois, ao api.url do próprio modelo. Aceita a substituição ${ENV_VAR}.
Uma credencial — resolvida, nesta ordem, a partir de options.apiKey, depois do armazenamento persistente de autenticação e, por fim, das variáveis env do provedor.

A configuração manual também precisa de um mapa models explícito. O editor interativo preenche esse mapa a partir do endpoint ou dos IDs de modelo que você informar.

Nuvens GPU privadas dedicadas são provedores de primeira classe em /connect → Nuvem GPU privada. Cole a URL compatível com OpenAI e o token (alibaba-pai, runpod, huggingface-endpoints, sagemaker, volcengine-ark, modelarts, tencent-ti ou custom-private-gpu); o AX Code chama GET …/models e usa automaticamente os IDs dos modelos implantados.

Catálogos de GPU hospedados (nebius, fireworks-ai, togetherai, baseten, nvidia, deepinfra) usam uma chave de API e o instantâneo de modelos incluído, o mesmo padrão que o OpenCode usa.

Gateway compatível com OpenAI

A maioria dos agregadores (LiteLLM, one-api, new-api e gateways gratuitos ou auto-hospedados) expõe uma superfície compatível com OpenAI. Acrescente isto ao seu ax-code.json (global em ~/.config/ax-code/ax-code.json, ou por projeto na raiz do repositório):

{
  "$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 },
        },
      },
    },
  },
}

A chave "my-gateway" é o ID do provedor que você seleciona em /connect e ax-code models.
Cada chave sob models é o ID local de seleção. Defina o id da entrada como o ID exato de modelo que o gateway espera quando ele diferir dessa chave; caso contrário, a chave é usada para modelos declarados manualmente que não tenham um mapeamento já existente no catálogo.
Prefira ${ENV_VAR} a uma chave literal, para que o segredo fique fora da configuração enviada ao repositório.

Aliases de modelo do gateway depois de mudar endpoints

Mudar options.baseURL não converte IDs de modelo configurados manualmente. Por exemplo, um endpoint AX Trust pode anunciar deepseek-flash enquanto uma seleção local existente é ax-trust/deepseek-v4-flash. Conserve a chave local e defina provider.ax-trust.models.deepseek-v4-flash.id como deepseek-flash. O AX Code então envia o ID do gateway nas requisições de API.

Veja o exemplo de configuração DeepSeek Flash do AX Trust. Mescle os campos relevantes do provedor na configuração existente, preservando os outros modelos e as configurações de capacidade deles. O exemplo usa {env:AX_TRUST_API_KEY}; defina essa variável de ambiente antes de iniciar o AX Code, ou conserve a configuração de credencial que você já tem. Reinicie o AX Code depois de editar.

Ao diagnosticar 403 model is not allowed, compare o ID de modelo da requisição com a resposta autenticada GET /models do endpoint. Um pedido bem-sucedido da lista de modelos, sozinho, não estabelece permissão para executar um modelo. Se o ID exato ainda falhar, confira as permissões de chave e de modelo no gateway.

Gateway compatível com Anthropic

Retransmissores que expõem /v1/messages (o formato da API Claude) usam o adaptador 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 },
        },
      },
    },
  },
}

Alguns retransmissores no formato Anthropic também respeitam diretamente as variáveis de ambiente do Claude. Para uma execução rápida sem interface, sem editar a configuração, você pode definir:

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

Uma entrada de configuração continua recomendada quando você quer que o gateway apareça como um provedor selecionável próprio, com uma lista de modelos escolhida.

Campos do modelo

As entradas de modelo reutilizam o esquema do registro; para um endpoint personalizado, os campos úteis são:

Campo	Significado
`name`	Rótulo exibido no seletor de modelos
`tool_call`	Se o modelo suporta chamada de ferramenta ou de função (necessário para ferramentas)
`reasoning`	Se o modelo emite raciocínio estendido
`attachment`	Se o modelo aceita anexos de imagem ou de arquivo
`limit`	Limites de tokens `{ context, output }` usados no orçamento
`modalities`	Matrizes opcionais `{ input, output }` (`text`, `image`, `pdf`, …)

Defina os sinalizadores de capacidade de acordo com o que o modelo upstream realmente suporta; o AX Code os usa para controlar chamadas de ferramenta, anexos e o orçamento de contexto.

Verificação

Depois de salvar a configuração:

ax-code models lista cada modelo que o provedor expõe.
/connect, dentro da TUI, mostra o provedor e permite autenticar se você usou uma chave env em vez de options.apiKey.

Se um modelo estiver ausente, confirme o ID do provedor, a chave do modelo e se o gateway está acessível em baseURL.

Solução de problemas

Erros de autenticação — confirme a ordem de resolução da credencial: options.apiKey prevalece; caso contrário, usa-se uma chave env ou do armazenamento de autenticação.
Fluxos parados — gateways às vezes acumulam SSE em buffer. Ajuste options.chunkTimeout (por fragmento) e options.timeout (requisição inteira) no provedor.
Chamadas de ferramenta rejeitadas — defina "tool_call": true no modelo e confirme que o modelo upstream por trás do gateway realmente suporta ferramentas.