OpenClaw Docker: como instalar com Docker Compose em 2026

Resposta direta: para instalar o OpenClaw com Docker, clone o repositório oficial, defina OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest e execute ./scripts/docker/setup.sh. O script prepara os volumes, faz o onboarding, gera o token do Gateway e inicia o serviço com Docker Compose. Depois, abra http://127.0.0.1:18789/ e informe o token salvo no arquivo .env.

Docker é uma opção para quem quer isolar o Gateway, usar uma imagem reproduzível ou manter o OpenClaw em um servidor sem instalar o runtime diretamente no sistema. Ele não é obrigatório: para testar pela primeira vez no próprio computador, a instalação nativa do OpenClaw costuma ser mais simples. Para VPS, laboratório, CI e ambientes que já usam containers, Docker Compose oferece um caminho mais previsível.

Este guia segue o fluxo oficial atual: imagem publicada no GitHub Container Registry, script scripts/docker/setup.sh, porta 18789, estado persistente em /home/node/.openclaw e comandos executados pelo serviço openclaw-cli. Evite tutoriais antigos que usam imagens, portas ou caminhos diferentes sem explicar a versão.

Instalação rápida do OpenClaw no Docker

Se Docker e Git já estão instalados, este é o caminho curto:

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

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh

O setup solicita as credenciais do provedor de IA, cria um token para o Gateway, corrige permissões dos diretórios persistentes, executa o onboarding e sobe o container.

Quando terminar, abra:

http://127.0.0.1:18789/

Cole na interface o token gravado em .env. Para recuperar a URL autenticada pelo terminal, use:

docker compose run --rm openclaw-cli dashboard --no-open

Quando usar Docker — e quando não usar

Um detalhe importante: Gateway em Docker e sandbox Docker são coisas diferentes. Você pode executar o Gateway diretamente no host e usar containers apenas para isolar ferramentas. Também pode rodar o Gateway em container sem habilitar sandbox. Escolha cada camada pelo risco que precisa controlar.

Pré-requisitos

Você precisa de:

• Docker Desktop ou Docker Engine;
• Docker Compose v2, chamado com docker compose;
• Git para baixar o repositório oficial;
• espaço em disco para imagem, dados e logs;
• uma credencial de provedor, como Anthropic, OpenAI ou outro suportado, salvo apenas durante o onboarding;
• pelo menos 6 GB de RAM disponíveis se for construir a imagem localmente. Usar a imagem pré-construída reduz essa necessidade de build.

Confirme o ambiente:

docker --version
docker compose version
git --version

No Windows, use Docker Desktop com WSL2. No macOS, Docker Desktop é o caminho mais direto. Em Linux, instale Docker Engine e o plugin Compose pelos pacotes oficiais da sua distribuição.

Passo 1: baixe o repositório oficial

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

Execute os próximos comandos na raiz desse repositório. O arquivo docker-compose.yml e o script de setup trabalham juntos; copiar apenas um trecho de Compose de um tutorial antigo pode deixar de fora variáveis, volumes e ajustes de segurança atuais.

Passo 2: escolha a imagem oficial

A imagem principal é publicada no GitHub Container Registry:

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"

Também existe um espelho oficial no Docker Hub:

export OPENCLAW_IMAGE="openclaw/openclaw:latest"

Prefira uma dessas origens e evite mirrors não oficiais. Para produção, considere fixar uma tag de versão em vez de depender permanentemente de latest; assim, atualização e rollback ficam deliberados.

Se você quiser construir a imagem a partir do código que clonou, não defina OPENCLAW_IMAGE e execute o setup normalmente. O script cria a imagem local openclaw:local, mas o build exige mais memória e tempo.

Passo 3: execute o setup

./scripts/docker/setup.sh

O script oficial cuida de etapas que costumam causar erro em configurações manuais:

