Docker

Docker é opcional. Use-o somente 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 quer apenas o ciclo de desenvolvimento mais rápido. Use o fluxo de instalação normal.
• Observação sobre sandboxing: o backend de sandbox padrão usa Docker quando o sandboxing está habilitado, mas o sandboxing fica desativado por padrão e não exige que o Gateway completo seja executado no Docker. Backends de sandbox SSH e OpenShell também estão disponíveis. Consulte Sandboxing.

# 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 falta de memória em hosts com 1 GB, com saída 137)
• Espaço em disco suficiente para imagens e logs
• Se estiver executando em um VPS/host público, revise Fortalecimento 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

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

# WhatsApp (QR)
docker compose run --rm openclaw-cli channels login

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

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

# Fluxo manual

Se você preferir executar cada etapa manualmente 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-daemon
docker 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:

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 seu caminho de código-fonte empacotado, 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 pacote compilado correspondente em /app/dist/extensions/synology-chat para o mesmo id de Plugin.

# Observabilidade

A exportação OpenTelemetry é de saída 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 a partir 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 faça o scrape:

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 não autenticado. 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   # liveness
curl -fsS http://127.0.0.1:18789/readyz     # readiness

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

Snapshot de integridade profunda autenticado:

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

# LAN versus loopback

scripts/docker/setup.sh usa OPENCLAW_GATEWAY_BIND=lan por padrão para que o acesso do host a http://127.0.0.1:18789 funcione com a publicação de porta 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 é executado 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 são executados no host:

A configuração Docker empacotada usa essas URLs do host como 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 Docker Engine no Linux. O Docker Desktop já fornece o mesmo nome de host no macOS e Windows.

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.0
OLLAMA_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 exemplo --add-host=host.docker.internal:host-gateway.

# Bonjour / mDNS

A rede bridge do Docker geralmente não encaminha multicast Bonjour/mDNS (224.0.0.251:5353) de forma confiável. Portanto, a configuração Compose empacotada usa OPENCLAW_DISABLE_BONJOUR=1 por padrão para que o Gateway não entre em ciclo de falhas ou reinicie repetidamente o anúncio quando a bridge descartar 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 multicast mDNS funciona.

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

# Armazenamento e persistência

O Docker Compose monta via bind OPENCLAW_CONFIG_DIR em /home/node/.openclaw e OPENCLAW_WORKSPACE_DIR em /home/node/.openclaw/workspace, então esses caminhos sobrevivem à substituição do contêiner. Quando uma das variáveis não está definida, o docker-compose.yml empacotado usa ${HOME}/.openclaw como fallback (e ${HOME}/.openclaw/workspace para a montagem do workspace), ou /tmp/.openclaw quando o próprio HOME também está 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 provedores armazenada
• .env para segredos de runtime baseados em env, como OPENCLAW_GATEWAY_TOKEN

Plugins baixáveis instalados armazenam o estado do pacote no diretório home montado do OpenClaw, então registros de instalação de Plugins e raízes de pacote sobrevivem à substituição do contêiner. A inicialização do Gateway não gera árvores de dependência de Plugins empacotados.

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

Pontos críticos de crescimento de disco: monitore media/, arquivos JSONL de sessão, cron/runs/*.jsonl, raízes de pacotes de plugins instalados e logs rotativos em arquivo em /tmp/openclaw/.

# Auxiliares de shell (opcional)

Para facilitar o gerenciamento diário do Docker, instale o ClawDock:

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

Se você instalou o ClawDock pelo caminho raw antigo scripts/shell-helpers/clawdock-helpers.sh, execute novamente o comando de instalação acima para que seu arquivo auxiliar local acompanhe o novo local.

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

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

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

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

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

FROM node:24-bookworm
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"
RUN corepack enable
WORKDIR /app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build
ENV NODE_ENV=production
CMD ["node","dist/index.js"]

# Executando em um VPS?

Consulte Hetzner (Docker VPS) e Docker VM Runtime 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 oferece uma barreira rígida em torno de sessões de agente não confiáveis ou multi-tenant sem colocar todo o Gateway em contêiner.

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/bloqueio de ferramentas, isolamento de rede, limites de recursos e contêineres de navegador.

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

• Sandboxing -- referência completa de sandbox
• OpenShell -- acesso interativo ao shell de contêineres de 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 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-open
docker compose run --rm openclaw-cli devices list
docker 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

# Relacionado

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