Autenticação de modelos no OpenClaw

A documentação abre esta página com uma nota de escopo que vale repetir: ela cobre a autenticação com provedores de modelos, chaves de API, OAuth, reutilização da CLI do Claude e o setup token da Anthropic, e não o token ou a senha que protege a conexão com o Gateway. O OpenClaw suporta OAuth e chaves de API para os provedores, e a recomendação é direta: para um host de Gateway sempre ligado, uma chave de API é a opção mais previsível, enquanto os fluxos de assinatura e OAuth funcionam quando combinam com a sua conta no provedor. A seguir: a configuração recomendada, os caminhos da Anthropic, onde ficam as credenciais, como verificá-las, a rotação e como escolher qual credencial uma sessão usa.

A configuração recomendada

• Crie uma chave no console do provedor, exporte-a no host do Gateway, a máquina que roda o Gateway, e verifique com o comando models status.
• Se o Gateway roda sob systemd ou launchd, coloque a chave no arquivo env do diretório de estado para que o daemon consiga lê-la, reinicie e verifique de novo com models status e o doctor; o onboarding pode armazenar as chaves para uso do daemon se você preferir não gerenciar variáveis.
• A reutilização da CLI do Claude é um caminho aprovado pela Anthropic e o preferido para uso local ou em desktop quando existe um login do Claude no host: faça login no Claude Code e depois diga ao OpenClaw para rotear os modelos da Anthropic pelo backend local da CLI do Claude; o OpenClaw nunca lê, armazena, renova nem repassa os tokens de login nativos, o processo instalado renova o próprio login, e o serviço precisa resolver o executável no seu path.
• O setup token é o outro caminho da Anthropic: um token de longa duração exibido pelo Claude Code em qualquer máquina e armazenado no host pelo comando auth login no modo setup-token, que exige um terminal interativo.

Para um host de gateway sempre ligado, uma chave de API é a opção mais previsível; fluxos de assinatura/OAuth também funcionam quando combinam com o modelo de conta do seu provedor.

Onde ficam as credenciais

A inserção manual de token funciona para qualquer provedor e grava no armazenamento de autenticação SQLite por agente, que é de onde o OpenClaw lê os perfis de autenticação; detalhes de endpoint, como URLs base, tipos de API, IDs de modelo, cabeçalhos e tempos limite, pertencem à configuração do provedor, não aos perfis. Instalações mais antigas com arquivos de autenticação JSON são importadas pelo doctor com backups com carimbo de data e hora, rotas externas, como um modo SDK do Bedrock, são metadados de configuração, e não credenciais, e as credenciais podem ser referências a segredos para chaves e tokens, exceto nos perfis em modo OAuth, que as rejeitam. Remover uma autenticação salva não revoga a chave no provedor, e remover a autenticação de um provedor pelo plano de controle enquanto o Gateway roda interrompe as execuções ativas nesse provedor com um motivo de parada de autenticação revogada, para que os clientes possam mostrar por que a execução parou.

Verificar, rotacionar, escolher

• O comando models status e o doctor são as verificações; a flag check sai com um quando uma credencial está expirada ou ausente e com dois quando está para expirar, para automação, e a flag probe executa sondagens de autenticação ao vivo com flags de escopo, relatando perfis excluídos pela ordem de autenticação, provedores com autenticação mas sem modelo sondável e cooldowns de limite de taxa restritos a um modelo, que deixam os modelos irmãos utilizáveis.
• Alguns provedores repetem uma requisição limitada por taxa com outra chave configurada, em uma prioridade fixa: uma única chave de substituição ao vivo, uma lista delimitada de chaves, a variável de chave simples e depois qualquer variante com prefixo, com os provedores do Google também recorrendo à chave genérica do Google; a rotação só é acionada por erros de limite de taxa, de cota e de requisições em excesso, e frases de throttling específicas de cada provedor acionam, em vez disso, a classificação separada de failover.
• Os perfis de chave de API da OpenAI e os perfis OAuth do ChatGPT ou do Codex usam o mesmo ID canônico da OpenAI, e o doctor reescreve IDs de perfil legados do Codex e entradas de ordem de autenticação. Vários logins para um mesmo provedor ficam separados por IDs de perfil, a flag force exclui um perfil travado ou da conta errada e executa o fluxo de novo, uma sessão fixa uma credencial específica com o comando model e um sufixo de perfil, e os comandos de ordem de autenticação por agente consultam, definem e limpam a seleção automática.

OpenClaw com Claude e OpenClaw com uma assinatura do ChatGPT são as duas rotas por assinatura que esta página mantém separadas de uma chave de API.

Quando falha

“No credentials found” significa que a chave não está no host do Gateway ou que o caminho do setup token nunca foi executado, e models status confirma a correção; um token prestes a expirar ou expirado aparece no mesmo status e pode ser renovado pelo setup token ou substituído por uma chave de API. Os comandos de nova sessão e de reset limpam o estado automático de fallback e de rotação, mas preservam as fixações explícitas de perfil válidas, e mudar a ordem de autenticação só muda a seleção automática. Failover de modelos no OpenClaw é o mecanismo que troca de modelo ou de provedor diante de falhas repetidas, distinto da rotação de chaves, e segredos no OpenClaw, a sintaxe de referência que as referências a chaves e tokens usam.

Na Diali

Na Diali, uma chave que você traz vai para o Vault, e a configuração que geramos faz referência a ela; sem chave, o assistente roda com os créditos de IA gerenciados, e o painel mostra qual dos dois está em uso. Um plano ChatGPT, SuperGrok ou MiniMax que você já paga também pode movê-lo: o painel mostra um código de uso único, você o aprova na própria página do provedor e o assistente guarda o login, então a Diali nunca tem o token. O setup token da Anthropic e o login pelo Claude CLI estão desativados na Diali, porque os termos da Anthropic não permitem que um serviço hospedado rode com uma assinatura Claude; no lugar, funcionam uma chave de API da Anthropic ou os créditos gerenciados. OpenClaw hospedado na Diali é o assistente, e modelos e provedores do OpenClaw cobre os provedores por trás das chaves.

• Uma chave de API no host para um Gateway sempre ligado.
• Perfis de autenticação no SQLite, endpoints na configuração.
• Rotação em limites de taxa; failover para todo o resto.