Docker

Docker é opcional. Use-o para um ambiente de Gateway isolado e descartável ou em um host sem instalações locais. Se você já desenvolve em sua própria máquina, use o fluxo de instalação normal.

O backend de sandbox padrão usa Docker quando agents.defaults.sandbox está habilitado, mas o sandboxing vem desativado por padrão e não exige que o próprio Gateway seja executado no Docker. Os backends de sandbox SSH e OpenShell também estão disponíveis; consulte Sandboxing.

Hospeda vários usuários? Consulte Hospedagem multilocatário para conhecer o modelo de uma célula por locatário.

Pré-requisitos

• Docker Desktop (ou Docker Engine) + Docker Compose v2
• Pelo menos 2 GB de RAM para compilar a imagem (pnpm install pode ser encerrado por OOM em hosts com 1 GB, com código de saída 137)
• Espaço em disco suficiente para imagens e logs
• Em um VPS/host público, consulte Reforço de segurança para exposição de rede, especialmente a cadeia 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

BUILD_GIT_COMMIT="$(git rev-parse HEAD)"BUILD_TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"docker build \  --build-arg "GIT_COMMIT=${BUILD_GIT_COMMIT}" \  --build-arg "OPENCLAW_BUILD_TIMESTAMP=${BUILD_TIMESTAMP}" \  -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

O contexto do Docker exclui .git. Passe a identidade do código-fonte como argumentos de compilação, conforme mostrado acima, para que a tela Sobre da imagem informe o commit obtido no checkout e um carimbo de data e hora da compilação. scripts/docker/setup.sh resolve e transmite os dois valores automaticamente.

Atualização de imagens de contêiner

Quando você substitui a imagem do OpenClaw, mas mantém o mesmo estado/configuração montado, o novo Gateway executa migrações de atualização seguras para a inicialização e a convergência de plugins antes de ficar pronto. Atualizações rotineiras da imagem não devem exigir uma execução separada de openclaw doctor --fix.

Se a inicialização não conseguir concluir esses reparos com segurança, o Gateway será encerrado em vez de ser informado como íntegro. Com uma política de reinicialização, Docker, Podman ou Kubernetes podem mostrar o contêiner do Gateway sendo reiniciado. Mantenha o volume de estado montado e, em seguida, execute a mesma imagem uma vez com openclaw doctor --fix como comando do contêiner, usando as mesmas montagens de estado/configuração utilizadas pelo Gateway:

docker run --rm -v <openclaw-state>:/home/node/.openclaw <image> openclaw doctor --fixpodman run --rm -v <openclaw-state>:/home/node/.openclaw <image> openclaw doctor --fix

Depois que o doctor terminar, reinicie o contêiner do Gateway com seu comando padrão. No Kubernetes, execute o mesmo comando em um Job avulso ou pod de depuração montado no mesmo PVC e, em seguida, reinicie o Deployment ou StatefulSet.

Variáveis de ambiente

Variáveis opcionais aceitas por scripts/docker/setup.sh (e, para o contêiner do Gateway, diretamente por docker-compose.yml):

A imagem oficial não inclui Homebrew. Durante a integração inicial, o OpenClaw oculta instaladores de dependências de Skills exclusivos do brew em um contêiner Linux sem brew; forneça essas dependências por meio de uma imagem personalizada ou instale-as manualmente. Use OPENCLAW_IMAGE_APT_PACKAGES para dependências empacotadas para Debian e OPENCLAW_IMAGE_PIP_PACKAGES para dependências Python (executa python3 -m pip install --break-system-packages durante a compilação; portanto, fixe as versões e use somente índices nos quais você confia).

Se o Docker informar ResourceExhausted, cannot allocate memory ou for interrompido durante tsdown, aumente o limite de memória do compilador do Docker ou tente novamente com heaps explícitos menores:

OPENCLAW_DOCKER_BUILD_NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB=4096

Imagens compiladas a partir do código-fonte com plugins selecionados

OPENCLAW_EXTENSIONS seleciona ids de manifestos de plugins no checkout do código-fonte; nomes de diretórios de origem existentes também são aceitos quando são diferentes. A compilação do Docker resolve a seleção para diretórios de origem uma única vez, instala dependências de produção e, quando um plugin selecionado é publicado separadamente com openclaw.build.bundledDist: false, compila seu runtime na distribuição agrupada raiz. Esse empacotamento exclusivo do Docker não altera o contrato do artefato npm ou ClawHub do plugin. IDs desconhecidos, inválidos ou ambíguos fazem a compilação da imagem falhar. IDs conhecidos somente de dependência/código-fonte mantêm seu preparo existente de código-fonte e dependências sem ganhar uma entrada compilada na distribuição raiz. Um plugin selecionado com entradas de compilação unificadas deve ser compilado com sucesso; o código-fonte e a saída de runtime de plugins externos não selecionados são removidos.

