Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

¿Docker es adecuado para mí?

  • : 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 en sandbox: el backend de sandbox predeterminado usa Docker cuando el aislamiento en sandbox está habilitado, pero el aislamiento en sandbox 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 Aislamiento en sandbox.

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 falta de memoria en hosts de 1 GB con salida 137)
  • Suficiente 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

1

Compilar la imagen

Desde la raíz del repositorio, ejecuta el script de configuración:
./scripts/docker/setup.sh
Esto compila la imagen del Gateway localmente. Para usar una imagen precompilada en su lugar:
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh
Las imágenes precompiladas se publican en GitHub Container Registry. Etiquetas comunes: main, latest, <version> (por ejemplo, 2026.2.26).
2

Completar la incorporación

El script de configuración ejecuta la incorporación automáticamente. Hará lo siguiente:
  • solicitar claves de API del proveedor
  • generar un token de Gateway y escribirlo en .env
  • crear el directorio de clave secreta del perfil de autenticación
  • iniciar el Gateway mediante Docker Compose
Durante la configuración, la incorporación previa al inicio y las escrituras de configuración se ejecutan directamente mediante openclaw-gateway. openclaw-cli es para comandos que ejecutas después de que el contenedor del Gateway ya existe.
3

Abrir la interfaz de control

Abre http://127.0.0.1:18789/ en tu navegador y pega el secreto compartido configurado en Ajustes. El script de configuración escribe un token en .env de forma predeterminada; si cambias la configuración del contenedor a autenticación por contraseña, usa esa contraseña en su lugar.¿Necesitas la URL otra vez?
docker compose run --rm openclaw-cli dashboard --no-open
4

Configurar canales (opcional)

Usa el contenedor de la CLI para añadir canales de mensajería:
# 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>"
Documentación: WhatsApp, Telegram, Discord

Flujo manual

Si prefieres ejecutar cada paso por tu cuenta 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-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
Ejecuta docker compose desde la raíz del repositorio. Si habilitaste OPENCLAW_EXTRA_MOUNTS u OPENCLAW_HOME_VOLUME, el script de configuración escribe docker-compose.extra.yml; inclúyelo con -f docker-compose.yml -f docker-compose.extra.yml.
Como openclaw-cli comparte el espacio de nombres de red de openclaw-gateway, es una herramienta posterior al inicio. Antes de docker compose up -d openclaw-gateway, ejecuta la incorporación y las escrituras de configuración durante la configuración mediante openclaw-gateway con --no-deps --entrypoint node.

Variables de entorno

El script de configuración acepta estas variables de entorno opcionales:
VariablePropósito
OPENCLAW_IMAGEUsar una imagen remota en lugar de compilar localmente
OPENCLAW_DOCKER_APT_PACKAGESInstalar paquetes apt adicionales durante la compilación (separados por espacios)
OPENCLAW_EXTENSIONSIncluir ayudantes de plugins incluidos seleccionados durante la compilación
OPENCLAW_EXTRA_MOUNTSMontajes bind de host adicionales (separados por comas source:target[:opts])
OPENCLAW_HOME_VOLUMEPersistir /home/node en un volumen Docker con nombre
OPENCLAW_SANDBOXOptar por el arranque de sandbox (1, true, yes, on)
OPENCLAW_SKIP_ONBOARDINGOmitir el paso de incorporación interactiva (1, true, yes, on)
OPENCLAW_DOCKER_SOCKETSobrescribir la ruta del socket de Docker
OPENCLAW_DISABLE_BONJOURDesactivar la publicidad Bonjour/mDNS (predeterminado en 1 para Docker)
OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYSDesactivar las superposiciones de montaje bind de código fuente de plugins incluidos
OTEL_EXPORTER_OTLP_ENDPOINTEndpoint compartido del recopilador OTLP/HTTP para exportación de OpenTelemetry
OTEL_EXPORTER_OTLP_*_ENDPOINTEndpoints OTLP específicos de señal para trazas, métricas o registros
OTEL_EXPORTER_OTLP_PROTOCOLSobrescritura del protocolo OTLP. Hoy solo se admite http/protobuf
OTEL_SERVICE_NAMENombre de servicio usado para recursos de OpenTelemetry
OTEL_SEMCONV_STABILITY_OPT_INOptar por los atributos semánticos experimentales GenAI más recientes
OPENCLAW_OTEL_PRELOADEDOmitir el inicio de un segundo SDK de OpenTelemetry cuando ya hay uno precargado
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 paquete compilado /app/dist/extensions/synology-chat correspondiente para el mismo id de plugin.

