openclaw models

Descoberta, varredura e configuração de modelos (modelo padrão, fallbacks, perfis de autenticação).

Relacionado:

• Provedores + modelos: Modelos
• Conceitos de seleção de modelos + comando de barra /models: Conceito de modelos
• Configuração de autenticação de provedor: Primeiros passos

Comandos comuns

openclaw models statusopenclaw models listopenclaw models set <model-or-alias>openclaw models scan

openclaw models status mostra o padrão/fallbacks resolvidos, além de uma visão geral de autenticação. Quando instantâneos de uso do provedor estão disponíveis, a seção de status OAuth/chave de API inclui janelas de uso do provedor e instantâneos de cota. Provedores atuais de janela de uso: Anthropic, GitHub Copilot, Gemini CLI, OpenAI, MiniMax, Xiaomi e z.ai. A autenticação de uso vem de hooks específicos do provedor quando disponíveis; caso contrário, o OpenClaw recorre a credenciais OAuth/chave de API correspondentes de perfis de autenticação, ambiente ou configuração. Na saída --json, auth.providers é a visão geral do provedor ciente de ambiente/configuração/armazenamento, enquanto auth.oauth é apenas a integridade dos perfis do armazenamento de autenticação. Adicione --probe para executar sondagens de autenticação ao vivo em cada perfil de provedor configurado. As sondagens são solicitações reais (podem consumir tokens e acionar limites de taxa). Use --agent <id> para inspecionar o estado de modelo/autenticação de um agente configurado. Quando omitido, o comando usa OPENCLAW_AGENT_DIR se definido; caso contrário, usa o agente padrão configurado. Linhas de sondagem podem vir de perfis de autenticação, credenciais de ambiente ou models.json. Para solucionar problemas de OAuth do OpenAI ChatGPT/Codex, openclaw models status, openclaw models auth list --provider openai e openclaw config get agents.defaults.model --json são a forma mais rápida de confirmar se um agente tem um perfil OAuth openai utilizável para openai/* por meio do runtime nativo do Codex. Consulte Configuração do provedor OpenAI.

Observações:

• models set <model-or-alias> aceita provider/model ou um alias.
• models list é somente leitura: ele lê configuração, perfis de autenticação, estado de catálogo existente e linhas de catálogo pertencentes ao provedor, mas não reescreve models.json.
• A coluna Auth é em nível de provedor e somente leitura. Ela é calculada a partir de metadados locais de perfil de autenticação, marcadores de ambiente, chaves de provedor configuradas, marcadores de provedor local, marcadores de ambiente/perfil do AWS Bedrock e metadados de autenticação sintética de plugin; ela não carrega o runtime do provedor, lê segredos do chaveiro, chama APIs do provedor nem comprova prontidão exata de execução por modelo.
• models list --all --provider <id> pode incluir linhas de catálogo estático pertencentes ao provedor vindas de manifestos de plugin ou metadados de catálogo de provedor incluído, mesmo quando você ainda não se autenticou com esse provedor. Essas linhas ainda aparecem como indisponíveis até que a autenticação correspondente seja configurada.
• models list mantém o plano de controle responsivo enquanto a descoberta de catálogo do provedor é lenta. As visualizações padrão e configuradas recorrem a linhas de modelo configuradas ou sintéticas após uma espera curta e deixam a descoberta terminar em segundo plano. Use --all quando precisar do catálogo completo descoberto exato e estiver disposto a aguardar a descoberta do provedor.
• Um models list --all amplo mescla linhas de catálogo do manifesto sobre linhas do registro sem carregar hooks complementares do runtime do provedor. Caminhos rápidos de manifesto filtrados por provedor usam apenas provedores marcados como static; provedores marcados como refreshable permanecem apoiados por registro/cache e anexam linhas de manifesto como complementos, enquanto provedores marcados como runtime permanecem na descoberta de registro/runtime.
• models list mantém metadados de modelo nativos e limites de runtime distintos. Na saída em tabela, Ctx mostra contextTokens/contextWindow quando um limite efetivo de runtime difere da janela de contexto nativa; linhas JSON incluem contextTokens quando um provedor expõe esse limite.
• models list --provider <id> filtra por id de provedor, como moonshot ou openai. Ele não aceita rótulos de exibição de seletores interativos de provedor, como Moonshot AI.
• Referências de modelo são analisadas dividindo na primeira /. Se o ID do modelo incluir / (estilo OpenRouter), inclua o prefixo do provedor (exemplo: openrouter/moonshotai/kimi-k2).
• Se você omitir o provedor, o OpenClaw resolve a entrada primeiro como um alias, depois como uma correspondência única de provedor configurado para esse id exato de modelo e só então recorre ao provedor padrão configurado com um aviso de obsolescência. Se esse provedor não expuser mais o modelo padrão configurado, o OpenClaw recorre ao primeiro provedor/modelo configurado em vez de apresentar um padrão obsoleto de provedor removido.
• models status pode mostrar marker(<value>) na saída de autenticação para placeholders não secretos (por exemplo OPENAI_API_KEY, secretref-managed, minimax-oauth, oauth:chutes, ollama-local) em vez de mascará-los como segredos.

Varredura de modelos

models scan lê o catálogo público :free do OpenRouter e ranqueia candidatos para uso como fallback. O catálogo em si é público, portanto varreduras somente de metadados não precisam de uma chave do OpenRouter.

Por padrão, o OpenClaw tenta sondar suporte a ferramentas e imagens com chamadas de modelo ao vivo. Se nenhuma chave do OpenRouter estiver configurada, o comando recorre à saída somente de metadados e explica que modelos :free ainda exigem OPENROUTER_API_KEY para sondagens e inferência.

Opções:

• --no-probe (somente metadados; sem consulta de configuração/segredos)
• --min-params <b>
• --max-age-days <days>
• --provider <name>
• --max-candidates <n>
• --timeout <ms> (tempo limite da solicitação de catálogo e por sondagem)
• --concurrency <n>
• --yes
• --no-input
• --set-default
• --set-image
• --json

--set-default e --set-image exigem sondagens ao vivo; resultados de varredura somente de metadados são informativos e não são aplicados à configuração.

Status dos modelos

Opções:

• --json
• --plain
• --check (sai com 1=expirado/ausente, 2=expirando)
• --probe (sondagem ao vivo de perfis de autenticação configurados)
• --probe-provider <name> (sonda um provedor)
• --probe-profile <id> (ids de perfil repetidos ou separados por vírgula)
• --probe-timeout <ms>
• --probe-concurrency <n>
• --probe-max-tokens <n>
• --agent <id> (id de agente configurado; substitui OPENCLAW_AGENT_DIR)

--json mantém stdout reservado para o payload JSON. Diagnósticos de perfil de autenticação, provedor e inicialização são direcionados para stderr para que scripts possam canalizar stdout diretamente para ferramentas como jq.

Categorias de status de sondagem:

• ok
• auth
• rate_limit
• billing
• timeout
• format
• unknown
• no_model

Casos esperados de detalhe/código de motivo da sondagem:

• excluded_by_auth_order: existe um perfil armazenado, mas uma auth.order.<provider> explícita o omitiu, então a sondagem relata a exclusão em vez de tentar usá-lo.
• missing_credential, invalid_expires, expired, unresolved_ref: o perfil está presente, mas não é elegível/resolvível.
• no_model: a autenticação do provedor existe, mas o OpenClaw não conseguiu resolver um candidato de modelo sondável para esse provedor.

Aliases + fallbacks

openclaw models aliases listopenclaw models fallbacks list

Perfis de autenticação

openclaw models auth addopenclaw models auth list [--provider <id>] [--json]openclaw models auth login --provider <id>openclaw models auth login --provider openai --profile-id openai:workopenclaw models auth paste-api-key --provider <id>openclaw models auth setup-token --provider <id>openclaw models auth paste-token

models auth add é o auxiliar interativo de autenticação. Ele pode iniciar um fluxo de autenticação do provedor (OAuth/chave de API) ou orientar você na colagem manual de token, dependendo do provedor escolhido.

models auth list lista os perfis de autenticação salvos para o agente selecionado sem imprimir token, chave de API ou material secreto OAuth. Use --provider <id> para filtrar para um provedor, como openai, e --json para scripts.

models auth login executa o fluxo de autenticação de um plugin de provedor (OAuth/chave de API). Use openclaw plugins list para ver quais provedores estão instalados. Use openclaw models auth --agent <id> <subcommand> para gravar resultados de autenticação em um armazenamento específico de agente configurado. A flag pai --agent é respeitada por add, list, login, paste-api-key, setup-token, paste-token e login-github-copilot.

Para modelos OpenAI, --provider openai usa por padrão login de conta ChatGPT/Codex. Use --method api-key apenas quando quiser adicionar um perfil de chave de API OpenAI, normalmente como backup para limites de assinatura do Codex. Execute openclaw doctor --fix para migrar estados antigos de autenticação/perfil com prefixo legado OpenAI Codex para openai.

Exemplos:

openclaw models auth login --provider openai --set-defaultopenclaw models auth login --provider openai --method api-keyopenclaw models auth paste-api-key --provider openaiopenclaw models auth list --provider openai

Observações:

• login aceita --profile-id <id> para provedores que oferecem suporte a perfis nomeados durante o login. Use isso para manter separados múltiplos logins para o mesmo provedor.
• paste-api-key aceita chaves de API geradas em outro lugar, solicita o valor da chave e o grava no id de perfil padrão <provider>:manual, a menos que você passe --profile-id. Em automação, canalize a chave em stdin, por exemplo printf "%s\n" "$OPENAI_API_KEY" | openclaw models auth paste-api-key --provider openai.
• setup-token e paste-token continuam sendo comandos genéricos de token para provedores que expõem métodos de autenticação por token.
• setup-token exige um TTY interativo e executa o método de autenticação por token do provedor (usando por padrão o método setup-token desse provedor quando ele expõe um).
• paste-token aceita uma string de token gerada em outro lugar ou por automação.
• paste-token exige --provider, solicita o valor do token por padrão e o grava no id de perfil padrão <provider>:manual, a menos que você passe --profile-id.
• Em automação, canalize o token em stdin em vez de passá-lo como argumento para que as credenciais do provedor não apareçam no histórico do shell nem em listas de processos.
• paste-token --expires-in <duration> armazena uma expiração absoluta do token a partir de uma duração relativa como 365d ou 12h.
• Para openai, chaves de API OpenAI e material de token ChatGPT/OAuth são formatos de autenticação diferentes. Use paste-api-key para chaves de API OpenAI sk-... e paste-token apenas para material de autenticação por token.
• Observação sobre Anthropic: a equipe da Anthropic nos informou que o uso estilo OpenClaw da Claude CLI é permitido novamente, então o OpenClaw trata o reuso da Claude CLI e o uso de claude -p como sancionados para esta integração, a menos que a Anthropic publique uma nova política.
• Anthropic setup-token / paste-token continuam disponíveis como um caminho de token compatível do OpenClaw, mas o OpenClaw agora prefere o reuso da Claude CLI e claude -p quando disponíveis.

Relacionado

• Referência da CLI
• Seleção de modelos
• Failover de modelos