CLI de Modelos

Refs de modelo escolhem um provedor e um modelo. Normalmente, eles não escolhem o runtime de agente de baixo nível. Por exemplo, openai/gpt-5.5 pode executar pelo caminho normal do provedor OpenAI ou pelo runtime do app-server do Codex, dependendo de agents.defaults.agentRuntime.id. 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 do perfil de autenticação openai-codex. Veja Runtimes de agentes.

# Como a seleção de modelo funciona

O OpenClaw seleciona modelos nesta ordem:

# Fonte 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 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 primeiro um primário sabidamente ruim.
• Seleções de sessão do usuário são exatas. /model, o seletor de modelos, 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 cair para outro modelo configurado.
• Cron --model / payload model é um primário por job. Ele ainda usa fallbacks configurados, a menos que o job forneça fallbacks explícitos no payload (use fallbacks: [] para uma execução de cron estrita).
• Os seletores de modelo padrão e allowlist da CLI respeitam models.mode: "replace" listando models.providers.*.models explícitos em vez de carregar todo o catálogo integrado.
• O seletor de modelos da Control UI pede ao Gateway a visão configurada de modelos: agents.defaults.models quando presente; caso contrário, models.providers.*.models explícitos mais provedores com autenticação utilizável. O catálogo integrado completo é reservado para visões de navegação explícitas, como models.list com view: "all" ou openclaw models list --all.

# Política rápida de modelos

• Defina seu primário como o modelo de geração mais recente mais forte disponível para você.
• Use fallbacks para tarefas sensíveis a custo/latência e chats de menor risco.
• Para agentes com ferramentas habilitadas ou entradas não confiáveis, evite camadas de modelo 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.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)
• models.providers (provedores personalizados gravados em models.json)

# Edições seguras da allowlist

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

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

# "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

Quando o comando rejeitado incluía uma substituição de runtime, como /model openai/gpt-5.5 --runtime codex, corrija primeiro a allowlist 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 de 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.

Exemplo de configuração de allowlist:

{
  agent: {
    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 status

Comportamento/configuração completa do comando: Comandos de barra.

# 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/com autenticação disponível por padrão. Flags úteis:

--allboolean

Catálogo completo. Inclui linhas de catálogo estático pertencentes a provedores incluídos antes de a autenticação ser configurada, para que visualizações apenas de descoberta possam mostrar modelos indisponíveis até você adicionar credenciais de provedor correspondentes.

--localboolean

Apenas provedores locais.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcHJvdmlkZXIgPGlk " type="string"> Filtre por id do provedor, por exemplo moonshot. Rótulos exibidos por seletores interativos não são aceitos.

--plainboolean

Um modelo por linha.

--jsonboolean

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 OAuth para perfis encontrados no armazenamento de autenticação (avisa dentro de 24h por padrão). --plain imprime apenas o modelo primário resolvido.

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 sondar modelos quanto a suporte a ferramentas e imagens.

--no-probeboolean

Pule sondagens ao vivo (somente metadados).

"--min-params

"--max-age-days

"--provider

"--max-candidates

--set-defaultboolean

Defina agents.defaults.model.primary para a primeira seleção.

--set-imageboolean

Defina agents.defaults.imageModel.primary para a primeira seleção de imagem.

Os resultados da varredura são classificados por:

1. Suporte a imagem
2. Latência de ferramenta
3. Tamanho do contexto
4. Contagem de parâmetros

Entrada:

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

Quando sondagens ao vivo são executadas em uma TUI, você pode selecionar fallbacks interativamente. No modo não interativo, passe --yes para aceitar os padrões. Resultados somente de metadados são informativos; --set-default e --set-image exigem sondagens 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). Esse arquivo é mesclado por padrão, a menos que models.mode seja definido como replace.

# Relacionados

• Runtimes de agente — PI, Codex e outros runtimes de loop de agente
• Referência de configuração — chaves de configuração de modelo
• Geração de imagem — configuração de modelo de imagem
• Failover de modelo — cadeias de fallback
• Provedores de modelo — roteamento e autenticação de provedores
• Geração de música — configuração de modelo de música
• Geração de vídeo — configuração de modelo de vídeo