Docker

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

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

¿Aloja a varios usuarios? Consulte Alojamiento multiinquilino para conocer el modelo de una celda por inquilino.

Requisitos previos

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

Gateway en contenedores

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

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

El contexto de Docker excluye .git. Pase la identidad del código fuente como argumentos de compilación como se muestra anteriormente, para que la pantalla Acerca de de la imagen indique el commit extraído y una marca de tiempo de compilación. scripts/docker/setup.sh resuelve y pasa ambos valores automáticamente.

Actualizar imágenes de contenedor

Cuando sustituye la imagen de OpenClaw pero conserva el mismo estado y la misma configuración montados, el nuevo Gateway ejecuta migraciones de actualización seguras durante el inicio y la convergencia de plugins antes de estar listo. Las actualizaciones rutinarias de imágenes no deberían requerir una ejecución independiente de openclaw doctor --fix.

Si el proceso de inicio no puede completar esas reparaciones de forma segura, el Gateway finaliza en lugar de informar de que está en buen estado. Con una política de reinicio, Docker, Podman o Kubernetes pueden mostrar el contenedor del Gateway reiniciándose. Conserve el volumen de estado montado y, a continuación, ejecute una vez la misma imagen con openclaw doctor --fix como comando del contenedor, utilizando los mismos montajes de estado y configuración que utiliza el 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

Cuando doctor finalice, reinicie el contenedor del Gateway con su comando predeterminado. En Kubernetes, ejecute el mismo comando en un Job de una sola ejecución o en un pod de depuración montado en el mismo PVC y, a continuación, reinicie el Deployment o StatefulSet.

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 la incorporación, OpenClaw oculta los instaladores de dependencias de Skills exclusivos de brew en un contenedor Linux sin brew; proporcione esas dependencias mediante una imagen personalizada o instálelas manualmente. Utilice OPENCLAW_IMAGE_APT_PACKAGES para las dependencias empaquetadas para Debian y OPENCLAW_IMAGE_PIP_PACKAGES para las dependencias de Python (ejecuta python3 -m pip install --break-system-packages durante la compilación, por lo que debe fijar las versiones y utilizar únicamente índices de confianza).

Si Docker informa de ResourceExhausted, cannot allocate memory o se interrumpe durante tsdown, aumente el límite de memoria del compilador de Docker o vuelva a intentarlo con tamaños de montón 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

Imágenes compiladas desde el código fuente con plugins seleccionados

OPENCLAW_EXTENSIONS selecciona los identificadores de manifiesto de los plugins del checkout del código fuente; también se aceptan los nombres existentes de los directorios de código fuente cuando son diferentes. La compilación de Docker resuelve una vez la selección en directorios de código fuente, instala las dependencias de producción y, cuando un plugin seleccionado se publica por separado con openclaw.build.bundledDist: false, compila su runtime en la distribución incluida raíz. Este empaquetado exclusivo de Docker no cambia el contrato de artefactos npm ni ClawHub del plugin. Los identificadores desconocidos, no válidos o ambiguos hacen que falle la compilación de la imagen. Los identificadores conocidos que son solo de dependencia o código fuente conservan su preparación existente de código fuente y dependencias sin obtener una entrada compilada en la distribución raíz. Un plugin seleccionado con entradas de compilación unificadas debe compilarse correctamente; se eliminan el código fuente y la salida del runtime de los plugins externos no seleccionados.

Por ejemplo, estos comandos compilan imágenes independientes y autónomas del Gateway FakeCo para varias arquitecturas, destinadas a ClickClack, Slack y Microsoft Teams. ClawRouter ya forma parte del runtime raíz de OpenClaw, por lo que la imagen de ClickClack selecciona únicamente clickclack. El argumento de navegador vacío explícito mantiene la imagen predeterminada sin 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 o --platform linux/amd64 --load para una única compilación local nativa. La salida multiplataforma y el SBOM y la procedencia adjuntos requieren un registro u otra salida de Buildx que conserve las certificaciones. Después de publicar, inspeccione el manifiesto e implemente el resumen inmutable en lugar de la etiqueta mutable del SHA del código fuente:

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

