Ejecuta OpenClaw en Podman rootless: Guía rápida

¿Alguna vez has sentido que gestionar contenedores como root es un riesgo innecesario para tu servidor? Si buscas una forma más segura y eficiente de desplegar tu Gateway, usar Podman en modo rootless es la mejor opción. Es una alternativa excelente a Docker que te permite mantener todo bajo control sin comprometer la seguridad de tu sistema.

Ejecuta el Gateway de OpenClaw en un contenedor de Podman sin privilegios de root. Utiliza la misma imagen que Docker (construida desde el Dockerfile del repositorio).

Requisitos

• Podman (rootless)
• Sudo para la configuración inicial (crear usuario, construir imagen)

Inicio rápido

1. Configuración inicial (desde la raíz del repositorio; crea el usuario, construye la imagen e instala el script de lanzamiento):

./setup-podman.sh

Esto también crea un archivo mínimo ~openclaw/.openclaw/openclaw.json (configura gateway.mode="local") para que el Gateway pueda arrancar sin ejecutar el asistente.

Por defecto, el contenedor no se instala como un servicio de systemd; debes iniciarlo manualmente (ver abajo). Para una configuración de tipo producción con inicio automático y reinicios, instálalo como un servicio de usuario Quadlet de systemd en su lugar:

./setup-podman.sh --quadlet

(O configura OPENCLAW_PODMAN_QUADLET=1; usa --container para instalar solo el contenedor y el script de lanzamiento).

Variables de entorno opcionales para la construcción (configúralas antes de ejecutar setup-podman.sh):

• OPENCLAW_DOCKER_APT_PACKAGES: instala paquetes apt adicionales durante la construcción de la imagen.
• OPENCLAW_EXTENSIONS: preinstala dependencias de extensiones (nombres de extensiones separados por espacios, ej. diagnostics-otel matrix).

2. Iniciar el Gateway (manual, para pruebas rápidas):

./scripts/run-openclaw-podman.sh launch

3. Asistente de configuración (ej. para añadir canales o proveedores):

./scripts/run-openclaw-podman.sh launch setup

Luego abre http://127.0.0.1:18789/ y usa el token de ~openclaw/.openclaw/.env (o el valor impreso durante la configuración).

Systemd (Quadlet, opcional)

Si ejecutaste ./setup-podman.sh --quadlet (o OPENCLAW_PODMAN_QUADLET=1), se instala una unidad de Podman Quadlet para que el Gateway funcione como un servicio de usuario de systemd para el usuario openclaw. El servicio se habilita e inicia al final de la configuración.

• Iniciar: sudo systemctl --machine openclaw@ --user start openclaw.service
• Detener: sudo systemctl --machine openclaw@ --user stop openclaw.service
• Estado: sudo systemctl --machine openclaw@ --user status openclaw.service
• Logs: sudo journalctl --machine openclaw@ --user -u openclaw.service -f

El archivo quadlet se encuentra en ~openclaw/.config/containers/systemd/openclaw.container. Para cambiar puertos o el entorno, edita ese archivo (o el .env que utiliza), luego ejecuta sudo systemctl --machine openclaw@ --user daemon-reload y reinicia el servicio. Al arrancar el sistema, el servicio se inicia automáticamente si el “lingering” está habilitado para openclaw (la configuración hace esto cuando loginctl está disponible).

Para añadir quadlet después de una configuración inicial que no lo usó, vuelve a ejecutar: ./setup-podman.sh --quadlet.

El usuario openclaw (sin login)

setup-podman.sh crea un usuario de sistema dedicado llamado openclaw:

• Shell: nologin: no permite inicio de sesión interactivo, lo que reduce la superficie de ataque.

• Home: ej. /home/openclaw: contiene ~/.openclaw (configuración, workspace) y el script de lanzamiento run-openclaw-podman.sh.

• Rootless Podman: El usuario debe tener un rango de subuid y subgid. Muchas distribuciones los asignan automáticamente al crear el usuario. Si la configuración muestra una advertencia, añade estas líneas a /etc/subuid y /etc/subgid:

  openclaw:100000:65536

  Luego inicia el Gateway como ese usuario (ej. desde cron o systemd):

  sudo -u openclaw /home/openclaw/run-openclaw-podman.sh
  sudo -u openclaw /home/openclaw/run-openclaw-podman.sh setup

• Configuración: Solo openclaw y root pueden acceder a /home/openclaw/.openclaw. Para editar la configuración: usa la Control UI una vez que el Gateway esté funcionando, o ejecuta sudo -u openclaw $EDITOR /home/openclaw/.openclaw/openclaw.json.

Entorno y configuración

