Configuração do OpenClaw: guia completo do openclaw.json e boas práticas

Atualizado em 08/06/2026: os campos, o dmPolicy, os comandos de auditoria de segurança e as orientações de proteção contra a CVE-2026-25253 foram revisados com base na documentação oficial de configuração do Gateway do OpenClaw. Os itens de configuração devem seguir a documentação oficial.

Depois de colocar o serviço do OpenClaw em funcionamento, você abre ~/.openclaw/openclaw.json e encontra uma tela cheia de parâmetros: gateway, channel, skills, provider… e, dentro de cada campo, várias opções aninhadas. O dmPolicy deve ser pairing ou allowlist? O gateway.auth.token é, na prática, a senha? É preciso ativar todas as skills?

O que preocupa ainda mais é que, no fim de janeiro de 2026, o OpenClaw corrigiu uma vulnerabilidade grave (CVE-2026-25253, pontuação CVSS 8,8). Um invasor podia roubar o token de autenticação por um parâmetro de URL e, depois, executar comandos arbitrários. Com uma configuração inadequada, o assistente de IA poderia virar uma porta dos fundos para terceiros.

Este é exatamente o guia que eu gostaria de ter encontrado naquela época. A seguir, vamos analisar sistematicamente todos os módulos do openclaw.json: o que cada parâmetro significa, por que ele existe, como configurá-lo em produção, além de problemas que já enfrentei e um checklist de segurança.

Guia econômico para criar sua “lagosta”: ArkClaw deixa os agentes de IA realmente acessíveis

O OpenClaw (a famosa “lagosta”) está em alta e é útil, mas sua configuração afasta muita gente. O ArkClaw, da ByteDance Volcano Engine, reduz essa barreira ao mínimo. Sem precisar lidar com servidores nem configurar tokens, você ganha com um clique um agente de IA disponível 24 horas por dia, capaz de controlar o navegador, executar scripts e gerenciar o calendário.

O principal é o preço: a mensalidade custa apenas 9,9 yuans e, com meu código de convite ZLKUK54M (cadastre-se aqui), sai por 8,9 yuans. Se você programa, o Coding Plan Pro ainda permite usar o serviço gratuitamente.

Noções básicas sobre o arquivo de configuração

Onde fica e qual é sua estrutura

Por padrão, o arquivo de configuração do OpenClaw fica em ~/.openclaw/openclaw.json. Se você usou o assistente de instalação, ele é gerado automaticamente; em uma instalação manual, talvez seja necessário criá-lo. Os nomes dos campos, níveis de aninhamento e valores padrão devem seguir a documentação oficial de configuração do Gateway. Os exemplos abaixo servem para explicar a estrutura; depois de uma atualização de versão principal, confira novamente a documentação.

Ao abrir o arquivo, você verá cinco módulos principais:

• Gateway: porta, autenticação, logs e outras configurações do serviço de gateway
• Channel: configuração dos canais de comunicação, como WhatsApp e Telegram
• Skills: gerenciamento e permissões dos módulos de skills
• Provider: provedor do modelo de IA, como Anthropic, OpenAI ou um modelo local
• Security: políticas de segurança e controle de acesso

A estrutura é bastante lógica: Gateway controla a entrada, Channel cuida da comunicação, Skills define os recursos, Provider é o cérebro e Security protege o sistema.

Formas de configurar e ordem de prioridade

O OpenClaw aceita quatro formas de configuração:

1. Assistente interativo: escolha passo a passo durante a instalação; indicado para iniciantes
2. Edição direta do JSON: altere o arquivo com vim ou nano; indicado para quem já conhece configurações
3. Variáveis de ambiente: úteis em containers ou para substituir temporariamente um parâmetro
4. Automação por scripts: gere configurações em implantações em lote

O ponto importante é a ordem de prioridade: variáveis de ambiente > arquivo de configuração > valores padrão.

Por exemplo, se o arquivo define gateway.port: 18789, mas a variável OPENCLAW_GATEWAY_PORT=9000 também está definida, a porta efetiva será 9000. Isso é especialmente útil durante a depuração: você testa outro valor sem alterar o arquivo.

As versões de 2026 também adicionaram suporte a servidores MCP (Model Context Protocol), permitindo conectar vários mecanismos de busca e ferramentas por uma interface comum. Além disso, o comando openclaw doctor agora verifica automaticamente o estado da configuração e sugere correções.

Configuração detalhada do Gateway

