Documento Técnico de Arquitectura — Sistema de Orquestación Cloud-Edge

Campo	Valor
Versión del Documento	1.0
Versión del Script	1.0
Fecha	2026-05-26
Autor	Jorge Samuel Marín Mendoza
Estado	Revisión

---

Índice

1. Resumen Ejecutivo
2. Stack Tecnológico
3. Diagrama de Arquitectura Conceptual
4. Diagrama de Arquitectura del Sistema (Despliegue)
5. Diagrama de Arquitectura con OpenClaw (Instalación Completa)
6. Pasos de Pre-Instalación
7. Pasos de Instalación
8. Explicación Detallada del Script
   • 8.1 Estructura General
   • 8.2 Función ask() y Flujo de Autorización
   • 8.3 Fase 1: Instalación Base
   • 8.4 Fase 2: Caddy (HTTPS Opcional)
   • 8.5 Flags Modulares
   • 8.6 Multi-Provider Cloud
   • 8.7 Generación de docker-compose.yml
9. Pasos de Post-Instalación
10. Variables de Entorno
11. Referencia de Flags y Comandos
12. Archivos del Repositorio
13. Troubleshooting

---

1. Resumen Ejecutivo

setup-entorno.sh es un instalador y orquestador interactivo diseñado para desplegar un ecosistema completo de inteligencia artificial Cloud-Edge en un solo servidor. Su objetivo es eliminar la complejidad manual de instalar y configurar los siguientes componentes:

• Docker Engine + Docker Compose v2 como capa de contenedores
• OpenClaw como orquestador central de agentes de IA
• Ollama como motor de inferencia local (opcional)
• Múltiples proveedores cloud (Anthropic, OpenAI, Google, DeepSeek, NVIDIA, etc.)
• Caddy como proxy HTTPS opcional
• Telegram como canal de comunicación opcional

Está diseñado para ejecutarse en entornos WSL2 (Windows), Proxmox CT, VPS o Bare-metal Linux, detectando automáticamente el entorno y adaptando la instalación.

El script sigue una filosofía "Verificar → Preguntar → Actuar": cada paso verifica la existencia previa de un componente, pregunta al usuario si desea proceder, y actúa en consecuencia. Esto permite ejecuciones seguras, repetibles y no destructivas.

---

2. Stack Tecnológico

Componente	Tecnología	Propósito
Contenedores	Docker Engine 27.x + Docker Compose v2	Aislamiento y orquestación de servicios
Orquestador IA	OpenClaw v2026.x (ghcr.io/openclaw/openclaw:latest)	Gateway de agentes de IA multi-modelo
Inferencia Local	Ollama (latest)	Modelos open-source locales (deepseek-coder, qwen, gemma, etc.)
Proxy HTTPS	Caddy v2 (opcional)	Certificados SSL automáticos, acceso seguro
Mensajería	Telegram Bot API (opcional)	Canal de comunicación con el gateway
Modelos Cloud	Múltiples proveedores (ver abajo)	Inferencia cloud con APIs propietarias
Sistema Base	Ubuntu 24.04 LTS / Debian 13	SO del contenedor/máquina host

Proveedores Cloud Soportados

#	Proveedor	Modelos Ejemplo
1	Anthropic	Claude 3.5 Sonnet, Claude 3 Opus
2	OpenAI	GPT-4o, GPT-4o-mini, o1, o3-mini
3	Google	Gemini 2.5 Pro, Gemini 2.5 Flash
4	DeepSeek	DeepSeek V3, DeepSeek R1
5	NVIDIA	Nemotron Ultra 253B, Llama 4 Maverick, Kimi K2.6
6	OpenRouter	Todos los modelos (ruteo unificado)
7	xAI	Grok-2, Grok-3
8	Mistral	Mistral Large, Mistral Small
9	Together AI	Modelos open-source hosteados
10	Groq	LPU inference (Mixtral, Llama)
11	Fireworks	Modelos optimizados

---

