Como configurar OpenAI e Claude no OpenClaw (API key e OAuth)

Você instalou o OpenClaw. Rodou openclaw onboard. E travou na tela de provedor.

São quatro caminhos possíveis, dois provedores, dois modelos de cobrança. Este guia cobre cada um com comandos reais e as diferenças que importam na prática.

TL;DR

Provedor	Método	Comando	Quando usar
OpenAI	API key (chave de acesso direto)	`openclaw onboard --openai-api-key`	Uso esporádico, paga por tokens (as unidades de texto que o modelo processa — cada palavra gasta alguns)
OpenAI	OAuth (um método de login seguro, como quando você entra num site usando sua conta Google)	`openclaw models auth login --provider openai-codex`	Já tem ChatGPT Plus/Codex
Claude	API key	`openclaw onboard --anthropic-api-key`	Uso intenso, contexto longo
Claude	setup-token	`claude setup-token` → `openclaw models auth setup-token --provider anthropic`	Já tem assinatura Claude

API key vs assinatura: a diferença real

API (a ponte que conecta o OpenClaw ao modelo de IA) key é pagar por litro no posto. Você usa quando precisa, a conta chega no final do mês proporcional ao uso.

Assinatura com OAuth (um método de login seguro, como quando você entra num site usando sua conta Google) é mensalidade. Você já paga fixo todo mês (ChatGPT Plus, Claude Pro). O OpenClaw reutiliza essa sessão via OAuth — nenhum custo adicional por tokens usados.

API KEY                          OAUTH (assinatura)
-----------                      ------------------
Você → API key → Provedor        Você → Login OAuth → Provedor
       ↓                                 ↓
  Cobrança por token              Cobrança mensal fixa
  Sem limite de contexto*         Limites da assinatura
  Precisa de billing ativo        Precisa de conta no provedor

A escolha não é técnica — é financeira. Se você já paga uma assinatura, OAuth evita cobrança dupla. Se não tem assinatura, API key é mais direto.

OpenAI

Caminho 1: API key (pay-as-you-go)

Acesse platform.openai.com → API keys → Create new secret key. Copie o valor (ele só aparece uma vez).

openclaw onboard --openai-api-key

O terminal vai pedir a key. Cole e confirme. Para usar esse provedor nas conversas:

Modelo: openai/gpt-5.4-mini

Requisito: conta com billing ativo (saldo ou cartão cadastrado) no OpenAI. Sem crédito, a key existe mas as chamadas retornam erro 429 (limite atingido).

Caminho 2: assinatura ChatGPT/Codex (OAuth)

Se você tem ChatGPT Plus ou acesso ao Codex cloud, o login usa OAuth (método de login seguro via conta existente) — abre o browser, você autoriza, o token fica salvo localmente.

openclaw models auth login --provider openai-codex

O terminal abre o browser em auth.openai.com. Faça login com a conta da assinatura. Após autorizar, o terminal confirma ✓ autenticado.

Modelo: openai/gpt-5.4-nano

O prefixo do modelo é o mesmo do caminho 1: openai/. Desde o OpenClaw 2.0 (2026.8.1), refs antigas codex/... e openai-codex/... deixaram de ser o formato atual — se sua config ainda tem alguma, rode openclaw doctor --fix para migrá-las para openai/....

Transporte e compactação

O OpenClaw negocia o tipo de conexão automaticamente com o servidor OpenAI:

SSE (Server-Sent Events): padrão para a maioria das integrações — o servidor manda dados para o app em tempo real
WebSocket: para streaming (a resposta aparece em tempo real, palavra por palavra) de alta frequência
auto: OpenClaw escolhe com base na latência (velocidade de resposta) medida

Compactação automática acontece quando a conversa atinge 70% do limite de tamanho. Mensagens antigas são resumidas antes de serem enviadas ao modelo, reduzindo tokens consumidos sem perder o fio da conversa.

Claude/Anthropic

Caminho 1: API key

Acesse console.anthropic.com → API keys → Create Key. O console mostra a key completa uma vez.

openclaw onboard --anthropic-api-key

Modelo: anthropic/claude-opus-5

Com API key, você tem acesso a conversas muito longas com o Claude Opus 5 — até 1 milhão de tokens (cada token equivale a cerca de 3/4 de uma palavra). Com OAuth via setup-token, o limite é menor — determinado pela assinatura.