• Token: Se guarda en ~openclaw/.openclaw/.env como OPENCLAW_GATEWAY_TOKEN. setup-podman.sh y run-openclaw-podman.sh lo generan si falta (usa openssl, python3 o od).
• Opcional: En ese archivo .env puedes configurar claves de proveedores (ej. GROQ_API_KEY, OLLAMA_API_KEY) y otras variables de entorno de OpenClaw.
• Puertos del host: Por defecto, el script mapea el 18789 (Gateway) y el 18790 (bridge). Puedes sobrescribir el mapeo de puertos del host con OPENCLAW_PODMAN_GATEWAY_HOST_PORT y OPENCLAW_PODMAN_BRIDGE_HOST_PORT al lanzar.
• Bind del Gateway: Por defecto, run-openclaw-podman.sh inicia el Gateway con --bind loopback para un acceso local seguro. Para exponerlo en la LAN, configura OPENCLAW_GATEWAY_BIND=lan y ajusta gateway.controlUi.allowedOrigins (o habilita explícitamente el fallback de host-header) en openclaw.json.
• Rutas: La configuración y el workspace del host por defecto son ~openclaw/.openclaw y ~openclaw/.openclaw/workspace. Sobrescribe las rutas del host usadas por el script de lanzamiento con OPENCLAW_CONFIG_DIR y OPENCLAW_WORKSPACE_DIR.

Modelo de almacenamiento

• Datos persistentes en el host: OPENCLAW_CONFIG_DIR y OPENCLAW_WORKSPACE_DIR se montan mediante bind-mount en el contenedor y mantienen su estado en el host.
• Sandbox efímero en tmpfs: si habilitas agents.defaults.sandbox, los contenedores de sandbox de herramientas montan tmpfs en /tmp, /var/tmp y /run. Esas rutas están respaldadas por memoria y desaparecen con el contenedor del sandbox; la configuración del contenedor Podman de nivel superior no añade sus propios montajes tmpfs.
• Puntos críticos de crecimiento en disco: las rutas principales a vigilar son media/, agents/<agentId>/sessions/sessions.json, archivos JSONL de transcripciones, cron/runs/*.jsonl y los logs rotativos bajo /tmp/openclaw/ (o tu logging.file configurado).

setup-podman.sh prepara la imagen tar en un directorio temporal privado e imprime el directorio base elegido durante la configuración. Para ejecuciones sin root, acepta TMPDIR solo cuando esa base es segura de usar; de lo contrario, recurre a /var/tmp y luego a /tmp. El tar guardado permanece solo para el propietario y se transmite al podman load del usuario de destino, por lo que los directorios temporales privados del llamador no bloquean la configuración.

Comandos útiles

• Logs: Con quadlet: sudo journalctl --machine openclaw@ --user -u openclaw.service -f. Con script: sudo -u openclaw podman logs -f openclaw
• Detener: Con quadlet: sudo systemctl --machine openclaw@ --user stop openclaw.service. Con script: sudo -u openclaw podman stop openclaw
• Iniciar de nuevo: Con quadlet: sudo systemctl --machine openclaw@ --user start openclaw.service. Con script: vuelve a ejecutar el script de lanzamiento o podman start openclaw
• Eliminar contenedor: sudo -u openclaw podman rm -f openclaw: la configuración y el workspace en el host se mantienen.

Solución de problemas

• Permiso denegado (EACCES) en config o auth-profiles: El contenedor usa por defecto --userns=keep-id y se ejecuta con el mismo uid/gid que el usuario del host que ejecuta el script. Asegúrate de que OPENCLAW_CONFIG_DIR y OPENCLAW_WORKSPACE_DIR en tu host pertenezcan a ese usuario.
• Inicio del Gateway bloqueado (falta gateway.mode=local): Asegúrate de que ~openclaw/.openclaw/openclaw.json exista y tenga configurado gateway.mode="local". setup-podman.sh crea este archivo si no existe.
• Podman rootless falla para el usuario openclaw: Revisa que /etc/subuid y /etc/subgid contengan una línea para openclaw (ej. openclaw:100000:65536). Añádela si falta y reinicia.
• Nombre de contenedor en uso: El script de lanzamiento usa podman run --replace, por lo que el contenedor existente se reemplaza al iniciar de nuevo. Para limpiar manualmente: podman rm -f openclaw.
• Script no encontrado al ejecutar como openclaw: Asegúrate de que setup-podman.sh se haya ejecutado para que run-openclaw-podman.sh esté copiado en el home de openclaw (ej. /home/openclaw/run-openclaw-podman.sh).
• Servicio Quadlet no encontrado o falla al iniciar: Ejecuta sudo systemctl --machine openclaw@ --user daemon-reload después de editar el archivo .container. Quadlet requiere cgroups v2: podman info --format '{{.Host.CgroupsVersion}}' debería mostrar 2.

Opcional: ejecutar como tu propio usuario

Para ejecutar el Gateway como tu usuario normal (sin un usuario openclaw dedicado): construye la imagen, crea ~/.openclaw/.env con OPENCLAW_GATEWAY_TOKEN y ejecuta el contenedor con --userns=keep-id y montajes a tu ~/.openclaw. El script de lanzamiento está diseñado para el flujo del usuario openclaw; para una configuración de usuario único, puedes ejecutar manualmente el comando podman run del script, apuntando la configuración y el workspace a tu home. Recomendación para la mayoría de los usuarios: usa setup-podman.sh y ejecútalo como el usuario openclaw para que la configuración y el proceso estén aislados.

Pasos siguientes

• Configuración de proveedores de IA
• Gestión de canales

AI Setup Assistant