Por exemplo, estes comandos compilam imagens de Gateway autônomas, separadas e multiarquitetura da FakeCo para ClickClack, Slack e Microsoft Teams. O ClawRouter já faz parte do runtime raiz do OpenClaw, portanto a imagem do ClickClack seleciona somente clickclack. O argumento de navegador explicitamente vazio mantém a imagem padrão sem Chromium:

SOURCE_SHA="$(git rev-parse HEAD)"BUILD_TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"REGISTRY="registry.example.com/fakeco" build_gateway_image() {  gateway="$1"  selected_plugin="$2"  docker buildx build \    --platform linux/amd64,linux/arm64 \    --build-arg "GIT_COMMIT=${SOURCE_SHA}" \    --build-arg "OPENCLAW_BUILD_TIMESTAMP=${BUILD_TIMESTAMP}" \    --build-arg "OPENCLAW_EXTENSIONS=${selected_plugin}" \    --build-arg OPENCLAW_INSTALL_BROWSER= \    --provenance=mode=max \    --sbom=true \    --tag "${REGISTRY}/openclaw-${gateway}:${SOURCE_SHA}" \    --push \    .} build_gateway_image clickclack clickclackbuild_gateway_image slack slackbuild_gateway_image teams msteams

Use --platform linux/arm64 --load ou --platform linux/amd64 --load para uma única compilação local nativa. A saída multiplataforma e o SBOM/proveniência anexados exigem um registro ou outra saída do Buildx que preserve atestações. Após o envio, inspecione o manifesto e implante o digest imutável em vez da tag mutável do SHA do código-fonte:

docker buildx imagetools inspect \  "${REGISTRY}/openclaw-clickclack:${SOURCE_SHA}"# Implantar: registry.example.com/fakeco/openclaw-clickclack@sha256:<manifest-digest>

Essas imagens destinam-se a gateways autônomos baseados em OCI e usuários genéricos do Docker. Gateways gerenciados pelo Crabhelm não as consomem: esse caminho de entrega compila um arquivo de appliance x86_64 separado contendo um tarball npm do OpenClaw e fixa os digests do Node, do arquivo e do manifesto. Compile esse appliance independentemente a partir do mesmo código-fonte integrado do OpenClaw.

Para testar o código-fonte de um plugin agrupado em uma imagem empacotada, monte um diretório de código-fonte do 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. Isso substitui o pacote compilado correspondente em /app/dist/extensions/synology-chat para o mesmo id de plugin.

Observabilidade

A exportação do OpenTelemetry é feita de saída do contêiner do Gateway para seu coletor OTLP; ela não precisa de uma porta Docker publicada. Para incluir o exportador agrupado em uma imagem compilada localmente:

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

As imagens oficiais pré-compiladas já incluem diagnostics-otel; instale clawhub:@openclaw/diagnostics-otel por conta própria somente se você o tiver removido. Para habilitar a exportação, permita e habilite o plugin diagnostics-otel na configuração e defina diagnostics.otel.enabled=true (consulte o exemplo completo em Exportação do OpenTelemetry). Os 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.

As métricas do Prometheus reutilizam a porta do Gateway já publicada. Instale clawhub:@openclaw/diagnostics-prometheus, habilite o plugin diagnostics-prometheus e faça a coleta em:

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 do Prometheus.

Verificações de integridade

Endpoints de sondagem do contêiner (sem exigência de autenticação):

curl -fsS http://127.0.0.1:18789/healthz   # atividadecurl -fsS http://127.0.0.1:18789/readyz     # prontidão

O HEALTHCHECK integrado da imagem consulta /healthz; falhas repetidas marcam o contêiner como unhealthy para que os orquestradores possam reiniciá-lo ou substituí-lo.

Instantâneo detalhado e autenticado da integridade:

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

LAN versus loopback

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

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

Provedores locais do host

Dentro do contêiner, 127.0.0.1 é o próprio contêiner, não o host. Use host.docker.internal para provedores em execução no host:

A configuração agrupada usa essas URLs como padrões de integração inicial do LM Studio/Ollama, e docker-compose.yml mapeia host.docker.internal para o Gateway do host no Docker Engine para Linux (o Docker Desktop fornece o mesmo alias no macOS/Windows). Os serviços do host devem escutar em um endereço que o Docker consiga acessar:

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

Está usando seu próprio arquivo do Compose ou docker run? Adicione o mesmo mapeamento por conta própria, por exemplo, --add-host=host.docker.internal:host-gateway.

Backend da CLI do Claude no Docker

A imagem oficial não pré-instala o Claude Code. Instale-o e faça login dentro do usuário node do contêiner e, em seguida, persista o diretório pessoal desse contêiner para que atualizações da imagem não apaguem o binário nem o estado de autenticação.

Para uma nova instalação, 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 existente, interrompa a pilha e recarregue primeiro os valores atuais de .env — o script de configuração sempre reescreve .env usando o shell e os padrões atuais; ele não lê o arquivo por conta própria:

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

