Introdução ao OpenClaw: A Revolução no Controle de Modelos de IA

O OpenClaw se tornou uma das ferramentas mais procuradas em 2026 para quem busca autonomia total no uso de modelos de linguagem artificial. Neste guia definitivo e detalhado, você aprenderá passo a passo como instalar e configurar o OpenClaw utilizando a API gratuita do OpenRouter, além de resolver todos os erros comuns que aparecem durante o processo de instalação.

Este tutorial foi testado e validado em ambiente Ubuntu/WSL2 e cobre desde a instalação básica até a resolução completa de problemas críticos como erros de parse, configuração inadequada de tokens e problemas com variáveis de ambiente.

Se você chegou até aqui procurando por "como instalar OpenClaw", "OpenClaw com OpenRouter gratuito", "resolver erro de parse OpenClaw" ou "configurar OpenClaw no WSL2", você está no lugar certo. Vamos resolver tudo isso juntos!

Sumário

O que é o OpenClaw e por que usar?
Pré-requisitos para instalação
Obtendo sua API Key gratuita do OpenRouter
Instalação inicial do OpenClaw
Resolvendo o erro de parse (JSON)
Configurando o token da API do modelo
Acessando o dashboard do OpenClaw
Troubleshooting: Problemas comuns
Conclusão e próximos passos

O que é o OpenClaw e por que usar?

O OpenClaw é uma plataforma open-source revolucionária que permite você ter controle total sobre modelos de IA localmente/externamente. Com o OpenClaw, você pode:

Executar modelos de IA poderosos gratuitamente usando APIs como o OpenRouter
Ter controle total sobre seus dados e privacidade
Customizar completamente a experiência de uso
Integrar com diversos modelos e provedores
Criar automações e workflows personalizados

A combinação do OpenClaw + OpenRouter é especialmente poderosa porque você consegue acesso a modelos de ponta (como Claude, GPT-4, Llama e outros) através de créditos gratuitos e preços extremamente competitivos.

Pré-requisitos para instalação

Antes de começar a instalação do OpenClaw, certifique-se de ter os seguintes requisitos instalados e configurados em seu sistema:

Requisitos de Sistema

Sistema Operacional: Ubuntu 20.04+ ou WSL2 (Windows Subsystem for Linux 2)
Docker: Versão 20.10 ou superior
Docker Compose: Versão 2.0 ou superior
Memória RAM: Mínimo 4GB (recomendado 8GB)
Espaço em disco: Mínimo 10GB livres

Verificando as instalações

Para verificar se você tem o Docker instalado corretamente, execute:

docker --version
docker compose version

Se você não tiver o Docker instalado, siga a documentação oficial do Docker para sua distribuição Linux ou configure o WSL2 no Windows.

Obtendo sua API Key gratuita do OpenRouter

O OpenRouter é uma plataforma que agrega diversos provedores de modelos de IA em uma única API. Eles oferecem créditos gratuitos para novos usuários e preços muito competitivos.

Passo 1: Criar conta no OpenRouter

Acesse https://openrouter.ai
Clique em "Sign Up" ou "Get Started"
Crie sua conta usando email ou login social (Google/GitHub)
Confirme seu email se necessário

Passo 2: Gerar sua API Key

Após fazer login, acesse a página de API Keys
Clique em "Create API Key" ou "Generate Key"
Dê um nome descritivo para sua chave (ex: "OpenClaw Production")
IMPORTANTE: Copie a chave imediatamente e guarde em local seguro
A chave terá o formato: sk-or-v1-xxxxxxxxxxxxxxxxxxxxx

![Inserir imagem: Painel de geração de API Key]

Passo 3: Verificar créditos gratuitos

O OpenRouter oferece alguns modelos gratuitos. Verifique:

Acesse o dashboard
Pesquise por: Z.ai: GLM 4.5 Air (free)

⚠️ IMPORTANTE: Guarde sua API Key em local seguro. Nunca compartilhe publicamente ou commit em repositórios Git!

Instalação inicial do OpenClaw

Agora vamos instalar o OpenClaw usando Docker Compose. Este é o método mais simples e recomendado.

Passo 1: Baixar o OpenClaw

git clone https://github.com/openclaw/openclaw
cd openclaw 
./docker-setup.sh

Passo 2: Iniciar os containers

Agora vamos subir os containers do OpenClaw:

docker compose up -d

Passo 3: Verificar se os containers estão rodando

Verifique o status dos containers:

docker ps