3. Diagrama de Arquitectura Conceptual

                            ┌─────────────────────────────┐
                            │     PROVEEDORES CLOUD        │
                            │  ┌─────┐ ┌──────┐ ┌──────┐  │
                            │  │NVIDIA│ │Google│ │Deep- │  │
                            │  │      │ │      │ │Seek  │  │
                            │  └──┬──┘ └──┬───┘ └──┬───┘  │
                            │  ┌─────┐ ┌──────┐ ┌──────┐  │
                            │  │OpenAI│ │Anthro│ │xAI   │  │
                            │  │      │ │pic   │ │Grok  │  │
                            │  └──┬──┘ └──┬───┘ └──┬───┘  │
                            └─────┼────────┼────────┼──────┘
                                  │        │        │
                            ┌─────▼────────▼────────▼──────┐
                            │       OPENCLAW GATEWAY         │
                            │  ┌─────────────────────────┐   │
                            │  │   Router de Modelos      │   │
                            │  │   (cloud → local → fallb)│   │
                            │  └───────────┬─────────────┘   │
                            │              │                  │
                            │  ┌───────────▼─────────────┐   │
                            │  │   Agentes (sub-agentes)  │   │
                            │  │   Diego, Luna, Sergio,   │   │
                            │  │   Diana, Nora, etc.      │   │
                            │  └─────────────────────────┘   │
                            └──────────────┬─────────────────┘
                                           │
              ┌────────────────────────────┼──────────────────┐
              │                            │                   │
    ┌─────────▼─────────┐     ┌────────────▼─────────┐ ┌─────▼──────┐
    │   OLLAMA (Local)   │     │     TELEGRAM BOT     │ │  WEB UI    │
    │  deepseek-coder    │     │   Comandos → Gateway  │ │ :18789     │
    │  qwen, gemma, etc. │     │   Respuestas → Chat   │ │ Dashboard  │
    └───────────────────┘     └───────────────────────┘ └────────────┘

---

4. Diagrama de Arquitectura del Sistema (Despliegue)

┌─────────────────────────────────────────────────────────────────────┐
│  SERVIDOR / LAPTOP                                                    │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │  SISTEMA OPERATIVO (Ubuntu 24.04 / Debian 13 / WSL2)          │  │
│  │                                                               │  │
│  │  ┌─────────────────────────────────────────────────────────┐  │  │
│  │  │  DOCKER ENGINE 27.x + DOCKER COMPOSE v2                  │  │  │
│  │  │                                                         │  │  │
│  │  │  ┌──────────────────────────────────────────────────┐   │  │  │
│  │  │  │  docker-compose.yml                               │   │  │  │
│  │  │  │  Directorio: ~/.docker/openclaw/                  │   │  │  │
│  │  │  └──────────────────────┬───────────────────────────┘   │  │  │
│  │  │                         │                               │  │  │
│  │  │  ┌──────────────────────▼──────────┐  ┌──────────────┐  │  │  │
│  │  │  │  openclaw-gateway               │  │ ollama-server │  │  │  │
│  │  │  │  ghcr.io/openclaw/openclaw:latest│  │ ollama:latest│  │  │  │
│  │  │  │                                 │  │              │  │  │  │
│  │  │  │  PUERTOS:                       │  │  PUERTOS:    │  │  │  │
│  │  │  │   - 18789 (Web UI + API)        │  │  - 11434     │  │  │  │
│  │  │  │                                 │  │              │  │  │  │
│  │  │  │  VOLÚMENES:                     │  │  VOLÚMENES:  │  │  │  │
│  │  │  │   - ~/.openclaw → /home/node/   │  │  - ~/.ollama │  │  │  │
│  │  │  │     /.openclaw (datos)          │  │    /data     │  │  │  │
│  │  │  │   - /var/run/docker.sock (sandbox)│  │    → /root/ │  │  │  │
│  │  │  │   - TZ=America/Mexico_City      │  │    .ollama   │  │  │  │
│  │  │  │                                 │  │              │  │  │  │
│  │  │  │  ENTORNO:                       │  │  ENTORNO:    │  │  │  │
│  │  │  │   - OPENCLAW_GATEWAY_TOKEN      │  │  - OLLAMA_   │  │  │  │
│  │  │  │   - TZ=America/Mexico_City      │  │    KEEP_ALIVE │  │  │  │
│  │  │  │                                 │  │  - TZ=America │  │  │  │
│  │  │  │                                 │  │    /Mexico_  │  │  │  │
│  │  │  │                                 │  │    City      │  │  │  │
│  │  │  └─────────────────────────────────┘  └──────────────┘  │  │  │
│  │  └─────────────────────────────────────────────────────────┘  │  │
│  │                                                               │  │
│  │  ┌──────────────────────┐   ┌────────────────────────────┐    │  │
│  │  │  CADDY (opcional)     │   │  ECOSYSTEM CONFIG          │    │  │
│  │  │  Proxy HTTPS          │   │  ~/.openclaw-ecosystem.conf│    │  │
│  │  │  Puerto 443/8443      │   │  + ~/.openclaw-token       │    │  │
│  │  └──────────────────────┘   └────────────────────────────┘    │  │
│  └───────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘

