Saltar al contenido principal

​
Docker (opcional)

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: lo 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 sandboxing de agentes también usa Docker, pero no requiere que todo el gateway se ejecute en Docker. 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 finalizar por OOM en hosts de 1 GB con salida 137)
  • Suficiente disco para imágenes y registros
  • 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

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 API del proveedor
  • generar un token de gateway y escribirlo en .env
  • iniciar el gateway mediante Docker Compose
Durante la configuración, la incorporación previa al inicio y las escrituras de configuración se ejecutan mediante openclaw-gateway directamente. openclaw-cli es para los comandos que ejecutas después de que el contenedor del gateway ya existe.
3

Abrir la Control UI

Abre http://127.0.0.1:18789/ en tu navegador y pega el secreto compartido configurado en Settings. 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 CLI para agregar 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 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-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 o 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.
Debido a que 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 en tiempo de 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_EXTENSIONSPreinstalar dependencias de extensiones en tiempo de compilación (nombres separados por espacios)
OPENCLAW_EXTRA_MOUNTSMontajes bind adicionales del host (separados por comas source:target[:opts])
OPENCLAW_HOME_VOLUMEPersistir /home/node en un volumen Docker con nombre
OPENCLAW_SANDBOXActivar el arranque del sandbox (1, true, yes, on)
OPENCLAW_DOCKER_SOCKETSobrescribir la ruta del socket de Docker

​
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 consulta /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 vs loopback

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

​
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. Ese directorio de configuración montado es donde OpenClaw guarda:
  • openclaw.json para la configuración de comportamiento
  • agents/<agentId>/agent/auth-profiles.json para la autenticación OAuth/claves API almacenada del proveedor
  • .env para secretos de tiempo de ejecución respaldados por variables de entorno, como OPENCLAW_GATEWAY_TOKEN
Para obtener detalles completos de persistencia en implementaciones en VM, consulta Docker VM Runtime - What persists where. Puntos críticos de crecimiento en disco: vigila media/, los archivos JSONL de sesión, cron/runs/*.jsonl, y los registros rotativos bajo /tmp/openclaw/.

​
Ayudantes de shell (opcional)

Para una gestión diaria más sencilla 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 antigua ruta raw scripts/shell-helpers/clawdock-helpers.sh, vuelve a ejecutar el comando de instalación anterior para que tu archivo 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 rootless):
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 se cumplan los requisitos previos del sandbox. Si la configuración del sandbox no puede completarse, el script restablece agents.defaults.sandbox.mode a off.
Deshabilita la asignación de pseudo-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 alcanzar el gateway a través de 127.0.0.1. Trata esto como un límite de confianza compartido. La configuración de compose elimina NET_RAW/NET_ADMIN y habilita no-new-privileges en openclaw-cli.
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 pertenezcan a uid 1000:
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
Ordena tu Dockerfile para que las capas de dependencias se almacenen 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 sin privilegios de root. Para un contenedor más completo:
  1. Persistir /home/node: export OPENCLAW_HOME_VOLUME="openclaw_home"
  2. Incluir dependencias del sistema: export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"
  3. Instalar navegadores de Playwright: 
    docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium
  4. Persistir descargas del navegador: establece PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright y usa OPENCLAW_HOME_VOLUME o OPENCLAW_EXTRA_MOUNTS.
Si eliges OAuth de OpenAI Codex en el asistente, se abre una URL en el navegador. En configuraciones Docker o sin interfaz gráfica, copia la URL completa de redirección a la que llegues y pégala de vuelta en el asistente para completar la autenticación.
La imagen principal de Docker usa node:24-bookworm y publica anotaciones OCI de imagen base incluyendo org.opencontainers.image.base.name, org.opencontainers.image.source y otras. Consulta OCI image annotations.

​
¿Ejecutarlo en un VPS?

Consulta Hetzner (Docker VPS) y Docker VM Runtime para ver los pasos compartidos de implementación en VM, incluidos la incorporación de binarios, persistencia y actualizaciones.

​
Sandbox de agentes

Cuando agents.defaults.sandbox está habilitado, el gateway ejecuta la ejecución de herramientas del agente (shell, lectura/escritura de archivos, etc.) dentro de contenedores Docker aislados, mientras que el gateway en sí permanece en el host. Esto te da una barrera sólida alrededor de sesiones de agentes no confiables o multiinquilino sin poner en contenedor todo el gateway. El alcance del sandbox puede ser por agente (predeterminado), por sesión o compartido. Cada alcance obtiene su propio workspace 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 ver 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 predeterminada del sandbox: 
scripts/sandbox-setup.sh

​
Solución de problemas

Compila la imagen del sandbox con scripts/sandbox-setup.sh 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 workspace montado, o ejecuta chown sobre la carpeta del workspace.
OpenClaw ejecuta comandos con sh -lc (shell de login), que obtiene /etc/profile y puede restablecer PATH. Establece docker.env.PATH para anteponer tus rutas de herramientas personalizadas, o agrega un script en /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 vuelve a intentarlo.
Obtén un enlace nuevo del panel 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, Devices.
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