Docker

Docker es opcional. Úsalo para un entorno de Gateway aislado y desechable, o para un host sin instalaciones locales. Si ya desarrollas en tu propia máquina, usa en su lugar el flujo de instalación normal.

El backend de sandbox predeterminado usa Docker cuando agents.defaults.sandbox está habilitado, pero el sandboxing está desactivado de forma predeterminada y no requiere que el Gateway se ejecute en Docker. También están disponibles los backends de sandbox SSH y OpenShell; consulta Sandboxing.

Requisitos previos

• Docker Desktop (o Docker Engine) + Docker Compose v2
• Al menos 2 GB de RAM para compilar la imagen (pnpm install puede ser terminado por OOM en hosts de 1 GB con salida 137)
• Espacio suficiente en disco para imágenes y registros
• En un VPS/host público, revisa Refuerzo de seguridad para exposición de red, especialmente la cadena de firewall DOCKER-USER de Docker

Gateway en contenedor

./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>"

Flujo manual

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

Variables de entorno

Variables opcionales aceptadas por scripts/docker/setup.sh (y, para el contenedor del Gateway, directamente por docker-compose.yml):

La imagen oficial no incluye Homebrew. Durante el onboarding, OpenClaw oculta instaladores de dependencias de Skills exclusivos de brew en un contenedor Linux sin brew; proporciona esas dependencias mediante una imagen personalizada o instálalas manualmente. Usa OPENCLAW_IMAGE_APT_PACKAGES para dependencias empaquetadas por Debian y OPENCLAW_IMAGE_PIP_PACKAGES para dependencias de Python (ejecuta python3 -m pip install --break-system-packages en tiempo de compilación, así que fija versiones y usa solo índices en los que confíes).

Si Docker informa ResourceExhausted, cannot allocate memory o se interrumpe durante tsdown, aumenta el límite de memoria del constructor de Docker o vuelve a intentarlo con heaps explícitos más pequeños:

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

Para probar el código fuente de un plugin incluido contra una imagen empaquetada, monta un directorio de código fuente de plugin sobre su ruta de código fuente empaquetada, por ejemplo, OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. Eso sobrescribe el paquete compilado correspondiente /app/dist/extensions/synology-chat para el mismo id de plugin.

Observabilidad

La exportación de OpenTelemetry es saliente desde el contenedor del Gateway hacia tu colector OTLP; no necesita ningún puerto Docker publicado. Para incluir el exportador incluido en una imagen 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

Las imágenes oficiales precompiladas ya incluyen diagnostics-otel; instala clawhub:@openclaw/diagnostics-otel tú mismo solo si lo eliminaste. Para habilitar la exportación, permite y habilita el plugin diagnostics-otel en la configuración y luego establece diagnostics.otel.enabled=true (consulta el ejemplo completo en Exportación de OpenTelemetry). Los encabezados de autenticación del colector van mediante diagnostics.otel.headers, no mediante variables de entorno de Docker.

Las métricas de Prometheus reutilizan el puerto del Gateway ya publicado. Instala clawhub:@openclaw/diagnostics-prometheus, habilita el plugin diagnostics-prometheus y luego recopila:

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

La ruta está protegida por la autenticación del Gateway; no expongas un puerto público /metrics separado ni una ruta de proxy inverso sin autenticación. Consulta Métricas de Prometheus.

Comprobaciones de estado

Endpoints de sondeo del contenedor (no requieren autenticación):

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

El HEALTHCHECK integrado de la imagen hace ping a /healthz; los fallos repetidos marcan el contenedor como unhealthy para que los orquestadores puedan reiniciarlo o reemplazarlo.

Instantánea profunda de estado autenticada:

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

LAN frente a loopback

scripts/docker/setup.sh usa de forma predeterminada OPENCLAW_GATEWAY_BIND=lan para que http://127.0.0.1:18789 en el host funcione con la publicación de puertos de Docker.

• lan (predeterminado): el navegador del host y la CLI del host pueden alcanzar el puerto publicado del gateway.
• loopback: solo los procesos dentro del espacio de nombres de red del contenedor pueden alcanzar el gateway directamente.

Proveedores locales del host

Dentro del contenedor, 127.0.0.1 es el propio contenedor, no el host. Usa host.docker.internal para proveedores que se ejecutan en el host:

La configuración incluida usa esas URL como valores predeterminados de incorporación para LM Studio/Ollama, y docker-compose.yml asigna host.docker.internal al gateway del host en Linux Docker Engine (Docker Desktop proporciona el mismo alias en macOS/Windows). Los servicios del host deben escuchar en una dirección que Docker pueda alcanzar:

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

¿Usas tu propio archivo Compose o docker run? Agrega tú mismo la misma asignación, por ejemplo --add-host=host.docker.internal:host-gateway.

Backend de Claude CLI en Docker

La imagen oficial no preinstala Claude Code. Instálalo e inicia sesión dentro del usuario node del contenedor, luego conserva ese home del contenedor para que las actualizaciones de imagen no borren el binario ni el estado de autenticación.

Para una instalación nueva, habilita un volumen persistente de /home/node antes de ejecutar la configuración:

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

Para una instalación existente, detén la pila y vuelve a cargar primero los valores actuales de .env: el script de configuración siempre reescribe .env desde el shell actual y los valores predeterminados; no lee el archivo por sí solo:

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

Si .env contiene valores que tu shell no puede cargar con source, vuelve a exportar manualmente primero aquello de lo que dependes (OPENCLAW_IMAGE, puertos, modo de enlace, rutas personalizadas, OPENCLAW_EXTRA_MOUNTS, sandbox, omitir incorporación). La superposición generada monta el volumen home tanto para openclaw-gateway como para openclaw-cli; ejecuta los comandos restantes con esa superposición (y docker-compose.override.yml primero, si usas uno):

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'

