Docker

Docker é opcional. Use-o apenas se você quiser um Gateway em contêiner ou validar o fluxo do Docker.

Docker é adequado para mim?

• Sim: você quer um ambiente de Gateway isolado e descartável ou executar o OpenClaw em um host sem instalações locais.
• Não: você está executando na sua própria máquina e só quer o ciclo de desenvolvimento mais rápido. Use o fluxo de instalação normal.
• Observação sobre sandbox: o backend de sandbox padrão usa Docker quando o sandbox está habilitado, mas o sandbox vem desativado por padrão e não exige que todo o Gateway seja executado no Docker. Backends de sandbox SSH e OpenShell também estão disponíveis. Consulte Sandbox.

Pré-requisitos

• Docker Desktop (ou Docker Engine) + Docker Compose v2
• Pelo menos 2 GB de RAM para a criação da imagem (pnpm install pode ser encerrado por OOM em hosts com 1 GB e saída 137)
• Espaço em disco suficiente para imagens e logs
• Se estiver executando em um VPS/host público, revise Endurecimento de segurança para exposição à rede, especialmente a política de firewall DOCKER-USER do Docker.

Gateway em contêiner

./scripts/docker/setup.sh

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

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

docker load -i openclaw-image.tarexport OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"./scripts/docker/setup.sh --offline

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

# WhatsApp (QR)docker compose run --rm openclaw-cli channels login # Telegramdocker compose run --rm openclaw-cli channels add --channel telegram --token "<token>" # Discorddocker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

Fluxo manual

Se você preferir executar cada etapa por conta própria em vez de usar o script de configuração:

docker build -t openclaw:local -f Dockerfile .docker compose run --rm --no-deps --entrypoint node openclaw-gateway \  dist/index.js onboard --mode local --no-install-daemondocker compose run --rm --no-deps --entrypoint node openclaw-gateway \  dist/index.js config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"},{"path":"gateway.controlUi.allowedOrigins","value":["http://localhost:18789","http://127.0.0.1:18789"]}]'docker compose up -d openclaw-gateway

Variáveis de ambiente

O script de configuração aceita estas variáveis de ambiente opcionais:

A imagem Docker oficial não inclui Homebrew. Durante o onboarding, o OpenClaw oculta instaladores de dependências de Skills exclusivos do brew quando está em execução em um contêiner Linux sem brew; essas dependências devem ser fornecidas por uma imagem personalizada ou instaladas manualmente. Para dependências disponíveis em pacotes Debian, use OPENCLAW_IMAGE_APT_PACKAGES durante o build da imagem. O nome legado OPENCLAW_DOCKER_APT_PACKAGES ainda é aceito. Para dependências Python, use OPENCLAW_IMAGE_PIP_PACKAGES. Isso executa python3 -m pip install --break-system-packages durante o build da imagem, então fixe as versões dos pacotes e use apenas índices de pacotes em que você confia. Builds a partir do código-fonte definem OPENCLAW_DOCKER_BUILD_NODE_OPTIONS como --max-old-space-size=8192 por padrão e deixam OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB indefinido para que o wrapper do tsdown possa respeitar os limites de memória do contêiner. Eles também definem OPENCLAW_DOCKER_BUILD_SKIP_DTS=1 por padrão porque imagens de runtime removem arquivos de declaração após o build. Se o Docker relatar ResourceExhausted, cannot allocate memory ou abortar durante tsdown, aumente o limite de memória do builder Docker ou tente novamente com heaps explícitos menores, por exemplo OPENCLAW_DOCKER_BUILD_NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB=4096.

Mantenedores podem testar o código-fonte de Plugins empacotados contra uma imagem empacotada montando um diretório de código-fonte de Plugin sobre o caminho do código-fonte empacotado dele, por exemplo OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. Esse diretório de código-fonte montado substitui o bundle compilado correspondente em /app/dist/extensions/synology-chat para o mesmo id de Plugin.

Observabilidade

A exportação OpenTelemetry sai do contêiner do Gateway para o seu coletor OTLP. Ela não exige uma porta Docker publicada. Se você criar a imagem localmente e quiser que o exportador OpenTelemetry empacotado esteja disponível dentro da imagem, inclua suas dependências de runtime:

export OPENCLAW_EXTENSIONS="diagnostics-otel"export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4318"export OTEL_SERVICE_NAME="openclaw-gateway"./scripts/docker/setup.sh

Instale o Plugin oficial @openclaw/diagnostics-otel do ClawHub em instalações Docker empacotadas antes de habilitar a exportação. Imagens personalizadas criadas a partir do código-fonte ainda podem incluir o código-fonte local do Plugin com OPENCLAW_EXTENSIONS=diagnostics-otel. Para habilitar a exportação, permita e habilite o Plugin diagnostics-otel na configuração e então defina diagnostics.otel.enabled=true ou use o exemplo de configuração em Exportação OpenTelemetry. Cabeçalhos de autenticação do coletor são configurados por meio de diagnostics.otel.headers, não por variáveis de ambiente do Docker.

Métricas Prometheus usam a porta do Gateway já publicada. Instale clawhub:@openclaw/diagnostics-prometheus, habilite o Plugin diagnostics-prometheus e então colete:

http://<gateway-host>:18789/api/diagnostics/prometheus

A rota é protegida pela autenticação do Gateway. Não exponha uma porta pública /metrics separada nem um caminho de proxy reverso sem autenticação. Consulte Métricas Prometheus.

Verificações de integridade

Endpoints de probe do contêiner (sem autenticação necessária):

curl -fsS http://127.0.0.1:18789/healthz   # livenesscurl -fsS http://127.0.0.1:18789/readyz     # readiness

A imagem Docker inclui um HEALTHCHECK integrado que faz ping em /healthz. Se as verificações continuarem falhando, o Docker marca o contêiner como unhealthy e os sistemas de orquestração podem reiniciá-lo ou substituí-lo.

Snapshot autenticado de integridade profunda:

docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

LAN vs loopback

scripts/docker/setup.sh define por padrão OPENCLAW_GATEWAY_BIND=lan para que o acesso do host a http://127.0.0.1:18789 funcione com a publicação de portas do Docker.

• lan (padrão): o navegador do host e a CLI do host conseguem acessar a porta publicada do gateway.
• loopback: somente processos dentro do namespace de rede do contêiner conseguem acessar o gateway diretamente.

Provedores locais do host

Quando o OpenClaw roda no Docker, 127.0.0.1 dentro do contêiner é o próprio contêiner, não sua máquina host. Use host.docker.internal para provedores de IA que rodam no host:

A configuração Docker incluída usa essas URLs de host como os padrões de onboarding do LM Studio e Ollama, e docker-compose.yml mapeia host.docker.internal para o gateway do host do Docker para o Docker Engine no Linux. O Docker Desktop já fornece o mesmo nome de host no macOS e Windows.

Os serviços do host também precisam escutar em um endereço acessível pelo Docker:

lms server start --port 1234 --bind 0.0.0.0OLLAMA_HOST=0.0.0.0:11434 ollama serve

Se você usar seu próprio arquivo Compose ou comando docker run, adicione o mesmo mapeamento de host por conta própria, por exemplo --add-host=host.docker.internal:host-gateway.

Backend Claude CLI no Docker

A imagem Docker oficial do OpenClaw não pré-instala o Claude Code. Instale e faça login no Claude Code dentro do usuário do contêiner que executa o OpenClaw, depois persista esse home do contêiner para que upgrades de imagem não apaguem o binário ou o estado de autenticação do Claude.

Para novas instalações Docker, habilite um volume persistente em /home/node antes de executar a configuração:

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

Para uma instalação Docker existente, pare a stack primeiro e recarregue os valores atuais do Docker .env antes de executar novamente a configuração. O script de configuração não lê .env por conta própria; ele reescreve .env a partir do shell atual e dos padrões. Para o .env gerado, execute:

set -a. ./.envset +aexport OPENCLAW_HOME_VOLUME="${OPENCLAW_HOME_VOLUME:-openclaw_home}"./scripts/docker/setup.sh