---

5. Diagrama de Arquitectura con OpenClaw (Instalación Completa)

┌───────────────────────────────────────────────────────────────────────────┐
│  ECOSISTEMA OPENCLAW — Cloud-Edge (Instalación Completa)                  │
├───────────────────────────────────────────────────────────────────────────┤
│                                                                           │
│  ┌─ USUARIO ───────────────────────────────────────────────────────────┐  │
│  │                                                                      │  │
│  │  ┌───────────────────┐    ┌───────────────────┐    ┌──────────────┐  │  │
│  │  │ Navegador Web     │    │ Telegram (señal)   │    │ Terminal SSH │  │  │
│  │  │ http://IP:18789   │    │ /comando → gateway │    │ túnel -L     │  │  │
│  │  └────────┬──────────┘    └────────┬──────────┘    └──────┬───────┘  │  │
│  └───────────┼────────────────────────┼─────────────────────┼──────────┘  │
│              │                        │                     │            │
│  ┌───────────▼────────────────────────▼─────────────────────▼──────────┐ │
│  │                    GATEWAY OPENCLAW (:18789)                         │ │
│  │                                                                      │ │
│  │  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────────┐ │ │
│  │  │ Control UI   │  │ API REST     │  │ Sub-agentes (sandbox)      │ │ │
│  │  │ Dashboard    │  │ rutas /api   │  │ Diego, Luna, Sergio, etc.  │ │ │
│  │  │ WebChat      │  │ v1/messages  │  │ Aislados por Docker        │ │ │
│  │  └──────┬───────┘  └──────┬───────┘  └─────────┬──────────────────┘ │ │
│  └─────────┼─────────────────┼────────────────────┼────────────────────┘ │
│            │                 │                    │                      │
│            │    ┌────────────┼────────────────────┘                      │
│            │    │            │                                           │
│  ┌─────────▼────▼─────┐  ┌──▼────────────────────────┐                  │
│  │   OLLAMA (:11434)   │  │   MODELOS CLOUD            │                 │
│  │   deepseek-coder    │  │   ┌──────┐ ┌──────┐       │                 │
│  │   qwen2.5-coder     │  │   │NVIDIA│ │Google│       │                 │
│  │   gemma, phi, etc.  │  │   ├──────┤ ├──────┤       │                 │
│  │   (modelos locales)  │  │   │DeepSe│ │OpenAI│       │                 │
│  └─────────────────────┘  │   └──────┘ └──────┘       │                 │
│                           └───────────────────────────┘                 │
│                                                                          │
│  ┌─ ACCESO ──────────────────────────────────────────────────────────┐  │
│  │  Opción A: http://IP:18789 (Firefox)                              │  │
│  │  Opción B: ssh -L 18789:localhost:18789 user@IP → localhost       │  │
│  │  Opción C: https://IP:8443 (Caddy, cualquier navegador)           │  │
│  │  Token: guardado en ~/.openclaw-token                             │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│  ┌─ SANDBOX ─────────────────────────────────────────────────────────┐  │
│  │  /var/run/docker.sock montado → aísla sub-agentes en contenedores│  │
│  │  TZ=America/Mexico_City → huso horario correcto                  │  │
│  └───────────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────────────┘

