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 ejecutando 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 sandboxing: el backend de sandbox predeterminado usa Docker cuando el sandboxing está habilitado, pero el sandboxing está desactivado de forma predeterminada y no requiere que todo el Gateway se ejecute en Docker. Los backends de sandbox SSH y OpenShell también están disponibles. 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 terminarse por OOM en hosts de 1 GB con salida 137)
• Espacio suficiente en disco para imágenes y logs
• Si se ejecuta en un VPS/host público, revisa Endurecimiento 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

docker compose run --rm openclaw-cli dashboard --no-open

# 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>"

# Flujo manual

Si prefieres ejecutar cada paso tú mismo en vez 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-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

# Variables de entorno

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

Los mantenedores pueden probar el código fuente de plugins incluidos 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 bundle compilado correspondiente /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 realiza el scrape:

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   # liveness
curl -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 establece 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 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

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 Docker incluida usa esas URL del host como valores predeterminados de incorporación de 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 accesible desde Docker:

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

Si usas tu propio archivo Compose o comando docker run, agrega tú mismo el mismo mapeo de host, por ejemplo --add-host=host.docker.internal:host-gateway.

# Bonjour / mDNS

Las redes bridge de Docker normalmente no reenvían multicast Bonjour/mDNS (224.0.0.251:5353) de forma fiable. Por eso, la configuración Compose incluida establece de forma predeterminada OPENCLAW_DISABLE_BONJOUR=1 para que el Gateway no entre en un bucle de fallos ni reinicie repetidamente los anuncios cuando el bridge descarta el tráfico multicast.

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

Para problemas comunes y solución de problemas, consulta Descubrimiento Bonjour.

# Almacenamiento y persistencia

Docker Compose monta con bind OPENCLAW_CONFIG_DIR en /home/node/.openclaw y OPENCLAW_WORKSPACE_DIR en /home/node/.openclaw/workspace, por lo que esas rutas sobreviven al reemplazo del contenedor. Cuando alguna variable no está establecida, el docker-compose.yml incluido recurre a ${HOME}/.openclaw (y ${HOME}/.openclaw/workspace para el montaje del workspace), o a /tmp/.openclaw cuando también falta HOME. 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 mantiene:

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

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

Para detalles completos de persistencia en despliegues de VM, consulta Docker VM Runtime: qué persiste y dónde.

Puntos críticos de crecimiento del disco: vigila media/, los archivos JSONL de sesión, cron/runs/*.jsonl, las raíces de paquetes de plugins instalados y los registros de archivo rotativos 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.sh
echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

Si instalaste ClawDock desde la ruta sin procesar anterior scripts/shell-helpers/clawdock-helpers.sh, vuelve a ejecutar el comando de instalación anterior para que tu archivo auxiliar local 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 ver la guía completa de ayudantes.

export OPENCLAW_SANDBOX=1
./scripts/docker/setup.sh

export OPENCLAW_SANDBOX=1
export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
./scripts/docker/setup.sh

docker compose run -T --rm openclaw-cli gateway probe
docker compose run -T --rm openclaw-cli devices list --json

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

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"]

# ¿Ejecutarlo en un VPS?

Consulta Hetzner (Docker VPS) y Docker VM Runtime para ver los pasos de despliegue en VM compartida, incluida la incorporación de binarios, la persistencia y las actualizaciones.

# Entorno aislado de 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 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 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, 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 de origen):

scripts/sandbox-setup.sh

Para instalaciones npm sin un checkout de origen, 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-open
docker compose run --rm openclaw-cli devices list
docker 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 de Docker Compose
• Actualización — mantener OpenClaw actualizado
• Configuración — configuración del Gateway después de la instalación