Configuración de Docker (Opcional)

Configurar entornos de desarrollo puede ser un proceso frustrante. A veces solo quieres que las cosas funcionen sin pasar horas instalando dependencias que podrían entrar en conflicto con tu configuración local.

Docker aparece como una solución para mantener todo limpio, permitiendo que tu Gateway se ejecute en un entorno aislado y controlado.

Requisitos previos

Para este paso, solo necesitas lo siguiente:

• Docker instalado en tu sistema.
• Una terminal activa.

Inicio rápido

Docker es opcional. No necesitas configurarlo a menos que tengas un objetivo específico en mente. Te recomiendo usarlo únicamente en estos dos escenarios:

1. Gateway contenedorizado: Si prefieres ejecutar tu Gateway dentro de un contenedor para mantener la consistencia entre entornos.
2. Validación: Si necesitas comprobar que el flujo de trabajo de Docker funciona según lo esperado en tu implementación.

Si no encajas en estas situaciones, puedes saltarte este paso y continuar con la instalación estándar.

Solución de problemas

La documentación actual no reporta problemas específicos ni errores comunes para este proceso, ya que su implementación es complementaria al flujo principal.

Si tienes dudas específicas sobre tu configuración, consulta al AI Setup Assistant.

Próximos pasos

• Configuración de API
• Guía del Gateway

---
title: "¿Es Docker la opción adecuada para ti?"
description: "Decide si debes ejecutar OpenClaw en Docker o de forma local según tus necesidades de desarrollo y aislamiento."
---

Configurar entornos locales suele ser un dolor de cabeza. A veces terminas con la máquina llena de dependencias y versiones de Node.js que solo usaste para un proyecto rápido. Es frustrante cuando quieres probar algo nuevo y terminas rompiendo la configuración de tu sistema principal.

Si estás dudando sobre usar Docker con OpenClaw, aquí tienes mi recomendación directa para que elijas el mejor camino.

### ¿Es Docker para mí?

- **Sí**: quieres un entorno de Gateway aislado y desechable, o necesitas ejecutar OpenClaw en un host sin realizar instalaciones locales.
- **No**: estás trabajando en tu propia máquina y buscas el ciclo de desarrollo (dev loop) más rápido. Si es así, usa el flujo de instalación normal.

**Nota sobre Sandboxing**: el sandboxing de agentes también utiliza Docker, pero **no** requiere que el Gateway completo se ejecute dentro de Docker. Puedes ver más detalles en [Sandboxing](/docs/gateway/sandboxing).

Esta guía cubre:
- Gateway contenedorizado (OpenClaw completo en Docker).
- Sandbox de agente por sesión (Gateway en el host + herramientas de agente aisladas en Docker).

Para más detalles sobre el aislamiento, consulta: [Sandboxing](/docs/gateway/sandboxing).

### What You'll Need

Antes de empezar, asegúrate de cumplir con estos requisitos:
- Docker Desktop (o Docker Engine) + Docker Compose v2.
- Suficiente espacio en disco para almacenar imágenes y logs.

### Quick Start

Si decides que Docker es tu mejor opción, sigue estos pasos para tener el entorno listo en menos de 5 minutos:

1. Elige si quieres el Gateway completo en contenedor o solo el Sandbox para agentes.
2. Verifica que Docker Compose v2 esté activo en tu terminal.
3. Configura el almacenamiento para los logs según tus necesidades de espacio.

### Troubleshooting

Aquí tienes un par de puntos que pueden fallar y cómo solucionarlos:

- **Falta de espacio**: Docker consume disco rápidamente con las imágenes y logs. Revisa tu almacenamiento si el Gateway deja de responder.
- **Versión de Compose**: Si usas una versión anterior a la v2, podrías encontrar errores de compatibilidad. Actualiza Docker Desktop o Docker Engine.

¿Necesitas ayuda personalizada para tu configuración? Prueba el [AI Setup Assistant](/docs/).

### What's Next
- [Sandboxing](/docs/gateway/sandboxing)

¿Alguna vez has pasado horas configurando dependencias solo para descubrir que algo falla por una versión distinta de Node.js? Gestionar entornos locales y remotos suele ser frustrante cuando las librerías del sistema no coinciden o los permisos de archivos causan errores inesperados.

Usar Docker Compose elimina estos problemas de raíz. Te permite empaquetar todo lo necesario en un contenedor, garantizando que el Gateway funcione exactamente igual en tu máquina que en un VPS.

What You’ll Need

Para seguir esta guía, necesitas tener instalado lo siguiente:

• Docker y Docker Compose.
• El repositorio clonado localmente.
• Acceso a la terminal en la raíz del proyecto.

Quick Start

Esta es la ruta de 5 minutos recomendada para tener todo listo. Ejecuta este comando desde la raíz del repositorio:

./docker-setup.sh

Este script automatiza varias tareas:

• Construye la imagen del Gateway.
• Ejecuta el asistente de configuración (onboarding wizard).
• Muestra consejos para configurar proveedores.
• Inicia el Gateway mediante Docker Compose.
• Genera un token y lo escribe en tu archivo .env.

Puedes usar estas variables de entorno opcionales:

• OPENCLAW_DOCKER_APT_PACKAGES: Instala paquetes apt adicionales durante la construcción.
• OPENCLAW_EXTRA_MOUNTS: Añade montajes bind adicionales desde el host.
• OPENCLAW_HOME_VOLUME: Persiste la carpeta /home/node en un volumen con nombre.

Cuando el proceso termine:

1. Abre http://127.0.0.1:18789/ en tu navegador.
2. Pega el token en la Control UI (Settings → token).
3. Si necesitas la URL de nuevo, ejecuta: docker compose run --rm openclaw-cli dashboard --no-open.

El sistema guarda la configuración y el workspace en estas rutas de tu host:

• ~/.openclaw/
• ~/.openclaw/workspace

Si estás usando un VPS, consulta la guía de Hetzner (Docker VPS).

Shell Helpers (opcional)

Para gestionar Docker en el día a día, instala ClawDock:

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh

Añádelo a tu configuración de shell (zsh):

echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

Ahora puedes usar comandos como clawdock-start, clawdock-stop, clawdock-dashboard o clawdock-help. Tienes más detalles en el README de ClawDock Helper.

Flujo manual (Compose)

Si prefieres no usar el script automático, sigue estos pasos:

docker build -t openclaw:local -f Dockerfile .
docker compose run --rm openclaw-cli onboard
docker compose up -d openclaw-gateway

Ejecuta siempre docker compose desde la raíz. Si activaste OPENCLAW_EXTRA_MOUNTS o OPENCLAW_HOME_VOLUME, el script de configuración genera un archivo docker-compose.extra.yml. Debes incluirlo en tus comandos:

docker compose -f docker-compose.yml -f docker-compose.extra.yml <command>

Configuración avanzada y persistencia

Montajes adicionales

Para montar directorios extra del host en los contenedores, define OPENCLAW_EXTRA_MOUNTS antes de lanzar el script. Usa una lista separada por comas:

export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

Persistencia de la home del contenedor

Si quieres que /home/node sobreviva a la recreación de contenedores, usa un volumen con nombre:

export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh

Instalación de paquetes apt

Si necesitas herramientas de compilación o librerías multimedia, usa OPENCLAW_DOCKER_APT_PACKAGES:

export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential"
./docker-setup.sh

Contenedor para Power-users

La imagen por defecto prioriza la seguridad y corre como el usuario node (no-root). Esto implica que no hay instalación de paquetes en runtime ni navegadores Chromium por defecto.

Si necesitas todas las funciones, sigue estos pasos:

1. Persiste /home/node para mantener descargas y caches:

export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh

2. Incluye dependencias en la imagen:

export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"
./docker-setup.sh

3. Instala navegadores Playwright sin npx:

docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

4. Persiste descargas de Playwright: Configura PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright en tu docker-compose.yml y asegúrate de que la ruta sea persistente.

Optimización de rebuilds

Para acelerar la construcción de la imagen, usa este orden en tu Dockerfile para aprovechar la cache de capas:

FROM node:22-bookworm

# Install Bun (required for build scripts)
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"

RUN corepack enable

WORKDIR /app

# Cache dependencies unless package metadata changes
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"]

Configuración de canales

Usa el contenedor de la CLI para configurar tus canales:

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

Troubleshooting

• Error de permisos (EACCES): La imagen usa el uid 1000. Si tienes errores en /home/node/.openclaw, ajusta los permisos en tu host: sudo chown -R 1000:1000 /ruta/config /ruta/workspace
• Token o Pairing: Si ves mensajes de “unauthorized” o “pairing required”, genera un nuevo link y aprueba el dispositivo:

  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>

• OpenAI Codex OAuth: En entornos headless, la redirección a 127.0.0.1:1455 fallará en el navegador. Copia la URL completa de la página de error y pégala en el asistente de la terminal para completar la autenticación.
• Health check: Verifica el estado con este comando: docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