---

6. Pasos de Pre-Instalación

Requisitos del Sistema

Recurso	Mínimo	Recomendado
CPU	2 núcleos	4+ núcleos
RAM	4 GB	8+ GB
Disco	20 GB libres	50+ GB (para modelos locales)
SO	Linux (Ubuntu 22.04+, Debian 12+)	Ubuntu 24.04 LTS
WSL2	Windows 11 22H2+	Windows 11 Pro

Dependencias Previas

sudo apt update && sudo apt install -y curl wget git

Verificaciones de Entorno

El script detecta automáticamente estos entornos:

Entorno	Detección	Comportamiento
WSL2	/proc/version contiene "microsoft"	Instalación completa sin systemd
Proxmox CT	systemd-detect-virt devuelve "lxc"	Instalación completa con systemd
VPS	Sin virtualización anidada	Instalación completa con systemd
Bare-metal	Sin virtualización	Instalación completa con systemd

Puerto Libre

Asegúrate de que el puerto 18789 esté disponible:

ss -tlnp | grep 18789 || echo "Puerto 18789 libre"

---

7. Pasos de Instalación

1. Descargar el Script

# Opción A — Desde el repositorio
git clone http://<tu-servidor>:3000/JMarin1980/setup-entorno.git
cd setup-entorno

# Opción B — Directo (si tienes wget)
wget -O setup-entorno.sh <url-del-raw>
chmod +x setup-entorno.sh

2. Ejecutar Instalación Completa

./setup-entorno.sh

3. Flujo de Instalación

Fase	Componente	Qué hace
1/2	Docker Engine	Verifica, instala si no existe, agrega usuario al grupo docker
1/2	Docker Compose v2	Verifica, instala si no existe
1/2	OpenClaw	Genera docker-compose.yml con socket Docker + TZ, inicia contenedor
2/2	Caddy (opcional)	Pregunta si instalar proxy HTTPS con certificados SSL automáticos

4. Uso con Flags Modulares

# Solo instalar Docker
./setup-entorno.sh --docker

# Solo configurar OpenClaw (después de tener Docker)
./setup-entorno.sh --openclaw

# Configurar modelos cloud
./setup-entorno.sh --cloud

# Configurar modelos locales (Ollama)
./setup-entorno.sh --ollama

# Solo Telegram
./setup-entorno.sh --telegram

# Gestión de modelos (cloud + local)
./setup-entorno.sh --models

---

8. Explicación Detallada del Script

8.1 Estructura General

El script setup-entorno.sh (v6.1, ~2289 líneas) está organizado en las siguientes secciones:

01-50   │ Cabecera, versión, configuración, colores
51-160  │ Funciones utility (random_port, port_available, find_available_port, ask)
161-250 │ Verificaciones (check_docker, check_ollama, detect_environment)
251-400 │ Instalación (install_docker, install_docker_compose, openclaw_local, gen_compose)
401-660 │ Configuración Cloud (configure_cloud_models — multi-provider)
661-850 │ OpenClaw config (openclaw_config, start_services, configure_caddy)
851-1310│ Telegram, pairing, modelos, reset, verify
1311-1740│ Flags: usage, --approve, --fix-ao, --allow-lan-fallback, parseo de args
1741-2289│ MAIN: Fase 1 + Fase 2 + ejecución por filtro

Funciones clave:

Función	Línea	Propósito
ask()	~127	Pregunta al usuario con default [Y/n]
ask_yn()	~132	Pregunta sí/no sin texto extra
ask_mode()	~142	Menú de 3 opciones (local/remote/skip)
check_docker()	~180	Verifica Docker Engine
install_docker()	~195	Instala Docker desde repo oficial
detect_environment()	~230	Detecta WSL2 / Proxmox / VPS / Bare-metal
random_port()	~56	Puerto aleatorio en rango seguro
find_available_port()	~65	Encuentra puerto libre
gen_compose()	~349	Genera docker-compose.yml
configure_cloud_models()	~401	Bucle interactivo multi-provider
openclaw_config()	~670	Configuración post-instalación del gateway
start_services()	~700	docker compose up -d
configure_caddy()	~750	Instala y configura Caddy
configure_telegram()	~860	Configura bot de Telegram
step_models()	~1200	Menú de gestión de modelos
print_install_info()	~1320	Muestra resumen post-instalación

