Docker

Docker es opcional. Úsalo solo si quieres un Gateway en contenedor o validar el flujo de Docker.

¿Docker es adecuado para mí?

• Sí: quieres un entorno de Gateway aislado y desechable, o ejecutar OpenClaw en un host sin instalaciones locales.
• No: estás ejecutándolo en tu propia máquina y solo quieres el ciclo de desarrollo más rápido. Usa el flujo de instalación normal en su lugar.
• Nota sobre aislamiento: el backend de aislamiento predeterminado usa Docker cuando el aislamiento está habilitado, pero el aislamiento está desactivado de forma predeterminada y no requiere que todo el Gateway se ejecute en Docker. También están disponibles los backends de aislamiento SSH y OpenShell. Consulta Aislamiento.

Requisitos previos

• Docker Desktop (o Docker Engine) + Docker Compose v2
• Al menos 2 GB de RAM para compilar la imagen (pnpm install puede ser finalizado por OOM en hosts de 1 GB con salida 137)
• Espacio suficiente en disco para imágenes y registros
• Si lo ejecutas en un VPS/host público, revisa Refuerzo de seguridad para exposición de red, especialmente la política 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

Si prefieres ejecutar cada paso tú mismo en lugar de usar el script de configuración:

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

El script de configuración acepta estas variables de entorno opcionales:

La imagen oficial de Docker no incluye Homebrew. Durante el onboarding, OpenClaw oculta los instaladores de dependencias de Skills que solo usan brew cuando se ejecuta en un contenedor Linux sin brew; esas dependencias deben proporcionarse mediante una imagen personalizada o instalarse manualmente. Para dependencias disponibles desde paquetes Debian, usa OPENCLAW_IMAGE_APT_PACKAGES durante la compilación de la imagen. El nombre heredado OPENCLAW_DOCKER_APT_PACKAGES todavía se acepta. Para dependencias de Python, usa OPENCLAW_IMAGE_PIP_PACKAGES. Esto ejecuta python3 -m pip install --break-system-packages durante la compilación de la imagen, así que fija las versiones de los paquetes y usa solo índices de paquetes en los que confíes. Las compilaciones desde código fuente establecen de forma predeterminada OPENCLAW_DOCKER_BUILD_NODE_OPTIONS en --max-old-space-size=8192 y dejan OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB sin definir para que el wrapper de tsdown pueda respetar los límites de memoria del contenedor. También establecen de forma predeterminada OPENCLAW_DOCKER_BUILD_SKIP_DTS=1 porque las imágenes de runtime eliminan los archivos de declaración después de la compilación. Si Docker informa ResourceExhausted, cannot allocate memory o se interrumpe durante tsdown, aumenta el límite de memoria del builder de Docker o vuelve a intentarlo con heaps explícitos más pequeños, por ejemplo OPENCLAW_DOCKER_BUILD_NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB=4096.

Los mantenedores pueden probar el código fuente de un Plugin incluido contra una imagen empaquetada montando 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. Ese directorio de código fuente montado sobrescribe el paquete compilado coincidente de /app/dist/extensions/synology-chat para el mismo id de Plugin.

Observabilidad

La exportación de OpenTelemetry sale desde el contenedor del Gateway hacia tu colector OTLP. No requiere un puerto Docker publicado. Si compilas la imagen localmente y quieres que el exportador de OpenTelemetry incluido esté disponible dentro de la imagen, incluye sus dependencias 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

Instala el Plugin oficial @openclaw/diagnostics-otel desde ClawHub en instalaciones Docker empaquetadas antes de habilitar la exportación. Las imágenes personalizadas compiladas desde código fuente aún pueden incluir el código fuente del Plugin local con OPENCLAW_EXTENSIONS=diagnostics-otel. Para habilitar la exportación, permite y habilita el Plugin diagnostics-otel en la configuración, luego establece diagnostics.otel.enabled=true o usa el ejemplo de configuración en Exportación de OpenTelemetry . Los encabezados de autenticación del colector se configuran mediante diagnostics.otel.headers, no mediante variables de entorno de Docker.

Las métricas de Prometheus usan 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 autenticar. Consulta Métricas de Prometheus.

Comprobaciones de salud

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

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

La imagen de Docker incluye un HEALTHCHECK integrado que hace ping a /healthz. Si las comprobaciones siguen fallando, Docker marca el contenedor como unhealthy y los sistemas de orquestación pueden 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 el acceso del host a http://127.0.0.1:18789 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

Cuando OpenClaw se ejecuta en Docker, 127.0.0.1 dentro del contenedor es el propio contenedor, no tu máquina host. Usa host.docker.internal para proveedores de IA que se ejecutan en el host:

La configuración de Docker incluida usa esas URL de host como valores predeterminados de incorporación para LM Studio y Ollama, y docker-compose.yml asigna host.docker.internal al gateway del host de Docker para Docker Engine en Linux. Docker Desktop ya proporciona el mismo nombre de host en macOS y Windows.

Los servicios del host también deben escuchar en una dirección alcanzable desde Docker:

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

Si usas tu propio archivo Compose o comando docker run, agrega tú mismo la misma asignación de host, por ejemplo --add-host=host.docker.internal:host-gateway.

Backend Claude CLI en Docker

