Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Docker é opcional. Use-o somente se você quiser um Gateway conteinerizado ou validar o fluxo do Docker.

​
O 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 loop 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 sandboxing está habilitado, mas sandboxing vem 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 build da imagem (pnpm install pode ser encerrado por OOM 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 Endurecimento de segurança para exposição de rede, especialmente a política de firewall DOCKER-USER do Docker.

​
Gateway conteinerizado

1

Faça build da imagem

A partir da raiz do repo, execute o script de configuração:
./scripts/docker/setup.sh
Isso cria a imagem do Gateway localmente. Para usar uma imagem pré-criada:
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh
Imagens pré-criadas são publicadas no GitHub Container Registry. Tags comuns: main, latest, <version> (por exemplo, 2026.2.26).
2

Conclua o onboarding

O script de configuração executa o onboarding automaticamente. Ele vai:
  • solicitar chaves de API de provedores
  • gerar um token do Gateway e gravá-lo em .env
  • criar o diretório de chave secreta de perfil de autenticação
  • iniciar o Gateway via Docker Compose
Durante a configuração, o onboarding antes da inicialização e as gravações de configuração passam diretamente por openclaw-gateway. openclaw-cli é para comandos que você executa depois que o contêiner do Gateway já existe.
3

Abra a UI de Controle

Abra http://127.0.0.1:18789/ no seu navegador e cole o segredo compartilhado configurado em Configurações. O script de configuração grava um token em .env por padrão; se você trocar a configuração do contêiner para autenticação por senha, use essa senha.Precisa da URL novamente?
docker compose run --rm openclaw-cli dashboard --no-open
4

Configure canais (opcional)

Use o contêiner da CLI para adicionar canais de mensagens:
# 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>"
Docs: WhatsApp, Telegram, Discord

​
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-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
Execute docker compose a partir da raiz do repo. Se você habilitou OPENCLAW_EXTRA_MOUNTS ou OPENCLAW_HOME_VOLUME, o script de configuração grava docker-compose.extra.yml; inclua-o com -f docker-compose.yml -f docker-compose.extra.yml.
Como openclaw-cli compartilha o namespace de rede do openclaw-gateway, ele é uma ferramenta pós-inicialização. Antes de docker compose up -d openclaw-gateway, execute o onboarding e as gravações de configuração durante a configuração pelo openclaw-gateway com --no-deps --entrypoint node.

​
Variáveis de ambiente

O script de configuração aceita estas variáveis de ambiente opcionais:
VariávelFinalidade
OPENCLAW_IMAGEUsar uma imagem remota em vez de criar localmente
OPENCLAW_DOCKER_APT_PACKAGESInstalar pacotes apt extras durante o build (separados por espaço)
OPENCLAW_EXTENSIONSIncluir auxiliares de plugins empacotados selecionados no momento do build
OPENCLAW_EXTRA_MOUNTSBind mounts extras do host (separados por vírgula, source:target[:opts])
OPENCLAW_HOME_VOLUMEPersistir /home/node em um volume Docker nomeado
OPENCLAW_SANDBOXAtivar bootstrap de sandbox (1, true, yes, on)
OPENCLAW_SKIP_ONBOARDINGPular a etapa de onboarding interativo (1, true, yes, on)
OPENCLAW_DOCKER_SOCKETSobrescrever o caminho do socket do Docker
OPENCLAW_DISABLE_BONJOURDesabilitar anúncio Bonjour/mDNS (padrão 1 para Docker)
OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYSDesabilitar overlays de bind mount de código-fonte de plugins empacotados
OTEL_EXPORTER_OTLP_ENDPOINTEndpoint compartilhado do coletor OTLP/HTTP para exportação OpenTelemetry
OTEL_EXPORTER_OTLP_*_ENDPOINTEndpoints OTLP específicos por sinal para traces, métricas ou logs
OTEL_EXPORTER_OTLP_PROTOCOLSobrescrita do protocolo OTLP. Somente http/protobuf é compatível hoje
OTEL_SERVICE_NAMENome do serviço usado para recursos OpenTelemetry
OTEL_SEMCONV_STABILITY_OPT_INAtivar os atributos semânticos experimentais GenAI mais recentes
OPENCLAW_OTEL_PRELOADEDPular a inicialização de um segundo SDK OpenTelemetry quando um já estiver pré-carregado
Mantenedores podem testar o código-fonte de plugins empacotados em 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 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 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 scrape: 
http://<gateway-host>:18789/api/diagnostics/prometheus
A rota é protegida pela autenticação do Gateway. Não exponha uma porta /metrics pública 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 integrado que consulta /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 vs loopback

scripts/docker/setup.sh define 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): navegador do host e CLI do host conseguem alcançar a porta publicada do Gateway.
  • loopback: somente processos dentro do namespace de rede do contêiner conseguem alcançar o Gateway diretamente.
