Como Instalar OpenClaw no Docker: Guia Completo 2026

Quer rodar o OpenClaw em um ambiente isolado, reproduzível e fácil de gerenciar? Docker é a resposta. Neste guia completo, vamos configurar o OpenClaw em container desde o zero, com todas as melhores práticas para produção.

Por Que Usar Docker para OpenClaw?

Antes de começar, entenda as vantagens:

Isolamento: Seu ambiente de IA fica separado do sistema host, sem conflitos de dependências.

Portabilidade: Funciona igual em qualquer máquina — desenvolvimento, homologação, produção.

Facilidade de backup: Volumes Docker são fáceis de exportar e restaurar.

Escalabilidade: Precisa de mais instâncias? Docker Compose ou Kubernetes facilitam.

Segurança: Container com privilégios mínimos, sem acesso direto ao sistema operacional.

Pré-requisitos

Antes de começar, você precisa ter instalado:

Docker Engine

# Ubuntu/Debian
sudo apt update
sudo apt install docker.io docker-compose-plugin

# Fedora/RHEL
sudo dnf install docker docker-compose-plugin

# macOS (com Homebrew)
brew install docker docker-compose

# Windows
# Baixe o Docker Desktop em https://docker.com/products/docker-desktop

Verifique a instalação:

docker --version
# Docker version 24.x.x ou superior

docker compose version
# Docker Compose version v2.x.x

Chaves de API

O OpenClaw precisa de pelo menos uma chave de API de provedor de LLM:

Anthropic: https://console.anthropic.com (recomendado para Claude)
OpenAI: https://platform.openai.com
OpenRouter: https://openrouter.ai (acesso a múltiplos modelos)
Google AI: https://makersuite.google.com (para Gemini)

Guarde suas chaves em local seguro — vamos usá-las em breve.

Estrutura do Projeto

Vamos criar uma estrutura organizada:

openclaw-docker/
├── docker-compose.yml      # Configuração dos containers
├── .env                    # Variáveis de ambiente (secretas)
├── config/
│   └── openclaw.json       # Configuração do OpenClaw
├── data/
│   └── state/              # Dados persistentes (memória, histórico)
└── workspace/              # Seu workspace de trabalho
    ├── AGENTS.md
    ├── SOUL.md
    └── memory/

Crie a estrutura:

mkdir -p openclaw-docker/{config,data/state,workspace/memory}
cd openclaw-docker

Passo 1: Arquivo docker-compose.yml

Crie o arquivo docker-compose.yml:

version: '3.8'

services:
  openclaw:
    image: node:22-slim
    container_name: openclaw-gateway
    restart: unless-stopped
    working_dir: /app/workspace
    
    # Comando para instalar e rodar OpenClaw
    command: >
      sh -c "
        npm install -g openclaw@latest &&
        openclaw gateway start --foreground
      "
    
    # Variáveis de ambiente do arquivo .env
    env_file:
      - .env
    
    # Variáveis adicionais
    environment:
      - NODE_ENV=production
      - OPENCLAW_STATE_DIR=/app/state
      - OPENCLAW_CONFIG=/app/config/openclaw.json
    
    # Volumes persistentes
    volumes:
      # Configuração do OpenClaw
      - ./config:/app/config:ro
      # Dados persistentes (memória, histórico, etc)
      - ./data/state:/app/state
      # Seu workspace de trabalho
      - ./workspace:/app/workspace
    
    # Healthcheck para monitoramento (node:slim não tem curl/wget)
    healthcheck:
      test: ["CMD-SHELL", "node -e \"const http = require('http'); http.get('http://localhost:3000/health', r => process.exit(r.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))\""]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s
    
    # Limites de recursos (ajuste conforme necessidade)
    deploy:
      resources:
        limits:
          memory: 2G
        reservations:
          memory: 512M

Explicação dos Componentes

image: node:22-slim — Imagem base leve do Node.js 22. OpenClaw é uma aplicação Node.js.

restart: unless-stopped — Reinicia automaticamente se cair, mas respeita stops manuais.