La imagen oficial de Docker de OpenClaw no preinstala Claude Code. Instala e inicia sesión en Claude Code dentro del usuario del contenedor que ejecuta OpenClaw, y luego conserva ese home del contenedor para que las actualizaciones de imagen no borren el binario ni el estado de autenticación de Claude.

Para instalaciones nuevas de Docker, habilita un volumen persistente /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 de Docker existente, detén primero el stack y vuelve a cargar los valores actuales de Docker .env antes de ejecutar de nuevo la configuración. El script de configuración no lee .env por sí solo; reescribe .env a partir del shell actual y los valores predeterminados. Para el .env generado, ejecuta:

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

Si tu .env contiene valores que tu shell no puede cargar con source, vuelve a exportar manualmente primero los valores existentes de los que dependes, como OPENCLAW_IMAGE, puertos, modo de enlace, rutas personalizadas, OPENCLAW_EXTRA_MOUNTS, sandbox y opciones para omitir la incorporación. La superposición generada monta el volumen home tanto para openclaw-gateway como para openclaw-cli.

Ejecuta los comandos restantes con la superposición Compose generada para que ambos servicios monten el home persistido. Si tu configuración también usa docker-compose.override.yml, inclúyelo antes de docker-compose.extra.yml.

Instala Claude Code en ese 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'

El instalador nativo escribe el binario claude bajo /home/node/.local/bin/claude. Indica a OpenClaw que use esa ruta del contenedor:

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 dentro del mismo home de contenedor 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

Después de eso, puedes usar 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 de Claude Code bajo /home/node/.local/bin y /home/node/.local/share/claude, además de la configuración y el estado de autenticación de Claude Code bajo /home/node/.claude y /home/node/.claude.json. Conservar solo /home/node/.openclaw no basta para reutilizar Claude CLI. Si usas OPENCLAW_EXTRA_MOUNTS en lugar de un volumen home, monta todas esas rutas de Claude en ambos servicios Docker.

Bonjour / mDNS

La red bridge de Docker normalmente no reenvía multicast Bonjour/mDNS (224.0.0.251:5353) de forma fiable. Por eso la configuración Compose incluida usa de forma predeterminada OPENCLAW_DISABLE_BONJOUR=1, para que el Gateway no entre en un ciclo de fallos ni reinicie repetidamente la publicidad cuando el bridge descarte el tráfico multicast.

Usa la URL publicada del Gateway, Tailscale o DNS-SD de área amplia para hosts Docker. Configura OPENCLAW_DISABLE_BONJOUR=0 solo cuando se ejecute con red de host, macvlan u otra red donde se sepa que el multicast mDNS funciona.

Para advertencias y solución de problemas, consulta descubrimiento Bonjour.

Almacenamiento y persistencia

Docker Compose monta con bind 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, de modo que esas rutas sobreviven al reemplazo del contenedor. Cuando alguna variable no está definida, el docker-compose.yml incluido recurre a ${HOME}, o a /tmp cuando HOME también falta. Eso evita que docker compose up emita una especificación de volumen con origen vacío en entornos básicos.

Ese directorio de configuración montado es donde OpenClaw conserva:

• openclaw.json para la configuración de comportamiento
• agents/<agentId>/agent/auth-profiles.json para autenticación OAuth/clave de API de proveedores almacenada
• .env para secretos de runtime respaldados por variables de entorno, como OPENCLAW_GATEWAY_TOKEN

El directorio de claves secretas de perfiles de autenticación almacena la clave de cifrado local usada para el material de tokens de perfiles de autenticación basados en OAuth. Consérvalo con el estado de tu host Docker, pero separado de OPENCLAW_CONFIG_DIR.

Los plugins descargables instalados almacenan el estado de su paquete bajo el home montado de OpenClaw, de modo que los registros de instalación de plugins y las raíces de paquetes sobreviven al reemplazo del contenedor. El arranque del Gateway no genera árboles de dependencias de plugins incluidos.

Para detalles completos de persistencia en despliegues de VM, consulta Runtime de VM de Docker - Qué persiste dónde.

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

Ayudantes de shell (opcional)

Para una gestión diaria de Docker más sencilla, 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 ClawDock desde la ruta raw antigua scripts/shell-helpers/clawdock-helpers.sh, vuelve a ejecutar el comando de instalación anterior para que tu archivo local de ayudantes siga la nueva ubicación.

Luego usa clawdock-start, clawdock-stop, clawdock-dashboard, etc. Ejecuta clawdock-help para ver todos los comandos. Consulta ClawDock para la guía completa de ayudantes.

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 (VPS con Docker) y Runtime de VM de Docker para ver pasos compartidos de despliegue en VM, incluida la inclusión de binarios, la persistencia y las actualizaciones.

Entorno aislado del agente

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 de Docker aislados mientras el propio Gateway permanece en el host. Esto te da una barrera firme alrededor de sesiones de agente no confiables o multiinquilino sin contenerizar todo el Gateway.

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

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

• Entorno aislado -- referencia completa del entorno aislado
• OpenShell -- acceso interactivo de shell a contenedores del entorno aislado
• Entorno aislado y herramientas multiagente -- anulaciones por agente

Habilitación rápida

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

Compila la imagen predeterminada del entorno aislado (desde un checkout del código fuente):

scripts/sandbox-setup.sh

Para instalaciones de npm sin un checkout del código fuente, consulta Entorno aislado § 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