Você deve ver algo como:

CONTAINER ID   IMAGE                     STATUS         PORTS
abc123def456   openclaw/openclaw:latest  Up 2 minutes   0.0.0.0:18789->18789/tcp

Resolvendo o erro de parse (JSON)

Um dos erros mais comuns durante a primeira execução do OpenClaw é o erro de parse do arquivo JSON de configuração. Isso acontece porque o container não consegue criar ou ler corretamente o arquivo de configuração.

Sintomas do erro de parse

Dashboard não abre
Logs mostram erros relacionados a JSON
Mensagens como "JSON Parse Error" ou "Unexpected token"

Solução completa passo a passo

Passo A: Entrar no container

Primeiro, precisamos acessar o container que está com problema:

docker exec -it openclaw-openclaw-gateway-1 /bin/bash

Você verá o prompt mudar, indicando que está dentro do container:

node@abc123def456:~$

Passo B: Criar o diretório de configuração

Dentro do container, crie o diretório necessário:

mkdir -p /home/node/.openclaw

Passo C: Criar o arquivo de configuração correto

Agora vamos criar o arquivo JSON de configuração com o conteúdo correto:

cat > /home/node/.openclaw/openclaw.json << 'EOF'
{
  "gateway": {
    "mode": "local",
    "bind": "lan",
    "port": 18789,
    "controlUi": {
      "enabled": true,
      "allowInsecureAuth": true
    },
    "auth": {
      "mode": "token",
      "token": "TOKEN_GERADO_NA_HORA_DE_INSTALAR_O_OPENCLAW_OU_PODE_SER_QUALQUER_OUTRO_ALEATORIO"
    },
    "trustedProxies": [
      "192.168.65.0/24",
      "172.17.0.0/16"
    ]
  }
}
EOF

⚠️ IMPORTANTE: Substitua TOKEN_GERADO_NA_HORA_DE_INSTALAR_O_OPENCLAW_OU_PODE_SER_QUALQUER_OUTRO_ALEATORIO pelo mesmo token que você colocou no arquivo .env na variável OPENCLAW_GATEWAY_TOKEN.

Passo C.1: Conferir se o arquivo foi criado corretamente

Verifique o conteúdo do arquivo:

cat /home/node/.openclaw/openclaw.json

Você deve ver o JSON formatado corretamente. Se houver algum erro de sintaxe, o problema persistirá.

![Inserir imagem: Verificando conteúdo do arquivo JSON]

Passo D: Sair do container

Agora que o arquivo foi criado, saia do container:

exit

Você voltará ao terminal do seu sistema Ubuntu/WSL2.

![Inserir imagem: Saindo do container]

Passo E: Reiniciar os containers

Para aplicar as mudanças, reinicie os containers:

docker compose down
docker compose up -d

Passo F: Verificar os logs

Aguarde alguns segundos e verifique se não há mais erros:

docker logs openclaw-openclaw-gateway-1 --tail 120

Se tudo estiver correto, você verá mensagens indicando que o serviço iniciou com sucesso, sem erros de parse.

![Inserir imagem: Logs sem erros]

Configurando o token da API do modelo

Mesmo após configurar o arquivo .env ou até mesmo durante a instalação, às vezes o OpenClaw não reconhece automaticamente a API Key do OpenRouter. Isso é um problema comum e tem uma solução definitiva.

Por que isso acontece?

O problema ocorre porque:

O docker-compose.yml usa variáveis de ambiente externas (como ${OPENROUTER_API_KEY})
Essas variáveis precisam estar corretamente mapeadas no arquivo .env
E também precisam estar explicitamente declaradas no environment de cada serviço

Sintomas deste problema

Dashboard abre, mas não consegue usar modelos
Erros relacionados a "API Key not found" ou "Authentication failed"
Requisições falham com erro 401 ou 403

Solução definitiva

Passo 1: Verificar o arquivo .env

Primeiro, confirme que seu arquivo .env está correto:

cd ~/openclaw
cat .env

Deve conter:

OPENCLAW_GATEWAY_TOKEN=seu-token-forte-aqui
OPENROUTER_API_KEY=sk-or-v1-sua-chave-completa-aqui

Se não estiver assim, edite:

nano .env

Regras importantes:

⚠️ NÃO use aspas ao redor dos valores
⚠️ NÃO coloque espaços antes ou depois do =
⚠️ Substitua pelos seus valores reais

Exemplo correto:

OPENROUTER_API_KEY=sk-or-v1-abc123def456