volumes — Três mapeamentos importantes:

/app/config — Configurações (somente leitura)
/app/state — Dados persistentes (histórico, credenciais)
/app/workspace — Seu workspace de trabalho

healthcheck — Verifica se o gateway está respondendo.

deploy.resources — Limita uso de memória para evitar problemas.

Passo 2: Variáveis de Ambiente (.env)

Crie o arquivo .env com suas chaves de API:

# .env - NUNCA COMMITE ESTE ARQUIVO!

# Provedor principal (escolha um)
ANTHROPIC_API_KEY=sk-ant-...
# ou
OPENAI_API_KEY=sk-...
# ou
OPENROUTER_API_KEY=sk-or-...

# Opcional: Brave Search para busca web
BRAVE_API_KEY=BSA...

# Configurações do Gateway
OPENCLAW_LOG_LEVEL=info
OPENCLAW_HOST=0.0.0.0
OPENCLAW_PORT=3000

Importante: Adicione .env ao seu .gitignore:

echo ".env" >> .gitignore

Passo 3: Configuração do OpenClaw

Crie config/openclaw.json:

{
  "models": {
    "default": "anthropic/claude-sonnet-4-20250514",
    "providers": {
      "anthropic": {
        "apiKey": "${ANTHROPIC_API_KEY}"
      }
    }
  },
  "gateway": {
    "host": "0.0.0.0",
    "port": 3000
  },
  "workspace": {
    "path": "/app/workspace"
  },
  "memory": {
    "enabled": true,
    "path": "/app/state/memory"
  },
  "logging": {
    "level": "info",
    "file": "/app/state/logs/gateway.log"
  }
}

Configuração Multi-Provedor

Para usar múltiplos provedores:

{
  "models": {
    "default": "anthropic/claude-sonnet-4-20250514",
    "providers": {
      "anthropic": {
        "apiKey": "${ANTHROPIC_API_KEY}"
      },
      "openai": {
        "apiKey": "${OPENAI_API_KEY}"
      },
      "openrouter": {
        "apiKey": "${OPENROUTER_API_KEY}"
      }
    },
    "aliases": {
      "sonnet": "anthropic/claude-sonnet-4-20250514",
      "opus": "anthropic/claude-opus-4-5",
      "gpt4": "openai/gpt-4-turbo"
    }
  }
}

Passo 4: Configurar Workspace

Crie os arquivos básicos do workspace:

workspace/AGENTS.md:

# AGENTS.md

Este é o workspace do OpenClaw rodando em Docker.

## Regras
- Mantenha logs em memory/
- Use paths relativos dentro do workspace

workspace/SOUL.md:

# SOUL.md

Você é um assistente útil rodando em ambiente containerizado.

## Comportamento
- Seja conciso e direto
- Foque em resolver problemas
- Sempre informe quando precisar de acesso externo

Passo 5: Iniciar o Container

Agora vamos rodar:

# Subir em modo detached (background)
docker compose up -d

# Ver logs em tempo real
docker compose logs -f

# Verificar status
docker compose ps

A primeira execução pode demorar alguns minutos enquanto o npm instala o OpenClaw.

Verificar se Está Funcionando

# Verificar health
curl http://localhost:3000/health

# Ver logs do gateway
docker compose logs openclaw

Passo 6: Conectar Canais

WhatsApp via Terminal

Acesse o container para conectar WhatsApp:

# Entrar no container
docker compose exec openclaw bash

# Dentro do container, rode:
openclaw whatsapp link

# Escaneie o QR code com seu WhatsApp

Primeiro, crie um bot no @BotFather e pegue o token.

Adicione ao openclaw.json:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "${TELEGRAM_BOT_TOKEN}"
    }
  }
}

Adicione ao .env:

TELEGRAM_BOT_TOKEN=123456789:ABC...

Reinicie:

docker compose restart

Discord

Similar ao Telegram, adicione:

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "${DISCORD_BOT_TOKEN}"
    }
  }
}

Gerenciamento do Container

Comandos Úteis

# Parar o container
docker compose stop