8.2 Función ask() y Flujo de Autorización

ask() {
    local step_name="$1"
    local default="${2:-y}"
    local prompt
    [ "$default" = "y" ] && prompt="[Y/n]" || prompt="[y/N]"
    echo -e -n "${YELLOW}🔸 ${step_name}${NC} — ${prompt}: "
    read -r respuesta
    respuesta="${respuesta:-$default}"
    case "$respuesta" in
        [YySs]*) return 0 ;;
        *) warn "Omitido."; return 1 ;;
    esac
}

Cada paso en el script sigue el patrón:

if check_docker_installed; then
    ask "Docker ya instalado. ¿Reinstalar?" "n" || return 0
fi
ask "Instalar Docker Engine?" || return 1
# ... ejecuta instalación ...

8.3 Fase 1: Instalación Base

La Fase 1 se ejecuta automáticamente cuando se invoca el script sin flags:

1. Docker Engine: Verifica docker --version + docker info. Si no existe, instala desde el repositorio oficial de Docker. Agrega el usuario al grupo docker.
2. Docker Compose v2: Verifica docker compose version. Si no existe, instala docker-compose-plugin.
3. OpenClaw: Llama a openclaw_local() que:
   • Toma un puerto libre (o el especificado)
   • Genera docker-compose.yml en ~/.docker/openclaw/
   • Ejecuta docker compose up -d
4. Inicio de servicios: Espera 3 segundos y verifica que los contenedores estén corriendo.

8.4 Fase 2: Caddy (HTTPS Opcional)

Se pregunta al usuario si desea instalar Caddy como proxy HTTPS. Si acepta:

• Instala Caddy desde el repositorio oficial
• Configura un archivo Caddyfile con proxy inverso hacia openclaw-gateway
• Obtiene certificados SSL automáticos (Let's Encrypt)
• El acceso queda disponible en https://IP:8443

Si no se instala Caddy, se sugiere usar túnel SSH o Firefox para acceso directo por IP.

8.4.1 Flag --fix-caddy: Restauración tras reinicio

La flag --fix-caddy fue diseñada para restaurar Caddy automáticamente después de un corte de luz, reboot del servidor o cualquier reinicio inesperado. Su flujo es independiente de la instalación inicial — no requiere volver a ejecutar la instalación completa.

Comportamiento detallado:

1. Detección del puerto del contenedor OpenClaw

   • Primero intenta docker port openclaw-gateway
   • Fallback: lee el puerto mapeado del docker-compose.yml (necesario en Docker 29.1.3 donde docker port tiene bugs)
   • Último fallback: ~/.openclaw-ecosystem.conf o puerto por defecto 18789

2. Determinación del puerto Caddy

   • Si se pasa como argumento (--fix-caddy 54193), se usa ese puerto
   • Si no, se lee de ~/.openclaw-ecosystem.conf (guardado en ejecuciones anteriores)
   • Si no hay configuración previa, usa el puerto por defecto 54193

3. Verificación de instalación

   • Si Caddy no está instalado, muestra advertencia y sugiere ejecutar --caddy primero

4. Generación/verificación de certificados SSL auto-firmados

   • Crea directorio /etc/caddy/certs
   • Si no existe cert.pem, genera uno nuevo con OpenSSL (SAN: IP del host, localhost)
   • Si existe, reutiliza los certificados existentes

5. Ajuste de permisos

   • Asigna propietario caddy:caddy a los archivos de certificados
   • key.pem en modo 600, cert.pem en modo 644

6. Reconstrucción del Caddyfile

   • Configura proxy inverso localhost:<DETECTED_PORT>
   • Con TLS apuntando a los certificados generados
   • local_certs y auto_https off para evitar conflictos

7. Copia y reinicio vía systemd

   • Copia el Caddyfile a /etc/caddy/Caddyfile
   • Ejecuta systemctl restart caddy

8. Verificación

   • Confirma que Caddy esté activo con systemctl is-active --quiet caddy

9. Actualización de allowedOrigins

   • Agrega las URLs https://localhost:<PUERTO>, https://127.0.0.1:<PUERTO> y https://<IP>:<PUERTO> a openclaw.json

10. Persistencia

    • Guarda CADDY_ACTIVE=true y CADDY_PORT=<PUERTO> en ~/.openclaw-ecosystem.conf

Diagrama de flujo:

flowchart TD
    A[Inicio --fix-caddy] --> B{¿Puerto Caddy
como argumento?}
    B -->|Sí| C[Usar puerto indicado]
    B -->|No| D[Buscar en
ecosystem.conf]
    D -->|Encontrado| C
    D -->|No encontrado| E[Usar default 54193]
    C --> F[Detectar puerto
del contenedor]
    F --> G{¿docker port
funciona?}
    G -->|Sí| H[Usar puerto detectado]
    G -->|No| I[Leer de
docker-compose.yml]
    I --> H
    H --> J[Generar/verificar
certificados SSL]
    J --> K[Ajustar permisos
de certs]
    K --> L[Reconstruir
Caddyfile]
    L --> M[Reiniciar Caddy
vía systemd]
    M --> N{¿Caddy
corriendo?}
    N -->|Sí| O[Actualizar
allowedOrigins]
    N -->|No| P[Mostrar error
y salir]
    O --> Q[Guardar en
ecosystem.conf]
    Q --> R[✅ Restaurado]

8.5 Flags Modulares

El script soporta los siguientes flags para ejecución granular:

# Infraestructura
./setup-entorno.sh --docker          # Solo instalar Docker + Compose
./setup-entorno.sh --openclaw        # Solo desplegar OpenClaw
./setup-entorno.sh --caddy           # Solo instalar Caddy

# Modelos
./setup-entorno.sh --cloud           # Configurar proveedores cloud
./setup-entorno.sh --ollama          # Configurar modelos locales
./setup-entorno.sh --models          # Menú completo de modelos
./setup-entorno.sh --apply-cloud     # Re-aplicar modelo cloud
./setup-entorno.sh --verify-cloud    # Verificar API keys cloud
./setup-entorno.sh --reset-models    # Eliminar TODOS los modelos cloud

# Comunicación
./setup-entorno.sh --telegram        # Configurar bot de Telegram

# Operaciones
./setup-entorno.sh --update          # Actualizar OpenClaw
./setup-entorno.sh --start           # Iniciar contenedor
./setup-entorno.sh --stop            # Detener contenedor
./setup-entorno.sh --approve <code>  # Aprobar dispositivo (pairing)
./setup-entorno.sh --fix-ao          # Reparar allowedOrigins
./setup-entorno.sh --fix-caddy [puerto]  # Restaurar Caddy tras reinicio del servidor
./setup-entorno.sh --install-info    # Mostrar info de instalación
./setup-entorno.sh --help            # Mostrar ayuda

8.6 Multi-Provider Cloud

La función configure_cloud_models() implementa un bucle interactivo que permite agregar múltiples proveedores cloud en una sola ejecución:

¿Configurar proveedor cloud #1? [Y/n]: y
Selecciona un proveedor cloud:
  1) Anthropic    (Claude)
  2) OpenAI       (GPT, o1, o3-mini)
  3) Google       (Gemini 2.5 Pro/Flash)
  4) DeepSeek     (V3, R1)
  5) NVIDIA       (Nemotron, Llama)
  6) OpenRouter   (todos los modelos)
  7) xAI          (Grok)
  8) Mistral
  9) Together AI
 10) Groq         (LPU inference)
 11) Fireworks

Para cada proveedor:

1. Solicita la API Key (la guarda en el archivo de ecosystem config)
2. Pregunta si desea descubrir modelos automáticamente vía API o ingresarlos manualmente
3. Agrega los modelos seleccionados al openclaw.json mediante docker exec openclaw-gateway openclaw config set
4. Actualiza el allowlist de modelos usando openclaw config set models.allow[*] con merge