Caminho 2: setup-token (assinatura Claude)

Se você tem Claude Pro ou Claude Max, gere um setup-token no cliente oficial:

# Passo 1: gerar o token no Claude
claude setup-token

# Saída esperada:
# Setup token: sk-ant-st03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Válido por: 15 minutos

# Passo 2: registrar no OpenClaw
openclaw models auth setup-token --provider anthropic

O terminal pede o token gerado no passo 1. Cole e confirme.

Tokens expiram. Se o OpenClaw retornar token_expired em algum momento, repita os dois passos. Não tem como renovar — você gera um novo.

Cache de prompt e thinking

// openclaw.json — arquivo de configuração do OpenClaw para o provedor Anthropic
{
  providers: {
    anthropic: {
      cacheRetention: "long",  // quanto tempo guardar o cache (cópia temporária) do contexto: "none" | "short" | "long"
      thinking: true            // ativa raciocínio passo a passo (padrão: true no Claude 4.6+)
    }
  }
}

cacheRetention controla quanto tempo o Anthropic mantém o cache (cópia temporária para não ter que buscar de novo) do seu system prompt em memória. "long" reduz a demora em sessões longas. "none" desativa o cache e cobra tokens cheios em cada chamada.

Thinking adaptativo está ativo por padrão desde o Claude 4.6. Para tarefas simples ele usa menos passos de raciocínio. Para tarefas complexas, expande automaticamente. Você pode desativar com thinking: false se quiser respostas mais rápidas.

O limite de 1 milhão de tokens funciona com API key. Com setup-token de assinatura, o limite efetivo é o da sua assinatura Claude — contexto reduzido na assinatura (confira os docs).

Qual escolher?

Critério	OpenAI API	OpenAI OAuth	Claude API	Claude OAuth
Custo	Por token	Plano fixo	Por token	Plano fixo
Limite de contexto	Limite do modelo (GPT-5.6)	Limite do plano	1M (Opus 5)	Limite do plano
Setup	2 min	5 min (browser)	2 min	5 min (2 passos)
Token expira?	Não	Não	Não	Sim (setup-token)
Melhor para	Uso esporádico	Já tem Plus	Docs longas, código	Já tem Claude Pro

Não existe opção objetivamente melhor. Se você já paga Claude Pro e vai usar o OpenClaw no dia a dia, OAuth do Claude economiza dinheiro. Se vai usar eventualmente e quer o contexto de 1M, API key do Claude faz mais sentido.

Modelo padrão no settings

Depois de configurar o provedor, defina o modelo padrão para não precisar especificar toda conversa:

// ~/.openclaw/openclaw.json — arquivo de configuração global do OpenClaw
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-5", // modelo padrão para todas as conversas
        // ou: "openai/gpt-5.6-sol"
      },
    },
  },
}

O modelo padrão é usado quando você abre uma conversa sem especificar. Você ainda pode trocar por sessão (a conversa ativa entre você e o agente) digitando /model openai/gpt-5.4-mini direto no chat.

Troubleshooting

invalid_api_key

A key está errada ou inativa. Verifique se copiou ela completa (chaves da OpenAI começam com sk-, as da Anthropic com sk-ant-). Confirme que o billing (saldo ou cartão) está ativo no painel do provedor.

token_expired no Claude OAuth

O setup-token tem validade curta (15 minutos). Gere um novo:

# Passo 1: gera um novo token no Claude
claude setup-token
# Passo 2: registra no OpenClaw
openclaw models auth setup-token --provider anthropic

billing_not_active

Conta existe mas sem crédito ou cartão configurado. Acesse o painel do provedor, adicione crédito, aguarde 1-2 minutos e tente novamente.

model_not_found

O nome do modelo está incorreto. Os formatos são exatos — qualquer variação causa erro:

openai/gpt-5.4-mini (não openai/gpt5.4-mini nem gpt-5.4-mini)
openai/gpt-5.4-nano (modelo diferente, não misture com o anterior)
anthropic/claude-opus-5 (não claude-opus-5 sem o prefixo)

Diagnóstico geral

openclaw models status

Mostra o estado de cada provedor configurado: autenticado, expirado, sem billing, inacessível. É o primeiro lugar para olhar quando algo não funciona.