El instalador nativo escribe claude en /home/node/.local/bin/claude. Apunta OpenClaw a esa ruta:

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

Inicia sesión y verifica desde el mismo home persistente:

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

Luego usa el backend claude-cli incluido:

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 conserva la instalación nativa en /home/node/.local/bin y /home/node/.local/share/claude, además de la configuración/autenticación de Claude Code en /home/node/.claude y /home/node/.claude.json. Conservar solo /home/node/.openclaw no es suficiente; si usas OPENCLAW_EXTRA_MOUNTS en lugar de un volumen home, monta todas esas rutas de Claude en ambos servicios.

Bonjour / mDNS

Las redes bridge de Docker normalmente no reenvían multicast Bonjour/mDNS (224.0.0.251:5353) de forma fiable. Cuando OPENCLAW_DISABLE_BONJOUR no está definido, el Plugin Bonjour incluido desactiva automáticamente la publicidad LAN una vez que detecta que se ejecuta en un contenedor, por lo que no entrará en un ciclo de fallos reintentando el multicast que el bridge descarta. Define OPENCLAW_DISABLE_BONJOUR=1 para forzarlo a desactivarse independientemente de la detección, o 0 para forzarlo a activarse (solo en redes del host, macvlan u otra red donde se sepa que el multicast mDNS funciona).

De lo contrario, usa la URL publicada del Gateway, Tailscale o DNS-SD de área amplia para hosts Docker. Consulta descubrimiento de Bonjour para ver problemas habituales y solución de problemas.

Almacenamiento y persistencia

Docker Compose monta mediante bind mount OPENCLAW_CONFIG_DIR en /home/node/.openclaw, OPENCLAW_WORKSPACE_DIR en /home/node/.openclaw/workspace y OPENCLAW_AUTH_PROFILE_SECRET_DIR en /home/node/.config/openclaw, por lo que esas rutas sobreviven al reemplazo del contenedor. Cuando una variable no está definida, docker-compose.yml usa una ruta alternativa bajo ${HOME}, o /tmp si falta el propio HOME, de modo que docker compose up nunca emite una especificación de volumen con origen vacío en entornos básicos.

Ese directorio de configuración montado contiene:

• openclaw.json para la configuración de comportamiento

• agents/<agentId>/agent/auth-profiles.json para la autenticación OAuth/clave de API almacenada del proveedor

• .env para secretos de runtime respaldados por env, como OPENCLAW_GATEWAY_TOKEN

  El directorio secreto del perfil de autenticación almacena la clave de cifrado local para el material de tokens del perfil de autenticación respaldado por OAuth. Consérvalo con el estado de tu host Docker, pero separado de OPENCLAW_CONFIG_DIR.

  Los plugins descargables instalados almacenan el estado del paquete bajo el directorio principal de OpenClaw montado, por lo que los registros de instalación y las raíces de los paquetes sobreviven al reemplazo del contenedor; el inicio del gateway no regenera los árboles de dependencias de plugins incluidos.

  Para obtener detalles completos sobre la persistencia de la VM, consulta Tiempo de ejecución de VM Docker - Qué persiste y dónde.

  Puntos críticos de crecimiento del disco: media/, archivos JSONL de sesión, la base de datos SQLite de estado compartido, las raíces de paquetes de plugins instalados y los registros de archivo rotativos bajo /tmp/openclaw/.

  Ayudantes de shell (opcional)

  Para comandos cotidianos más breves, instala 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

  Si instalaste desde la ruta anterior scripts/shell-helpers/clawdock-helpers.sh, vuelve a ejecutar el comando anterior para que tu ayudante local siga la ubicación actual. Luego usa clawdock-start, clawdock-stop, clawdock-dashboard, etc. (ejecuta clawdock-help para ver la 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"]

¿Ejecutar en un VPS?

Consulta Hetzner (Docker VPS) y Docker VM Runtime para ver los pasos de despliegue de VM compartida, incluido el horneado del binario, la persistencia y las actualizaciones.

Entorno aislado de agentes

Cuando agents.defaults.sandbox está habilitado con el backend de Docker, el Gateway ejecuta las herramientas del agente (shell, lectura/escritura de archivos, etc.) dentro de contenedores Docker aislados mientras el propio Gateway permanece en el host: una barrera rígida alrededor de sesiones de agente no confiables o multiinquilino sin contenerizar todo el Gateway.

El alcance del sandbox puede ser por agente (predeterminado), por sesión o compartido; cada alcance obtiene su propio workspace montado en /workspace. También puedes configurar políticas de herramientas de permitir/denegar, aislamiento de red, límites de recursos y contenedores de navegador.

Para la configuración completa, imágenes, notas de seguridad y perfiles multiagente:

• Sandboxing -- referencia completa del sandbox
• OpenShell -- acceso interactivo de shell a contenedores de sandbox
• Sandbox y herramientas multiagente -- anulaciones por agente

Activación rápida

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

Compila la imagen de sandbox predeterminada (desde un checkout de código fuente):

scripts/sandbox-setup.sh

Para instalaciones npm sin un checkout de código fuente, consulta Sandboxing § Imágenes y configuración para ver comandos docker build en línea.

Solución 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

Relacionado

• Resumen de instalación — todos los métodos de instalación
• Podman — alternativa de Podman a Docker
• ClawDock — configuración comunitaria con Docker Compose
• Actualización — mantener OpenClaw actualizado
• Configuración — configuración del Gateway después de la instalación