Estas imágenes están destinadas a gateways autónomos basados en OCI y a usuarios genéricos de Docker. Los gateways administrados por Crabhelm no las utilizan: esa vía de entrega compila un archivo de dispositivo x86_64 independiente que contiene un tarball npm de OpenClaw y fija los resúmenes de Node, del archivo y del manifiesto. Compile ese dispositivo por separado a partir del mismo código fuente de OpenClaw incorporado.

Para probar el código fuente de un plugin incluido con una imagen empaquetada, monte un directorio de código fuente del 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. Esto sustituye el paquete compilado correspondiente de /app/dist/extensions/synology-chat para el mismo identificador de plugin.

Observabilidad

La exportación de OpenTelemetry es saliente desde el contenedor del Gateway hacia su recopilador OTLP; no necesita ningún puerto de Docker publicado. Para incluir el exportador incorporado 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; instale clawhub:@openclaw/diagnostics-otel por su cuenta únicamente si lo eliminó. Para habilitar la exportación, permita y habilite el plugin diagnostics-otel en la configuración y, después, establezca diagnostics.otel.enabled=true (consulte el ejemplo completo en Exportación de OpenTelemetry). Los encabezados de autenticación del recopilador se configuran mediante diagnostics.otel.headers, no mediante variables de entorno de Docker.

Las métricas de Prometheus reutilizan el puerto del Gateway ya publicado. Instale clawhub:@openclaw/diagnostics-prometheus, habilite el plugin diagnostics-prometheus y, después, recopile:

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

La ruta está protegida mediante la autenticación del Gateway; no exponga un puerto público /metrics independiente ni una ruta de proxy inverso sin autenticar. Consulte 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   # actividadcurl -fsS http://127.0.0.1:18789/readyz     # disponibilidad

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

Instantánea detallada y autenticada del estado:

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

LAN frente a loopback

scripts/docker/setup.sh establece 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 y la CLI del host pueden acceder al puerto publicado del Gateway.
• loopback: solo los procesos dentro del espacio de nombres de red del contenedor pueden acceder directamente al Gateway.

Proveedores locales del host

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

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

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

¿Usa su propio archivo de Compose o docker run? Añada la misma asignación, por ejemplo, --add-host=host.docker.internal:host-gateway.

Backend de Claude CLI en Docker

La imagen oficial no incluye Claude Code preinstalado. Instálelo e inicie sesión dentro del contenedor con el usuario node y, a continuación, conserve de forma persistente el directorio personal de ese contenedor para que las actualizaciones de la imagen no borren el binario ni el estado de autenticación.

