Configuração Inicial do OpenClaw: Primeiro Agente Rodando

Com o OpenClaw instalado e os conceitos de arquitetura claros, chegou a hora de colocar o primeiro agente para funcionar. Este capítulo cobre as duas camadas de configuração, gestão segura de credenciais e o processo completo de criar e testar um agente mínimo.

As Duas Camadas de Configuração

O OpenClaw separa configuração em duas camadas, e entender essa divisão evita muita confusão:

Configuração global — o arquivo ~/.openclaw/openclaw.json (formato JSON5). Define quais canais estão ativos, qual modelo de IA é o padrão, como funciona o sandbox e a sessão. É a parte “de máquina”.
Comportamento do agente — arquivos Markdown em ~/.openclaw/workspace/ (AGENTS.md, SOUL.md, IDENTITY.md). É aqui que vive a persona, as instruções operacionais e os limites — não no JSON. É a parte “de conteúdo”.

A persona e as regras do agente NÃO ficam no openclaw.json. Ficam no AGENTS.md (instruções) e no SOUL.md (tom e limites). O mapa completo do workspace está em anatomia do workspace OpenClaw.

O openclaw.json

JSON5 é JSON com comentários (//) e vírgulas finais permitidos. O jeito mais simples de criar o arquivo é rodar openclaw onboard — o esquema exato e sempre atualizado fica na referência de configuração oficial. Um exemplo enxuto:

// ~/.openclaw/openclaw.json
{
  // Chaves de API: referencie variáveis de ambiente, não cole o valor aqui
  env: {
    ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY}",
  },

  // Modelo padrão das conversas (formato "provedor/modelo") + fallback
  defaults: {
    model: "anthropic/claude-haiku-4-5",
    fallbacks: ["openrouter/anthropic/claude-sonnet-4-6"],
  },

  // Canais ativos (objeto, uma chave por canal)
  channels: {
    whatsapp: {
      enabled: true,
      dmPolicy: "pairing", // só responde a contatos pareados explicitamente
    },
  },

  // Isolamento de execução
  sandbox: {
    backend: "docker", // "docker" | "openshell" | "ssh"
    capabilities: { drop: ["ALL"] },
  },

  // Sessão: 48h de inatividade antes de resetar (padrão v2026.3.22)
  session: {
    idleMinutes: 2880,
  },
}

Mude o arquivo, reinicie o gateway (openclaw gateway restart) e o OpenClaw recarrega tudo. Como o dmPolicy padrão é pairing, o WhatsApp via OpenClaw usa o protocolo do WhatsApp Web (Baileys) e pede um pareamento por QR Code na primeira conexão — não há token da API oficial da Meta para colar aqui.

Gerenciando API Keys com Segurança

A regra mais importante: nunca coloque chaves de API diretamente no arquivo de configuração.

No exemplo acima, a chave usa a sintaxe "${ANTHROPIC_API_KEY}". O OpenClaw lê variáveis de ambiente ao iniciar, então o openclaw.json pode ser versionado no Git sem vazar credenciais.

Onde Guardar as Variáveis

Crie um arquivo .env em ~/.openclaw/:

# ~/.openclaw/.env
ANTHROPIC_API_KEY=sk-ant-api03-...

Proteja o arquivo:

chmod 600 ~/.openclaw/.env

O OpenClaw carrega o .env de ~/.openclaw/ ao iniciar. Variáveis de ambiente exportadas no shell também funcionam — o .env é opcional.

Onde Obter as API Keys

Anthropic (Claude)

Crie conta em console.anthropic.com
Vá em API Keys → Create Key
Copie a chave (começa com sk-ant-)
Configure um limite de gasto mensal para evitar surpresas — comece com US$ 10

OpenAI (GPT)

Acesse platform.openai.com
API Keys → Create new secret key
Configure também um spending limit

Nota sobre câmbio: as APIs cobram em dólar. Se o câmbio subir, sua fatura em reais sobe junto. Limites de gasto em dólar protegem contra isso — defina um limite baixo no início e ajuste conforme o uso real.

Isolamento com Sandbox

Para isolar o agente do sistema, configure o sandbox no openclaw.json. O OpenClaw suporta 3 backends: Docker (com --cap-drop ALL, o mais seguro), OpenShell (leve, sem Docker) e SSH (executa em máquina remota).

{
  sandbox: {
    backend: "docker", // "docker" | "openshell" | "ssh"
    capabilities: { drop: ["ALL"] },
  },
}

Controle de Custo

O OpenClaw não cobra nada — quem cobra é a API do modelo. Há três alavancas práticas para manter a conta sob controle, da mais eficaz para a menos:

Escolha do modelo: um modelo Haiku/nano custa uma fração de um Opus/Pro. Para atendimento e tarefas curtas, o modelo barato resolve. Defina-o como defaults.model e use o caro só onde precisar.
Limite de gasto no provedor: configure um spending limit em dólar no console da Anthropic/OpenAI. É o teto que realmente protege contra surpresa — independe de qualquer config do OpenClaw.
Fallback consciente: na chave fallbacks, prefira modelos baratos. Assim, se o principal falhar, você não cai num modelo caro sem perceber.

Para roteamento entre modelos (primário barato, fallback forte), veja multi-model routing com OpenRouter. Para os limites de gasto e o impacto do câmbio, releia a seção de API keys acima.

Criando o Primeiro Agente

O comportamento do agente vive no workspace, não no JSON. Vamos criar um atendente para um MEI de entregas. O openclaw.json só precisa do canal e do modelo — o resto é a persona em AGENTS.md.

Config global (já coberta acima): canal whatsapp ativo + defaults.model apontando para o Haiku. Agora a persona, em ~/.openclaw/workspace/AGENTS.md:

# AGENTS.md — atendimento Entregas Rápidas Ltda

## Quem você é
Assistente de atendimento da Entregas Rápidas Ltda no WhatsApp.

## Informações da operação
- Horário: segunda a sábado, 8h às 20h
- Áreas de entrega: São Paulo capital e Grande São Paulo
- Prazo: 2h para SP capital, 4h para Grande SP
- Frete: R$ 15 (SP capital), R$ 25 (Grande SP)

## Como atender
- Seja cordial mas direto
- Para rastreamento, peça o número do pedido
- Dúvidas de nota fiscal ou pagamento: encaminhe para financeiro@entregasrapidas.com.br
- Não confirme prazos diferentes dos acima
- Se não souber, diga que vai transferir para um atendente humano

O tom (formal/informal, idioma, formato das respostas) vai no SOUL.md. Com AGENTS.md preenchido e o canal ativo, o agente já responde às perguntas frequentes — sem nenhuma ferramenta, só com as instruções do workspace.

Skills do ClawHub

Para instalar habilidades do registro público: openclaw skills install nome-da-skill. Skills criadas no workspace (~/.openclaw/workspace/skills/) sempre têm prioridade sobre as instaladas.

Testando Localmente

Antes de conversar pelo WhatsApp, teste o agente pela linha de comando:

openclaw agent --message "Qual o horário de funcionamento?"

O agente responde no terminal usando as instruções do AGENTS.md. Teste alguns cenários para verificar o comportamento:

# Pergunta dentro do conhecimento do agente
openclaw agent --message "Vocês entregam em Guarulhos?"

# Pergunta fora do conhecimento
openclaw agent --message "Aceita pagamento com criptomoeda?"

# Solicitação de rastreamento
openclaw agent --message "Quero rastrear meu pedido 12345"

Aplicando as Configurações

Depois de editar o openclaw.json ou os arquivos do workspace, reinicie o gateway:

openclaw gateway restart

Verifique se tudo carregou:

openclaw status

A saída confirma que o gateway está rodando e mostra os canais ativos. Para um diagnóstico mais profundo (chaves, conectividade, permissões), use openclaw doctor.

Na Prática: MEI Designer Freelancer

Mesmo padrão, outro negócio. O openclaw.json muda só na escolha do modelo, se você quiser; a persona vai toda no AGENTS.md:

# AGENTS.md — Studio Criativo da Ana

## Quem você é
Assistente do Studio Criativo da Ana — design e identidade visual, no WhatsApp.

## Serviços e preços aproximados (confirmar orçamento por e-mail)
- Logo + manual de marca: R$ 1.200 a R$ 2.500
- Posts para redes sociais (pacote mensal, 8 artes): R$ 600
- Cardápio digital: R$ 350 a R$ 700
- Apresentação comercial (até 15 slides): R$ 800

## Regras
- Prazo médio: 7 a 15 dias úteis dependendo do projeto
- Pagamento: PIX ou cartão em até 3x sem juros
- Orçamentos formais: ana@studiocriativo.com.br

## Como atender
- Seja simpática e profissional
- Para orçamento específico, peça a descrição do projeto e diga que responde por e-mail em até 24h úteis
- Não confirme prazos menores que os informados
- Fora do horário comercial, avise que responde no próximo dia útil

Para controlar o horário de atendimento e outras políticas finas, consulte a referência de configuração oficial — os nomes de chave mudam entre versões e a fonte oficial é sempre a referência correta.

Com isso rodando, o WhatsApp da Ana responde a perguntas de preço, prazo e processo sozinho — sem ela parar o trabalho criativo a cada mensagem.

O próximo passo natural é dar ferramentas ao agente para consultar dados externos. O capítulo sobre web e APIs cobre isso. E para ver mensagens prontas que funcionam bem com agentes, explore os templates disponíveis.

Conteúdo original do OpenClaw Club Brasil, escrito para o mercado brasileiro. Referência oficial: documentação do OpenClaw.