Use valores de modo de bind em gateway.bind (lan / loopback / custom / tailnet / auto), não aliases de host como 0.0.0.0 ou 127.0.0.1.

​
Provedores locais no 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 rodam no host:
ProvedorURL padrão do hostURL de configuração do Docker
LM Studiohttp://127.0.0.1:1234http://host.docker.internal:1234
Ollamahttp://127.0.0.1:11434http://host.docker.internal:11434
A configuração Docker empacotada usa essas URLs de host como padrões de onboarding do LM Studio e do 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 hostname no macOS e Windows. Serviços do host também devem escutar em um endereço alcançá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 conta própria, 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 define OPENCLAW_DISABLE_BONJOUR=1 por padrão para que o Gateway não entre em loop de falhas nem 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 multicast mDNS seja conhecido por funcionar. Para armadilhas comuns e solução de problemas, consulte Descoberta Bonjour.

​
Armazenamento e persistência

O Docker Compose faz bind mount de 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 é definida, o docker-compose.yml empacotado recua para ${HOME}, ou /tmp quando o próprio HOME também está ausente. Isso impede que docker compose up emita uma especificação de volume com fonte vazia em ambientes mínimos. 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
O diretório de chave secreta de 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 baixáveis instalados armazenam seu estado de pacote sob o diretório inicial 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 embutidos. Para detalhes completos de persistência em implantações de VM, consulte Runtime de VM do 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 pacote de plugins instalados e logs de arquivo rotativos sob /tmp/openclaw/.

​
Auxiliares de shell (opcional)