1. sincroniza as variáveis necessárias no .env;
2. prepara os diretórios persistentes;
3. corrige permissões para o usuário do container;
4. executa o onboarding;
5. gera a autenticação do Gateway;
6. sincroniza a configuração;
7. inicia o serviço openclaw-gateway pelo Compose.

Durante o onboarding, escolha o provedor de IA e informe a credencial quando solicitada. Não coloque tokens reais em docker-compose.yml, exemplos públicos, histórico do shell ou Git. O arquivo .env deve permanecer fora do controle de versão.

Passo 4: abra a Control UI

A porta padrão do Gateway no fluxo oficial é 18789:

http://127.0.0.1:18789/

A interface pedirá o token gerado pelo setup. Se você não o encontrou, rode:

docker compose run --rm openclaw-cli dashboard --no-open

Para confirmar que o container está ativo:

docker compose ps
docker compose logs --tail=100 openclaw-gateway

Também há endpoints de saúde úteis para monitoramento:

curl -fsS http://127.0.0.1:18789/healthz
curl -fsS http://127.0.0.1:18789/startupz
curl -fsS http://127.0.0.1:18789/readyz

• healthz verifica se o processo está vivo;
• startupz indica se concluiu a inicialização e pode receber tráfego;
• readyz faz uma verificação mais profunda, incluindo prontidão dos canais.

Passo 5: conecte WhatsApp, Telegram ou Discord

Use o container auxiliar openclaw-cli, que compartilha a rede do Gateway e evita depender de uma instalação local do comando OpenClaw.

WhatsApp

docker compose run --rm openclaw-cli channels login

Escaneie o QR code solicitado. A sessão precisa permanecer nos diretórios persistentes; não destrua os volumes ao recriar o container.

Telegram

docker compose run --rm openclaw-cli \
  channels add --channel telegram --token "<token>"

Crie o bot no @BotFather. Em servidores e automações, prefira referências por variável de ambiente em vez de deixar o token gravado em scripts. Veja também o guia de bot no Telegram.

Discord

docker compose run --rm openclaw-cli \
  channels add --channel discord --token "<token>"

Depois de conectar um canal, envie uma mensagem de teste e acompanhe os logs:

docker compose logs -f openclaw-gateway

Onde ficam os dados persistentes

O Compose oficial monta três áreas importantes:

No host, as origens são controladas principalmente por:

• OPENCLAW_CONFIG_DIR;
• OPENCLAW_WORKSPACE_DIR;
• OPENCLAW_AUTH_PROFILE_SECRET_DIR.

Se essas variáveis não forem definidas, o Compose usa caminhos sob $HOME. Não trate o container como armazenamento: containers podem ser substituídos; os dados importantes precisam estar nos bind mounts ou volumes.

Os maiores consumidores de disco tendem a ser arquivos em media/, bancos SQLite por agente, transcrições legadas, plugins instalados e logs. Monitore o crescimento:

docker system df
du -sh ~/.openclaw 2>/dev/null || true
docker compose logs --tail=200 openclaw-gateway

Não execute docker compose down -v sem entender quais volumes serão removidos.

Backup antes de atualizar

Pare brevemente o Gateway para obter uma cópia consistente dos diretórios montados:

docker compose stop openclaw-gateway

tar -czf "openclaw-backup-$(date +%Y%m%d-%H%M).tar.gz" \
  "${OPENCLAW_CONFIG_DIR:-$HOME/.openclaw}" \
  "${OPENCLAW_AUTH_PROFILE_SECRET_DIR:-$HOME/.openclaw-auth-profile-secrets}"

docker compose start openclaw-gateway

Ajuste os caminhos se você personalizou o .env. Proteja o arquivo de backup porque ele pode conter configuração, histórico e material de autenticação. Para uma estratégia mais completa, consulte o guia de backup do OpenClaw.

Como atualizar o OpenClaw no Docker

Se estiver usando imagem oficial, atualize o checkout e a imagem, depois recrie o serviço:

git pull --ff-only
docker compose pull
docker compose up -d openclaw-gateway