O Gateway é a porta de entrada do OpenClaw, responsável pelo acesso à interface web e pelas conexões de clientes remotos.

Configuração básica: porta e autenticação

{
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "your-secret-token-here"
    },
    "remote": {
      "token": "your-remote-token-here"
    }
  }
}

• port: porta de acesso à interface web, 18789 por padrão. Abra http://localhost:18789 para ver o painel de controle do OpenClaw. Se a porta estiver ocupada, use outra, como 19000.

• auth.token: token de autenticação do gateway, equivalente a uma senha. Quem obtiver esse token poderá controlar totalmente sua instância do OpenClaw. A CVE-2026-25253 existia justamente porque o token podia vazar por parâmetros de URL.

• remote.token: token usado por clientes remotos, como aplicativos para celular ou desktop. Ele é separado de auth.token para permitir a troca independente.

Aviso de segurança: a versão de 29 de janeiro de 2026 removeu a opção "auth: none". Antes era possível desativar a autenticação para facilitar o desenvolvimento; agora, token ou password é obrigatório. Foi uma correção direta para a vulnerabilidade.

Configuração avançada: logs e WebSocket

{
  "gateway": {
    "logging": {
      "redactSensitive": true
    }
  }
}

Quando redactSensitive é true, dados sensíveis são ocultados automaticamente nos logs: chaves de API, tokens e outras informações são substituídos por ***. Assim, ao copiar um log para um issue público, você reduz o risco de expor credenciais sem querer.

Inicie o gateway com openclaw gateway. Depois que o serviço estiver em execução, você verá algo parecido com:

[Gateway] Listening on http://localhost:18789
[Gateway] Authentication: Token-based

Estratégia de configuração dos Channels

O módulo Channel define em quais plataformas o OpenClaw pode conversar com você.

Tipos de canal compatíveis

No momento, há quatro canais principais:

1. WhatsApp: pareamento por QR code; o mais usado
2. Telegram: Bot API; adequado para grupos
3. Discord: indicado para comunidades técnicas
4. Mattermost: colaboração de equipes corporativas

Cada canal tem uma configuração própria. No WhatsApp, o fluxo usa leitura de QR code; o Telegram exige um Bot Token; no Discord, é necessário criar uma Application.

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

Configuração da política de mensagens privadas (DM)

Esta é uma das partes que mais geram dúvida. O dmPolicy determina se desconhecidos podem enviar mensagens ao seu assistente de IA.

Há quatro modos:

1. pairing (modo padrão)

{
  "channel": {
    "dmPolicy": "pairing"
  }
}

Remetentes desconhecidos precisam primeiro concluir o pareamento. O OpenClaw gera um código de seis dígitos, válido por uma hora, que você precisa aprovar manualmente:

openclaw pairing approve whatsapp ABC123

Esse modo equilibra segurança e praticidade: na primeira vez em que um contato fala com seu assistente, você o aprova; depois disso, a comunicação segue normalmente.

2. allowlist (modo de lista de permissões)

{
  "channel": {
    "dmPolicy": "allowlist",
    "allowFrom": [
      "+1234567890",
      "telegram:@username"
    ]
  }
}

Apenas pessoas na lista podem enviar mensagens; todas as demais são bloqueadas. É indicado quando você sabe exatamente quem usará o serviço.

3. open (modo aberto)

{
  "channel": {
    "dmPolicy": "open",
    "allowFrom": ["*"]
  }
}

Qualquer pessoa pode enviar mensagens. Sinceramente, esse modo é muito arriscado. Só vale a pena em uma demonstração pública ou em testes; não o recomendo para uso permanente.

4. disabled (modo desativado)

Desativa totalmente as mensagens privadas e aceita apenas mensagens em grupos.

Isolamento de sessões para vários usuários

Se sua instância do OpenClaw atender várias pessoas, como em uma equipe, o isolamento de sessões é importante:

{
  "channel": {
    "session": {
      "dmScope": "per-channel-peer"
    }
  }
}

Assim, o histórico de cada pessoa fica separado e as conversas não se misturam.

Estratégia para grupos

A configuração de grupos é relativamente simples, mas há uma opção fundamental: mentionGating, o controle por menção com @.

{
  "channel": {
    "groupPolicy": "mention",
    "mentionGating": true
  }
}

Quando ativado, o assistente de IA responde apenas às mensagens que o mencionam com @, em vez de monitorar tudo o que é enviado no grupo. Isso evita que ele vire um bot “always-on” que inunda a conversa com respostas.

