CLI de modelos - OpenClaw

Failover de modelo

Rotação de perfil de autenticação, cooldowns e como isso interage com fallbacks.

Provedores de modelo

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

Runtimes de agente

OpenClaw, Codex e outros runtimes de loop de agente.

Referência de configuração

Chaves de configuração de modelo.

Refs de modelo escolhem um provedor e um modelo. Em geral, elas não escolhem o runtime de agente de baixo nível. Refs de agente OpenAI são a principal exceção: openai/gpt-5.5 é executado pelo runtime de app-server do Codex por padrão no provedor oficial da OpenAI. Refs de assinatura do Copilot (github-copilot/*) também podem ser configuradas para usar o Plugin de runtime de agente externo GitHub Copilot — esse caminho permanece explícito (sem fallback auto). Substituições explícitas de runtime pertencem à política de provedor/modelo, não ao agente ou à sessão inteira. No modo de runtime Codex, a ref openai/gpt-* não implica cobrança por chave de API; a autenticação pode vir de uma conta Codex ou de um perfil OAuth openai. Consulte Runtimes de agente e runtime de agente GitHub Copilot.

Como a seleção de modelo funciona

O OpenClaw seleciona modelos nesta ordem:

Modelo primário

agents.defaults.model.primary (ou agents.defaults.model).

Fallbacks

agents.defaults.model.fallbacks (em ordem).

Failover de autenticação do provedor

O failover de autenticação acontece dentro de um provedor antes de passar para o próximo modelo.

Superfícies de modelo relacionadas

agents.defaults.models é a allowlist/catálogo de modelos que o OpenClaw pode usar (mais aliases). Use entradas provider/* para limitar provedores visíveis mantendo a descoberta de provedores dinâmica.
agents.defaults.utilityModel é um modelo opcional de menor custo para tarefas internas curtas, como títulos gerados de sessões de dashboard e títulos compatíveis de threads/tópicos de canais. agents.list[].utilityModel por agente o substitui. Quando não definido, essas tarefas usam o modelo primário do agente. Tarefas utilitárias são chamadas de modelo separadas e podem enviar conteúdo delimitado da tarefa ao provedor de modelo selecionado.
agents.defaults.imageModel é usado somente quando o modelo primário não consegue aceitar imagens.
agents.defaults.pdfModel é usado pela ferramenta pdf. Se omitido, a ferramenta recorre a agents.defaults.imageModel e depois ao modelo resolvido da sessão/padrão.
agents.defaults.imageGenerationModel é usado pela capacidade compartilhada de geração de imagens. Se omitido, image_generate ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os provedores registrados restantes de geração de imagens em ordem de ID de provedor. Se você definir um provedor/modelo específico, configure também a autenticação/chave de API desse provedor.
agents.defaults.musicGenerationModel é usado pela capacidade compartilhada de geração de música. Se omitido, music_generate ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os provedores registrados restantes de geração de música em ordem de ID de provedor. Se você definir um provedor/modelo específico, configure também a autenticação/chave de API desse provedor.
agents.defaults.videoGenerationModel é usado pela capacidade compartilhada de geração de vídeo. Se omitido, video_generate ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os provedores registrados restantes de geração de vídeo em ordem de ID de provedor. Se você definir um provedor/modelo específico, configure também a autenticação/chave de API desse provedor.
Padrões por agente podem substituir agents.defaults.model via agents.list[].model mais vinculações (consulte Roteamento multiagente).

Origem da seleção e comportamento de fallback

O mesmo provider/model pode significar coisas diferentes dependendo de onde veio:

Padrões configurados (agents.defaults.model.primary e primários específicos de agente) são o ponto de partida normal e usam agents.defaults.model.fallbacks.
Seleções de fallback automáticas são um estado temporário de recuperação. Elas são armazenadas com modelOverrideSource: "auto" para que turnos posteriores possam continuar usando a cadeia de fallback sem sondar um primário sabidamente problemático toda vez; o OpenClaw sonda periodicamente o primário original de novo, limpa a seleção automática quando ele se recupera e anuncia transições de fallback/recuperação uma vez por mudança de estado.
Seleções de sessão do usuário são exatas. /model, o seletor de modelo, session_status(model=...) e sessions.patch armazenam modelOverrideSource: "user"; se esse provedor/modelo selecionado estiver inacessível, o OpenClaw falha de forma visível em vez de passar para outro modelo configurado.
Alterar agents.defaults.model.primary não reescreve seleções de sessão existentes. Se o status disser This session is pinned to X; config primary Y will apply to new/unpinned sessions., limpe a seleção da sessão atual com /model default para que ela herde o primário configurado novamente.
Cron --model / payload model é um primário por tarefa. Ele ainda usa fallbacks configurados, a menos que a tarefa forneça fallbacks explícitos no payload (use fallbacks: [] para uma execução cron estrita).
Seletores de modelo padrão e allowlist da CLI respeitam models.mode: "replace" listando models.providers.*.models explícitos em vez de carregar o catálogo completo integrado.
O seletor de modelos da Control UI pergunta ao Gateway por sua visão de modelo configurada: agents.defaults.models quando presente, incluindo entradas provider/* para todo o provedor; caso contrário, models.providers.*.models explícitos mais provedores com autenticação utilizável. O catálogo completo integrado é reservado para visões explícitas de navegação, como models.list com view: "all" ou openclaw models list --all.

Política rápida de modelo

Defina seu primário como o modelo mais forte de geração mais recente disponível para você.
Use fallbacks para tarefas sensíveis a custo/latência e chat de menor risco.
Para agentes com ferramentas habilitadas ou entradas não confiáveis, evite camadas de modelos mais antigas/fracas.

Onboarding (recomendado)

Se você não quiser editar a configuração manualmente, execute o onboarding:

openclaw onboard

Ele pode configurar modelo + autenticação para provedores comuns, incluindo assinatura OpenAI Code (Codex) (OAuth) e Anthropic (chave de API ou Claude CLI).

Chaves de configuração (visão geral)

agents.defaults.model.primary e agents.defaults.model.fallbacks
agents.defaults.utilityModel
agents.defaults.imageModel.primary e agents.defaults.imageModel.fallbacks
agents.defaults.pdfModel.primary e agents.defaults.pdfModel.fallbacks
agents.defaults.imageGenerationModel.primary e agents.defaults.imageGenerationModel.fallbacks
agents.defaults.videoGenerationModel.primary e agents.defaults.videoGenerationModel.fallbacks
agents.defaults.models (allowlist + aliases + parâmetros de provedor + entradas dinâmicas de provedor provider/*)
models.providers (provedores personalizados gravados em models.json)

Refs de modelo são normalizadas para minúsculas. IDs de provedor são exatos nos demais casos; use o ID de provedor anunciado pelo plugin.Exemplos de configuração de provedor (incluindo OpenCode) ficam em OpenCode.

Edições seguras de allowlist

Use gravações aditivas ao atualizar agents.defaults.models manualmente:

openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge

Regras de proteção contra sobrescrita

openclaw config set protege mapas de modelo/provedor contra sobrescritas acidentais. Uma atribuição de objeto simples a agents.defaults.models, models.providers ou models.providers.<id>.models é rejeitada quando removeria entradas existentes. Use --merge para alterações aditivas; use --replace somente quando o valor fornecido deve se tornar o valor-alvo completo.A configuração interativa de provedor e openclaw configure --section model também mesclam seleções com escopo de provedor na allowlist existente, portanto adicionar Codex, Ollama ou outro provedor não descarta entradas de modelo não relacionadas. Configure preserva um agents.defaults.model.primary existente quando a autenticação de provedor é reaplicada. Comandos explícitos de definição de padrão, como openclaw models auth login --provider <id> --set-default e openclaw models set <model>, ainda substituem agents.defaults.model.primary.

”Modelo não permitido” (e por que as respostas param)

Se agents.defaults.models estiver definido, ele se torna a allowlist para /model e para substituições de sessão. Quando um usuário seleciona um modelo que não está nessa allowlist, o OpenClaw 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

Isso acontece antes que uma resposta normal seja gerada, então a mensagem pode parecer que ele “não respondeu”. A correção é uma destas opções:

Adicione o modelo a agents.defaults.models, ou
Limpe a allowlist (remova agents.defaults.models), ou
Escolha um modelo em /model list.

Quando o comando rejeitado incluía uma substituição de runtime, como /model openai/gpt-5.5 --runtime codex, corrija a allowlist primeiro e depois tente novamente o mesmo comando /model ... --runtime .... Para execução nativa do Codex, o modelo selecionado ainda é openai/gpt-5.5; o runtime codex seleciona o harness e usa a autenticação do Codex separadamente. Para modelos locais/GGUF, armazene a ref completa com prefixo do provedor na allowlist, por exemplo ollama/gemma4:26b, lmstudio/Gemma4-26b-a4-it-gguf ou o provedor/modelo exato mostrado por openclaw models list --provider <provider>. Nomes de arquivos locais simples ou nomes de exibição não são suficientes quando a allowlist está ativa. Se você quiser limitar provedores sem listar manualmente todos os modelos, adicione entradas provider/* a agents.defaults.models:

{
  agents: {
    defaults: {
      models: {
        "openai/*": {},
        "vllm/*": {},
      },
    },
  },
}

Com essa política, /model, /models e seletores de modelo mostram o catálogo descoberto apenas para esses provedores. Novos modelos dos provedores selecionados podem aparecer sem editar a allowlist. Entradas exatas provider/model podem ser misturadas com entradas provider/* quando você precisa de um modelo específico de outro provedor. Exemplo de configuração de allowlist:

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-sonnet-4-6" },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "anthropic/claude-opus-4-6": { alias: "Opus" },
      },
    },
  },
}

Alternando modelos no chat (`/model`)

Você pode alternar modelos para a sessão atual sem reiniciar:

/model
/model list
/model 3
/model openai/gpt-5.4
/model default
/model status

Comportamento do seletor

/model (e /model list) é um seletor compacto e numerado (família de modelo + provedores disponíveis).
No Discord, /model e /models abrem um seletor interativo com menus suspensos de provedor e modelo mais uma etapa de envio.
No Telegram, as seleções do seletor /models têm escopo de sessão; elas não alteram o padrão persistente do agente em openclaw.json.
/models add está obsoleto e agora retorna uma mensagem de obsolescência em vez de registrar modelos pelo chat.
/model <#> seleciona a partir desse seletor.

Persistência e troca ao vivo

/model persiste a nova seleção da sessão imediatamente.
Se o agente estiver ocioso, a próxima execução usa o novo modelo imediatamente.
Se uma execução já estiver ativa, o OpenClaw marca uma troca ao vivo como pendente e só reinicia no novo modelo em um ponto de nova tentativa limpo.
Se a atividade de ferramentas ou a saída da resposta já tiver começado, a troca pendente pode permanecer na fila até uma oportunidade posterior de nova tentativa ou o próximo turno do usuário.
/model default limpa a seleção da sessão e retorna a sessão ao modelo padrão configurado.
Uma referência /model selecionada pelo usuário é estrita para essa sessão: se o provedor/modelo selecionado estiver inacessível, a resposta falha de forma visível em vez de responder silenciosamente a partir de agents.defaults.model.fallbacks. Isso é diferente dos padrões configurados e dos modelos primários de trabalhos cron, que ainda podem usar cadeias de fallback.
/model status é a visualização detalhada (candidatos de autenticação e, quando configurado, endpoint do provedor baseUrl + modo api).

Análise de refs

As refs de modelo são analisadas dividindo no primeiro /. Use provider/model ao digitar /model <ref>.
Se o ID do modelo em si contiver / (estilo OpenRouter), você deve incluir o prefixo do provedor (exemplo: /model openrouter/moonshotai/kimi-k2).
Se você omitir o provedor, o OpenClaw resolve a entrada nesta ordem:
1. correspondência de alias
2. correspondência única de provedor configurado para esse ID de modelo exato sem prefixo
3. fallback obsoleto para o provedor padrão configurado — se esse provedor não expuser mais o modelo padrão configurado, o OpenClaw usa como fallback o primeiro provedor/modelo configurado para evitar expor um padrão obsoleto de provedor removido.

Comportamento/configuração completos do comando: Comandos slash.

Comandos da CLI

openclaw models list
openclaw models status
openclaw models set <provider/model>
openclaw models set-image <provider/model>

openclaw models aliases list
openclaw models aliases add <alias> <provider/model>
openclaw models aliases remove <alias>

openclaw models fallbacks list
openclaw models fallbacks add <provider/model>
openclaw models fallbacks remove <provider/model>
openclaw models fallbacks clear

openclaw models image-fallbacks list
openclaw models image-fallbacks add <provider/model>
openclaw models image-fallbacks remove <provider/model>
openclaw models image-fallbacks clear

openclaw models (sem subcomando) é um atalho para models status.

`models list`

Mostra modelos configurados/disponíveis por autenticação por padrão. Flags úteis:

--all

boolean

Catálogo completo. Inclui linhas de catálogo estático pertencentes ao provedor e incluídas no pacote antes da autenticação ser configurada, para que visualizações somente de descoberta possam mostrar modelos indisponíveis até você adicionar credenciais correspondentes do provedor.

--local

boolean

Somente provedores locais.

--provider <id>

string

Filtra por ID de provedor, por exemplo moonshot. Rótulos de exibição de seletores interativos não são aceitos.

--plain

boolean

Um modelo por linha.

--json

boolean

Saída legível por máquina.

`models status`

Mostra o modelo primário resolvido, fallbacks, modelo de imagem e uma visão geral de autenticação dos provedores configurados. Também expõe o status de expiração OAuth para perfis encontrados no armazenamento de autenticação (avisa dentro de 24h por padrão). --plain imprime somente o modelo primário resolvido.

Comportamento de autenticação e probes

O status OAuth é sempre mostrado (e incluído na saída --json). Se um provedor configurado não tiver credenciais, models status imprime uma seção Autenticação ausente.
JSON inclui auth.oauth (janela de aviso + perfis) e auth.providers (autenticação efetiva por provedor, incluindo credenciais com base em env). auth.oauth é somente a saúde dos perfis do armazenamento de autenticação; provedores somente por env não aparecem ali.
Use --check para automação (sai com 1 quando ausente/expirado, 2 quando prestes a expirar).
Use --probe para verificações de autenticação ao vivo; linhas de probe podem vir de perfis de autenticação, credenciais env ou models.json.
Se auth.order.<provider> explícito omitir um perfil armazenado, o probe relata excluded_by_auth_order em vez de tentar usá-lo. Se a autenticação existir, mas nenhum modelo que possa ser testado por probe puder ser resolvido para esse provedor, o probe relata status: no_model.

A escolha de autenticação depende do provedor/conta. Para hosts de Gateway sempre ativos, chaves de API geralmente são as mais previsíveis; a reutilização da Claude CLI e perfis OAuth/token existentes da Anthropic também são compatíveis.

Exemplo (Claude CLI):

claude auth login
openclaw models status

Varredura (modelos gratuitos do OpenRouter)

openclaw models scan inspeciona o catálogo de modelos gratuitos do OpenRouter e pode opcionalmente testar modelos por probe para suporte a ferramentas e imagens.

--no-probe

boolean

Ignora probes ao vivo (somente metadados).

--min-params <b>

number

Tamanho mínimo de parâmetros (bilhões).

--max-age-days <days>

number

Ignora modelos mais antigos.

--provider <name>

string

Filtro de prefixo de provedor.

--max-candidates <n>

number

Tamanho da lista de fallbacks.

--set-default

boolean

Define agents.defaults.model.primary como a primeira seleção.

--set-image

boolean

Define agents.defaults.imageModel.primary como a primeira seleção de imagem.

O catálogo /models do OpenRouter é público, então varreduras somente de metadados podem listar candidatos gratuitos sem uma chave. Probes e inferência ainda exigem uma chave de API do OpenRouter (de perfis de autenticação ou OPENROUTER_API_KEY). Se nenhuma chave estiver disponível, openclaw models scan usa como fallback a saída somente de metadados e deixa a configuração inalterada. Use --no-probe para solicitar explicitamente o modo somente de metadados.

Os resultados da varredura são classificados por:

Suporte a imagem
Latência de ferramenta
Tamanho do contexto
Contagem de parâmetros

Entrada:

Lista /models do OpenRouter (filtro :free)
Probes ao vivo exigem chave de API do OpenRouter de perfis de autenticação ou OPENROUTER_API_KEY (consulte Variáveis de ambiente)
Filtros opcionais: --max-age-days, --min-params, --provider, --max-candidates
Controles de solicitação/probe: --timeout, --concurrency

Quando probes ao vivo são executados em um TTY, você pode selecionar fallbacks interativamente. Em modo não interativo, passe --yes para aceitar os padrões. Resultados somente de metadados são informativos; --set-default e --set-image exigem probes ao vivo para que o OpenClaw não configure um modelo OpenRouter sem chave e inutilizável.

Registro de modelos (`models.json`)

Provedores personalizados em models.providers são gravados em models.json no diretório do agente (padrão ~/.openclaw/agents/<agentId>/agent/models.json). Catálogos de Plugin de provedor são armazenados como shards de catálogo gerados pertencentes ao Plugin no estado de Plugin do agente e carregados automaticamente. Esse arquivo é mesclado por padrão, a menos que models.mode esteja definido como replace.

Precedência do modo de mesclagem

Precedência do modo de mesclagem para IDs de provedor correspondentes:

baseUrl não vazio já presente no models.json do agente vence.
apiKey não vazio no models.json do agente vence somente quando esse provedor não é gerenciado por SecretRef no contexto atual de configuração/perfil de autenticação.
Valores de apiKey de provedor gerenciado por SecretRef são atualizados a partir de marcadores de origem (ENV_VAR_NAME para refs env, secretref-managed para refs file/exec) em vez de persistir segredos resolvidos.
Valores de cabeçalho de provedor gerenciado por SecretRef são atualizados a partir de marcadores de origem (secretref-env:ENV_VAR_NAME para refs env, secretref-managed para refs file/exec).
apiKey/baseUrl vazios ou ausentes no agente usam como fallback 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 de marcadores é autoritativa pela origem: o OpenClaw grava marcadores a partir do snapshot de configuração de origem ativo (pré-resolução), não de valores de segredo resolvidos em runtime. Isso se aplica sempre que o OpenClaw regenera models.json, incluindo caminhos orientados por comando como openclaw agent.

Relacionados

Runtimes de agentes — OpenClaw, Codex e outros runtimes de loop de agentes
Referência de configuração — chaves de configuração de modelo
Geração de imagens — configuração de modelo de imagem
Failover de modelos — cadeias de fallback
Provedores de modelo — roteamento de provedor e autenticação
Geração de música — configuração de modelo de música
Geração de vídeo — configuração de modelo de vídeo

Failover de modelo

Provedores de modelo

Runtimes de agente

Referência de configuração

​Como a seleção de modelo funciona

​Origem da seleção e comportamento de fallback

​Política rápida de modelo

​Onboarding (recomendado)

​Chaves de configuração (visão geral)

​Edições seguras de allowlist

​”Modelo não permitido” (e por que as respostas param)

​Alternando modelos no chat (/model)

​Comandos da CLI

​models list

​models status

​Varredura (modelos gratuitos do OpenRouter)

​Registro de modelos (models.json)

​Relacionados

Como a seleção de modelo funciona

Origem da seleção e comportamento de fallback

Política rápida de modelo

Onboarding (recomendado)

Chaves de configuração (visão geral)

Edições seguras de allowlist

”Modelo não permitido” (e por que as respostas param)

Alternando modelos no chat (`/model`)

Comandos da CLI

`models list`

`models status`

Varredura (modelos gratuitos do OpenRouter)

Registro de modelos (`models.json`)

Relacionados