# Iniciar novamente
docker compose start

# Reiniciar (aplica mudanças de config)
docker compose restart

# Ver uso de recursos
docker stats openclaw-gateway

# Entrar no container para debug
docker compose exec openclaw bash

# Ver logs das últimas 100 linhas
docker compose logs --tail=100

Atualizar OpenClaw

Para atualizar para a versão mais recente:

# Parar o container
docker compose down

# Forçar rebuild com nova imagem
docker compose build --no-cache

# Subir novamente
docker compose up -d

Ou, para atualização in-place:

# Entrar no container
docker compose exec openclaw bash

# Atualizar
npm update -g openclaw

# Sair e reiniciar
exit
docker compose restart

Backup e Restauração

Fazer Backup

# Backup dos dados persistentes
tar -czvf openclaw-backup-$(date +%Y%m%d).tar.gz \
  data/ workspace/ config/

# Ou apenas o estado (memória, histórico)
tar -czvf openclaw-state-$(date +%Y%m%d).tar.gz data/

Restaurar Backup

# Parar container
docker compose down

# Restaurar
tar -xzvf openclaw-backup-20260201.tar.gz

# Subir novamente
docker compose up -d

Troubleshooting

Container não inicia

# Ver logs de erro
docker compose logs --tail=50

# Verificar se a porta está em uso
lsof -i :3000

Problema comum: Porta 3000 já em uso. Mude a porta no docker-compose.yml:

ports:
  - "3001:3000"

Erro de permissão nos volumes

# Dar permissão ao usuário do container (node, UID 1000)
sudo chown -R 1000:1000 data/ workspace/

OpenClaw não encontra chaves de API

Verifique se o arquivo .env existe e tem as chaves:

# Verificar variáveis carregadas
docker compose exec openclaw env | grep API_KEY

Container reiniciando constantemente

Verifique os logs:

docker compose logs -f openclaw

Causas comuns:

Memória insuficiente (aumente o limite)
Chave de API inválida
Configuração JSON malformada

WhatsApp desconecta frequentemente

O estado do WhatsApp é salvo em /app/state. Verifique se o volume está persistindo:

ls -la data/state/

Configuração Avançada

Usando Rede Docker Específica

version: '3.8'

services:
  openclaw:
    # ... configurações anteriores ...
    networks:
      - openclaw-net

networks:
  openclaw-net:
    driver: bridge

Proxy Reverso com Nginx

Se quiser expor via HTTPS:

services:
  openclaw:
    # ... remova a seção ports ...
    expose:
      - "3000"
    networks:
      - internal

  nginx:
    image: nginx:alpine
    ports:
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./certs:/etc/nginx/certs:ro
    networks:
      - internal
      - external

networks:
  internal:
    internal: true
  external:

Múltiplas Instâncias

Para rodar múltiplos agentes:

services:
  openclaw-main:
    # ... configuração principal ...
    environment:
      - OPENCLAW_CONFIG=/app/config/main.json

  openclaw-worker:
    # ... mesma configuração base ...
    environment:
      - OPENCLAW_CONFIG=/app/config/worker.json

Checklist de Produção

Antes de ir para produção, verifique:

.env não está no controle de versão
Volumes persistentes configurados
Backups automatizados configurados
Limites de memória definidos
Healthcheck funcionando
Logs sendo coletados
Monitoramento de recursos ativo
Restart policy configurada
Chaves de API válidas e com billing ativo
Firewall configurado (se exposto externamente)

Conclusão

Rodar OpenClaw em Docker oferece uma experiência de deployment consistente e gerenciável. Com os volumes corretos, você tem persistência de dados. Com o docker-compose, você tem facilidade de gerenciamento.

Os principais benefícios:

Isolamento — Sem conflitos de dependências
Portabilidade — Funciona igual em qualquer lugar
Facilidade — Um comando para subir tudo
Segurança — Container com privilégios mínimos

Próximos passos sugeridos:

Configure canais de comunicação
Personalize seu SOUL.md
Configure a memória persistente

Teve problemas? Entre no Discord da comunidade para suporte.