Al finalizar, permite seleccionar el modelo principal de entre todos los configurados.

8.7 Generación de docker-compose.yml

La función gen_compose() genera el archivo docker-compose.yml en ~/.docker/openclaw/:

services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw-gateway
    restart: unless-stopped
    ports:
      - "${port}:18789"
    volumes:
      - ${OC_DATA_DIR}:/home/node/.openclaw
      - /var/run/docker.sock:/var/run/docker.sock    # ← Sandbox
    environment:
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
      - TZ=America/Mexico_City                       # ← Zona horaria
    command: ["node","openclaw.mjs","gateway","--allow-unconfigured","--bind","lan"]

  ollama:                          # ← Opcional, solo si se seleccionó
    image: ollama/ollama:latest
    container_name: ollama-server
    restart: unless-stopped
    ports:
      - "11434:11434"
    volumes:
      - ${OLLAMA_LOCAL_DIR}:/root/.ollama
    environment:
      - OLLAMA_KEEP_ALIVE=24h
      - TZ=America/Mexico_City

Características del compose generado:

• Socket Docker: Monta /var/run/docker.sock para habilitar el sandbox mode de OpenClaw. Esto permite que los sub-agentes se aíslen en contenedores Docker separados.
• Zona Horaria: TZ=America/Mexico_City en ambos servicios para que las fechas y horas sean correctas.
• Persistencia de datos: Los datos de OpenClaw se guardan en ~/.openclaw/ y los de Ollama en ~/.ollama/data/ del host.
• Token de autenticación: Se pasa como variable de entorno OPENCLAW_GATEWAY_TOKEN.
• Bind LAN: El gateway se inicia con --bind lan para permitir acceso desde otros equipos de la red local.

---

9. Pasos de Post-Instalación

9.1 Pairing (Primera Conexión)

Cuando abras el gateway por primera vez, verás un código de pairing. Para aprobarlo:

./setup-entorno.sh --approve 3aa94063-xxxx-xxxx-xxxx-xxxxxxxxxxxx

O manualmente:

docker exec openclaw-gateway openclaw devices approve 3aa94063-xxxx-...

9.2 Configurar Modelos Cloud

./setup-entorno.sh --cloud

Sigue el asistente interactivo para agregar proveedores (Anthropic, OpenAI, Google, DeepSeek, NVIDIA, etc.). Te pedirá la API Key y luego te permitirá seleccionar los modelos.

9.3 Configurar Modelos Locales (Ollama)

./setup-entorno.sh --ollama

O usa el menú integrado:

./setup-entorno.sh --models

9.4 Configurar Telegram

./setup-entorno.sh --telegram

Te pedirá:

1. Token del bot de Telegram (de @BotFather)
2. Tu ID de usuario de Telegram
3. Política de DMs (allowlist/abierto) y grupos (habilitado/deshabilitado)

9.5 Verificar Estado

./setup-entorno.sh --install-info

Muestra: IPs del servidor, puerto de OpenClaw, estado de servicios, modelos configurados.

---

10. Variables de Entorno

Variable	Default	Descripción
DOCKER_DIR	$HOME/.docker/openclaw	Directorio del docker-compose.yml
OPENCLAW_REPO	https://github.com/openclaw/openclaw.git	Repositorio de OpenClaw
OC_DATA_DIR	$HOME/.openclaw	Datos persistentes del gateway
OLLAMA_LOCAL_DIR	$HOME/.ollama/data	Datos persistentes de Ollama
ECOSYSTEM_CONFIG	$HOME/.openclaw-ecosystem.conf	Configuración del ecosistema
LOG_FILE	$HOME/setup-entorno-{fecha}.log	Log de instalación
PORT_MIN	49152	Puerto mínimo para random_port
PORT_MAX	65535	Puerto máximo para random_port

---

11. Referencia de Flags y Comandos