Configuração do módulo Skills

Skills são a parte mais interessante do OpenClaw: elas determinam o que o assistente de IA pode fazer.

Conceitos básicos de Skills

As skills são extensões modulares de recursos. O OpenClaw inclui algumas skills nativas, e a loja ClawHub oferece mais de 700 opções:

• Gerenciamento de calendário (Google Calendar, Outlook)
• Navegação na web (skill browser)
• Gerenciamento de arquivos (file_manager)
• Comandos de terminal (skill exec)
• Execução de código (python, node)

As skills são instaladas em ~/.openclaw/skills/. A prioridade é: skills do workspace > skills do usuário > skills nativas.

Isso significa que uma skill personalizada chamada browser dentro do diretório do projeto substitui a versão instalada globalmente. Assim, você pode adaptar os recursos a cada projeto.

Configuração e gerenciamento de Skills

Cada skill tem um arquivo SKILL.md com metadados em YAML:

---
name: google-calendar
description: Manage Google Calendar events
requirements:
  bins:
    - gcalcli
  env:
    - GOOGLE_CALENDAR_API_KEY
---

O campo bins lista os executáveis exigidos. Nesse exemplo, a skill de calendário precisa do utilitário de linha de comando gcalcli. Se ele não estiver instalado, a skill não será carregada.

Há três formas de instalar:

1. Instalação pela GUI: clique em “Add Skill” na interface web, pesquise e instale
2. Instalação pela CLI: openclaw skill install google-calendar
3. Instalação manual: copie o diretório da skill para ~/.openclaw/skills/

Solução de problemas com Skills

Falhas ao carregar skills são comuns. Use este comando para verificar as dependências:

openclaw skill check google-calendar

Ele mostra quais dependências estão ausentes, se as variáveis de ambiente foram definidas e se a configuração do sistema operacional é compatível.

Se o problema continuar, consulte o log do Gateway:

openclaw gateway --verbose

O log mostra cada etapa do carregamento da skill e deixa claro onde ocorreu o erro.

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

Otimização para modelos pequenos

Se você usa um modelo local quantizado com uma janela de contexto pequena, como um modelo de 7B parâmetros, talvez precise desativar algumas skills para controlar o tamanho do contexto. Quanto mais skills, maior o prompt do sistema e menor o espaço disponível para a conversa.

Restrição de skills de alto risco

Algumas skills têm permissões amplas e exigem cautela:

• exec: executa comandos shell arbitrários
• browser: acessa páginas arbitrárias
• web_fetch: busca conteúdo externo
• web_search: consulta mecanismos de busca

Essas skills podem ser abusadas diante de uma entrada maliciosa. Se não forem essenciais, desative-as.

Configuração do provedor de modelos

O Provider determina qual cérebro de IA o OpenClaw usará.

Provedores de IA compatíveis

1. Anthropic (Claude): principal recomendação oficial, API estável e recursos de segurança completos
2. OpenAI: suporte previsto em breve, incluindo modelos como GPT-5
3. Modelos locais: LM Studio, Ollama e outros
4. OpenRouter: interface única para vários modelos, usando uma só API Key
5. Servidores MCP: novidade de 2026, com suporte ao Model Context Protocol

Parâmetros de configuração do Provider

A configuração mais simples, usando a Anthropic, é:

{
  "provider": {
    "type": "anthropic",
    "apiKey": "sk-ant-..."
  }
}

Ainda assim, não recomendo gravar a API Key diretamente no arquivo. Prefira uma variável de ambiente:

export ANTHROPIC_API_KEY="sk-ant-..."

Com isso, o arquivo de configuração pode entrar no controle de versão sem expor a chave.

Configuração de modelos locais

{
  "provider": {
    "type": "openai-compatible",
    "baseURL": "http://localhost:1234/v1",
    "modelId": "kimi-k2.5-chat"
  }
}

• baseURL: endereço do servidor do modelo local; o LM Studio usa a porta 1234 por padrão
• modelId: nome do modelo que será usado

Configuração de servidor MCP (novo recurso)

{
  "provider": {
    "mcpServers": {
      "onesearch": {
        "command": "npx",
        "args": ["-y", "@onesearch/mcp-server"]
      }
    }
  }
}

O OneSearch MCP permite acessar vários mecanismos de busca, como Google, Bing e Brave, por uma interface comum, sem configurar uma API Key separada para cada um.

Cuidados com modelos locais

