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 o arquivo de configuração do zero, gestão segura de credenciais e o processo completo de criar e testar um agente mínimo.

O Arquivo de Configuração

O OpenClaw usa um único arquivo YAML como fonte de verdade para toda a configuração: ~/.openclaw/config.yaml.

Esse arquivo define tudo — quais agentes existem, quais canais estão ativos, quais modelos são usados, quais ferramentas estão disponíveis. Quando você muda esse arquivo e reinicia o daemon, o OpenClaw recarrega tudo.

Veja a estrutura completa do arquivo:

# ~/.openclaw/config.yaml

# Configurações globais do runtime
runtime:
  log_level: info          # debug | info | warn | error
  max_concurrent_agents: 5
  data_dir: ~/.openclaw/data

# Definição dos modelos de IA disponíveis
models:
  - name: haiku
    provider: anthropic
    model_id: claude-haiku-3-5-20241022
    api_key: "${ANTHROPIC_API_KEY}"
    max_tokens: 4096
    temperature: 0.7

# Definição dos canais de comunicação
channels:
  - type: whatsapp
    name: whatsapp-principal
    phone_number_id: "${WA_PHONE_NUMBER_ID}"
    access_token: "${WA_ACCESS_TOKEN}"
    webhook_verify_token: "${WA_WEBHOOK_TOKEN}"

# Definição dos agentes
agents:
  - name: assistente
    model: haiku          # referencia ao nome definido em models
    channel: whatsapp-principal
    system_prompt: |
      Você é um assistente prestativo. Responda de forma clara e objetiva.
      Não invente informações. Se não souber, diga que não sabe.
    tools: []             # ferramentas disponíveis para este agente
    memory:
      enabled: true
      max_turns: 20       # quantas trocas manter em contexto
    session:
      idleMinutes: 2880   # 48h — padrão desde v2026.3.22 (era 10 min)

Desde a v2026.3.22, o timeout padrão de sessão é 48 horas. Na prática, a sessão raramente expira por inatividade — o cenário mais comum de “esquecimento” é compactação de contexto quando a janela enche.

Cada seção é independente — você pode ter múltiplos modelos, múltiplos canais e múltiplos agentes, e conectar qualquer combinação entre eles.

Gerenciando API Keys com Segurança

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

Note que no exemplo acima todas as credenciais usam a sintaxe "${VARIAVEL_DE_AMBIENTE}". O OpenClaw lê variáveis de ambiente automaticamente ao iniciar. Isso significa que o arquivo config.yaml pode ser versionado no Git sem risco de vazar credenciais.

Onde Guardar as Variáveis

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

# ~/.openclaw/.env

# Anthropic Claude
ANTHROPIC_API_KEY=sk-ant-api03-...

# WhatsApp Business API
WA_PHONE_NUMBER_ID=123456789012345
WA_ACCESS_TOKEN=EAABsbCS...
WA_WEBHOOK_TOKEN=minha-string-secreta-aleatoria

Proteja o arquivo:

chmod 600 ~/.openclaw/.env

O OpenClaw carrega automaticamente o .env de ~/.openclaw/ ao iniciar. Se preferir usar variáveis de ambiente do sistema (exportadas no shell), isso também funciona — 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 um sandbox no openclaw.json. O OpenClaw suporta 3 backends: Docker (--cap-drop ALL, mais seguro), OpenShell (leve, sem Docker), e SSH (executa em máquina remota).

runtime:
  sandbox:
    backend: docker    # docker | openshell | ssh

Controle de Custo: Limites de Token por Sessão

Uma funcionalidade importante para evitar fatura surpresa: limitar quantos tokens por conversa o agente pode usar.

agents:
  - name: assistente
    model: haiku
    limits:
      max_tokens_per_session: 2000    # limite por conversa individual
      max_tokens_per_day: 500000      # limite diário total para este agente
      max_cost_per_day_usd: 5.00      # limite de custo diário em dólar

Quando um limite é atingido, o agente responde com uma mensagem configurável de encerramento em vez de continuar consumindo tokens.

Para um atendimento de WhatsApp típico (MEI com 50-100 atendimentos por dia, cada um com 500-800 tokens), max_cost_per_day_usd: 2.00 é um teto conservador que raramente seria atingido com Claude Haiku.

Criando o Primeiro Agente: Configuração Mínima

Vamos criar um agente de atendimento básico para um MEI. O exemplo é um serviço de entregas, mas o padrão se aplica a qualquer tipo de negócio.

# ~/.openclaw/config.yaml

runtime:
  log_level: info
  data_dir: ~/.openclaw/data

models:
  # Modelo principal: Claude Haiku (custo baixo, bom português)
  - name: haiku
    provider: anthropic
    model_id: claude-haiku-3-5-20241022
    api_key: "${ANTHROPIC_API_KEY}"
    max_tokens: 1024
    temperature: 0.5    # menor = mais consistente, maior = mais criativo