Se seu .env contiver valores que seu shell não consegue carregar com source, reexporte manualmente primeiro os valores existentes dos quais você depende, como OPENCLAW_IMAGE, portas, modo de vinculação, caminhos personalizados, OPENCLAW_EXTRA_MOUNTS, sandbox e configurações de pular onboarding. O overlay gerado monta o volume home para openclaw-gateway e openclaw-cli.

Execute os comandos restantes com o overlay Compose gerado para que ambos os serviços montem o home persistido. Se sua configuração também usar docker-compose.override.yml, inclua-o antes de docker-compose.extra.yml.

Instale o Claude Code nesse home persistido:

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint sh openclaw-cli -lc \  'curl -fsSL https://claude.ai/install.sh | bash'

O instalador nativo grava o binário claude em /home/node/.local/bin/claude. Diga ao OpenClaw para usar esse caminho do contêiner:

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli config set \  agents.defaults.cliBackends.claude-cli.command \  /home/node/.local/bin/claude

Faça login e verifique de dentro do mesmo home de contêiner persistido:

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint /home/node/.local/bin/claude openclaw-cli auth logindocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint /home/node/.local/bin/claude openclaw-cli auth status --textdocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli models auth login \  --provider anthropic --method cli --set-defaultdocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli models list --provider anthropic

Depois disso, você pode usar o backend claude-cli incluído:

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli agent \  --agent main \  --model claude-cli/claude-sonnet-4-6 \  --message "Say hello from Docker Claude CLI"

OPENCLAW_HOME_VOLUME persiste a instalação nativa do Claude Code em /home/node/.local/bin e /home/node/.local/share/claude, além das configurações e do estado de autenticação do Claude Code em /home/node/.claude e /home/node/.claude.json. Persistir apenas /home/node/.openclaw não é suficiente para reutilizar o Claude CLI. Se você usar OPENCLAW_EXTRA_MOUNTS em vez de um volume home, monte todos esses caminhos do Claude em ambos os serviços Docker.

Bonjour / mDNS

Redes bridge do Docker geralmente não encaminham multicast Bonjour/mDNS (224.0.0.251:5353) de forma confiável. Portanto, a configuração Compose incluída define por padrão OPENCLAW_DISABLE_BONJOUR=1 para que o Gateway não entre em crash-loop nem reinicie repetidamente a publicidade quando a bridge descartar o tráfego multicast.

Use a URL publicada do Gateway, Tailscale ou DNS-SD de área ampla para hosts Docker. Defina OPENCLAW_DISABLE_BONJOUR=0 somente ao executar com rede do host, macvlan ou outra rede em que se sabe que o multicast mDNS funciona.

Para pegadinhas e solução de problemas, consulte descoberta Bonjour.

Armazenamento e persistência

O Docker Compose monta por bind OPENCLAW_CONFIG_DIR em /home/node/.openclaw, OPENCLAW_WORKSPACE_DIR em /home/node/.openclaw/workspace e OPENCLAW_AUTH_PROFILE_SECRET_DIR em /home/node/.config/openclaw, para que esses caminhos sobrevivam à substituição do contêiner. Quando qualquer variável não estiver definida, o docker-compose.yml incluído recua para ${HOME}, ou /tmp quando o próprio HOME também estiver ausente. Isso impede que docker compose up emita uma especificação de volume com origem vazia em ambientes básicos.

Esse diretório de configuração montado é onde o OpenClaw mantém:

• openclaw.json para configuração de comportamento
• agents/<agentId>/agent/auth-profiles.json para autenticação OAuth/chave de API de provedor armazenada
• .env para segredos de runtime baseados em env, como OPENCLAW_GATEWAY_TOKEN

O diretório de chave secreta do perfil de autenticação armazena a chave de criptografia local usada para material de token de perfil de autenticação baseado em OAuth. Mantenha-o com o estado do seu host Docker, mas separado de OPENCLAW_CONFIG_DIR.

Plugins instalados por download armazenam seu estado de pacote no home montado do OpenClaw, então registros de instalação de plugins e raízes de pacotes sobrevivem à substituição do contêiner. A inicialização do Gateway não gera árvores de dependência de plugins incluídos.

