Skip to main content
Esta página aborda a autenticação de provedores de modelos (chaves de API, OAuth, reutilização da CLI do Claude, token de configuração da Anthropic). Para autenticação da conexão com o Gateway (token, senha, proxy confiável), consulte Configuração e Autenticação por proxy confiável.
O OpenClaw oferece suporte a OAuth e chaves de API para provedores de modelos. Para um host de Gateway sempre ativo, uma chave de API é a opção mais previsível; fluxos de assinatura/OAuth também funcionam quando são compatíveis com o modelo de conta do seu provedor.

​
Configuração recomendada: chave de API (qualquer provedor)

  1. Crie uma chave de API no console do seu provedor.
  2. Coloque-a no host do Gateway (a máquina que executa openclaw gateway):
  1. Se o Gateway for executado pelo systemd/launchd, coloque a chave em ~/.openclaw/.env para que o daemon possa lê-la:
  1. Reinicie o processo do Gateway (ou o daemon) e verifique novamente:
openclaw onboard também pode armazenar chaves de API para uso pelo daemon caso você não queira gerenciar variáveis de ambiente por conta própria. Consulte Variáveis de ambiente para ver a precedência completa de carregamento do ambiente (env.shellEnv, ~/.openclaw/.env, systemd/launchd).

​
Anthropic: reutilização da CLI do Claude

A autenticação por token de configuração da Anthropic continua sendo um caminho compatível. A reutilização da CLI do Claude (uso no estilo claude -p) também é autorizada para esta integração; quando um login da CLI do Claude está disponível no host, esse é o caminho preferencial para uso local/em desktop. Para hosts de Gateway de longa duração, uma chave de API da Anthropic ainda é a opção mais previsível, com controle explícito de cobrança no lado do servidor. Configuração do host para reutilizar a CLI do Claude:
Este processo tem duas etapas: autenticar o Claude Code na Anthropic no host e, em seguida, instruir o OpenClaw a encaminhar a seleção de modelos da Anthropic pelo backend local claude-cli e armazenar o perfil de autenticação correspondente do OpenClaw. Se claude não estiver no PATH, instale o Claude Code ou defina agents.defaults.cliBackends.claude-cli.command como o caminho do binário.

​
Inserção manual de token

Funciona com qualquer provedor; grava no armazenamento SQLite de autenticação por agente e atualiza a configuração:
O OpenClaw lê os perfis de autenticação do openclaw-agent.sqlite de cada agente. Os detalhes do endpoint (baseUrl, api, IDs de modelos, cabeçalhos, tempos limite) pertencem a models.providers.<id> em openclaw.json ou models.json, não aos perfis de autenticação. Se uma instalação mais antiga ainda tiver auth-profiles.json, auth-state.json ou uma estrutura simples como { "openrouter": { "apiKey": "..." } }, execute openclaw doctor --fix para importá-la para o SQLite; o doctor mantém backups com data e hora ao lado dos arquivos JSON originais. Rotas de autenticação externas, como auth: "aws-sdk" do Bedrock, não são credenciais. Para uma rota nomeada do Bedrock, defina auth.profiles.<id>.mode: "aws-sdk" em openclaw.json — não grave type: "aws-sdk" no armazenamento de perfis de autenticação. openclaw doctor --fix migra marcadores legados do AWS SDK do armazenamento de credenciais para os metadados de configuração.

​
Credenciais baseadas em SecretRef

  • Credenciais api_key podem usar keyRef: { source, provider, id }
  • Credenciais token podem usar tokenRef: { source, provider, id }
  • Perfis no modo OAuth rejeitam credenciais SecretRef: se auth.profiles.<id>.mode for "oauth", um keyRef/tokenRef baseado em SecretRef para esse perfil será rejeitado.

​
Verificação do status de autenticação dos modelos

Verificação adequada para automação, com saída 1 quando a credencial estiver expirada/ausente e 2 quando estiver prestes a expirar:
Sondagens de autenticação em tempo real (adicione --probe-provider, --probe-profile, --probe-timeout, --probe-concurrency ou --probe-max-tokens para restringir o escopo):
Observações:
  • As linhas da sondagem podem vir de perfis de autenticação, credenciais do ambiente ou de models.json.
  • Se auth.order.<provider> omitir um perfil armazenado, a sondagem relatará excluded_by_auth_order para esse perfil em vez de testá-lo.
  • Se houver autenticação, mas o OpenClaw não conseguir resolver um modelo que possa ser sondado para esse provedor, a sondagem relatará status: no_model.
  • Os períodos de espera por limite de taxa podem ser específicos do modelo: um perfil em período de espera para um modelo ainda pode atender a um modelo relacionado no mesmo provedor.