Si necesitas ayuda personalizada, consulta nuestro AI Setup Assistant.

What’s Next

• Dashboard
• Devices
• WhatsApp
• Telegram

Seguro que te ha pasado: quieres que tu agente ejecute scripts o manipule archivos, pero te da pánico que termine borrando algo importante en tu sistema o accediendo a datos privados. Es el dilema clásico de darle libertad al agente sin comprometer tu máquina.

La solución es usar un Sandbox. Te permite ejecutar herramientas en un entorno controlado sin que el Gateway pierda el control de la sesión. Es la mejor forma de trabajar si buscas seguridad y orden en tus flujos de trabajo con agentes.

Requisitos previos

Para configurar esto, solo necesitas lo que indica la documentación oficial:

• Docker instalado y funcionando.
• Acceso a los scripts de configuración en el repositorio (scripts/).
• El archivo de configuración de tu Gateway listo para editar.

Inicio rápido

Si quieres tener esto listo en menos de 5 minutos, sigue estos pasos:

1. Construye la imagen base: Ejecuta el script para crear la imagen de Docker necesaria:

   scripts/sandbox-setup.sh

2. Activa el Sandbox en tu configuración: Añade esto a tu archivo de configuración para habilitar el aislamiento en sesiones que no sean la principal:

   {
     agents: {
       defaults: {
         sandbox: {
           mode: "non-main",
           scope: "agent"
         }
       }
     }
   }

3. Reinicia tu Gateway: Al detectar los cambios, las herramientas ahora se ejecutarán dentro de contenedores Docker.

Cómo funciona el Sandbox

Cuando activas agents.defaults.sandbox, las sesiones que no son la principal ejecutan sus herramientas dentro de un contenedor Docker. El Gateway se queda en tu host, pero la ejecución está aislada. Aquí tienes los detalles clave:

• Scope: Por defecto es "agent" (un contenedor y workspace por agente). Puedes cambiarlo a "session" si quieres aislamiento total por cada sesión.
• Workspace: Cada entorno tiene una carpeta montada en /workspace.
• Media: Los archivos multimedia entrantes se copian a media/inbound/* dentro del workspace para que las herramientas puedan leerlos.
• Acceso opcional: Puedes configurar agents.defaults.sandbox.workspaceAccess para decidir cuánto puede ver el agente de tu sistema.

Aviso importante: Si usas scope: "shared", desactivas el aislamiento entre sesiones. Todas compartirán el mismo contenedor y workspace.

Configuración por agente (Multi-agent)

Si usas rutas para múltiples agentes, cada uno puede tener su propia configuración de Sandbox y herramientas usando agents.list[].sandbox. Esto te permite mezclar niveles de acceso:

1. Acceso total para tu agente personal y herramientas de solo lectura con workspace limitado para agentes de trabajo.
2. Agentes públicos sin acceso a herramientas de shell o sistema de archivos.

Si necesitas ejemplos de precedencia, revisa Multi-Agent Sandbox & Tools.

Comportamiento por defecto

El Sandbox viene con una configuración predefinida para que no tengas que empezar de cero:

• Imagen: openclaw-sandbox:bookworm-slim
• Red: none por defecto (tienes que activarla explícitamente si necesitas salida a internet).
• Auto-prune: Se eliminan contenedores inactivos tras 24 horas o si tienen más de 7 días de antigüedad.
• Workspace: El valor workspaceAccess: "none" usa ~/.openclaw/sandboxes.
  • "ro": Monta el workspace del agente en /agent como solo lectura (desactiva write, edit y apply_patch).
  • "rw": Monta el workspace en /workspace con permisos de lectura y escritura.

Herramientas permitidas y denegadas

• Permitidas (Allow): exec, process, read, write, edit, sessions_list, sessions_history, sessions_send, sessions_spawn, session_status.
• Denegadas (Deny): browser, canvas, nodes, cron, discord, gateway.

Configuración completa

Aquí tienes un ejemplo con todos los parámetros que puedes ajustar en agents.defaults.sandbox.docker, incluyendo límites de memoria y seguridad:

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
        },
        prune: {
          idleHours: 24,
          maxAgeDays: 7,
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec", "process", "read", "write", "edit",
          "sessions_list", "sessions_history", "sessions_send",
          "sessions_spawn", "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

Imágenes especializadas

Sandbox con herramientas comunes

Si necesitas Node, Go o Rust, puedes construir una imagen más completa:

scripts/sandbox-common-setup.sh

Luego, cambia la imagen en tu configuración a openclaw-sandbox-common:bookworm-slim.

Sandbox para el Browser

Para ejecutar la herramienta browser dentro del contenedor:

1. Construye la imagen: scripts/sandbox-browser-setup.sh.
2. Activa el navegador en la configuración:

{
  agents: {
    defaults: {
      sandbox: {
        browser: { enabled: true },
      },
    },
  },
}

Esto usa Chromium con CDP y un observador noVNC opcional. Recuerda que si usas una lista de permitidos (allow), debes añadir browser manualmente.

Políticas de herramientas y limpieza

La lógica de las herramientas es sencilla: deny siempre gana. Si allow está vacío, todas las herramientas están disponibles (menos las que estén en deny). Si allow tiene elementos, solo esos estarán disponibles.

Para la limpieza de contenedores (Pruning), tienes dos opciones:

• prune.idleHours: Elimina contenedores sin uso tras X horas.
• prune.maxAgeDays: Elimina contenedores que superen X días de vida.

Solución de problemas

Si tienes problemas al configurar el Sandbox, revisa estos puntos basados en la documentación:

• Fallo al instalar paquetes en setupCommand: Verifica que docker.network no esté en "none". Si readOnlyRoot es true, no podrás instalar nada. Además, asegúrate de que el user sea root (omítelo o usa "0:0") para ejecutar apt-get.
• Los cambios no se aplican: OpenClaw recrea los contenedores cuando cambia la configuración, a menos que el contenedor haya sido usado recientemente (menos de 5 minutos). Si está “caliente”, verás un aviso en el log con el comando exacto para forzar la recreación: openclaw sandbox recreate ....
• Aislamiento roto: Ten cuidado, permitir la herramienta browser en el sandbox rompe el aislamiento porque el navegador se ejecuta en el host.

Notas de seguridad

El muro de seguridad solo se aplica a las herramientas de ejecución y archivos (exec, read, write, etc.). Las herramientas que solo funcionan en el host, como la cámara o el canvas, están bloqueadas por defecto en el entorno de Sandbox.

Si tienes dudas sobre cómo configurar un parámetro específico, usa el AI Setup Assistant.

Próximos pasos

• Sandboxing Deep Dive
• Multi-Agent Sandbox & Tools

Configurar entornos de desarrollo aislados suele ser un reto cuando los permisos de archivos o las variables de entorno no cooperan. Es frustrante intentar ejecutar un agente y encontrarte con que el contenedor no arranca o que tus herramientas personalizadas simplemente no aparecen.

Si estás teniendo problemas para que tu Sandbox funcione correctamente, no pierdas tiempo probando configuraciones al azar. Aquí tienes las soluciones directas a los fallos más frecuentes basados en la configuración de Docker de OpenClaw.

Requisitos previos

• Acceso al repositorio de OpenClaw y al script scripts/sandbox-setup.sh.
• Archivo de configuración para modificar agents.defaults.sandbox.docker.

Inicio rápido

Si quieres solucionar los problemas de imagen y permisos rápido, sigue estos dos pasos:

1. Ejecuta el script de configuración inicial:

   ./scripts/sandbox-setup.sh

2. Asegura que el UID:GID en docker.user coincida con el dueño de tu carpeta de trabajo.

Solución de problemas

Aquí tienes las soluciones a los problemas documentados:

• Falta la imagen de Docker: Si el sistema no encuentra la imagen, debes construirla usando scripts/sandbox-setup.sh o definir manualmente el parámetro agents.defaults.sandbox.docker.image en tu configuración.
• El contenedor no aparece como “ejecutándose”: No es un error. OpenClaw crea el contenedor de forma automática por cada sesión y solo bajo demanda.
• Errores de permisos en el Sandbox: Este fallo ocurre cuando los permisos del contenedor no coinciden con los de tu máquina. Configura docker.user con un UID:GID que sea dueño de tu workspace montado, o aplica un chown a la carpeta del workspace.
• No se encuentran las herramientas (Custom tools): OpenClaw ejecuta comandos usando sh -lc (login shell), lo que carga /etc/profile y puede resetear tu PATH. Tienes dos opciones:
  • Configura docker.env.PATH para incluir tus rutas (ej. /custom/bin:/usr/local/share/npm-global/bin).
  • Añade un script dentro de /etc/profile.d/ en tu Dockerfile.

¿Necesitas ayuda con una configuración específica? Prueba el AI Setup Assistant.

Próximos pasos

• Configuración de Agentes
• Guía de Docker Sandbox