Pular para o conteúdo principal
Perguntas e respostas sobre modelos e perfis de autenticação. Para configuração, sessões, Gateway, canais e solução de problemas, consulte a FAQ principal.

​
Modelos: padrões, seleção, aliases, troca

O modelo padrão do OpenClaw é o que você definir como:
agents.defaults.model.primary
Modelos são referenciados como provider/model (exemplo: openai/gpt-5.5 ou anthropic/claude-sonnet-4-6). Se você omitir o provedor, o OpenClaw primeiro tenta um alias, depois uma correspondência única de provedor configurado para esse id exato de modelo, e só então recorre ao provedor padrão configurado como um caminho de compatibilidade obsoleto. Se esse provedor não expuser mais o modelo padrão configurado, o OpenClaw recorrerá ao primeiro provedor/modelo configurado em vez de exibir um padrão obsoleto de provedor removido. Ainda assim, você deve definir provider/model explicitamente.
Padrão recomendado: use o modelo de última geração mais forte disponível na sua pilha de provedores. Para agentes com ferramentas habilitadas ou entrada não confiável: priorize a força do modelo em vez do custo. Para chat rotineiro/de baixo risco: use modelos de fallback mais baratos e roteie por função do agente.O MiniMax tem sua própria documentação: MiniMax e Modelos locais.Regra prática: use o melhor modelo que você puder pagar para trabalhos de alto risco, e um modelo mais barato para chat ou resumos rotineiros. Você pode rotear modelos por agente e usar subagentes para paralelizar tarefas longas (cada subagente consome tokens). Consulte Modelos e Subagentes.Aviso importante: modelos mais fracos ou quantizados demais são mais vulneráveis a injeção de prompt e comportamento inseguro. Consulte Segurança.Mais contexto: Modelos.
Use comandos de modelo ou edite apenas os campos de modelo. Evite substituições completas da configuração.Opções seguras:
  • /model no chat (rápido, por sessão)
  • openclaw models set ... (atualiza apenas a configuração de modelo)
  • openclaw configure --section model (interativo)
  • edite agents.defaults.model em ~/.openclaw/openclaw.json
Evite config.apply com um objeto parcial, a menos que você pretenda substituir toda a configuração. Para edições por RPC, inspecione primeiro com config.schema.lookup e prefira config.patch. O payload de consulta fornece o caminho normalizado, documentação/restrições superficiais do esquema e resumos imediatos dos filhos para atualizações parciais. Se você sobrescreveu a configuração, restaure a partir de um backup ou execute novamente openclaw doctor para reparar.Documentação: Modelos, Configurar, Config, Doctor.
Sim. Ollama é o caminho mais fácil para modelos locais.Configuração mais rápida:
  1. Instale o Ollama em https://ollama.com/download
  2. Baixe um modelo local como ollama pull gemma4
  3. Se você também quiser modelos em nuvem, execute ollama signin
  4. Execute openclaw onboard e escolha Ollama
  5. Escolha Local ou Cloud + Local
Observações:
  • Cloud + Local oferece modelos em nuvem além dos seus modelos locais do Ollama
  • modelos em nuvem como kimi-k2.5:cloud não precisam de download local
  • para troca manual, use openclaw models list e openclaw models set ollama/<model>
Observação de segurança: modelos menores ou fortemente quantizados são mais vulneráveis a injeção de prompt. Recomendamos fortemente modelos grandes para qualquer bot que possa usar ferramentas. Se você ainda quiser modelos pequenos, habilite sandboxing e allowlists rígidas de ferramentas.Documentação: Ollama, Modelos locais, Provedores de modelo, Segurança, Sandboxing.
  • Essas implantações podem variar e mudar com o tempo; não há recomendação fixa de provedor.
  • Verifique a configuração atual de runtime em cada Gateway com openclaw models status.
  • Para agentes sensíveis à segurança/com ferramentas habilitadas, use o modelo de última geração mais forte disponível.