Exemplo ERRADO:

OPENROUTER_API_KEY = "sk-or-v1-abc123def456"

Salve e feche o arquivo.

Passo 2: Editar o docker-compose.yml

Agora precisamos garantir que o docker-compose.yml está passando as variáveis corretamente para os containers:

nano docker-compose.yml

Certifique-se de que AMBOS os serviços (openclaw-gateway e openclaw-cli) tenham a linha OPENROUTER_API_KEY: ${OPENROUTER_API_KEY} na seção environment.

O arquivo deve estar assim:

version: '3.8'

services:
  openclaw-gateway:
    image: openclaw/openclaw:latest
    container_name: openclaw-openclaw-gateway-1
    ports:
      - "18789:18789"
    environment:
      HOME: /home/node
      TERM: xterm-256color
      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN}
      OPENROUTER_API_KEY: ${OPENROUTER_API_KEY}  # <-- ESTA LINHA É CRÍTICA
    volumes:
      - openclaw-data:/home/node/.openclaw
    networks:
      - openclaw-network
    restart: unless-stopped

  openclaw-cli:
    image: openclaw/openclaw-cli:latest
    container_name: openclaw-openclaw-cli-1
    environment:
      HOME: /home/node
      TERM: xterm-256color
      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN}
      OPENROUTER_API_KEY: ${OPENROUTER_API_KEY}  # <-- ESTA LINHA É CRÍTICA
    volumes:
      - openclaw-data:/home/node/.openclaw
    networks:
      - openclaw-network
    depends_on:
      - openclaw-gateway
    restart: unless-stopped

volumes:
  openclaw-data:

networks:
  openclaw-network:
    driver: bridge

Salve o arquivo.

![Inserir imagem: docker-compose.yml editado com variáveis de ambiente]

Passo 3: Reiniciar completamente

Agora vamos parar e reiniciar tudo para garantir que as variáveis sejam carregadas:

docker compose down
docker compose up -d

![Inserir imagem: Containers sendo reiniciados]

Passo 4: Verificar as variáveis dentro do container

Para ter certeza absoluta de que as variáveis foram carregadas, vamos verificar dentro do container:

docker exec -it openclaw-openclaw-gateway-1 env | grep OPENROUTER

Você deve ver algo como:

OPENROUTER_API_KEY=sk-or-v1-abc123def456

![Inserir imagem: Verificando variáveis de ambiente no container]

Se aparecer vazio ou não mostrar nada, revise os passos anteriores.

Passo 5: Testar a conexão

Agora teste se o OpenClaw consegue se conectar ao OpenRouter. Acesse o dashboard (próxima seção) e tente fazer uma requisição para um modelo.

Acessando o dashboard do OpenClaw

Com tudo configurado corretamente, agora é hora de acessar a interface web do OpenClaw.

Passo 1: Construir a URL com token

A URL de acesso segue este formato:

http://localhost:18789/?token=SEU_TOKEN_AQUI

Substitua SEU_TOKEN_AQUI pelo valor que você definiu na variável OPENCLAW_GATEWAY_TOKEN do arquivo .env.

Exemplo completo:

Se seu token é meu-token-super-seguro-12345, a URL será:

http://localhost:18789/?token=meu-token-super-seguro-12345

![Inserir imagem: URL completa com token]

Passo 2: Abrir no navegador

Abra seu navegador favorito (Chrome, Firefox, Edge, etc.)
Cole a URL completa na barra de endereços
Pressione Enter

Se tudo estiver correto, você verá a interface do OpenClaw!

Passo 3: Salvar nos favoritos

Para não precisar digitar o token toda vez, salve a URL completa nos seus favoritos do navegador:

Com a página aberta, pressione Ctrl + D (Windows/Linux) ou Cmd + D (Mac)
Dê um nome como "OpenClaw Dashboard"
Salve

Passo 4: Explorar a interface

Agora você pode:

Fazer perguntas e testar os modelos
Configurar preferências
Ver histórico de conversas
Monitorar uso

Troubleshooting: Problemas comuns

Mesmo seguindo todos os passos, você pode encontrar alguns problemas. Aqui estão as soluções para os mais comuns:

Problema 1: Dashboard não abre (erro de conexão)

Sintomas:

Navegador mostra "Unable to connect"
Página não carrega

Diagnóstico:

docker ps

Verifique se o container está rodando e se a porta 18789 está mapeada.

![Inserir imagem: Verificando status dos containers]

