---
title: "Como Instalar OpenClaw no Docker: Guia Completo 2026"
url: "https://openclaw.ia.br/tutoriais/docker/"
markdown_url: "https://openclaw.ia.br/tutoriais/docker.MD"
description: "Tutorial passo a passo para rodar OpenClaw em container Docker. Inclui docker-compose, variáveis de ambiente, volumes persistentes e troubleshooting."
date: "2026-02-01"
author: "OpenClaw Brasil"
---

# Como Instalar OpenClaw no Docker: Guia Completo 2026

Tutorial passo a passo para rodar OpenClaw em container Docker. Inclui docker-compose, variáveis de ambiente, volumes persistentes e troubleshooting.


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

```bash
# 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:

```bash
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:

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

## Passo 1: Arquivo docker-compose.yml

Crie o arquivo `docker-compose.yml`:

```yaml
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:

```bash
# .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`:

```bash
echo ".env" >> .gitignore
```

## Passo 3: Configuração do OpenClaw

Crie `config/openclaw.json`:

```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:

```json
{
  "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:**
```markdown
# AGENTS.md

Este é o workspace do OpenClaw rodando em Docker.

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

**workspace/SOUL.md:**
```markdown
# 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:

```bash
# 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

```bash
# 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:

```bash
# Entrar no container
docker compose exec openclaw bash

# Dentro do container, rode:
openclaw whatsapp link

# Escaneie o QR code com seu WhatsApp
```

### Telegram

Primeiro, crie um bot no [@BotFather](https://t.me/BotFather) e pegue o token.

Adicione ao `openclaw.json`:

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

Adicione ao `.env`:
```bash
TELEGRAM_BOT_TOKEN=123456789:ABC...
```

Reinicie:
```bash
docker compose restart
```

### Discord

Similar ao Telegram, adicione:

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

## Gerenciamento do Container

### Comandos Úteis

```bash
# 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:

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# Parar container
docker compose down

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

# Subir novamente
docker compose up -d
```

## Troubleshooting

### Container não inicia

```bash
# 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:
```yaml
ports:
  - "3001:3000"
```

### Erro de permissão nos volumes

```bash
# 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:

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

### Container reiniciando constantemente

Verifique os logs:
```bash
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:

```bash
ls -la data/state/
```

## Configuração Avançada

### Usando Rede Docker Específica

```yaml
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:

```yaml
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:

```yaml
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](/tutoriais/primeiro-bot/)
- Personalize seu [SOUL.md](/tutoriais/personalizar-soul/)
- Configure a [memória persistente](/tutoriais/configurar-memoria/)

---

*Teve problemas? Entre no [Discord da comunidade](https://discord.com/invite/clawd) para suporte.*