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 suficiente en disco para imágenes y registros
• En un VPS o host público, revise el Refuerzo de seguridad para la 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

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 temporal de compilación. scripts/docker/setup.sh resuelve y pasa ambos valores automáticamente.

Actualización de imágenes de contenedor

Cuando sustituye la imagen de OpenClaw pero conserva el mismo estado y configuración montados, el nuevo Gateway ejecuta migraciones de actualización seguras para 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 inicio no puede completar esas reparaciones de forma segura, el Gateway finaliza en lugar de indicar que funciona correctamente. 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 la misma imagen una vez 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 termine, 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 memorias dinámicas explícitas más pequeñas:

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 plugins del checkout de origen; también se aceptan los nombres de directorios de origen existentes cuando difieren. La compilación de Docker resuelve una vez la selección en directorios de origen, instala las dependencias de producción y, cuando un plugin seleccionado se publica por separado con openclaw.build.bundledDist: false, compila su entorno de ejecución en la distribución incluida raíz. Este empaquetado exclusivo de Docker no cambia el contrato de artefactos npm o 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/origen mantienen su preparación de código fuente y dependencias existente sin obtener una entrada de distribución raíz compilada. Un plugin seleccionado con entradas de compilación unificadas debe compilarse correctamente; se eliminan el código fuente y la salida del entorno de ejecución de los plugins externos no seleccionados.

Por ejemplo, estos comandos compilan imágenes independientes y autónomas del Gateway de FakeCo para varias arquitecturas, destinadas a ClickClack, Slack y Microsoft Teams. ClawRouter ya forma parte del entorno de ejecución raíz de OpenClaw, por lo que la imagen de ClickClack selecciona únicamente clickclack. El argumento vacío explícito del navegador mantiene la imagen predeterminada libre de 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/procedencia adjuntos requieren un registro u otra salida de Buildx que conserve las certificaciones. Después de publicarla, inspeccione el manifiesto y despliegue el resumen inmutable en lugar de la etiqueta mutable del SHA de origen:

docker buildx imagetools inspect \  "${REGISTRY}/openclaw-clickclack:${SOURCE_SHA}"# Desplegar: 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 consumen: esa ruta de entrega genera un archivo independiente de dispositivo x86_64 que contiene un paquete tar npm de OpenClaw y fija los resúmenes de Node, del archivo y del manifiesto. Compile ese dispositivo de forma independiente a partir del mismo código fuente de OpenClaw integrado.

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, p. ej., OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro. Esto sustituye el paquete compilado /app/dist/extensions/synology-chat correspondiente al mismo identificador de plugin.

Observabilidad

La exportación de OpenTelemetry sale del contenedor del Gateway hacia el 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 solo si lo eliminó. Para habilitar la exportación, permita y habilite el plugin diagnostics-otel en la configuración y, a continuación, establezca diagnostics.otel.enabled=true (consulte el ejemplo completo en Exportación de OpenTelemetry). Los encabezados de autenticación del recopilador se proporcionan 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, a continuación, recopile:

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

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

Comprobaciones de estado

Extremos 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 incorporado en la imagen consulta /healthz; los fallos repetidos marcan el contenedor como unhealthy para que los orquestadores puedan reiniciarlo o sustituirlo.

Instantánea detallada de estado autenticada:

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

LAN frente a bucle invertido

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 (valor 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 su cuenta, p. ej., --add-host=host.docker.internal:host-gateway.

Backend de la CLI de Claude en Docker

La imagen oficial no preinstala Claude Code. Instálelo e inicie sesión dentro del usuario node del contenedor y, a continuación, conserve el directorio de inicio 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 /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 la pila y vuelva a cargar primero los valores actuales de .env: el script de configuración siempre vuelve a escribir .env a partir del shell y los valores predeterminados actuales; 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 manualmente primero aquello de lo que dependa (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 de inicio tanto para openclaw-gateway como para openclaw-cli; ejecute los comandos restantes con esa superposición (y primero docker-compose.override.yml, si usa 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. La imagen de OpenClaw incluye /home/node/.local/bin en PATH, por lo que el plugin incorporado de Anthropic lo resuelve sin una sustitución de la configuración del adaptador.

Inicie sesión y realice la verificación desde el mismo directorio de inicio 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, use el backend incorporado claude-cli:

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 la CLI de Claude 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/autenticación de Claude Code en /home/node/.claude y /home/node/.claude.json. Conservar solo /home/node/.openclaw no es suficiente; si usa OPENCLAW_EXTRA_MOUNTS en lugar de un volumen del directorio de inicio, monte todas esas rutas de Claude en ambos servicios.

Bonjour / mDNS

Las redes puente de Docker no suelen 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 Bonjour incorporado deshabilita automáticamente la difusión en la LAN cuando detecta que se está ejecutando en un contenedor, por lo que no entrará en un bucle de fallos al reintentar el tráfico multidifusión que el puente descarta. Establezca OPENCLAW_DISABLE_BONJOUR=1 para desactivarlo independientemente de la detección, o 0 para activarlo de forma forzada (solo en redes del host, macvlan u otra red donde se sepa que el tráfico multidifusión mDNS funciona).

De lo contrario, use la URL publicada del Gateway, Tailscale o DNS-SD de área extensa para los hosts de Docker. Consulte Detección mediante Bonjour para conocer las particularidades 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, para que esas rutas sobrevivan a la sustitución del contenedor. Cuando una variable no está definida, docker-compose.yml recurre a una ruta bajo ${HOME}, o a /tmp si falta el propio HOME, por lo que docker compose up nunca emite 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 OAuth/mediante clave de API almacenada de los proveedores
• .env para secretos del entorno de ejecución respaldados por variables de entorno, como OPENCLAW_GATEWAY_TOKEN

El directorio secreto de perfiles de autenticación almacena la clave de cifrado local para el material de tokens de perfiles de autenticación respaldado por OAuth. Manténgalo 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 de inicio 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 incorporados.

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

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

Ayudantes del shell (opcionales)

Para abreviar los comandos cotidianos, 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 realizó la instalación desde la ruta anterior scripts/shell-helpers/clawdock-helpers.sh, vuelva a ejecutar el comando anterior para que el ayudante local siga la ubicación actual. A continuación, use clawdock-start, clawdock-stop, clawdock-dashboard, etc. (ejecute 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"]

¿Se ejecuta en un VPS?

Consulte Hetzner (VPS con Docker) y Tiempo de ejecución de VM con Docker para conocer los pasos de despliegue en una VM compartida, incluidos la incorporació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 y escritura de archivos, etc.) dentro de contenedores Docker aislados, mientras que el propio gateway permanece en el host: una barrera sólida alrededor de las sesiones de agentes no fiables o multiinquilino sin contenerizar todo el gateway.

El ámbito del entorno aislado puede ser por agente (predeterminado), por sesión o compartido; cada ámbito obtiene su propio espacio de trabajo montado en /workspace. También se pueden 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 -- sustituciones por agente

Habilitación rápida

{  agents: {    defaults: {      sandbox: {        mode: "non-main", // desactivado | no principal | todos        scope: "agent", // sesión | agente | compartido      },    },  },}

Compile la imagen predeterminada del entorno aislado (desde una copia local del código fuente):

scripts/sandbox-setup.sh

Para instalaciones de npm sin una copia local del código fuente, consulte Entorno aislado § Imágenes y configuración para ver los 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 de Podman a Docker
• 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