Skip to main content

Failover de modelo

Rotação de perfis de autenticação, períodos de espera e como isso interage com os fallbacks.

Provedores de modelos

Visão geral rápida dos provedores e exemplos.

Referência da CLI de modelos

Referência completa do comando openclaw models e de suas flags.

Referência de configuração

Chaves de configuração de modelos, valores padrão e exemplos.
Uma referência de modelo (provider/model) escolhe um provedor e um modelo, não o runtime de agente de baixo nível. Quando a política de runtime não está definida ou é auto, a política de roteamento pertencente ao provedor da OpenAI pode selecionar o Codex somente para uma rota oficial HTTPS exata da Platform Responses ou ChatGPT Responses, sem nenhuma substituição de solicitação definida pelo autor; o prefixo openai/* sozinho nunca seleciona o Codex. Adaptadores de Completions, endpoints personalizados e comportamentos de solicitação definidos pelo autor permanecem no OpenClaw. Endpoints HTTP oficiais em texto simples são rejeitados. Consulte runtime de agente implícito da OpenAI. Referências do Copilot por assinatura (github-copilot/*) podem optar pelo Plugin externo de runtime de agente do GitHub Copilot, mas esse caminho é sempre explícito (nunca selecionado por auto). As substituições de runtime pertencem à política do provedor/modelo, não ao agente ou à sessão inteira. A seleção do runtime não determina o faturamento: as credenciais de chave de API da OpenAI e as credenciais de assinatura do ChatGPT/Codex permanecem distintas. Consulte Runtimes de agente e runtime de agente do GitHub Copilot.

​
Ordem de seleção

1

Modelo principal

agents.defaults.model.primary (ou agents.defaults.model como uma string simples).
2

Fallbacks

agents.defaults.model.fallbacks, tentados em ordem.
3

Failover de autenticação

A rotação de perfis de autenticação ocorre dentro de um provedor antes que o OpenClaw passe para o próximo modelo de fallback.
Superfícies relacionadas à configuração de modelos:
  • agents.defaults.models é a lista de permissões/catálogo de modelos que o OpenClaw pode usar, além dos aliases. Use entradas provider/* para permitir todos os modelos descobertos de um provedor sem listar cada um.
  • agents.defaults.utilityModel é um modelo opcional de menor custo para tarefas internas curtas, como títulos gerados para sessões do painel, títulos de threads/tópicos de canais compatíveis e narração do progresso. A configuração agents.list[].utilityModel por agente a substitui. Quando não está definido, o OpenClaw usa o modelo pequeno padrão declarado pelo provedor principal, quando houver um (OpenAI → gpt-5.6-luna, Anthropic → claude-haiku-4-5); caso contrário, usa o modelo principal do agente. Defina-o como uma string vazia para desativar o roteamento de utilitários. As tarefas de utilitário são chamadas de modelo separadas e podem enviar conteúdo limitado da tarefa ao provedor de modelo selecionado.
  • agents.defaults.imageModel é usado somente quando o modelo principal não aceita imagens.
  • agents.defaults.pdfModel é usado pela ferramenta pdf. Se não estiver definido, a ferramenta usa como fallback o imageModel e, depois, o modelo resolvido da sessão/padrão.
  • agents.defaults.imageGenerationModel, musicGenerationModel e videoGenerationModel dão suporte às ferramentas compartilhadas de geração de mídia. Se não estiver definido, cada modelo infere um provedor padrão com autenticação disponível: primeiro o provedor padrão atual e, depois, os demais provedores registrados para esse recurso, na ordem do ID do provedor. Defina agents.defaults.mediaGenerationAutoProviderFallback: false para desativar essa inferência entre provedores, mantendo os fallbacks explícitos.
  • A configuração agents.list[].model por agente (além das vinculações) substitui agents.defaults.model — consulte Roteamento multiagente.
Referência completa das chaves, valores padrão e exemplos em JSON5: Referência de configuração.

​
Origem da seleção e rigidez do fallback

O mesmo provider/model se comporta de maneira diferente dependendo de sua origem: Outras regras de seleção:
  • Alterar agents.defaults.model.primary não reescreve as fixações de sessão existentes. Se o status informar This session is pinned to X; config primary Y will apply to new/unpinned sessions., execute /model default para remover a fixação.
  • Os seletores de modelo padrão e de lista de permissões da CLI respeitam models.mode: "replace", listando apenas models.providers.*.models em vez do catálogo integrado completo.
  • O seletor de modelos da interface de controle solicita ao Gateway sua visualização de modelos configurada: agents.defaults.models quando definido (incluindo entradas curinga provider/*); caso contrário, models.providers.*.models mais os provedores com autenticação utilizável. O catálogo integrado completo é reservado para visualizações de navegação explícitas (models.list com view: "all" ou openclaw models list --all).
  • As interfaces de inventário de provedores usam models.list com view: "provider-config" para exibir linhas models.providers.*.models definidas pela fonte sem aplicar as listas de permissões dos seletores.
Mecânica completa: Failover de modelo.

​
Política rápida de modelos

  • Defina como principal o modelo mais avançado da geração mais recente disponível para você.
  • Use modelos de contingência para tarefas sensíveis a custo/latência e conversas de menor risco.
  • Para agentes com ferramentas habilitadas ou entradas não confiáveis, evite categorias de modelos mais antigas ou menos avançadas.

​
Integração inicial

Configura o modelo e a autenticação para provedores comuns sem editar manualmente a configuração, incluindo OAuth da assinatura do OpenAI Codex e Anthropic (chave de API ou reutilização da CLI do Claude). Sem um modelo principal configurado, uma nova configuração com chave de API da OpenAI seleciona openai/gpt-5.6; o ID simples da API direta é resolvido para o nível Sol. Uma nova configuração OAuth do ChatGPT/Codex seleciona a referência exata de catálogo openai/gpt-5.6-sol. A reautenticação preserva um modelo principal explícito existente, incluindo openai/gpt-5.5. Se o GPT-5.6 não estiver disponível para a conta, selecione openai/gpt-5.5 explicitamente; o OpenClaw não faz downgrade silencioso.

​
”O modelo não é permitido” (e por que as respostas param)

Se agents.defaults.models estiver definido, ele se tornará a lista de permissões para /model e substituições de sessão. Selecionar um modelo fora dessa lista retorna, antes que qualquer resposta normal seja gerada:
Corrija isso adicionando o modelo a agents.defaults.models, removendo completamente a lista de permissões (remova a chave) ou escolhendo um modelo em /model list. Se o comando rejeitado incluía uma substituição de runtime, como /model openai/gpt-5.5 --runtime codex, corrija primeiro a lista de permissões e repita o mesmo comando /model ... --runtime .... Para modelos locais/GGUF, a lista de permissões precisa da referência completa com o prefixo do provedor, por exemplo, ollama/gemma4:26b ou lmstudio/Gemma4-26b-a4-it-gguf — consulte openclaw models list --provider <provider> para obter a string exata. Apenas nomes de arquivo ou nomes de exibição não são suficientes quando a lista de permissões está ativa. Para limitar os provedores sem listar todos os modelos, use entradas curinga provider/*:
Nesse caso, /model, /models e os seletores de modelos exibem apenas o catálogo descoberto para esses provedores, e novos modelos podem aparecer sem editar a lista de permissões. Combine entradas exatas provider/model com entradas provider/* para incluir um modelo específico de outro provedor. Exemplo de lista de permissões com aliases:
Use --merge para alterações aditivas:
openclaw config set recusa atribuições de objetos simples a agents.defaults.models, models.providers ou models.providers.<id>.models quando elas removeriam entradas existentes; use --replace somente quando o novo valor deva se tornar o valor completo de destino. A configuração interativa de provedores e openclaw configure --section model já mesclam as seleções específicas do provedor na lista de permissões, portanto, adicionar um provedor não remove entradas não relacionadas; a configuração preserva um agents.defaults.model.primary existente. Comandos explícitos como openclaw models auth login --provider <id> --set-default e openclaw models set <model> ainda substituem o modelo principal.

​
/model no chat

  • /model e /model list exibem um seletor numerado compacto (família de modelos + provedores disponíveis); /model <#> seleciona uma opção dele. No Discord, isso abre listas suspensas de provedor/modelo com uma etapa Submit; no Telegram, as seleções do seletor são específicas da sessão e nunca reescrevem o padrão persistente do agente em openclaw.json. /models add está obsoleto e retorna uma mensagem em vez de registrar modelos pelo chat.
  • /model persiste imediatamente a nova seleção da sessão. Se o agente estiver ocioso, a próxima execução a usará imediatamente; se uma execução já estiver ativa, a troca ficará na fila para o próximo ponto de nova tentativa limpa (ou para um ponto posterior, se a atividade de ferramentas ou a saída da resposta já tiver começado).
  • /model default limpa a seleção da sessão para que ela volte a herdar o modelo primário configurado.
  • Uma referência de /model selecionada pelo usuário é estrita para essa sessão: se ficar inacessível, a resposta falhará de forma visível em vez de recorrer silenciosamente a agents.defaults.model.fallbacks. Os padrões configurados e os modelos primários de tarefas cron ainda usam cadeias de fallback.
  • /model status é a visualização detalhada: candidatos de autenticação por provedor e, quando configurados, o endpoint baseUrl do provedor e o modo de api.
  • As referências de modelo são analisadas pela divisão na primeira /; digite provider/model. Se o próprio ID do modelo contiver / (no estilo do OpenRouter), inclua o prefixo do provedor, por exemplo, /model openrouter/moonshotai/kimi-k2. Se você omitir o provedor, o OpenClaw tentará: (1) correspondência de alias, (2) correspondência exclusiva com um provedor configurado para esse ID de modelo exato sem prefixo, (3) o provedor padrão configurado (fallback obsoleto) — e, se esse provedor não disponibilizar mais o modelo padrão configurado, usará o primeiro provedor/modelo configurado para evitar expor um padrão obsoleto de um provedor removido.
  • As referências de modelo são normalizadas para letras minúsculas; fora isso, os IDs de provedores são exatos, portanto use o ID anunciado pelo plugin.
Comportamento completo dos comandos e configuração: Comandos de barra.

​
CLI

openclaw models sem subcomando é um atalho para models status, que também exibe a expiração do OAuth para perfis do armazenamento de autenticação (por padrão, alerta quando faltam até 24h). Opções completas, formatos JSON e subcomandos de perfis de autenticação: Referência da CLI de modelos.
openclaw models scan inspeciona o catálogo público de modelos gratuitos do OpenRouter e pode testar candidatos em tempo real quanto à compatibilidade com ferramentas e imagens. O catálogo em si é público, portanto verificações somente de metadados (--no-probe) não precisam de chave; testes em tempo real e --set-default/--set-image exigem uma chave de API do OpenRouter (perfil de autenticação ou OPENROUTER_API_KEY) e, sem ela, adotam uma postura restritiva, gerando apenas a saída de metadados.Os resultados são classificados por: compatibilidade com imagens, depois latência de ferramentas, depois tamanho do contexto e, por fim, quantidade de parâmetros. Em um TTY, os resultados testados solicitam uma seleção interativa de fallback; o modo não interativo exige --yes para aceitar os padrões.

​
Registro de modelos (models.json)

Os provedores personalizados configurados em models.providers são gravados em models.json no diretório do agente (por padrão, ~/.openclaw/agents/<agentId>/agent/models.json). Os catálogos de plugins de provedores são armazenados separadamente como fragmentos de catálogo gerados e pertencentes aos plugins, sendo carregados automaticamente. Por padrão, esse arquivo é mesclado com a configuração; defina models.mode: "replace" para usar somente os provedores configurados por você.
Para IDs de provedores correspondentes:
  • Um baseUrl não vazio já presente no models.json do agente prevalece.
  • Uma apiKey não vazia em models.json prevalece somente quando esse provedor não é gerenciado por SecretRef no contexto atual de configuração/perfil de autenticação.
  • Os valores de apiKey gerenciados por SecretRef são atualizados a partir dos marcadores de origem, em vez de persistirem os segredos resolvidos: o nome da variável de ambiente para referências de ambiente e secretref-managed para referências de arquivo/execução.
  • Os valores de cabeçalho gerenciados por SecretRef são atualizados da mesma forma, usando secretref-env:ENV_VAR_NAME para referências de ambiente.
  • Valores de apiKey/baseUrl vazios ou ausentes em models.json recorrem a models.providers da configuração.
  • Outros campos do provedor são atualizados a partir da configuração e dos dados normalizados do catálogo.
A persistência dos marcadores tem a origem como autoridade: sempre que regenera models.json — inclusive em fluxos acionados por comandos, como openclaw agent —, o OpenClaw grava os marcadores a partir do instantâneo da configuração de origem ativa (antes da resolução), e não a partir dos valores de segredos resolvidos em tempo de execução.

​
Relacionados