Saltar a contenido

svc-openclaw

A. Identidad

  • service_id: svc-openclaw
  • nombre: OpenClaw
  • estado: activo y healthy al 2026-06-01
  • owner: Gabi
  • criticidad: alta
  • fecha de alta: 2026-05-29
  • ultima revision: 2026-06-01

B. Proposito

  • resumen funcional: plataforma principal de agentes, chat y operaciones de OpenClaw.
  • rol dentro del VPS: aplicacion principal publicada para uso operativo.
  • por que existe: centraliza la experiencia funcional que hoy justifica el VPS.

C. Ubicacion

  • path VPS: /opt/stacks/openclaw
  • path repo/docs: docker/openclaw/ y docs/governance/services/svc-openclaw.md
  • compose file: /opt/stacks/openclaw/docker-compose.yml
  • .env real: pendiente de validar si existe archivo .env separado o si la configuracion vive en compose/config
  • archivos criticos:
  • /opt/stacks/openclaw/docker-compose.yml
  • /opt/stacks/openclaw/config/config.yaml
  • /opt/stacks/openclaw/config/agents/main/agent/auth-profiles.json
  • /opt/stacks/openclaw/config/agents/main/agent/auth-state.json
  • /opt/stacks/openclaw/config/identity/device-auth.json

D. Docker

  • stack: openclaw
  • container names:
  • openclaw-openclaw-gateway-1
  • image/tag: ghcr.io/openclaw/openclaw:2026.5.5
  • restart policy: unless-stopped
  • healthcheck: HTTP interno a /healthz sobre 18789
  • networks:
  • proxy-network
  • openclaw_openclaw_internal
  • volumes:
  • bind mounts sobre /opt/stacks/openclaw/config
  • bind mounts sobre /opt/stacks/openclaw/workspace
  • bind mounts sobre /opt/stacks/openclaw/auth-profile-secrets
  • bind mounts:
  • /opt/stacks/openclaw/config
  • /opt/stacks/openclaw/workspace
  • /opt/stacks/openclaw/auth-profile-secrets
  • exposed ports:
  • 18789/tcp
  • 18790/tcp
  • published ports:
  • ninguno al host
  • internal ports:
  • 18789/tcp gateway HTTP interno
  • 18790/tcp puerto interno expuesto por compose y no publicado al host

E. Red

  • redes Docker:
  • proxy-network para trafico con NPM
  • openclaw_openclaw_internal para trafico interno del stack
  • red publica/proxy: publica solo a traves de svc-nginx-proxy-manager
  • redes internas: openclaw_openclaw_internal
  • quien puede hablar con quien:
  • NPM puede hablar con openclaw-gateway:18789 por proxy-network
  • los componentes internos de OpenClaw pueden hablar entre si por la red interna
  • el host no llega a 18789 porque no hay puertos publicados
  • puertos internos:
  • 18789/tcp
  • 18790/tcp
  • puertos externos:
  • ninguno publicado directamente
  • firewall: queda protegido por la topologia sin puertos publicados y por el proxy reverso
  • observaciones de red: trustedProxies debe mantenerse alineado al proxy real

F. NPM / Proxy / Dominio

  • dominio: openclaw.alpuntodeventa.com.ar
  • proxy host: si
  • forward hostname: openclaw-gateway
  • forward port: 18789
  • SSL: si, via Let's Encrypt
  • websocket: validado PASS al 2026-06-01; transporte wss publico, allowedOrigins, connect.challenge, connect, autenticacion completa y sesion operativa revalidados con un dispositivo aprobado real, sin PAIRING_REQUIRED ni DEVICE_IDENTITY_REQUIRED
  • headers especiales: X-Forwarded-* desde NPM
  • HSTS: si
  • renovacion de certificado: automatica por NPM mientras el dominio y DNS sigan validos

G. Datos y persistencia

  • datos criticos:
  • configuracion de OpenClaw
  • estado de auth del agente main
  • identidad del dispositivo
  • workspace operativo
  • volumenes:
  • no usa volumenes Docker nombrados conocidos al 2026-05-31
  • carpetas bind:
  • /opt/stacks/openclaw/config
  • /opt/stacks/openclaw/workspace
  • /opt/stacks/openclaw/auth-profile-secrets
  • que se puede regenerar:
  • contenedores
  • redes del stack
  • directorio auth-profile-secrets si vuelve a quedar vacio
  • que NO se puede perder:
  • config/agents/main/agent/auth-profiles.json
  • config/agents/main/agent/auth-state.json
  • config/identity/device-auth.json
  • configuracion funcional del stack