Se .env contiver valores que seu shell não consegue carregar, reexporte primeiro e manualmente aquilo de que você depende (OPENCLAW_IMAGE, portas, modo de vinculação, caminhos personalizados, OPENCLAW_EXTRA_MOUNTS, sandbox, ignorar integração inicial). A sobreposição gerada monta o volume do diretório pessoal para openclaw-gateway e openclaw-cli; execute os comandos restantes com essa sobreposição (e docker-compose.override.yml primeiro, caso você use um):

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 claude em /home/node/.local/bin/claude. Direcione o OpenClaw para esse caminho:

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 usando o mesmo diretório pessoal 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

Em seguida, use o backend claude-cli agrupado:

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 "Diga olá a partir da CLI do Claude no Docker"

OPENCLAW_HOME_VOLUME persiste a instalação nativa em /home/node/.local/bin e /home/node/.local/share/claude, além das configurações/autenticação do Claude Code em /home/node/.claude e /home/node/.claude.json. Persistir somente /home/node/.openclaw não é suficiente; se você usar OPENCLAW_EXTRA_MOUNTS em vez de um volume de diretório pessoal, monte todos esses caminhos do Claude nos dois serviços.

Bonjour / mDNS

A rede de ponte do Docker normalmente não encaminha multicast Bonjour/mDNS (224.0.0.251:5353) de forma confiável. Quando OPENCLAW_DISABLE_BONJOUR não está definido, o plugin Bonjour agrupado desabilita automaticamente a divulgação na LAN assim que detecta que está sendo executado em um contêiner, evitando entrar em um ciclo de falhas ao tentar novamente o multicast descartado pela ponte. Defina OPENCLAW_DISABLE_BONJOUR=1 para forçar a desativação independentemente da detecção ou 0 para forçar a ativação (somente em rede de host, macvlan ou outra rede na qual se saiba que o multicast mDNS funciona).

Caso contrário, use a URL publicada do Gateway, o Tailscale ou DNS-SD de longa distância para hosts Docker. Consulte Descoberta Bonjour para ver ressalvas e solução de problemas.

Armazenamento e persistência

O Docker Compose monta por vinculação 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 uma variável não está definida, docker-compose.yml usa um caminho alternativo em ${HOME}, ou /tmp se o próprio HOME estiver ausente, de modo que docker compose up nunca emita uma especificação de volume com origem vazia em ambientes básicos.

Esse diretório de configuração montado conté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 provenientes do ambiente, como OPENCLAW_GATEWAY_TOKEN

O diretório de segredos dos perfis de autenticação armazena a chave de criptografia local para o material de token dos perfis de autenticação baseados em OAuth. Mantenha-o com o estado do host Docker, mas separado de OPENCLAW_CONFIG_DIR.

Plugins baixáveis instalados armazenam o estado dos pacotes no diretório pessoal montado do OpenClaw, portanto os registros de instalação e as raízes dos pacotes sobrevivem à substituição do contêiner; a inicialização do Gateway não regenera as árvores de dependências de plugins agrupados.

Para obter detalhes completos sobre persistência de VM, consulte Runtime de VM do Docker — o que persiste onde.

Pontos críticos de crescimento do disco: media/, bancos de dados SQLite por agente, transcrições JSONL de sessões legadas, banco de dados de estado SQLite compartilhado, raízes de pacotes de plugins instalados e logs rotativos de arquivos em /tmp/openclaw/.

Auxiliares de shell (opcional)

Para comandos cotidianos mais curtos, instale o 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 pelo caminho antigo scripts/shell-helpers/clawdock-helpers.sh, execute novamente o comando acima para que seu auxiliar local acompanhe o local atual. Em seguida, use clawdock-start, clawdock-stop, clawdock-dashboard etc. (execute clawdock-help para ver a lista completa).

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"]

Executando em um VPS?

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

Sandbox do agente

Quando agents.defaults.sandbox está ativado com o backend Docker, o Gateway executa as ferramentas do agente (shell, leitura/gravação de arquivos etc.) dentro de contêineres Docker isolados, enquanto o próprio Gateway permanece no host — uma barreira rígida em torno de sessões de agente não confiáveis ou multilocatário, sem colocar todo o Gateway em um contêiner.

O escopo do sandbox pode ser por agente (padrão), por sessão ou compartilhado; cada escopo recebe seu próprio espaço de trabalho 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 ver a configuração completa, as imagens, as observações de segurança e os perfis de múltiplos agentes:

• Sandbox -- referência completa do sandbox
• OpenShell -- acesso interativo ao shell dos contêineres de sandbox
• Sandbox e ferramentas para múltiplos agentes -- substituições por agente

Ativação rápida

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

Compile a imagem padrão do 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 Sandbox § Imagens e configuração para obter comandos docker build embutidos.

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 ao Docker
• ClawDock — configuração comunitária do Docker Compose
• Atualização — como manter o OpenClaw atualizado
• Configuração — configuração do Gateway após a instalação