Modelos locais têm vantagens reais: privacidade, custo e funcionamento offline. Porém, seus recursos de segurança são mais fracos do que os de modelos comerciais:

• Maior risco de injeção de prompt: modelos pequenos são mais fáceis de enganar com entradas maliciosas
• Janela de contexto pequena: mecanismos de segurança exigem prompts de sistema maiores, que talvez não caibam
• Limitações da quantização: depois da quantização em 4 bits, a capacidade de seguir instruções diminui

Se você precisar usar um modelo local:

• Restrinja rigorosamente as permissões das skills
• Ative o modo sandbox
• Não execute o modelo em uma máquina com dados sensíveis

Boas práticas de configuração de segurança

Segurança é sempre a prioridade. A CVE-2026-25253 mostrou que as consequências de uma configuração inadequada podem ser graves.

Checklist de segurança

Segurança básica (obrigatória)

• ✅ Nunca compartilhe o token do gateway: trate-o como a chave da sua casa
• ✅ Use um firewall e exponha apenas as portas necessárias, como a 18789
• ✅ Use autenticação por chave no SSH, não por senha
• ✅ Restrinja o acesso à interface web com VPN ou lista de IPs
• ✅ Na política de DM, prefira pairing ou allowlist
• ✅ Em grupos, ative o mention gating

Segurança avançada (altamente recomendada)

• ✅ Troque os tokens regularmente, ao menos uma vez por trimestre
• ✅ Ative a ocultação de dados sensíveis nos logs
• ✅ Restrinja skills de alto risco, como exec e browser
• ✅ Use um servidor dedicado, separado da sua principal máquina de trabalho

Segurança de entrada e sandbox

Existe uma regra de ouro: trate toda entrada externa como maliciosa.

Links, anexos e instruções coladas podem ter sido preparados para atacar o sistema. O sandbox opcional do OpenClaw permite isolar operações de alto risco:

{
  "security": {
    "sandbox": {
      "enabled": true,
      "skills": ["exec", "browser"]
    }
  }
}

Assim, as skills exec e browser são executadas em um ambiente isolado. Mesmo que sejam comprometidas, o sistema principal não é afetado.

Gerenciamento de secrets

Para gerenciar chaves de API, tokens e outras informações sensíveis:

1. Solução básica: transfira o arquivo .env ao servidor com SCP, sem colá-lo em chats
2. Solução avançada: use um gerenciador profissional de secrets, como Doppler ou HashiCorp Vault

O que nunca fazer:

• ❌ Enviar uma API Key por mensagem no Telegram
• ❌ Versionar secrets em um repositório Git
• ❌ Colar logs em um issue público, pois eles podem conter tokens

Auditoria e manutenção de segurança

O OpenClaw inclui comandos de auditoria:

# Verificação básica
openclaw security audit

# Verificação aprofundada
openclaw security audit --deep

# Aplicar correções de segurança automaticamente
openclaw security audit --fix

Esses comandos verificam:

• Se o token é suficientemente forte
• Se a porta está exposta à internet
• Se as permissões estão corretas (~/.openclaw deve ser 700 e o arquivo de configuração, 600)
• Se skills de alto risco estão ativadas
• Se a política de DM é segura

Permissões dos arquivos locais

chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json

Desse modo, somente você poderá ler e gravar o arquivo de configuração; outros usuários não conseguirão sequer abri-lo.

O que nunca fazer

• ❌ Expor a porta 18789 à internet
• ❌ Conceder acesso ao shell sem entender os riscos
• ❌ Instalar skills de fontes não verificadas
• ❌ Usar dmPolicy: "open" sem uma lista de permissões
• ❌ Executar o OpenClaw em uma máquina que armazena seu e-mail principal ou dados bancários

Exemplos práticos de configuração

Agora que a teoria está clara, veja configurações completas para alguns cenários reais.

Cenário 1: uso pessoal, apenas WhatsApp, modo pairing

{
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "generate-a-strong-random-token"
    },
    "logging": {
      "redactSensitive": true
    }
  },
  "channel": {
    "type": "whatsapp",
    "dmPolicy": "pairing",
    "session": {
      "dmScope": "per-channel-peer"
    }
  },
  "skills": {
    "enabled": [
      "calendar",
      "web_search",
      "file_manager"
    ],
    "disabled": [
      "exec",
      "browser"
    ]
  },
  "provider": {
    "type": "anthropic"
  },
  "security": {
    "sandbox": {
      "enabled": true
    }
  }
}