Solução:

# Verificar logs do gateway
docker logs openclaw-openclaw-gateway-1 --tail 120

# Se necessário, reiniciar
docker compose restart openclaw-gateway

Problema 2: Erro de autenticação no dashboard

Sintomas:

Página mostra "Authentication failed" ou "Invalid token"

Solução:

Confirme que o token na URL é exatamente igual ao do arquivo .env
Verifique se o arquivo JSON dentro do container tem o mesmo token:

docker exec -it openclaw-openclaw-gateway-1 cat /home/node/.openclaw/openclaw.json

Se estiver diferente, refaça os passos da seção "Resolvendo o erro de parse"

Problema 3: Modelos não respondem ou erro de API

Sintomas:

Dashboard abre, mas ao tentar usar um modelo aparece erro
Mensagens como "API Key invalid" ou "Authentication failed"

Solução:

Verificar se a API Key está correta:

# Verificar no container
docker exec -it openclaw-openclaw-gateway-1 env | grep OPENROUTER_API_KEY

# Verificar no arquivo .env
cat .env | grep OPENROUTER_API_KEY

Se estiverem diferentes ou vazias, refaça a seção "Configurando o token da API do modelo".

Problema 4: Erro "Port already in use"

Sintomas:

Container não inicia
Erro: "Bind for 0.0.0.0:18789 failed: port is already allocated"

Solução:

Outro serviço está usando a porta 18789. Você pode:

Opção A: Parar o serviço que está usando a porta Opção B: Mudar a porta do OpenClaw

Para mudar a porta, edite o docker-compose.yml:

ports:
  - "19000:18789"  # Mude de 18789 para 19000 (ou outra porta livre)

E acesse via: http://localhost:19000/?token=SEU_TOKEN

![Inserir imagem: Alterando porta no docker-compose]

Problema 5: Container reinicia constantemente

Sintomas:

docker ps mostra status "Restarting"
Container não fica online

Diagnóstico:

docker logs openclaw-openclaw-gateway-1 --tail 200

Procure por erros críticos nos logs.

Soluções comuns:

Arquivo de configuração JSON malformado (refazer seção de erro de parse)
Permissões incorretas nos volumes
Memória insuficiente

Para permissões:

docker compose down
docker volume rm openclaw_openclaw-data
docker compose up -d

Problema 6: Logs mostram "Cannot find module"

Sintomas:

Logs contêm erros como "Error: Cannot find module 'xxx'"

Solução:

A imagem pode estar corrompida. Forçar atualização:

docker compose down
docker rmi openclaw/openclaw:latest
docker rmi openclaw/openclaw-cli:latest
docker compose pull
docker compose up -d

![Inserir imagem: Atualizando imagens Docker]

Diagnóstico rápido universal

Sempre que tiver problemas, execute esta sequência de comandos:

# 1. Status dos containers
docker ps -a

# 2. Logs do gateway (últimas 120 linhas)
docker logs openclaw-openclaw-gateway-1 --tail 120

# 3. Logs do CLI (últimas 120 linhas)
docker logs openclaw-openclaw-cli-1 --tail 120

# 4. Verificar variáveis de ambiente
docker exec -it openclaw-openclaw-gateway-1 env | grep -E "OPENCLAW|OPENROUTER"

# 5. Verificar arquivo de configuração
docker exec -it openclaw-openclaw-gateway-1 cat /home/node/.openclaw/openclaw.json

Conclusão e próximos passos

Parabéns! 🎉 Você concluiu com sucesso a instalação e configuração completa do OpenClaw com a API gratuita do OpenRouter.

O que você aprendeu

Neste guia detalhado, você aprendeu:

✅ O que é o OpenClaw e suas vantagens
✅ Como obter créditos gratuitos no OpenRouter
✅ Instalação completa usando Docker Compose
✅ Resolução do erro crítico de parse do JSON
✅ Configuração correta de variáveis de ambiente
✅ Como acessar o dashboard com segurança
✅ Troubleshooting de problemas comuns

Próximos passos recomendados

Agora que você tem o OpenClaw funcionando, aqui estão algumas sugestões do que fazer:

1. Explorar diferentes modelos

O OpenRouter oferece acesso a diversos modelos de IA. Experimente:

Claude (Anthropic): Excelente para conversas naturais e análises
GPT-4 (OpenAI): Versátil para diversas tarefas
Llama (Meta): Open-source e rápido
Mistral: Eficiente e econômico

2. Configurar backup automático