Para facilitar o gerenciamento diário 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.sh
echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc
Se você instalou o ClawDock pelo caminho bruto 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
Caminho de socket personalizado (por exemplo, Docker sem root):
export OPENCLAW_SANDBOX=1
export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
./scripts/docker/setup.sh
O script monta docker.sock somente depois que os pré-requisitos do sandbox passam. Se a configuração do sandbox não puder ser concluída, o script redefine agents.defaults.sandbox.mode para off. Turnos de modo de código do Codex ainda ficam restritos ao workspace-write do Codex enquanto o sandbox do OpenClaw estiver ativo; não monte o socket Docker do host em contêineres de sandbox de agente.
Desative a alocação de pseudo-TTY do Compose com -T:
docker compose run -T --rm openclaw-cli gateway probe
docker compose run -T --rm openclaw-cli devices list --json
openclaw-cli usa network_mode: "service:openclaw-gateway" para que comandos da CLI possam acessar o Gateway por 127.0.0.1. Trate isso como um limite de confiança compartilhado. A configuração do Compose remove NET_RAW/NET_ADMIN e habilita no-new-privileges tanto em openclaw-gateway quanto em openclaw-cli.
Algumas configurações do Docker Desktop falham em consultas DNS a partir do sidecar openclaw-cli de rede compartilhada depois que NET_RAW é removido, o que aparece como EAI_AGAIN durante comandos apoiados por npm, como openclaw plugins install. Mantenha o arquivo Compose endurecido padrão para a operação normal do Gateway. A substituição local abaixo afrouxa a postura de segurança do contêiner da CLI ao restaurar as capacidades padrão do Docker, então use-a somente para o comando pontual da CLI que precisa de acesso ao registro de pacotes, não como sua invocação padrão do Compose:
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>
Se você já criou um contêiner openclaw-cli de longa duração, recrie-o com a mesma substituição. docker compose exec e docker exec não conseguem alterar capacidades Linux em um contêiner já criado.
A imagem executa como node (uid 1000). Se você vir erros de permissão em /home/node/.openclaw, confira se seus bind mounts do host pertencem ao uid 1000:
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
A mesma incompatibilidade pode aparecer como um aviso de plugin, como blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) seguido de plugin present but blocked. Isso significa que o uid do processo e o proprietário do diretório de plugin montado divergem. Prefira executar o contêiner como o uid 1000 padrão e corrigir a propriedade do bind mount. Só aplique chown em /path/to/openclaw-config/npm para root:root se você pretende executar o OpenClaw como root no longo prazo.
Ordene seu Dockerfile para que as camadas de dependência fiquem em cache. Isso evita reexecutar pnpm install a menos que os lockfiles mudem:
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"]
A imagem padrão prioriza segurança e executa como node não root. Para um contêiner com mais recursos:
  1. Persista /home/node: export OPENCLAW_HOME_VOLUME="openclaw_home"
  2. Inclua deps de sistema na imagem: export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"
  3. Inclua o Chromium do Playwright na imagem: export OPENCLAW_INSTALL_BROWSER=1
  4. Ou instale navegadores do Playwright em um volume persistido: 
    docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium
  5. Persista downloads de navegador: use OPENCLAW_HOME_VOLUME ou OPENCLAW_EXTRA_MOUNTS. O OpenClaw detecta automaticamente o Chromium gerenciado pelo Playwright da imagem Docker no Linux.
Se você escolher OAuth do OpenAI Codex no assistente, ele abre uma URL no navegador. Em Docker ou configurações headless, copie a URL de redirecionamento completa em que você chegar e cole-a de volta no assistente para concluir a autenticação.
A imagem principal de runtime do Docker usa node:24-bookworm-slim e inclui tini como o processo init de entrypoint (PID 1) para garantir que processos zumbi sejam coletados e sinais sejam tratados corretamente em contêineres de longa duração. Ela publica anotações OCI de imagem base, incluindo org.opencontainers.image.base.name, org.opencontainers.image.source e outras. O digest base do Node é atualizado por meio de PRs de imagem base Docker do Dependabot; builds de release não executam uma camada de atualização da distro. Consulte anotações de imagem OCI.

​
Executando em uma VPS?

Consulte Hetzner (VPS Docker) e Runtime de VM do Docker para etapas compartilhadas de implantação em VM, 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 dá a você uma barreira rígida em torno de sessões de agente não confiáveis ou multi-tenant sem conteinerizar o Gateway inteiro. 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:

​
Ativação rápida

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared
      },
    },
  },
}
Compile a imagem de sandbox padrão (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

Compile a imagem de sandbox com scripts/sandbox-setup.sh (checkout do código-fonte) ou o comando docker build inline de Sandboxing § Imagens e configuração (instalação npm), ou defina agents.defaults.sandbox.docker.image para sua imagem personalizada. Contêineres são criados automaticamente por sessão sob demanda.
Defina docker.user como um UID:GID que corresponda à propriedade do seu workspace montado, ou aplique chown na pasta do workspace.
O OpenClaw executa comandos com sh -lc (shell de login), que carrega /etc/profile e pode redefinir PATH. Defina docker.env.PATH para prefixar seus caminhos de ferramentas personalizadas, ou adicione um script sob /etc/profile.d/ no seu Dockerfile.
A VM precisa de pelo menos 2 GB de RAM. Use uma classe de máquina maior e tente novamente.
Busque um link novo do painel e aprove o dispositivo do navegador:
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>
Mais detalhes: Dashboard, Dispositivos.
Redefina o modo e o bind do Gateway:
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