Essa configuração é adequada para uso pessoal comum: oferece boa segurança, recursos suficientes e mantém desativadas as skills de alto risco.

Cenário 2: colaboração em equipe, vários canais, modo allowlist

{
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "team-gateway-token"
    },
    "remote": {
      "token": "team-remote-token"
    }
  },
  "channel": [
    {
      "type": "telegram",
      "dmPolicy": "allowlist",
      "allowFrom": [
        "telegram:@alice",
        "telegram:@bob",
        "telegram:@carol"
      ],
      "groupPolicy": "mention",
      "mentionGating": true
    },
    {
      "type": "discord",
      "dmPolicy": "allowlist",
      "allowFrom": [
        "discord:123456789"
      ]
    }
  ],
  "skills": {
    "enabled": [
      "calendar",
      "web_search",
      "github",
      "jira"
    ]
  },
  "provider": {
    "type": "anthropic"
  }
}

Uma configuração com vários canais usa um array, e cada canal gerencia sua própria lista de permissões. Nos grupos, o mention gating evita flood.

Cenário 3: modelo local, uso offline e conjunto reduzido de skills

{
  "gateway": {
    "port": 19000
  },
  "channel": {
    "type": "whatsapp",
    "dmPolicy": "allowlist",
    "allowFrom": ["+1234567890"]
  },
  "skills": {
    "enabled": [
      "calculator",
      "file_manager"
    ]
  },
  "provider": {
    "type": "openai-compatible",
    "baseURL": "http://localhost:1234/v1",
    "modelId": "llama-3.1-8b"
  }
}

Com um modelo local, mantenha o conjunto de skills o menor possível: a janela de contexto de modelos pequenos não comporta prompts de sistema muito grandes.

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

Erros comuns de configuração e soluções

Erro 1: não é possível conectar por incompatibilidade do token

Sintoma: a interface web mostra “Authentication failed”.

Solução: confira se gateway.auth.token é exatamente igual ao token informado, inclusive espaços e quebras de linha.

Erro 2: a skill não carrega por falta de dependências

Sintoma: o log mostra “Skill ‘google-calendar’ failed to load”.

Solução: execute openclaw skill check google-calendar e instale as dependências indicadas.

Erro 3: o Gateway não inicia por conflito de porta

Sintoma: Error: listen EADDRINUSE :::18789.

Solução: use outra porta ou localize e encerre o processo que ocupa a 18789.

Erro 4: formato inválido do arquivo de configuração

Sintoma: SyntaxError: Unexpected token } in JSON.

Solução: valide o JSON. Os problemas mais comuns são vírgulas sobrando e aspas incompatíveis.

Comandos de diagnóstico

# Ver o status do serviço
openclaw status

# Verificação de integridade
openclaw doctor

# Logs detalhados
openclaw gateway --verbose

Leituras relacionadas

• Guia completo de instalação do OpenClaw: da preparação do ambiente à primeira execução
• Arquitetura do OpenClaw em detalhes: design em três camadas e práticas de extensão
• OpenClaw vs. ChatGPT: comparação de arquitetura técnica, custos e privacidade

Conclusão

Depois de todos esses detalhes, três pontos concentram o essencial.

Primeiro, o arquivo de configuração é o coração do OpenClaw. Vale a pena entender cada parâmetro, não para exibir conhecimento técnico, mas para localizar rapidamente a causa de um problema.

Segundo, a segurança é sempre a prioridade. A CVE-2026-25253 comprovou que os riscos de uma configuração inadequada são reais. Proteja os tokens, restrinja as portas, endureça a política de DM e ative skills de alto risco apenas com cautela.

Terceiro, configuração não é uma tarefa feita uma única vez. Conforme o cenário de uso muda, a equipe cresce ou diminui e novas skills surgem, a configuração precisa ser ajustada continuamente. Revise-a de tempos em tempos e execute openclaw security audit para manter tudo sob controle.

Agora, faça três coisas:

1. Execute openclaw security audit --deep para verificar a configuração atual
2. Compare sua configuração com o checklist deste artigo e ajuste cada item
3. Faça backup da configuração otimizada em um local seguro, mas sem incluir os tokens

Se você encontrar problemas durante a configuração, a comunidade do OpenClaw é ativa, e há pessoas dispostas a ajudar no GitHub Discussions e no Discord. Compartilhe também sua experiência: todo mundo aprende passo a passo.