Quando você mantém os mesmos mounts, o Gateway novo executa migrações seguras de startup antes de ficar pronto. Valide depois da atualização:

docker compose ps
docker compose run --rm openclaw-cli doctor --json
curl -fsS http://127.0.0.1:18789/readyz

Se uma migração não puder ser concluída com segurança, o container pode reiniciar em loop. Preserve o estado e execute a mesma imagem uma vez com openclaw doctor --fix, usando os mesmos mounts. Não apague o diretório de estado como primeira tentativa. Veja o guia de atualização sem perder configuração antes de mudanças maiores.

Comandos Docker úteis

# Ver containers e health/status
docker compose ps

# Acompanhar logs
docker compose logs -f openclaw-gateway

# Últimas 200 linhas
docker compose logs --tail=200 openclaw-gateway

# Reiniciar o Gateway
docker compose restart openclaw-gateway

# Parar e iniciar sem remover dados
docker compose stop openclaw-gateway
docker compose start openclaw-gateway

# Rodar diagnóstico de leitura
docker compose run --rm openclaw-cli doctor --json

# Testar comunicação com o Gateway
docker compose run -T --rm openclaw-cli gateway probe

Segurança para VPS e produção

Não exponha a porta 18789 diretamente à internet sem revisar autenticação, firewall e modelo de confiança. O padrão local em 127.0.0.1 é apropriado para uso no próprio host. Para acesso remoto, prefira VPN, túnel SSH ou uma camada autenticada e restrita.

Checklist mínimo:

• use apenas imagens oficiais e, em produção, fixe uma versão;
• mantenha o token do Gateway e chaves de API fora do Git;
• restrinja a porta no firewall, inclusive na cadeia DOCKER-USER em hosts públicos;
• preserve no-new-privileges e as capacidades removidas no Compose oficial;
• não monte o socket Docker no container sem necessidade explícita;
• limite quem pode enviar mensagens aos canais conectados;
• revise ferramentas e skills antes de habilitá-las;
• faça backups criptografados e teste a restauração;
• monitore readyz, logs, disco e reinícios.

A imagem oficial e o Compose já aplicam algumas medidas, como remoção das capacidades NET_RAW e NET_ADMIN e no-new-privileges. Não desfaça esses controles apenas para contornar um erro sem investigar a causa. Leia o guia de segurança do OpenClaw antes de um deploy público.

Usar Ollama ou LM Studio no host

Quando o OpenClaw está em container e o modelo local roda no computador host, localhost dentro do container aponta para o próprio container — não para o host. O Compose oficial cria o alias host.docker.internal, inclusive no Docker Engine para Linux.

Configure o provedor local usando o host acessível pelo container, por exemplo:

http://host.docker.internal:11434

O serviço no host também precisa escutar em uma interface alcançável pela rede Docker. Faça isso apenas em rede confiável e aplique firewall. Para escolher modelo e requisitos de hardware, veja Ollama grátis com OpenClaw.

Troubleshooting: erros comuns

O container reinicia sem parar

Primeiro, veja o motivo real:

docker compose ps
docker compose logs --tail=200 openclaw-gateway

Procure falha de migração, permissão, configuração inválida, variável ausente ou falta de memória. Se ocorreu logo após atualização, rode o diagnóstico com o mesmo estado montado. O guia container Docker crashando traz uma sequência de investigação mais curta.

A porta 18789 já está em uso

ss -ltnp | grep 18789
# ou, no macOS:
lsof -i :18789

Pare o processo conflitante ou altere OPENCLAW_GATEWAY_PORT no .env, mantendo a porta interna do serviço em 18789.

A interface abre, mas pede token ou não conecta

Recupere um link atualizado e confira solicitações de dispositivo:

docker compose run --rm openclaw-cli dashboard --no-open
docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>

Confirme também que você está acessando a origem permitida e que o Gateway está em modo local com bind compatível.

Erro de permissão nos volumes