Proteja suas conversas e configurações:

# Criar script de backup
mkdir -p ~/openclaw-backups

# Backup manual
docker run --rm -v openclaw_openclaw-data:/data -v ~/openclaw-backups:/backup ubuntu tar czf /backup/openclaw-backup-$(date +%Y%m%d).tar.gz /data

3. Configurar acesso externo (opcional)

Se quiser acessar o OpenClaw de outros dispositivos na sua rede local:

Certifique-se de que o bind está configurado como "lan" (já está no nosso setup)
Acesse via: http://SEU_IP_LOCAL:18789/?token=SEU_TOKEN
Encontre seu IP local com: ip addr show ou ifconfig

⚠️ Segurança: Nunca exponha para a internet pública sem configurar HTTPS e autenticação forte!

4. Monitorar uso de créditos

Acompanhe seus gastos no OpenRouter:

Acesse https://openrouter.ai/dashboard
Veja estatísticas de uso
Configure alertas de limite de gastos

5. Integrar com outros serviços

O OpenClaw pode ser integrado com:

Ferramentas de automação
Scripts personalizados via API
Sistemas de documentação
Workflows de desenvolvimento

Recursos úteis

Documentação oficial do OpenClaw: https://docs.openclaw.ai
Comunidade no Discord: https://discord.gg/openclaw
OpenRouter Docs: https://openrouter.ai/docs
Repositório GitHub: https://github.com/openclaw/openclaw

Contribua com a comunidade

Se este guia foi útil para você:

⭐ Deixe uma estrela no repositório do OpenClaw
💬 Compartilhe sua experiência nos comentários
🐛 Reporte bugs ou melhorias
📝 Contribua com documentação

Suporte e ajuda

Se você encontrou algum problema não coberto neste guia:

Verifique a seção de Troubleshooting novamente
Consulte os logs detalhados com os comandos fornecidos
Procure na comunidade do OpenClaw
Abra uma issue no GitHub com detalhes completos

Perguntas Frequentes (FAQ)

O OpenRouter é realmente gratuito?

Sim, o OpenRouter oferece alguns modelos gratuitos, mas você também pode:

Adicionar créditos pagos (preços muito competitivos)
Usar modelos gratuitos disponíveis

Posso usar outros provedores além do OpenRouter?

Sim! O OpenClaw suporta diversos provedores. Você pode configurar APIs de:

OpenAI diretamente
Anthropic Claude
Google
E muitos outros

Meus dados estão seguros?

Com o OpenClaw rodando localmente via Docker:

✅ Suas conversas ficam no seu computador
✅ Você controla todos os dados
✅ Não há rastreamento de terceiros
⚠️ As requisições aos modelos vão para os provedores (OpenRouter, etc.)

Posso usar no Windows sem WSL2?

Tecnicamente sim, usando Docker Desktop para Windows, mas o WSL2 é altamente recomendado para melhor desempenho e compatibilidade.

O OpenClaw funciona em Raspberry Pi?

Depende da arquitetura. O OpenClaw precisa de imagens Docker compatíveis com ARM. Verifique a documentação oficial para suporte a ARM64.

Quanto de internet consome?

O consumo de dados depende do uso:

Requisições de texto: Poucos KB por mensagem
Requisições com imagens: Alguns MB dependendo do tamanho
Download inicial das imagens Docker: ~500MB-1GB (uma vez)

Posso ter múltiplas instâncias?

Sim, mas cada instância precisa usar portas diferentes. Edite o docker-compose.yml e mude a porta mapeada.

Changelog do guia

Versão 1.0.0 - Fevereiro de 2026

Guia completo inicial
Instalação no Ubuntu/WSL2
Resolução de erro de parse
Configuração de variáveis de ambiente
Troubleshooting completo

Agradecimentos

Obrigado por ler este guia até o fim! Espero que ele tenha sido útil para você configurar o OpenClaw com sucesso.

Se você teve alguma dificuldade ou tem sugestões de melhorias para este tutorial, por favor deixe um comentário ou entre em contato.

Boas conversas com IA! 🚀

Tags: openclaw, openrouter, api gratuita, docker, wsl2, ubuntu, instalação, tutorial, guia completo, erro de parse, configuração, ia, llm, claude, gpt-4, llama, inteligência artificial, self-hosted, open source, docker compose

Última atualização: Fevereiro de 2026

Como Usar Openclaw

Como Instalar OpenClaw no Windows: Guia Completo 2026