Flag	Descripción	Ejemplo
(sin flag)	Instalación base completa	./setup-entorno.sh
--docker	Solo instalar Docker + Compose	./setup-entorno.sh --docker
--openclaw	Solo desplegar OpenClaw	./setup-entorno.sh --openclaw
--ollama	Configurar modelos locales	./setup-entorno.sh --ollama
--cloud	Configurar modelos cloud	./setup-entorno.sh --cloud
--models	Menú de gestión de modelos	./setup-entorno.sh --models
--caddy	Instalar proxy HTTPS	./setup-entorno.sh --caddy
--telegram	Configurar bot de Telegram	./setup-entorno.sh --telegram
--apply-cloud	Re-aplicar modelo cloud	./setup-entorno.sh --apply-cloud
--verify-cloud	Verificar API keys	./setup-entorno.sh --verify-cloud
--reset-models	Eliminar modelos cloud	./setup-entorno.sh --reset-models
--approve <code>	Aprobar dispositivo (pairing)	./setup-entorno.sh --approve 3aa94063-...
--fix-ao	Reparar allowedOrigins	./setup-entorno.sh --fix-ao
--fix-caddy [puerto]	Restaurar Caddy tras reinicio	./setup-entorno.sh --fix-caddy
--allow-lan-fallback	Habilitar acceso LAN	./setup-entorno.sh --allow-lan-fallback
--start	Iniciar contenedor	./setup-entorno.sh --start
--stop	Detener contenedor	./setup-entorno.sh --stop
--update	Actualizar OpenClaw	./setup-entorno.sh --update
--install-info	Mostrar info de instalación	./setup-entorno.sh --install-info
--help	Mostrar ayuda	./setup-entorno.sh --help

---

12. Archivos del Repositorio

Archivo	Descripción
setup-entorno.sh	Script principal de instalación y orquestación (v6.2, ~2300+ líneas)
README.md	Este documento técnico de arquitectura
show-info.sh	Muestra información de acceso (IPs, puertos, token)
tunnel.sh	Helper para túnel SSH (resuelve WebSocket en Chrome/Edge)
uninstall.sh	Desinstalación completa del ecosistema (Docker, OpenClaw, Ollama, configs)
.gitignore	Exclusiones del repositorio

---

13. Troubleshooting

El contenedor no inicia

# Verificar logs
docker logs openclaw-gateway

# Verificar puerto ocupado
ss -tlnp | grep 18789

# Recrear contenedor
cd ~/.docker/openclaw && docker compose down && docker compose up -d

No puedo acceder desde Chrome/Edge (WebSocket bloqueado)

El navegador bloquea WebSocket sobre HTTP no seguro. Soluciones:

# Opción 1: Túnel SSH
ssh -L 18789:localhost:18789 user@servidor
# Luego abre: http://localhost:18789

# Opción 2: Caddy (HTTPS)
./setup-entorno.sh --caddy

# Opción 3: Usar Firefox (no bloquea WebSocket sobre HTTP)

# Opción 4: Habilitar LAN fallback
./setup-entorno.sh --allow-lan-fallback

Error de pairing: "No such device or address"

# Aprobar manualmente
docker exec openclaw-gateway openclaw devices approve <código>

El sandbox no funciona

El sandbox de OpenClaw requiere el socket de Docker montado. Verifica:

# Verificar que el socket está montado
docker exec openclaw-gateway ls -la /var/run/docker.sock

# Si no está, reconstruir el docker-compose.yml
./setup-entorno.sh --openclaw

Las fechas/horas son incorrectas

Verificar que la zona horaria está configurada:

docker exec openclaw-gateway date
# Debe mostrar hora de Ciudad de México (UTC-6)

Error de API Key en modelos cloud

# Verificar estado de las keys
./setup-entorno.sh --verify-cloud

# Re-aplicar un proveedor
./setup-entorno.sh --apply-cloud

Quiero reiniciar desde cero

# Desinstalar todo (pregunta paso a paso)
./uninstall.sh

# O manualmente
rm ~/.openclaw-ecosystem.conf
rm ~/.openclaw-token
cd ~/.docker/openclaw && docker compose down -v