Use o comando /model como uma mensagem independente:
/model sonnet
/model opus
/model gpt
/model gpt-mini
/model gemini
/model gemini-flash
/model gemini-flash-lite
Esses são os aliases integrados. Aliases personalizados podem ser adicionados via agents.defaults.models.Você pode listar modelos disponíveis com /model, /model list ou /model status./model (e /model list) mostra um seletor compacto e numerado. Selecione pelo número:
/model 3
Você também pode forçar um perfil de autenticação específico para o provedor (por sessão):
/model opus@anthropic:default
/model opus@anthropic:work
Dica: /model status mostra qual agente está ativo, qual arquivo auth-profiles.json está sendo usado e qual perfil de autenticação será tentado em seguida. Ele também mostra o endpoint configurado do provedor (baseUrl) e o modo de API (api) quando disponíveis.Como desafixo um perfil definido com @profile?Execute novamente /model sem o sufixo @profile:
/model anthropic/claude-opus-4-6
Se quiser voltar ao padrão, escolha-o em /model (ou envie /model <default provider/model>). Use /model status para confirmar qual perfil de autenticação está ativo.
/model provider/model seleciona essa rota exata de provedor para a sessão.Por exemplo, qianfan/deepseek-v4-flash e deepseek/deepseek-v4-flash são referências de modelo diferentes, embora ambas contenham deepseek-v4-flash. O OpenClaw não deve alternar silenciosamente de um provedor para outro apenas porque o id simples do modelo corresponde.Uma referência /model selecionada pelo usuário também é rígida para a política de fallback. Se esse provedor/modelo selecionado estiver indisponível, a resposta falha de forma visível em vez de responder a partir de agents.defaults.model.fallbacks. Cadeias de fallback configuradas ainda se aplicam a padrões configurados, primários de tarefas Cron e estado de fallback selecionado automaticamente.Se uma execução iniciada a partir de uma substituição fora da sessão tiver permissão para usar fallback, o OpenClaw tenta primeiro o provedor/modelo solicitado, depois os fallbacks configurados, e só então o primário configurado. Isso evita que ids simples de modelo duplicados saltem diretamente de volta para o provedor padrão.Consulte Modelos e Failover de modelo.
Sim. Trate a escolha do modelo e a escolha de runtime separadamente:
  • Agente nativo de programação do Codex: defina agents.defaults.model.primary como openai/gpt-5.5. Faça login com openclaw models auth login --provider openai quando quiser autenticação por assinatura ChatGPT/Codex.
  • Tarefas diretas da API OpenAI fora do loop do agente: configure OPENAI_API_KEY para imagens, embeddings, fala, realtime e outras superfícies da API OpenAI sem agente.
  • Autenticação por chave de API do agente OpenAI: use /model openai/gpt-5.5 com um perfil de chave de API openai ordenado.
  • Subagentes: roteie tarefas de programação para um agente focado em Codex com seu próprio modelo openai/gpt-5.5.
Consulte Modelos e Comandos de barra.
Use uma alternância de sessão ou um padrão de configuração:
  • Por sessão: envie /fast on enquanto a sessão estiver usando openai/gpt-5.5.
  • Padrão por modelo: defina agents.defaults.models["openai/gpt-5.5"].params.fastMode como true.
  • Corte automático: use /fast auto ou params.fastMode: "auto" para iniciar novas chamadas de modelo rapidamente até o corte automático e, depois, iniciar chamadas posteriores de nova tentativa, fallback, resultado de ferramenta ou continuação sem modo rápido. O corte padrão é de 60 segundos; defina params.fastAutoOnSeconds no modelo ativo para alterá-lo.
