Rodando OpenClaw no Docker: Um Guia de Implantação Passo a Passo

Por Que Docker?

Rodar o OpenClaw no Docker oferece três vantagens principais sobre uma instalação direta no sistema:

1. 1.Isolamento de segurança: O agente roda dentro de um container com acesso limitado ao seu sistema host. Se uma skill maliciosa ou injeção de prompt tentar acessar seus arquivos, o limite do container reduz o raio de explosão.
2. 2.Reprodutibilidade: A mesma imagem Docker roda de forma idêntica em qualquer máquina — seu laptop, um VPS ou um Raspberry Pi.
3. 3.Limpeza fácil: Quer começar do zero? Remova o container e suba um novo. Sem arquivos residuais, sem instalações quebradas de Node.js.

Pré-requisitos

• •Docker Desktop (macOS/Windows) ou Docker Engine (Linux)
• •Docker Compose v2 (incluído no Docker Desktop)
• •Pelo menos 2 GB de RAM disponíveis para o container
• •Uma chave de API de IA (Anthropic, OpenAI ou outro provedor suportado)

Início Rápido

Opção A: Docker Compose Oficial (Recomendado)

Clone o repositório do OpenClaw e use a configuração Docker integrada:

git clone https://github.com/openclaw/openclaw.git
cd openclaw

Execute o script de configuração, que cria os diretórios e configuração necessários:

bash docker-setup.sh

• •~/.openclaw/ — configuração, SOUL.md, chaves de API
• •~/openclaw/workspace/ — arquivos acessíveis ao agente

Execute o assistente de onboarding dentro do container:

docker compose run --rm openclaw-cli onboard

Siga os prompts para configurar sua chave de API e conectar uma plataforma de chat. Então inicie o gateway:

docker compose up -d openclaw-gateway

Seu agente agora está rodando em segundo plano.

Opção B: Imagem Pré-construída

Se você não quer clonar o repositório, use a imagem oficial pré-construída:

docker run -d \
  --name openclaw \
  --restart unless-stopped \
  -v ~/.openclaw:/root/.openclaw \
  -v ~/openclaw/workspace:/root/workspace \
  -p 3000:3000 \
  ghcr.io/openclaw/openclaw:latest

Referência do Docker Compose

Aqui está um docker-compose.yml anotado para uso em produção:

version: "3.8"
services:
  openclaw-gateway:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "3000:3000"        # Interface Web
    volumes:
      - ~/.openclaw:/root/.openclaw          # Configuração e dados
      - ~/openclaw/workspace:/root/workspace  # Workspace do agente
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - TZ=Asia/Shanghai     # Defina seu fuso horário
    mem_limit: 2g            # Previne uso excessivo de memória
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Crie um arquivo .env no mesmo diretório com suas chaves de API:

ANTHROPIC_API_KEY=sk-ant-xxxxx
OPENAI_API_KEY=sk-xxxxx

Variáveis de Ambiente

*Pelo menos uma chave de provedor de IA é necessária.

Gerenciando Seu Container

# Ver logs
docker logs -f openclaw

# Parar o agente
docker compose stop

# Iniciar o agente
docker compose up -d

# Reiniciar após mudanças na configuração
docker compose restart

# Atualizar para a última versão
docker compose pull
docker compose up -d

# Entrar no shell do container
docker exec -it openclaw bash

# Executar comandos CLI dentro do container
docker exec openclaw openclaw skill list
docker exec openclaw openclaw status

Hardening de Segurança

Limitar acesso ao sistema de arquivos

Monte apenas os diretórios que seu agente realmente precisa. Evite montar todo o seu diretório home:

volumes:
  - ~/.openclaw:/root/.openclaw:rw     # Configuração (leitura-escrita)
  - ~/documents:/root/docs:ro           # Documentos (somente leitura)

Isolamento de rede

Se seu agente não precisa acessar serviços da rede local, restrinja sua rede:

networks:
  openclaw-net:
    driver: bridge
    internal: false    # Defina como true para bloquear todo acesso externo

Sistema de arquivos raiz somente leitura

Para máxima segurança, torne o sistema de arquivos raiz somente leitura e permita escrita apenas em caminhos específicos:

read_only: true
tmpfs:
  - /tmp
  - /run

Atualizando

O OpenClaw lança versões frequentemente. Para atualizar sua implantação Docker:

docker compose pull           # Baixar a imagem mais recente
docker compose up -d          # Recriar container com a nova imagem
docker image prune -f         # Limpar imagens antigas

Sua configuração e dados persistem nos volumes montados, então as atualizações não são destrutivas.

Resolução de Problemas

Container crasha imediatamente: Verifique os logs com docker logs openclaw. Causas comuns: chaves de API faltando, memória insuficiente ou conflitos de porta.

QR code do WhatsApp não aparece: Execute o onboarding em modo interativo: docker compose run --rm openclaw-cli onboard. O QR code precisa de um terminal que suporte renderização.

Erros de permissão nos volumes montados: Certifique-se de que os diretórios do host existem e pertencem ao seu usuário: mkdir -p ~/.openclaw ~/openclaw/workspace.

Uso alto de memória: Defina mem_limit: 2g no docker-compose.yml para prevenir que o container consuma RAM excessiva.

Para mais detalhes, veja a documentação oficial do Docker e o docker-compose.yml no repositório.