---
title: "Gerenciando API Keys — Segurança e Boas Práticas"
url: "https://openclaw.ia.br/guias/api-keys/"
markdown_url: "https://openclaw.ia.br/guias/api-keys.MD"
description: "Como gerenciar API keys no OpenClaw. Obter, configurar e proteger suas chaves de API."
date: ""
author: ""
---

# Gerenciando API Keys — Segurança e Boas Práticas

Como gerenciar API keys no OpenClaw. Obter, configurar e proteger suas chaves de API.


# Gerenciando API Keys no OpenClaw

## Introdução

As API keys são a "senha de acesso" que permite ao OpenClaw se comunicar com modelos de IA como Claude (Anthropic) e GPT-4 (OpenAI). Sem elas, o assistente não consegue processar suas mensagens nem executar tarefas inteligentes. É por isso que gerenciar bem essas chaves é fundamental: uma key vazada pode resultar em cobranças inesperadas na sua conta, uso indevido dos seus créditos e até exposição de dados sensíveis.

Este guia cobre tudo que você precisa saber sobre API keys no contexto do OpenClaw: como obtê-las, configurá-las de forma segura, monitorar o consumo e o que fazer caso uma chave seja comprometida. Se você acabou de instalar o OpenClaw, este é um dos primeiros guias que deve ler — uma configuração incorreta de keys pode causar problemas difíceis de diagnosticar depois.

Diferente de senhas comuns, as API keys têm características especiais: elas não expiram automaticamente (a menos que você as revogue), podem ser usadas por qualquer pessoa que as tenha, e cada requisição feita com a sua key é cobrada na sua conta. Por isso, tratá-las com o mesmo cuidado que você teria com cartões de crédito é a abordagem certa.

## Pré-requisitos

Antes de seguir este guia, você precisará de:

- OpenClaw instalado e funcionando (veja [guia de instalação](/instalacao/))
- Uma conta na Anthropic (console.anthropic.com) ou OpenAI (platform.openai.com)
- Método de pagamento cadastrado na plataforma escolhida (necessário para ativar a API)
- Acesso ao terminal do servidor onde o OpenClaw está instalado

## Obtendo Suas API Keys

### Anthropic (Claude) — Recomendado

O Claude é o modelo padrão e recomendado para uso com o OpenClaw, pela qualidade de raciocínio e pelas políticas de privacidade mais rígidas da Anthropic.

**Passo a passo:**