H. Backups

  • ruta backup: /root/openclaw-backups/daily/<timestamp>/openclaw-stack.tgz
  • frecuencia: diario 03:00
  • retencion: diarios 30 dias, semanales 12, logs 90 dias
  • restore probado: si, documentado y certificado
  • RPO: 24 horas
  • RTO: 30-45 minutos en mismo VPS

I. Usos registrados

  • sin usos compartidos registrados al 2026-05-31

J. Dependencias

  • depende de:
  • svc-nginx-proxy-manager para publicacion por dominio
  • provider OpenAI para uso funcional del agente main
  • proxy-network
  • servicios que dependen de este:
  • app-openclaw-control
  • orden de arranque: primero redes, luego contenedor gateway, luego acceso por proxy
  • impacto si cae: se cae la interfaz principal, el chat y el caso de uso central del VPS

K. Operacion

  • como validar salud:
  • docker ps
  • openclaw health --json
  • curl -I https://openclaw.alpuntodeventa.com.ar/
  • comandos utiles:
  • docker ps --filter name=openclaw
  • docker inspect -f '{{.State.Health.Status}}' openclaw-openclaw-gateway-1
  • docker logs openclaw-openclaw-gateway-1
  • logs:
  • logs del contenedor openclaw-openclaw-gateway-1
  • salida de openclaw health --json
  • como reiniciar: restart controlado del stack OpenClaw
  • como detener: detener solo el stack openclaw
  • como recuperar: usar RESTORE-OPENCLAW.md

L. Seguridad

  • secretos: no documentados en valor; la auth efectiva observada vive en config/agents/main/agent/* y config/identity/*
  • usuarios tecnicos: agente main con auth OpenAI configurada
  • exposicion publica: si, solo por HTTPS detras de NPM
  • hardening:
  • sin puertos publicados al host
  • proxy dedicado para exposicion
  • dependencia explicita de trustedProxies
  • riesgos:
  • depende de auth operativa hacia OpenAI
  • la UI publica sigue siendo superficie expuesta
  • un cambio no trazado en proxy o auth puede degradar el acceso

L.1. Administracion de dispositivos

  • que es un dispositivo aprobado: una identidad concreta de browser o cliente que el gateway conoce y autoriza para conectarse con un rol y scopes definidos.
  • para que sirve: evita que cualquier cliente con token actue como admin; el acceso queda atado a un deviceId real y a permisos aprobados.
  • dispositivo oficial de administracion Control UI: Control UI oficial de Gabi
  • device id oficial: 3fa5280edf0e65d16f1ec60e686ae17d4e7b656e256bb6823dfe8f0e84a5fbf3
  • plataforma: Win32
  • cliente: openclaw-control-ui
  • modo: webchat
  • aprobado desde: 2026-05-31 00:38:32 -03
  • ultimo uso evidenciado: 2026-05-31 00:55:30 -03
  • proposito: administracion diaria de Control UI por Gabi
  • alcance aprobado: operator.admin, operator.read, operator.write, operator.approvals, operator.pairing
  • alcance operativo real: administrar la UI, aprobar pairing legitimo y operar sesiones sin relajar la politica de device auth.
  • cuando aprobar uno nuevo: solo si Gabi cambia de equipo/browser real o si aparece un cliente de mantenimiento conocido con un pedido claro y justificado.
  • que no hacer: no aprobar requests desconocidos, no aprobar upgrades de scopes por impulso, no copiar tokens o claves privadas a docs/Git y no inventar deviceId.
  • evidencia adicional del estado actual: existe un request pendiente 30ae9c15-2254-4eb3-b94d-7ced4d72e6ad para el cliente cli Linux 94483a84828c419a17a48b8eed6a0c3f1bac37a7eccb9197c9256ae43a2e812a pidiendo operator.pairing; no se aprobo porque no corresponde al acceso actual de Gabi en Control UI.

M. Estado y decisiones

  • decisiones tomadas:
  • publicar solo via NPM
  • no publicar puertos al host
  • usar proxy-network compartida y red interna propia
  • respaldar recurrentemente en /root/openclaw-backups
  • mantener copia externa Windows en C:\APV\backups\openclaw\
  • por que esta asi: reduce exposicion directa y deja trazada la auth critica en el backup real del stack
  • pendientes:
  • validar si existe .env real separado
  • revisar solo si hace falta el upgrade pendiente del cliente cli Linux antes de darle scopes mayores
  • riesgos aceptados:
  • dependencia del provider OpenAI para el flujo principal