Observabilidad

La exportación de OpenTelemetry es saliente desde el contenedor del Gateway hacia tu recopilador 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 en tiempo de ejecución:
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 todavía 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 y luego establece diagnostics.otel.enabled=true o usa el ejemplo de configuración 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 usan el puerto ya publicado del Gateway. 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   # liveness
curl -fsS http://127.0.0.1:18789/readyz     # readiness
La imagen 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 de estado profunda autenticada:
docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

LAN frente a loopback

scripts/docker/setup.sh establece OPENCLAW_GATEWAY_BIND=lan de forma predeterminada 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.
Usa valores de modo de enlace en gateway.bind (lan / loopback / custom / tailnet / auto), no alias de host como 0.0.0.0 o 127.0.0.1.

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:
ProveedorURL predeterminada del hostURL de configuración de Docker
LM Studiohttp://127.0.0.1:1234http://host.docker.internal:1234
Ollamahttp://127.0.0.1:11434http://host.docker.internal:11434
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 alcanzable 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, añade tú mismo la misma asignación de host, por ejemplo --add-host=host.docker.internal:host-gateway.

Bonjour / mDNS

Las redes bridge de Docker normalmente no reenvían de forma fiable multicast Bonjour/mDNS (224.0.0.251:5353). Por eso, la configuración Compose incluida establece de forma predeterminada OPENCLAW_DISABLE_BONJOUR=1 para que el Gateway no entre en bucle 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. Establece OPENCLAW_DISABLE_BONJOUR=0 solo cuando ejecutes con redes de host, macvlan u otra red donde se sepa que multicast mDNS funciona. Para problemas habituales y solución de problemas, consulta descubrimiento Bonjour.

Almacenamiento y persistencia

Docker Compose monta mediante 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, por lo que esas rutas sobreviven al reemplazo del contenedor. Cuando alguna variable no está definida, el docker-compose.yml incluido usa como respaldo una ruta bajo ${HOME}, o /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 mantiene:
  • 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 tiempo de ejecución respaldados por variables de entorno, como OPENCLAW_GATEWAY_TOKEN