Para una instalación nueva, habilite un volumen persistente en /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, detenga el conjunto de servicios y vuelva a cargar primero los valores actuales de .env: el script de configuración siempre vuelve a escribir .env a partir del entorno de 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 el shell no puede cargar, vuelva a exportar primero y de forma manual aquellos de los que depende (OPENCLAW_IMAGE, puertos, modo de enlace, rutas personalizadas, OPENCLAW_EXTRA_MOUNTS, entorno aislado, omisión de la incorporación). La superposición generada monta el volumen del directorio personal tanto para openclaw-gateway como para openclaw-cli; ejecute los comandos restantes con esa superposición (y primero con docker-compose.override.yml, si utiliza 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 guarda claude en /home/node/.local/bin/claude. Configure OpenClaw para que utilice 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

Inicie sesión y verifique el funcionamiento desde el mismo directorio personal 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

A continuación, utilice 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 "Saluda desde Claude CLI en Docker"

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 y autenticación de Claude Code en /home/node/.claude y /home/node/.claude.json. Conservar únicamente /home/node/.openclaw no es suficiente; si utiliza OPENCLAW_EXTRA_MOUNTS en lugar de un volumen para el directorio personal, monte todas esas rutas de Claude en ambos servicios.

Bonjour / mDNS

La red en puente de Docker no suele reenviar de forma fiable el tráfico multidifusión de Bonjour/mDNS (224.0.0.251:5353). Cuando OPENCLAW_DISABLE_BONJOUR no está definido, el Plugin de Bonjour incluido desactiva automáticamente la publicidad en la red LAN al detectar que se ejecuta en un contenedor, de modo que no entra en un bucle de fallos al reintentar el tráfico multidifusión que descarta el puente. Establezca OPENCLAW_DISABLE_BONJOUR=1 para forzar su desactivación independientemente de la detección, o 0 para forzar su activación (solo con redes de host, macvlan u otra red donde se sepa que el tráfico multidifusión mDNS funciona).

En los demás casos, utilice la URL publicada del Gateway, Tailscale o DNS-SD de área amplia para los hosts de Docker. Consulte Detección de Bonjour para conocer las salvedades y solucionar problemas.

Almacenamiento y persistencia

Docker Compose monta mediante enlace 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 a la sustitución del contenedor. Cuando una variable no está definida, docker-compose.yml utiliza una ruta alternativa bajo ${HOME}, o /tmp si tampoco existe HOME, por lo que docker compose up nunca genera una especificación de volumen con un origen vacío en entornos básicos.

Ese directorio de configuración montado contiene:

• openclaw.json para la configuración del comportamiento
• agents/<agentId>/agent/auth-profiles.json para la autenticación almacenada mediante OAuth o claves de API de proveedores
• .env para secretos de ejecución proporcionados mediante variables de entorno, como OPENCLAW_GATEWAY_TOKEN

El directorio de secretos de los perfiles de autenticación almacena la clave de cifrado local del material de tokens de los perfiles de autenticación basados en OAuth. Consérvelo junto con el estado del host de Docker, pero separado de OPENCLAW_CONFIG_DIR.

Los plugins descargables instalados almacenan el estado de los paquetes en el directorio personal montado de OpenClaw, por lo que los registros de instalación y las raíces de los paquetes sobreviven a la sustitución del contenedor; el inicio del Gateway no vuelve a generar los árboles de dependencias de los plugins incluidos.

Para obtener información completa sobre la persistencia de máquinas virtuales, consulte Entorno de ejecución de máquinas virtuales de Docker: qué se conserva y dónde.

Puntos críticos de crecimiento del disco: media/, las bases de datos SQLite de cada agente, las transcripciones JSONL de sesiones heredadas, la base de datos SQLite de estado compartido, las raíces de paquetes de los plugins instalados y los registros rotativos de archivos en /tmp/openclaw/.

Ayudantes de shell (opcionales)

Para acortar los comandos de uso cotidiano, instale 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 realizaste la instalación desde la antigua ruta scripts/shell-helpers/clawdock-helpers.sh, vuelve a ejecutar el comando anterior para que tu ayudante local apunte a la ubicación actual. Después, usa clawdock-start, clawdock-stop, clawdock-dashboard, etc. (ejecuta clawdock-help para consultar 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"]

¿Lo ejecutas en un VPS?

Consulta Hetzner (VPS con Docker) y Entorno de ejecución de VM con Docker para conocer los pasos de despliegue en una VM compartida, incluidos la inclusión de binarios en la imagen, la persistencia y las actualizaciones.

Entorno aislado del agente

Cuando agents.defaults.sandbox está activado con el backend de Docker, el Gateway ejecuta las herramientas del agente (shell, lectura/escritura de archivos, etc.) dentro de contenedores Docker aislados, mientras que el propio Gateway permanece en el host. Esto crea una barrera sólida alrededor de las sesiones de agentes no confiables o multiinquilino sin contenerizar todo el Gateway.

El ámbito del entorno aislado puede ser por agente (opción predeterminada), por sesión o compartido; cada ámbito obtiene su propio espacio de trabajo montado en /workspace. También puedes configurar políticas de herramientas permitidas y denegadas, aislamiento de red, límites de recursos y contenedores de navegador.

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

• Entorno aislado -- referencia completa del entorno aislado
• OpenShell -- acceso interactivo mediante shell a los contenedores del entorno aislado
• Entorno aislado y herramientas multiagente -- sobrescrituras por agente

Activació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 repositorio de código fuente):

scripts/sandbox-setup.sh

Para instalaciones de npm sin un repositorio de 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

Temas relacionados

• Descripción general de la instalación — todos los métodos de instalación
• Podman — alternativa a Docker basada en Podman
• ClawDock — configuración comunitaria de Docker Compose
• Actualización — cómo mantener OpenClaw actualizado
• Configuración — configuración del Gateway después de la instalación