Scripts operacionais opcionais (systemd/Termux): Scripts de monitoramento de autenticação.

​
Rotação de chaves de API (Gateway)

Alguns provedores repetem uma solicitação com uma chave alternativa configurada quando uma chamada atinge um limite de taxa do provedor. Ordem de prioridade das chaves por provedor:
  1. OPENCLAW_LIVE_<PROVIDER>_KEY (substituição única, fixa uma chave)
  2. <PROVIDER>_API_KEYS (lista separada por vírgulas, espaços ou pontos e vírgulas)
  3. <PROVIDER>_API_KEY
  4. <PROVIDER>_API_KEY_* (qualquer variável de ambiente com esse prefixo)
Os provedores do Google (google, google-vertex) também recorrem a GOOGLE_API_KEY. As duplicatas são removidas da lista combinada antes do uso. O OpenClaw só passa para a próxima chave quando a mensagem de erro corresponde a: rate_limit, rate limit, 429, quota exceeded/quota_exceeded, resource exhausted/resource_exhausted ou too many requests. Outros erros não são repetidos com chaves alternativas. Se todas as chaves falharem, o erro final da última tentativa será retornado.
Expressões específicas de provedores, como ThrottlingException, concurrency limit reached ou workers_ai ... quota limit exceeded, determinam a classificação de failover/nova tentativa (alternância de modelos ou provedores em caso de falhas repetidas), um mecanismo separado da rotação de chaves de API descrita acima.
Remover a autenticação salva não revoga a chave no provedor — faça a rotação ou a revogação no painel do provedor quando precisar invalidá-la no lado do provedor.

​
Remoção da autenticação do provedor enquanto o Gateway está em execução

Quando você remove a autenticação de um provedor pelo plano de controle do Gateway, o OpenClaw exclui os perfis de autenticação salvos desse provedor e interrompe as execuções ativas de chats/agentes cujo provedor do modelo selecionado corresponda ao removido. As execuções interrompidas emitem os eventos normais de cancelamento/ciclo de vida com stopReason: "auth-revoked", permitindo que os clientes conectados indiquem que a execução foi interrompida porque as credenciais foram removidas.

​
Controle da credencial utilizada

​
OpenAI e IDs legados openai-codex

Os perfis de chave de API da OpenAI e os perfis OAuth do ChatGPT/Codex usam o ID de provedor canônico openai. Use IDs de perfil openai:* e auth.order.openai em novas configurações. Se você encontrar openai-codex em configurações antigas, IDs de perfis de autenticação ou auth.order.openai-codex, trate-o como entrada de migração legada — não crie novos perfis openai-codex. Execute:
O doctor reescreve os IDs de perfil legados openai-codex:* e as entradas auth.order.openai-codex para a rota canônica openai. Para informações sobre o roteamento de modelos/tempo de execução específico da OpenAI, consulte OpenAI.

​
Durante o login (CLI)

--profile-id mantém separados vários logins OAuth do mesmo provedor em um único agente. --force exclui os perfis de autenticação salvos desse provedor no diretório do agente selecionado e, em seguida, executa novamente o mesmo fluxo de autenticação. Use essa opção quando um perfil salvo estiver travado, expirado ou associado à conta errada. Ela não revoga as credenciais no provedor.

​
Por sessão (comando de chat)

  • /model <alias-or-id>@<profileId> fixa uma credencial específica do provedor para a sessão atual (exemplos de IDs de perfil: anthropic:default, anthropic:work).
  • /model (ou /model list) exibe um seletor compacto; /model status exibe a visão completa (candidatos + próximo perfil de autenticação, além dos detalhes do endpoint do provedor quando configurados).
Se você alterar a ordem de autenticação ou a fixação de perfil em um chat que já está em execução, envie /new ou /reset para iniciar uma nova sessão — as sessões existentes mantêm a seleção atual de modelo/perfil até serem redefinidas.

​
Por agente (substituição pela CLI)

As substituições da ordem de autenticação são armazenadas no estado de autenticação SQLite desse agente:
Use --agent <id> para selecionar um agente específico; omita-o para usar o agente padrão configurado. openclaw models status --probe exibe perfis armazenados omitidos como excluded_by_auth_order, em vez de ignorá-los silenciosamente.

​
Solução de problemas

​
”Nenhuma credencial encontrada”

Configure uma chave de API da Anthropic no host do Gateway ou configure o caminho do token de configuração da Anthropic e verifique novamente:

​
Token prestes a expirar/expirado

Execute openclaw models status para identificar qual perfil está prestes a expirar. Se um perfil de token da Anthropic estiver ausente ou expirado, atualize-o por meio do token de configuração ou migre para uma chave de API da Anthropic.

​
Relacionados