CLI de modelos

Veja /concepts/model-failover para rotação de perfis de autenticação, cooldowns e como isso interage com fallbacks. Visão geral rápida de provedores + exemplos: /concepts/model-providers.

Como funciona a seleção de modelos

O OpenClaw seleciona modelos nesta ordem:

Primário (agents.defaults.model.primary ou agents.defaults.model).
Fallbacks em agents.defaults.model.fallbacks (em ordem).
Failover de autenticação do provedor acontece dentro de um provedor antes de passar para o próximo modelo.

Relacionado:

agents.defaults.models é a lista de permissões/catálogo de modelos que o OpenClaw pode usar (além de aliases).
agents.defaults.imageModel é usado apenas quando o modelo primário não aceita imagens.
Padrões por agente podem substituir agents.defaults.model via agents.list[].model mais bindings (veja /concepts/multi-agent).

Escolhas rápidas de modelos (anedóticas)

GLM: um pouco melhor para código/chamada de ferramentas.
MiniMax: melhor para escrita e “vibes”.

Assistente de configuração (recomendado)

Se voce não quiser editar a configuração manualmente, execute o assistente de integração inicial:

openclaw onboard

Ele pode configurar modelo + autenticação para provedores comuns, incluindo OpenAI Code (Codex) subscription (OAuth) e Anthropic (chave de API recomendada; claude setup-token também é compatível).

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

agents.defaults.model.primary e agents.defaults.model.fallbacks
agents.defaults.imageModel.primary e agents.defaults.imageModel.fallbacks
agents.defaults.models (lista de permissões + aliases + parâmetros do provedor)
models.providers (provedores personalizados gravados em models.json)

Referências de modelos são normalizadas para minúsculas. Aliases de provedores como z.ai/* normalizam para zai/*. Exemplos de configuração de provedores (incluindo OpenCode Zen) ficam em /gateway/configuration.

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

Se agents.defaults.models estiver definido, ele se torna a lista de permissões para /model e para substituições de sessão. Quando um usuário seleciona um modelo que não está nessa lista, o OpenClaw retorna:

Model "provider/model" is not allowed. Use /model to list available models.

Isso acontece antes de uma resposta normal ser gerada, então a mensagem pode parecer que “não respondeu”. A correção é:

Adicionar o modelo a agents.defaults.models, ou
Limpar a lista de permissões (remover agents.defaults.models), ou
Escolher um modelo de /model list.

Exemplo de configuração de lista de permissões:

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

Alternar modelos no chat (`/model`)

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

/model
/model list
/model 3
/model openai/gpt-5.2
/model status

Notas:

/model (e /model list) é um seletor compacto e numerado (família do modelo + provedores disponíveis).
/model <#> seleciona a partir desse seletor.
/model status é a visualização detalhada (candidatos de autenticação e, quando configurado, endpoint do provedor baseUrl + modo api).
Referências de modelos são analisadas dividindo no primeiro /. Use provider/model ao digitar /model <ref>.
Se o próprio ID do modelo contiver / (estilo OpenRouter), voce deve incluir o prefixo do provedor (exemplo: /model openrouter/moonshotai/kimi-k2).
Se voce omitir o provedor, o OpenClaw trata a entrada como um alias ou um modelo para o provedor padrão (funciona apenas quando não há / no ID do modelo).

Comportamento/configuração completa do comando: Slash commands.

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 os modelos configurados por padrão. Flags úteis:

--all: catálogo completo
--local: apenas provedores locais
--provider <name>: filtrar por provedor
--plain: um modelo por linha
--json: 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 exibe o status de expiração do OAuth para perfis encontrados no armazenamento de autenticação (avisa dentro de 24h por padrão). --plain imprime apenas o modelo primário resolvido. O status do OAuth é sempre exibido (e incluído na saída de --json). Se um provedor configurado não tiver credenciais, models status imprime uma seção Missing auth. O JSON inclui auth.oauth (janela de aviso + perfis) e auth.providers (autenticação efetiva por provedor). Use --check para automação (saída 1 quando ausente/expirada, 2 quando prestes a expirar). A autenticação preferida da Anthropic é o setup-token do Claude Code CLI (execute em qualquer lugar; cole no host do Gateway se necessário):

claude setup-token
openclaw models status

Varredura (modelos gratuitos do OpenRouter)

openclaw models scan inspeciona o catálogo de modelos gratuitos do OpenRouter e pode opcionalmente sondar modelos para suporte a ferramentas e imagens. Principais flags:

--no-probe: pular sondagens ao vivo (apenas metadados)
--min-params <b>: tamanho mínimo de parâmetros (bilhões)
--max-age-days <days>: pular modelos mais antigos
--provider <name>: filtro de prefixo de provedor
--max-candidates <n>: tamanho da lista de fallbacks
--set-default: definir agents.defaults.model.primary como a primeira seleção
--set-image: definir agents.defaults.imageModel.primary como a primeira seleção de imagem

A sondagem requer uma chave de API do OpenRouter (dos perfis de autenticação ou OPENROUTER_API_KEY). Sem uma chave, use --no-probe para listar apenas candidatos. Os resultados da varredura são classificados por:

Suporte a imagens
Latência de ferramentas
Tamanho de contexto
Contagem de parâmetros

Entrada

Lista de /models do OpenRouter (filtro :free)
Requer chave de API do OpenRouter dos perfis de autenticação ou OPENROUTER_API_KEY (veja /environment)
Filtros opcionais: --max-age-days, --min-params, --provider, --max-candidates
Controles de sondagem: --timeout, --concurrency

Ao executar em um TTY, voce pode selecionar fallbacks interativamente. No modo não interativo, passe --yes para aceitar os padrões.

Registro de modelos (`models.json`)

Provedores personalizados em models.providers são gravados em models.json sob o diretório do agente (padrão ~/.openclaw/agents/<agentId>/models.json). Este arquivo é mesclado por padrão, a menos que models.mode esteja definido como replace.

Visão geral

Conceitos de modelo

Configuração

Provedores

CLI de modelos

CLI de modelos

Como funciona a seleção de modelos

Escolhas rápidas de modelos (anedóticas)

Assistente de configuração (recomendado)

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

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

Alternar modelos no chat (`/model`)

Comandos da CLI

`models list`

`models status`

Varredura (modelos gratuitos do OpenRouter)

Registro de modelos (`models.json`)

Visão geral

Conceitos de modelo

Configuração

Provedores

​CLI de modelos

​Como funciona a seleção de modelos

​Escolhas rápidas de modelos (anedóticas)

​Assistente de configuração (recomendado)

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

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

​Alternar modelos no chat (/model)

​Comandos da CLI

​models list

​models status

​Varredura (modelos gratuitos do OpenRouter)

​Registro de modelos (models.json)

CLI de modelos

Como funciona a seleção de modelos

Escolhas rápidas de modelos (anedóticas)

Assistente de configuração (recomendado)

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

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

Alternar modelos no chat (`/model`)

Comandos da CLI

`models list`

`models status`

Varredura (modelos gratuitos do OpenRouter)

Registro de modelos (`models.json`)