CLI de modelos

Refs de modelo escolhem um provedor e um modelo. Normalmente, elas não escolhem o runtime de agente de baixo nível. As refs de agente OpenAI são a principal exceção: openai/gpt-5.5 é executado pelo runtime do app-server Codex por padrão no provedor OpenAI oficial. Refs de assinatura Copilot (github-copilot/*) também podem ser habilitadas para o plugin externo de runtime de agente GitHub Copilot — esse caminho permanece explícito (sem fallback auto). Sobrescritas 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

OpenClaw seleciona modelos nesta ordem:

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 principais específicos de agente) são o ponto de partida normal e usam agents.defaults.model.fallbacks.
• Seleções de fallback automático são estado de recuperação temporário. Elas são armazenadas com modelOverrideSource: "auto" para que turnos posteriores possam continuar usando a cadeia de fallback sem sondar um primário conhecido como problemático todas as vezes; o OpenClaw sonda periodicamente o primário original novamente, 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 cair 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 novamente o primário configurado.
• 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).
• O modelo padrão da CLI e os seletores de allowlist respeitam models.mode: "replace" listando models.providers.*.models explícitos em vez de carregar o catálogo integrado completo.
• O seletor de modelo da Control UI pede ao Gateway a visualização de modelo configurada: agents.defaults.models quando presente, incluindo entradas provider/* para o provedor inteiro; caso contrário, models.providers.*.models explícitos mais provedores com autenticação utilizável. O catálogo integrado completo é reservado para visualizaçõ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 de geração mais recente e mais forte disponível para você.
• Use fallbacks 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 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 OpenAI Code (Codex) subscription (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 + entradas dinâmicas de provedor provider/*)
• 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 sobrescritas 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 incluiu uma sobrescrita 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 autenticação 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 provider/model 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 combinadas com entradas provider/* quando você precisar 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" },      },    },  },}

Alternar 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/configuração completos do comando: Comandos de barra.

Comandos da CLI

openclaw models listopenclaw models statusopenclaw models set <provider/model>openclaw models set-image <provider/model> openclaw models aliases listopenclaw models aliases add <alias> <provider/model>openclaw models aliases remove <alias> openclaw models fallbacks listopenclaw models fallbacks add <provider/model>openclaw models fallbacks remove <provider/model>openclaw models fallbacks clear openclaw models image-fallbacks listopenclaw 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:

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

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 com 24h de antecedência por padrão). --plain imprime somente o modelo primário resolvido.

Exemplo (Claude CLI):

claude auth loginopenclaw 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.

Os resultados da varredura são classificados por:

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

Entrada:

• Lista /models do OpenRouter (filtro :free)
• Sondagens ao vivo exigem uma 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/sondagem: --timeout, --concurrency

Quando sondagens ao vivo são executadas em um 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 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 Plugins de provedores são armazenados como shards de catálogo gerados e pertencentes ao Plugin no estado de Plugin do agente e carregados automaticamente. Esse arquivo é mesclado por padrão, a menos que models.mode seja definido como replace.

Relacionados

• Runtimes de agente — OpenClaw, Codex e outros runtimes de loop de agente
• Referência de configuração — chaves de configuração de modelo
• Geração de imagens — 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