Exemplo:
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: {
            fastMode: "auto",
            fastAutoOnSeconds: 30,
          },
        },
      },
    },
  },
}
Para OpenAI, o modo rápido mapeia para service_tier = "priority" em solicitações nativas compatíveis de Responses. Substituições de sessão com /fast têm precedência sobre padrões de configuração. Turnos do servidor de aplicativo do Codex só podem receber o nível no início do turno, portanto auto se aplica no próximo turno de modelo iniciado pelo OpenClaw, e não dentro de um turno do servidor de aplicativo que já esteja em execução.Consulte Raciocínio e modo rápido e Modo rápido da OpenAI.
Se agents.defaults.models estiver definido, ele se torna a allowlist para /model e quaisquer substituições de sessão. Escolher um modelo que não esteja nessa lista retorna:
Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.
Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge
Esse erro é retornado em vez de uma resposta normal. Correção: adicione o modelo exato a agents.defaults.models, adicione um curinga de provedor como "provider/*": {} para catálogos dinâmicos de provedores, remova a allowlist ou escolha um modelo em /model list. Se o comando também incluiu --runtime codex, atualize primeiro a allowlist e tente novamente o mesmo comando /model provider/model --runtime codex.
Isso significa que o provedor não está configurado (nenhuma configuração de provedor MiniMax ou perfil de autenticação foi encontrado), portanto o modelo não pode ser resolvido.Lista de correção:
  1. Atualize para uma versão atual do OpenClaw (ou execute a partir de main no código-fonte) e reinicie o Gateway.
  2. Garanta que o MiniMax esteja configurado (assistente ou JSON), ou que a autenticação do MiniMax exista em env/perfis de autenticação para que o provedor correspondente possa ser injetado (MINIMAX_API_KEY para minimax, MINIMAX_OAUTH_TOKEN ou OAuth MiniMax armazenado para minimax-portal).
  3. Use o id exato do modelo (diferencia maiúsculas de minúsculas) para seu caminho de autenticação: minimax/MiniMax-M3, minimax/MiniMax-M2.7 ou minimax/MiniMax-M2.7-highspeed para configuração por chave de API, ou minimax-portal/MiniMax-M3, minimax-portal/MiniMax-M2.7 ou minimax-portal/MiniMax-M2.7-highspeed para configuração por OAuth.
  4. Execute: 
    openclaw models list
    e escolha na lista (ou /model list no chat).
Consulte MiniMax e Modelos.
Sim. Use MiniMax como padrão e troque modelos por sessão quando necessário. Fallbacks são para erros, não para “tarefas difíceis”, portanto use /model ou um agente separado.Opção A: trocar por sessão
{
  env: { MINIMAX_API_KEY: "sk-...", OPENAI_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "minimax/MiniMax-M3" },
      models: {
        "minimax/MiniMax-M3": { alias: "minimax" },
        "openai/gpt-5.5": { alias: "gpt" },
      },
    },
  },
}
Depois:
/model gpt
Opção B: agentes separados
  • Padrão do agente A: MiniMax
  • Padrão do agente B: OpenAI
  • Roteie por agente ou use /agent para trocar
Docs: Modelos, Roteamento multiagente, MiniMax, OpenAI.
Sim. O OpenClaw inclui alguns atalhos padrão (aplicados apenas quando o modelo existe em agents.defaults.models):
  • opus → anthropic/claude-opus-4-8
  • sonnet → anthropic/claude-sonnet-4-6
  • gpt → openai/gpt-5.4
  • gpt-mini → openai/gpt-5.4-mini
  • gpt-nano → openai/gpt-5.4-nano
  • gemini → google/gemini-3.1-pro-preview
  • gemini-flash → google/gemini-3-flash-preview
  • gemini-flash-lite → google/gemini-3.1-flash-lite
Se você definir seu próprio alias com o mesmo nome, o seu valor prevalece.
Os aliases vêm de agents.defaults.models.<modelId>.alias. Exemplo:
{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-6" },
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "anthropic/claude-sonnet-4-6": { alias: "sonnet" },
      },
    },
  },
}
Então /model sonnet (ou /<alias> quando compatível) resolve para esse ID de modelo.
OpenRouter (pagamento por token; muitos modelos):
{
  agents: {
    defaults: {
      model: { primary: "openrouter/anthropic/claude-sonnet-4-6" },
      models: { "openrouter/anthropic/claude-sonnet-4-6": {} },
    },
  },
  env: { OPENROUTER_API_KEY: "sk-or-..." },
}
Z.AI (modelos GLM):
{
  agents: {
    defaults: {
      model: { primary: "zai/glm-5" },
      models: { "zai/glm-5": {} },
    },
  },
  env: { ZAI_API_KEY: "..." },
}
Se você referenciar um provedor/modelo, mas a chave obrigatória do provedor estiver ausente, receberá um erro de autenticação em tempo de execução (por exemplo, No API key found for provider "zai").Nenhuma chave de API encontrada para o provedor após adicionar um novo agenteIsso geralmente significa que o novo agente tem um armazenamento de autenticação vazio. A autenticação é por agente e armazenada em:
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
Opções de correção:
  • Execute openclaw agents add <id> e configure a autenticação durante o assistente.
  • Ou copie apenas perfis api_key / token estáticos e portáveis do armazenamento de autenticação do agente principal para o armazenamento de autenticação do novo agente.
  • Para perfis OAuth, faça login a partir do novo agente quando ele precisar de sua própria conta; caso contrário, o OpenClaw pode ler por meio do agente padrão/principal sem clonar tokens de atualização.
