Pular para o conteúdo principal

​
Autenticação (Provedores de modelo)

Esta página cobre a autenticação de provedor de modelo (chaves de API, OAuth, reutilização do Claude CLI). Para autenticação de conexão com o gateway (token, senha, trusted-proxy), consulte Configuration e Trusted Proxy Auth.
O OpenClaw oferece suporte a OAuth e chaves de API para provedores de modelo. Para hosts de gateway sempre ativos, chaves de API geralmente são a opção mais previsível. Fluxos de assinatura/OAuth também são compatíveis quando correspondem ao modelo de conta do seu provedor. Consulte /concepts/oauth para o fluxo completo de OAuth e o layout de armazenamento. Para autenticação baseada em SecretRef (provedores env/file/exec), consulte Gerenciamento de segredos. Para regras de elegibilidade de credenciais/códigos de motivo usadas por models status --probe, consulte Semântica de Credenciais de Autenticação.

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

Se você estiver executando um gateway de longa duração, comece com uma chave de API para o provedor escolhido. Para Anthropic especificamente, a autenticação por chave de API é o caminho seguro. A reutilização do Claude CLI é o outro caminho compatível de configuração no estilo assinatura.
  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).
export <PROVIDER>_API_KEY="..."
openclaw models status
  1. Se o Gateway for executado sob systemd/launchd, prefira colocar a chave em ~/.openclaw/.env para que o daemon possa lê-la:
cat >> ~/.openclaw/.env <<'EOF'
<PROVIDER>_API_KEY=...
EOF
Em seguida, reinicie o daemon (ou reinicie o processo do seu Gateway) e verifique novamente: 
openclaw models status
openclaw doctor
Se preferir não gerenciar variáveis de ambiente por conta própria, o onboarding pode armazenar chaves de API para uso pelo daemon: openclaw onboard. Consulte Help para detalhes sobre herança de env (env.shellEnv, ~/.openclaw/.env, systemd/launchd).

​
Anthropic: compatibilidade legada de token

A autenticação Anthropic setup-token continua disponível no OpenClaw como um caminho legado/manual. A documentação pública do Claude Code da Anthropic ainda cobre o uso direto do terminal do Claude Code nos planos Claude, mas a Anthropic informou separadamente aos usuários do OpenClaw que o caminho de login Claude do OpenClaw conta como uso de harness de terceiros e exige Extra Usage cobrado separadamente da assinatura. Para o caminho de configuração mais claro, use uma chave de API da Anthropic ou migre para Claude CLI no host do gateway. Entrada manual de token (qualquer provedor; grava auth-profiles.json + atualiza a configuração): 
openclaw models auth paste-token --provider openrouter
Refs de perfil de autenticação também são compatíveis para credenciais estáticas:
  • credenciais api_key podem usar keyRef: { source, provider, id }
  • credenciais token podem usar tokenRef: { source, provider, id }
  • perfis em modo OAuth não oferecem suporte a credenciais SecretRef; se auth.profiles.<id>.mode estiver definido como "oauth", a entrada keyRef/tokenRef com suporte de SecretRef para esse perfil será rejeitada.
Verificação amigável para automação (saída 1 quando expirado/ausente, 2 quando expirando): 
openclaw models status --check
Probes ativos de autenticação: 
openclaw models status --probe
Observações:
  • Linhas de probe podem vir de perfis de autenticação, credenciais de env ou models.json.
  • Se auth.order.<provider> explícito omitir um perfil armazenado, o probe relatará excluded_by_auth_order para esse perfil em vez de tentá-lo.
  • Se a autenticação existir, mas o OpenClaw não conseguir resolver um candidato de modelo sondável para esse provedor, o probe relatará status: no_model.
  • Cooldowns de limite de taxa podem ter escopo por modelo. Um perfil em cooldown para um modelo ainda pode ser utilizável para um modelo irmão no mesmo provedor.
Scripts operacionais opcionais (systemd/Termux) estão documentados aqui: Scripts de monitoramento de autenticação