1. Acesse [console.anthropic.com](https://console.anthropic.com) e crie sua conta ou faça login
2. No menu lateral, clique em **API Keys**
3. Clique em **Create Key**
4. Dê um nome descritivo para a key (ex: "openclaw-producao", "openclaw-dev")
5. Copie a key imediatamente — ela só é exibida uma vez
6. Guarde em local seguro antes de fechar a página

```
Exemplo de formato de key Anthropic:
sk-ant-api03-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
```

**Dica importante:** Nomeie suas keys de forma descritiva. Se você tiver múltiplas instalações (casa, trabalho, servidor), crie uma key diferente para cada uma. Assim, se precisar revogar uma, as outras continuam funcionando.

### OpenAI (GPT-4)

Se você prefere usar modelos da OpenAI como alternativa ou complemento:

1. Acesse [platform.openai.com](https://platform.openai.com)
2. No menu lateral, clique em **API keys**
3. Clique em **Create new secret key**
4. Dê um nome e clique em **Create secret key**
5. Copie a key — ela também só é exibida uma vez

```
Exemplo de formato de key OpenAI:
sk-proj-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
```

**Atenção:** A OpenAI tem duas plataformas distintas — a API (platform.openai.com) e o ChatGPT web. As keys são diferentes e os planos de pricing também. Para o OpenClaw, você precisa da API, não da assinatura ChatGPT Plus.

## Configurando as Keys no OpenClaw

### Via CLI (Método Recomendado)

A forma mais fácil e segura de configurar suas keys é através da CLI do OpenClaw:

```bash
# Configurar key da Anthropic
openclaw auth add anthropic
# O sistema vai pedir para colar a key — ela não aparece na tela (seguro)

# Configurar key da OpenAI (opcional)
openclaw auth add openai
# Cole a key quando solicitado
```

O OpenClaw armazena as keys de forma segura no arquivo de configuração local, sem exibi-las em logs ou outputs.

### Via Variável de Ambiente

Para máxima segurança, especialmente em servidores, use variáveis de ambiente:

```bash
# Adicionar ao ~/.bashrc ou ~/.zshrc
export ANTHROPIC_API_KEY="sk-ant-api03-sua-key-aqui"
export OPENAI_API_KEY="sk-proj-sua-key-aqui"

# Aplicar as mudanças
source ~/.bashrc
```

```bash
# Verificar se foi configurado corretamente
echo $ANTHROPIC_API_KEY | head -c 20
# Deve mostrar o início da sua key
```

### Via Arquivo de Configuração

Você também pode configurar diretamente no `config.yaml`, mas **nunca coloque a key diretamente** — use referência à variável de ambiente:

```yaml
# ~/.openclaw/config.yaml — CORRETO
anthropic:
  apiKey: ${ANTHROPIC_API_KEY}

# NUNCA faça isso:
# anthropic:
#   apiKey: "sk-ant-api03-sua-key"  # ERRADO! Hardcoded!
```

### Verificando se a Configuração Está Correta

```bash
# Verificar status das keys configuradas
openclaw auth status

# Saída esperada:
# Anthropic: ✓ Configurado (sk-ant-...xxxx)
# OpenAI: ✓ Configurado (sk-proj-...xxxx)

# Testar conectividade
openclaw doctor
```

## Configuração Avançada

### Múltiplos Perfis de Key

Para situações onde você tem créditos separados (ex: pessoal vs. trabalho), configure perfis:

```yaml
# config.yaml
anthropic:
  profiles:
    pessoal:
      apiKey: ${ANTHROPIC_KEY_PESSOAL}
    trabalho:
      apiKey: ${ANTHROPIC_KEY_TRABALHO}
  defaultProfile: pessoal
```

Troque de perfil quando necessário:

```bash
openclaw config set anthropic.defaultProfile trabalho
```

### Keys de Backup

Configure uma key de fallback para quando a principal atingir o limite de rate:

```yaml
anthropic:
  apiKey: ${ANTHROPIC_API_KEY}
  fallbackKey: ${ANTHROPIC_API_KEY_BACKUP}
  fallbackOnError: true
```

### Rotação Automática de Keys

Para ambientes de produção, configure lembrete de rotação:

```yaml
security:
  keyRotation:
    enabled: true
    reminderDays: 90  # Lembrete a cada 90 dias
    channel: telegram  # Onde enviar o lembrete
```

### Limites de Gasto

Configure limites para evitar surpresas na fatura:

```yaml
billing:
  monthlyLimitUSD: 50
  alertThresholdPercent: 80  # Alerta ao atingir 80% do limite
  alertChannel: whatsapp
```

Configure também diretamente no console da Anthropic ou OpenAI — os dois sistemas de limite funcionam de forma independente, aumentando a proteção.

## Erros Comuns e Soluções

| Erro | Causa Provável | Solução |
|------|----------------|---------|
| `Authentication error: Invalid API key` | Key incorreta ou expirada | Verifique se copiou a key completa, sem espaços extras |
| `Rate limit exceeded` | Muitas requisições por minuto | Aguarde 1 minuto ou configure modelo menor como fallback |
| `Insufficient quota` | Créditos esgotados | Adicione créditos no console da plataforma |
| `Key not found in environment` | Variável de ambiente não definida | Execute `source ~/.bashrc` ou reinicie o gateway |
| `Connection refused` | Problema de rede ou firewall | Teste com `curl https://api.anthropic.com` |
| `Permission denied on config.yaml` | Permissões de arquivo incorretas | Execute `chmod 600 ~/.openclaw/config.yaml` |

## Boas Práticas

- **Uma key por ambiente:** Crie keys separadas para desenvolvimento, testes e produção. Assim, se comprometer uma, não afeta as outras e você sabe exatamente qual uso gerou quais custos.

- **Nomenclatura descritiva:** Use nomes como "openclaw-casa-2026", "openclaw-empresa-servidor1". Quando você tiver várias keys no console, vai agradecer por poder identificar cada uma.

- **Nunca commite no Git:** Adicione `config.yaml`, `.env` e qualquer arquivo com secrets ao `.gitignore`. Use o comando `git secrets` ou ferramentas similares para prevenir acidentes.

- **Rotacione periodicamente:** Mesmo sem evidência de vazamento, troque suas keys a cada 3-6 meses. É uma boa prática de segurança que limita a janela de exposição em caso de comprometimento não detectado.

- **Monitore o uso regularmente:** Acesse o console da Anthropic ou OpenAI semanalmente para verificar se o consumo está dentro do esperado. Picos inesperados podem indicar vazamento da key.

- **Configure alertas de billing:** Tanto a Anthropic quanto a OpenAI permitem configurar alertas de email quando o gasto atinge um valor. Use essa funcionalidade — é gratuita e pode te salvar de surpresas.

- **Use password manager:** Guarde suas keys em um gerenciador de senhas como Bitwarden (gratuito) ou 1Password. Não use notas no celular ou documentos de texto sem criptografia.

- **Revogue keys não utilizadas:** Se você criou uma key para testar e não usa mais, revogue-a imediatamente. Keys paradas são um risco desnecessário.

## Perguntas Frequentes

**Minha key foi comprometida — o que fazer?**
Aja imediatamente: acesse o console da plataforma, revogue a key comprometida e crie uma nova. Verifique o histórico de uso para identificar consumo indevido. Entre em contato com o suporte da plataforma se houver cobranças não reconhecidas. Depois, configure a nova key no OpenClaw e revise onde a key antiga estava armazenada para identificar o vazamento.

**Posso usar a mesma key em múltiplas instalações do OpenClaw?**
Tecnicamente sim, mas não é recomendado. Se uma das instalações for comprometida, você terá que revogar a key e atualizar todas as outras. Além disso, fica mais difícil identificar qual instalação está gerando qual consumo. Crie uma key por instalação.

**Como saber se minha key está funcionando sem enviar mensagens?**
Use o comando `openclaw doctor` que faz uma verificação de conectividade sem consumir tokens. Alternativamente, `openclaw auth status` verifica a validade da key.

**O OpenClaw armazena minha key de forma segura?**
Sim, o OpenClaw armazena keys com permissões de arquivo restritivas (600) e nunca as exibe em logs ou outputs. No entanto, você é responsável por não colocar a key diretamente em arquivos que possam ser versionados no Git.

**Qual é a diferença entre key de produção e key de teste?**
A Anthropic e a OpenAI não fazem essa distinção na API — todas as keys são "reais" e geram cobranças. A distinção é sua: crie keys com nomes diferentes e use limites de gasto diferentes para cada ambiente.

## Próximos Passos

Com suas keys configuradas e seguras, explore os próximos passos:

- [Guia de Segurança Completo](/guias/seguranca/) — Boas práticas gerais de segurança
- [Gerenciando Custos](/guias/custos/) — Como monitorar e reduzir gastos com APIs
- [Escolhendo Modelos](/guias/modelos/) — Qual modelo usar para cada tipo de tarefa
- [Privacidade e Dados](/guias/privacidade/) — Entenda onde seus dados vão
- [Troubleshooting](/troubleshooting/) — Resolução de problemas de configuração
- [Glossário: API](/glossario/api/) — Entenda o que é uma API e como funciona