Não reutilize agentDir entre agentes; isso causa colisões de autenticação/sessão.

​
Failover de modelo e “All models failed”

O failover acontece em duas etapas:
  1. Rotação de perfil de autenticação dentro do mesmo provedor.
  2. Fallback de modelo para o próximo modelo em agents.defaults.model.fallbacks.
Cooldowns se aplicam a perfis com falha (backoff exponencial), para que o OpenClaw possa continuar respondendo mesmo quando um provedor está com limitação de taxa ou falhando temporariamente.O bucket de limitação de taxa inclui mais do que respostas 429 simples. O OpenClaw também trata mensagens como Too many concurrent requests, ThrottlingException, concurrency limit reached, workers_ai ... quota limit exceeded, resource exhausted e limites periódicos de janela de uso (weekly/monthly limit reached) como limitações de taxa que justificam failover.Algumas respostas que parecem cobrança não são 402, e algumas respostas HTTP 402 também permanecem nesse bucket transitório. Se um provedor retornar texto explícito de cobrança em 401 ou 403, o OpenClaw ainda pode manter isso na faixa de cobrança, mas correspondedores de texto específicos do provedor permanecem restritos ao provedor que os possui (por exemplo, OpenRouter Key limit exceeded). Se uma mensagem 402 em vez disso parecer uma janela de uso repetível ou um limite de gastos de organização/workspace (daily limit reached, resets tomorrow, organization spending limit exceeded), o OpenClaw a trata como rate_limit, não como uma desativação longa por cobrança.Erros de estouro de contexto são diferentes: assinaturas como request_too_large, input exceeds the maximum number of tokens, input token count exceeds the maximum number of input tokens, input is too long for the model ou ollama error: context length exceeded permanecem no caminho de compaction/nova tentativa em vez de avançar o fallback de modelo.Texto genérico de erro de servidor é intencionalmente mais restrito do que “qualquer coisa com unknown/error nele”. O OpenClaw trata formatos transitórios com escopo de provedor, como o An unknown error occurred simples da Anthropic, o Provider returned error simples da OpenRouter, erros de motivo de parada como Unhandled stop reason: error, cargas JSON api_error com texto transitório de servidor (internal server error, unknown error, 520, upstream error, backend error) e erros de provedor ocupado como ModelNotReadyException como sinais de timeout/sobrecarga que justificam failover quando o contexto do provedor corresponde. Texto genérico de fallback interno como LLM request failed with an unknown error. permanece conservador e não aciona fallback de modelo sozinho.
Significa que o sistema tentou usar o ID de perfil de autenticação anthropic:default, mas não conseguiu encontrar credenciais para ele no armazenamento de autenticação esperado.Checklist de correção:
  • Confirme onde os perfis de autenticação ficam (caminhos novos vs. legados)
    • Atual: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
    • Legado: ~/.openclaw/agent/* (migrado por openclaw doctor)
  • Confirme que sua variável de ambiente é carregada pelo Gateway
    • Se você definir ANTHROPIC_API_KEY no shell, mas executar o Gateway via systemd/launchd, ele pode não herdá-la. Coloque-a em ~/.openclaw/.env ou habilite env.shellEnv.
  • Garanta que você está editando o agente correto
    • Configurações multiagente significam que pode haver vários arquivos auth-profiles.json.
  • Faça uma verificação básica do status de modelo/autenticação
    • Use openclaw models status para ver os modelos configurados e se os provedores estão autenticados.
Checklist de correção para “No credentials found for profile anthropic”Isso significa que a execução está fixada em um perfil de autenticação da Anthropic, mas o Gateway não consegue encontrá-lo em seu armazenamento de autenticação.
  • Use a Claude CLI
    • Execute openclaw models auth login --provider anthropic --method cli --set-default no host do gateway.
  • Se quiser usar uma chave de API em vez disso
    • Coloque ANTHROPIC_API_KEY em ~/.openclaw/.env no host do gateway.
    • Limpe qualquer ordem fixada que force um perfil ausente: 
      openclaw models auth order clear --provider anthropic
  • Confirme que você está executando comandos no host do gateway
    • No modo remoto, os perfis de autenticação ficam na máquina do gateway, não no seu laptop.
Se sua configuração de modelo incluir o Google Gemini como fallback (ou você tiver mudado para um atalho Gemini), o OpenClaw o tentará durante o fallback de modelo. Se você não configurou credenciais do Google, verá No API key found for provider "google".Correção: forneça autenticação do Google ou remova/evite modelos Google em agents.defaults.model.fallbacks / aliases para que o fallback não roteie para lá.Solicitação LLM rejeitada: assinatura de thinking obrigatória (Google Antigravity)Causa: o histórico da sessão contém blocos de thinking sem assinaturas (geralmente de um fluxo abortado/parcial). O Google Antigravity exige assinaturas para blocos de thinking.Correção: o OpenClaw agora remove blocos de thinking não assinados para o Google Antigravity Claude. Se ainda aparecer, inicie uma nova sessão ou defina /thinking off para esse agente.

​
Perfis de autenticação: o que são e como gerenciá-los

Relacionado: /concepts/oauth (fluxos OAuth, armazenamento de tokens, padrões de várias contas)
Um perfil de autenticação é um registro de credencial nomeado (OAuth ou chave de API) vinculado a um provedor. Os perfis ficam em:
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
Para inspecionar perfis salvos sem despejar segredos, execute openclaw models auth list (opcionalmente --provider <id> ou --json). Consulte CLI de modelos para obter detalhes.
O OpenClaw usa IDs prefixados pelo provedor, como:
  • anthropic:default (comum quando não existe identidade de email)
  • anthropic:<email> para identidades OAuth
  • IDs personalizados que você escolhe (por exemplo, anthropic:work)
Sim. A configuração aceita metadados opcionais para perfis e uma ordenação por provedor (auth.order.<provider>). Isso não armazena segredos; mapeia IDs para provedor/modo e define a ordem de rotação.O OpenClaw pode pular temporariamente um perfil se ele estiver em um cooldown curto (limites de taxa/timeouts/falhas de autenticação) ou em um estado desativado mais longo (cobrança/créditos insuficientes). Para inspecionar isso, execute openclaw models status --json e verifique auth.unusableProfiles. Ajuste: auth.cooldowns.billingBackoffHours*.Cooldowns por limite de taxa podem ter escopo de modelo. Um perfil em cooldown para um modelo ainda pode ser utilizável para um modelo irmão no mesmo provedor, enquanto janelas de cobrança/desativação ainda bloqueiam o perfil inteiro.Você também pode definir uma substituição de ordem por agente (armazenada no auth-state.json desse agente) via CLI:
# Usa como padrão o agente padrão configurado (omita --agent)
openclaw models auth order get --provider anthropic

# Bloquear rotação em um único perfil (tentar apenas este)
openclaw models auth order set --provider anthropic anthropic:default

# Ou definir uma ordem explícita (fallback dentro do provedor)
openclaw models auth order set --provider anthropic anthropic:work anthropic:default

# Limpar substituição (voltar para config auth.order / round-robin)
openclaw models auth order clear --provider anthropic
Para direcionar a um agente específico:
openclaw models auth order set --provider anthropic --agent main anthropic:default
Para verificar o que será realmente tentado, use:
openclaw models status --probe
Se um perfil armazenado for omitido da ordem explícita, a sondagem relata excluded_by_auth_order para esse perfil em vez de tentá-lo silenciosamente.
O OpenClaw oferece suporte a ambos:
  • OAuth / login via CLI frequentemente aproveita o acesso por assinatura quando o provedor oferece suporte. Para a Anthropic, o backend da Claude CLI do OpenClaw usa Claude Code claude -p; a Anthropic atualmente trata isso como uso do SDK/programático de Agent. A Anthropic pausou a alteração separada de crédito do Agent SDK de 15 de junho de 2026, então, por enquanto, isso ainda consome dos limites de uso da assinatura. Consulte o artigo sobre plano do Agent SDK da Anthropic para o aviso de pausa atual.
  • Chaves de API usam cobrança por token.
O assistente oferece suporte explícito à Anthropic Claude CLI, OpenAI Codex OAuth e chaves de API.

​
Relacionado