Não aplique chmod 777. Descubra primeiro o dono e o caminho montado:

docker compose config
docker compose run --rm --no-deps openclaw-cli id
ls -la "${OPENCLAW_CONFIG_DIR:-$HOME/.openclaw}"

Rode novamente ./scripts/docker/setup.sh, que inclui correções de permissão para o fluxo oficial. Em servidor, confirme se o diretório existe e se o usuário do container consegue escrever nele.

O Ollama não responde dentro do container

Teste pelo alias do host, não por localhost:

docker compose exec openclaw-gateway \
  node -e "fetch('http://host.docker.internal:11434/api/tags').then(r=>console.log(r.status)).catch(console.error)"

Se falhar, verifique se o Ollama aceita conexões fora do loopback e se o firewall permite tráfego da bridge Docker.

O disco encheu

docker system df
du -h -d 2 "${OPENCLAW_CONFIG_DIR:-$HOME/.openclaw}" | sort -h | tail

Faça backup antes de remover dados. Rotacione logs e revise mídia, sessões antigas e plugins. Não use docker system prune --volumes em um host de produção sem listar exatamente o que será apagado.

Perguntas frequentes sobre OpenClaw e Docker

Qual é a imagem Docker oficial do OpenClaw?

A imagem principal é ghcr.io/openclaw/openclaw:latest, publicada no GitHub Container Registry. O espelho oficial é openclaw/openclaw:latest no Docker Hub. Para produção, prefira uma tag de versão e evite imagens de terceiros.

Qual porta o OpenClaw usa no Docker?

O Gateway oficial usa a porta interna 18789, normalmente publicada na mesma porta do host. A Control UI fica em http://127.0.0.1:18789/. Tutoriais que usam 3000 podem se referir a configurações antigas ou personalizadas.

Docker Compose é obrigatório?

Não, mas é o caminho oficial recomendado para o Gateway containerizado porque coordena serviço, CLI auxiliar, rede, variáveis, volumes e controles de segurança. Um docker run isolado é mais fácil de copiar e mais fácil de deixar incompleto.

Posso usar OpenClaw Docker no Windows?

Sim. Instale Docker Desktop com WSL2, clone o repositório dentro do ambiente Linux e execute o setup. Evite misturar permissões e caminhos de arquivos entre PowerShell, Windows e WSL sem necessidade.

Docker deixa o OpenClaw totalmente seguro?

Não. Container reduz e organiza parte da superfície, mas não substitui autenticação, firewall, revisão de skills, controle de remetentes, política de dados e sandbox de ferramentas. Montar diretórios ou o socket Docker com permissões amplas pode anular boa parte do isolamento.

Como atualizar sem perder memória e configuração?

Mantenha os mesmos volumes ou bind mounts, faça backup, atualize a imagem e recrie o serviço com docker compose up -d. O estado persistente não deve ficar apenas na camada gravável do container. Depois, valide com doctor --json e readyz.

Dá para conectar WhatsApp no OpenClaw em Docker?

Sim. Rode docker compose run --rm openclaw-cli channels login, conclua o QR code e preserve os diretórios de estado. Se a sessão cair após recriar o container, revise os mounts e confirme que o estado não estava apenas dentro do container removido.

Docker é melhor que instalar via npm?

Para iniciantes no próprio computador, normalmente não. A instalação nativa é mais simples de depurar. Docker é melhor quando isolamento, portabilidade, servidor, automação de deploy ou versionamento da imagem justificam a camada extra.

Próximos passos

Depois que readyz responder com sucesso e a Control UI abrir:

1. conecte apenas um canal e envie uma mensagem de teste;
2. faça o primeiro backup dos diretórios persistentes;
3. revise o checklist de pós-instalação;
4. configure memória persistente;
5. antes de expor o serviço, aplique as boas práticas de produção.

Docker torna o ambiente reproduzível; a confiabilidade vem de combinar imagem oficial, estado persistente, atualização controlada, diagnóstico e segurança de rede.