> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # CLI de modelos Rotação de perfil de autenticação, cooldowns e como isso interage com fallbacks. Visão geral rápida de provedores e exemplos. OpenClaw, Codex e outros runtimes de loop de agente. 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](/pt-BR/concepts/agent-runtimes) e [runtime de agente GitHub Copilot](/pt-BR/plugins/copilot). ## Como a seleção de modelo funciona O OpenClaw seleciona modelos nesta ordem: `agents.defaults.model.primary` (ou `agents.defaults.model`). `agents.defaults.model.fallbacks` (em ordem). O failover de autenticação acontece dentro de um provedor antes de passar para o próximo modelo. * `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](/pt-BR/concepts/multi-agent)). ## 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: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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](/pt-BR/providers/opencode). ### Edições seguras de allowlist Use gravações aditivas ao atualizar `agents.defaults.models` manualmente: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge ``` `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..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 --set-default` e `openclaw models set `, 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 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 `. 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`: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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 ``` * `/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. * `/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`). * As refs de modelo são analisadas dividindo no **primeiro** `/`. Use `provider/model` ao digitar `/model `. * 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](/pt-BR/tools/slash-commands). ## Comandos da CLI ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw models list openclaw models status openclaw models set openclaw models set-image openclaw models aliases list openclaw models aliases add openclaw models aliases remove openclaw models fallbacks list openclaw models fallbacks add openclaw models fallbacks remove openclaw models fallbacks clear openclaw models image-fallbacks list openclaw models image-fallbacks add openclaw models image-fallbacks remove 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: 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. Somente provedores locais. Filtra por ID de provedor, por exemplo `moonshot`. Rótulos de exibição de seletores interativos não são aceitos. Um modelo por linha. 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. * 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.` 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): ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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. Ignora probes ao vivo (somente metadados). Tamanho mínimo de parâmetros (bilhões). Ignora modelos mais antigos. Filtro de prefixo de provedor. Tamanho da lista de fallbacks. Define `agents.defaults.model.primary` como a primeira seleção. 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: 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`) * Probes ao vivo exigem chave de API do OpenRouter de perfis de autenticação ou `OPENROUTER_API_KEY` (consulte [Variáveis de ambiente](/pt-BR/help/environment)) * 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//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 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](/pt-BR/concepts/agent-runtimes) — OpenClaw, Codex e outros runtimes de loop de agentes * [Referência de configuração](/pt-BR/gateway/config-agents#agent-defaults) — chaves de configuração de modelo * [Geração de imagens](/pt-BR/tools/image-generation) — configuração de modelo de imagem * [Failover de modelos](/pt-BR/concepts/model-failover) — cadeias de fallback * [Provedores de modelo](/pt-BR/concepts/model-providers) — roteamento de provedor e autenticação * [Geração de música](/pt-BR/tools/music-generation) — configuração de modelo de música * [Geração de vídeo](/pt-BR/tools/video-generation) — configuração de modelo de vídeo