​
Anthropic: migração para Claude CLI

Se o Claude CLI já estiver instalado e autenticado no host do gateway, você pode mudar uma configuração Anthropic existente para o backend de CLI. Este é um caminho de migração compatível do OpenClaw para reutilizar um login local do Claude CLI nesse host. Pré-requisitos:
  • claude instalado no host do gateway
  • Claude CLI já autenticado nele com claude auth login
openclaw models auth login --provider anthropic --method cli --set-default
Isso mantém seus perfis de autenticação Anthropic existentes para rollback, mas altera a seleção de modelo padrão para claude-cli/... e adiciona entradas correspondentes de lista de permissões do Claude CLI em agents.defaults.models. Verifique: 
openclaw models status
Atalho de onboarding: 
openclaw onboard --auth-choice anthropic-cli
openclaw onboard e openclaw configure interativos ainda preferem Claude CLI para Anthropic, mas Anthropic setup-token está disponível novamente como um caminho legado/manual e deve ser usado com a expectativa de cobrança de Extra Usage.

​
Verificando o status de autenticação de modelos

openclaw models status
openclaw doctor

​
Comportamento de rotação de chave de API (gateway)

Alguns provedores oferecem suporte a tentar novamente uma solicitação com chaves alternativas quando uma chamada de API atinge um limite de taxa do provedor.
  • Ordem de prioridade:
    • OPENCLAW_LIVE_<PROVIDER>_KEY (substituição única)
    • <PROVIDER>_API_KEYS
    • <PROVIDER>_API_KEY
    • <PROVIDER>_API_KEY_*
  • Provedores Google também incluem GOOGLE_API_KEY como fallback adicional.
  • A mesma lista de chaves é deduplicada antes do uso.
  • O OpenClaw tenta novamente com a próxima chave apenas para erros de limite de taxa (por exemplo 429, rate_limit, quota, resource exhausted, Too many concurrent requests, ThrottlingException, concurrency limit reached ou workers_ai ... quota limit exceeded).
  • Erros que não são de limite de taxa não são tentados novamente com chaves alternativas.
  • Se todas as chaves falharem, o erro final da última tentativa será retornado.

​
Controlando qual credencial é usada

​
Por sessão (comando de chat)

Use /model <alias-or-id>@<profileId> para fixar uma credencial específica de provedor para a sessão atual (exemplos de ids de perfil: anthropic:default, anthropic:work). Use /model (ou /model list) para um seletor compacto; use /model status para a visão completa (candidatos + próximo perfil de autenticação, além de detalhes do endpoint do provedor quando configurados).

​
Por agente (substituição de CLI)

Defina uma substituição explícita da ordem do perfil de autenticação para um agente (armazenada em auth-profiles.json desse agente): 
openclaw models auth order get --provider anthropic
openclaw models auth order set --provider anthropic anthropic:default
openclaw models auth order clear --provider anthropic
Use --agent <id> para direcionar a um agente específico; omita para usar o agente padrão configurado. Ao depurar problemas de ordem, openclaw models status --probe mostra perfis armazenados omitidos como excluded_by_auth_order em vez de ignorá-los silenciosamente. Ao depurar problemas de cooldown, lembre-se de que cooldowns de limite de taxa podem estar vinculados a um id de modelo específico, e não ao perfil inteiro do provedor.

​
Solução de problemas

​
”No credentials found”

Se o perfil Anthropic estiver ausente, migre essa configuração para Claude CLI ou uma chave de API no host do gateway e, em seguida, verifique novamente: 
openclaw models status

​
Token expirando/expirado

Execute openclaw models status para confirmar qual perfil está expirando. Se um perfil de token Anthropic legado estiver ausente ou expirado, migre essa configuração para Claude CLI ou uma chave de API.

​
Requisitos do Claude CLI

Necessário apenas para o caminho de reutilização do Anthropic Claude CLI:
  • Claude Code CLI instalado (comando claude disponível)