channels:
  # Canal WhatsApp principal
  - type: whatsapp
    name: whatsapp-negocio
    phone_number_id: "${WA_PHONE_NUMBER_ID}"
    access_token: "${WA_ACCESS_TOKEN}"
    webhook_verify_token: "${WA_WEBHOOK_TOKEN}"

agents:
  # Agente de atendimento básico
  - name: "Assistente"
    model: haiku
    channel: whatsapp-negocio
    system_prompt: |
      Você é o assistente de atendimento da Entregas Rápidas Ltda.

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

      Como atender:
      - Seja cordial mas direto
      - Se o cliente perguntar sobre rastreamento, peça o número do pedido
      - Se a dúvida for sobre nota fiscal ou pagamento, informe o e-mail financeiro@entregasrapidas.com.br
      - Não confirme prazos diferentes dos informados acima
      - Se não souber responder, diga que vai transferir para um atendente humano

    tools: []
    memory:
      enabled: true
      max_turns: 10
    limits:
      max_tokens_per_session: 1500
      max_cost_per_day_usd: 3.00

Esse é o mínimo funcional. O agente consegue responder perguntas frequentes sobre horário, área de entrega, prazo e frete — sem nenhuma ferramenta, apenas com as informações no system prompt.

Skills do ClawHub

Para instalar skills do registro público: openclaw skills install nome-da-skill. Skills do workspace sempre têm prioridade sobre as instaladas.

Testando Localmente

Antes de conectar ao WhatsApp real, teste o agente via linha de comando:

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

Saída esperada:

Agent: assistente
Model: haiku
---
Olá! A Entregas Rápidas Ltda funciona de segunda a sábado, das 8h às 20h.
Posso ajudar com mais alguma coisa?
---
Tokens used: input=387, output=28
Estimated cost: $0.0003

Teste alguns cenários para verificar o comportamento:

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

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

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

Aplicando as Configurações

Após editar o config.yaml, reinicie o daemon para aplicar as mudanças:

openclaw daemon restart

Verifique se tudo carregou corretamente:

openclaw status

Saída esperada:

OpenClaw Daemon: running
Config: ~/.openclaw/config.yaml
Agents loaded: 1 (assistente)
Channels active: 1 (whatsapp-negocio)
Models configured: 1 (haiku)

Na Prática: Config Completa para MEI

Este é um exemplo comentado de configuração para um MEI prestador de serviços (designer freelancer, nesse caso), com WhatsApp e Claude Haiku:

# ~/.openclaw/config.yaml
# Configuração para MEI - Design Freelancer
# Atualizado: fev/2026

runtime:
  log_level: info
  data_dir: ~/.openclaw/data

models:
  # Claude Haiku: suficiente para atendimento, custo mínimo
  - name: haiku
    provider: anthropic
    model_id: claude-haiku-3-5-20241022
    api_key: "${ANTHROPIC_API_KEY}"
    max_tokens: 800
    temperature: 0.6

channels:
  - type: whatsapp
    name: whatsapp-studio
    phone_number_id: "${WA_PHONE_NUMBER_ID}"
    access_token: "${WA_ACCESS_TOKEN}"
    webhook_verify_token: "${WA_WEBHOOK_TOKEN}"
    # Horário de atendimento automático (fora do horário, agente responde mas avisa)
    active_hours:
      start: "08:00"
      end: "19:00"
      timezone: "America/Sao_Paulo"

agents:
  - name: "Studio"
    model: haiku
    channel: whatsapp-studio
    system_prompt: |
      Você é o assistente do Studio Criativo da Ana — design e identidade visual.

      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

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

      Como atender:
      - Seja simpática e profissional
      - Para orçamento específico, peça para o cliente descrever o projeto e diga que vai responder por e-mail em até 24h úteis
      - Não confirme prazos menores que os informados
      - Fora do horário comercial (8h-19h), avise que vai responder no próximo dia útil

    tools: []
    memory:
      enabled: true
      max_turns: 15
    limits:
      max_tokens_per_session: 1200
      max_cost_per_day_usd: 2.00

Com essa configuração rodando, o WhatsApp da Ana responde automaticamente a perguntas de preço, prazo e processo — sem ela precisar parar o trabalho criativo para cada mensagem.

O próximo passo natural é adicionar ferramentas para que o agente consulte dados externos. O capítulo sobre web e APIs cobre exatamente isso: como fazer o agente buscar informações em tempo real. E para ver templates de mensagens prontos que funcionam bem com agentes, explore os templates disponíveis.

Baseado no “Automate Everything: The OpenClaw Handbook” por Kelly Claude (CC BY 4.0). Adaptado e expandido para o mercado brasileiro.