Para detalhes completos de persistência em implantações de VM, consulte Runtime de VM Docker - O que persiste onde.

Pontos críticos de crescimento de disco: monitore media/, arquivos JSONL de sessão, o banco de dados de estado SQLite compartilhado, raízes de pacotes de plugins instalados e logs de arquivo rotativos em /tmp/openclaw/.

Auxiliares de shell (opcional)

Para facilitar o gerenciamento cotidiano do Docker, instale ClawDock:

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.shecho 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

Se você instalou o ClawDock a partir do caminho bruto mais antigo scripts/shell-helpers/clawdock-helpers.sh, execute novamente o comando de instalação acima para que seu arquivo auxiliar local acompanhe a nova localização.

Depois use clawdock-start, clawdock-stop, clawdock-dashboard etc. Execute clawdock-help para todos os comandos. Consulte ClawDock para o guia completo do auxiliar.

export OPENCLAW_SANDBOX=1./scripts/docker/setup.sh

export OPENCLAW_SANDBOX=1export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock./scripts/docker/setup.sh

docker compose run -T --rm openclaw-cli gateway probedocker compose run -T --rm openclaw-cli devices list --json

printf '%s\n' \  'services:' \  '  openclaw-cli:' \  '    cap_drop: !reset []' \  > docker-compose.cli-no-dropped-caps.local.yml docker compose -f docker-compose.yml -f docker-compose.cli-no-dropped-caps.local.yml run --rm openclaw-cli plugins install <package>

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

FROM node:24-bookwormRUN curl -fsSL https://bun.sh/install | bashENV PATH="/root/.bun/bin:${PATH}"RUN corepack enableWORKDIR /appCOPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./COPY ui/package.json ./ui/package.jsonCOPY scripts ./scriptsRUN pnpm install --frozen-lockfileCOPY . .RUN pnpm buildRUN pnpm ui:installRUN pnpm ui:buildENV NODE_ENV=productionCMD ["node","dist/index.js"]

Rodando em um VPS?

Consulte Hetzner (Docker VPS) e Runtime de VM Docker para etapas de implantação em VM compartilhada, incluindo inclusão de binários na imagem, persistência e atualizações.

Sandbox de agente

Quando agents.defaults.sandbox está habilitado com o backend Docker, o Gateway executa ferramentas de agente (shell, leitura/gravação de arquivos etc.) dentro de contêineres Docker isolados, enquanto o próprio Gateway permanece no host. Isso cria uma barreira rígida em torno de sessões de agente não confiáveis ou multi-tenant sem conteinerizar todo o Gateway.

O escopo do sandbox pode ser por agente (padrão), por sessão ou compartilhado. Cada escopo recebe seu próprio workspace montado em /workspace. Você também pode configurar políticas de permissão/negação de ferramentas, isolamento de rede, limites de recursos e contêineres de navegador.

Para configuração completa, imagens, observações de segurança e perfis multiagente, consulte:

• Sandboxing -- referência completa de sandbox
• OpenShell -- acesso a shell interativo em contêineres sandbox
• Sandbox e ferramentas multiagente -- substituições por agente

Habilitação rápida

{  agents: {    defaults: {      sandbox: {        mode: "non-main", // off | non-main | all        scope: "agent", // session | agent | shared      },    },  },}

Crie a imagem padrão de sandbox (a partir de um checkout do código-fonte):

scripts/sandbox-setup.sh

Para instalações via npm sem um checkout do código-fonte, consulte Sandboxing § Imagens e configuração para comandos docker build inline.

Solução de problemas

docker compose run --rm openclaw-cli dashboard --no-opendocker compose run --rm openclaw-cli devices listdocker compose run --rm openclaw-cli devices approve <requestId>

docker compose run --rm openclaw-cli config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]'docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789

Relacionados

• Visão geral da instalação — todos os métodos de instalação
• Podman — alternativa Podman ao Docker
• ClawDock — configuração comunitária com Docker Compose
• Atualização — como manter o OpenClaw atualizado
• Configuração — configuração do Gateway após a instalação