El directorio de clave secreta del perfil de autenticación almacena la clave de cifrado local usada para material de tokens de 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 su estado de paquete bajo el directorio 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 ver todos los detalles de persistencia en despliegues de VM, consulta Tiempo de ejecución de VM Docker - Qué persiste 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 facilitar la gestión diaria de Docker, 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 de ayudante 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 del ayudante.
export OPENCLAW_SANDBOX=1
./scripts/docker/setup.sh
Ruta de socket personalizada (por ejemplo, Docker sin root):
export OPENCLAW_SANDBOX=1
export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
./scripts/docker/setup.sh
El script monta docker.sock solo después de que los prerrequisitos del sandbox se cumplan. Si la configuración del sandbox no puede completarse, el script restablece agents.defaults.sandbox.mode a off. Los turnos de modo de código de Codex siguen estando restringidos a workspace-write de Codex mientras el sandbox de OpenClaw está activo; no montes el socket de Docker del host en contenedores de sandbox de agente.
Desactiva la asignación de seudo-TTY de Compose con -T:
docker compose run -T --rm openclaw-cli gateway probe
docker compose run -T --rm openclaw-cli devices list --json
openclaw-cli usa network_mode: "service:openclaw-gateway" para que los comandos de la CLI puedan llegar al Gateway por 127.0.0.1. Trátalo como un límite de confianza compartido. La configuración de Compose elimina NET_RAW/NET_ADMIN y habilita no-new-privileges tanto en openclaw-gateway como en openclaw-cli.
Algunas configuraciones de Docker Desktop fallan en las búsquedas DNS desde el sidecar openclaw-cli de red compartida después de eliminar NET_RAW, lo que aparece como EAI_AGAIN durante comandos respaldados por npm como openclaw plugins install. Mantén el archivo de Compose reforzado predeterminado para la operación normal del Gateway. La sobrescritura local de abajo relaja la postura de seguridad del contenedor de la CLI al restaurar las capacidades predeterminadas de Docker, así que úsala solo para el comando puntual de la CLI que necesita acceso al registro de paquetes, no como tu invocación de Compose predeterminada:
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>
Si ya creaste un contenedor openclaw-cli de larga duración, recréalo con la misma sobrescritura. docker compose exec y docker exec no pueden cambiar las capacidades de Linux en un contenedor ya creado.
La imagen se ejecuta como node (uid 1000). Si ves errores de permisos en /home/node/.openclaw, asegúrate de que tus montajes bind del host sean propiedad del uid 1000:
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
La misma discrepancia puede aparecer como una advertencia de plugin como blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) seguida de plugin present but blocked. Eso significa que el uid del proceso y el propietario del directorio de plugin montado no coinciden. Prefiere ejecutar el contenedor con el uid 1000 predeterminado y corregir la propiedad del montaje bind. Solo aplica chown a /path/to/openclaw-config/npm como root:root si ejecutas intencionalmente OpenClaw como root a largo plazo.
Ordena tu Dockerfile para que las capas de dependencias queden en caché. Esto evita volver a ejecutar pnpm install a menos que cambien los lockfiles:
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"]
La imagen predeterminada prioriza la seguridad y se ejecuta como node no root. Para un contenedor con más funciones:
  1. Persistir /home/node: export OPENCLAW_HOME_VOLUME="openclaw_home"
  2. Incluir dependencias del sistema: export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"
  3. Incluir Playwright Chromium: export OPENCLAW_INSTALL_BROWSER=1
  4. O instalar navegadores de Playwright en un volumen persistente:
    docker compose run --rm openclaw-cli \
      node /app/node_modules/playwright-core/cli.js install chromium
    
  5. Persistir descargas de navegadores: usa OPENCLAW_HOME_VOLUME o OPENCLAW_EXTRA_MOUNTS. OpenClaw detecta automáticamente el Chromium gestionado por Playwright de la imagen Docker en Linux.
Si eliges OAuth de OpenAI Codex en el asistente, se abre una URL del navegador. En Docker o configuraciones sin interfaz, copia la URL de redirección completa a la que llegues y pégala de nuevo en el asistente para finalizar la autenticación.
La imagen principal de tiempo de ejecución de Docker usa node:24-bookworm-slim e incluye tini como proceso init de punto de entrada (PID 1) para asegurar que los procesos zombi se recojan y que las señales se gestionen correctamente en contenedores de larga duración. Publica anotaciones de imagen base OCI, incluidas org.opencontainers.image.base.name, org.opencontainers.image.source y otras. El digest base de Node se actualiza mediante PRs de imagen base Docker de Dependabot; las compilaciones de lanzamiento no ejecutan una capa de actualización de distribución. Consulta anotaciones de imagen OCI.

¿Ejecutando en un VPS?

Consulta Hetzner (VPS Docker) y Tiempo de ejecución de VM Docker para pasos de despliegue de VM compartidos, incluidas la inclusión de binarios, la persistencia y las actualizaciones.

Sandbox de agente

Cuando agents.defaults.sandbox está habilitado con el backend de Docker, el Gateway ejecuta la ejecución de 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 un muro sólido 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 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:

Habilitació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 comandos docker build en línea.

Solución de problemas

Compila la imagen de sandbox con scripts/sandbox-setup.sh (checkout de código fuente) o el comando docker build en línea de Sandboxing § Imágenes y configuración (instalación npm), o establece agents.defaults.sandbox.docker.image en tu imagen personalizada. Los contenedores se crean automáticamente por sesión bajo demanda.
Establece docker.user en un UID:GID que coincida con la propiedad de tu espacio de trabajo montado, o aplica chown a la carpeta del espacio de trabajo.
OpenClaw ejecuta comandos con sh -lc (shell de inicio de sesión), que carga /etc/profile y puede restablecer PATH. Establece docker.env.PATH para anteponer tus rutas de herramientas personalizadas, o agrega un script bajo /etc/profile.d/ en tu Dockerfile.
La VM necesita al menos 2 GB de RAM. Usa una clase de máquina más grande y reintenta.
Obtén un enlace de dashboard nuevo y aprueba el dispositivo del navegador:
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>
Más detalles: Dashboard, Dispositivos.
Restablece el modo y el bind del Gateway:
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