Arquitectura

Como OpenClaws aprovisiona, orquesta y aisla la infraestructura de tus agentes de IA.

Vision General

OpenClaws se ejecuta sobre tres herramientas principales de HashiCorp:

Nomad — Orquestacion de contenedores, planificacion, aislamiento de namespace y cuotas de recursos
Vault — Gestion de secretos, cifrado Transit, identidad de carga de trabajo basada en JWT
Consul — Descubrimiento de servicios, TLS mutuo y control de acceso basado en intenciones

Flujo de Aprovisionamiento

Crear Usuario

Cuando se crea un usuario, OpenClaws aprovisiona el namespace y la cuota de recursos:

create_user_flow.txt

1. Create Nomad namespace "oc-{user}" with tier metadata
2. Create resource quota "quota-{user}", attach to namespace
3. Create CSI volume "oc-{user}-data" (10 GB GCE Persistent Disk)

Agregar Agente(s)

Agregar agentes crea secretos por agente y reconstruye el contenedor del usuario:

add_agents_flow.txt

1. Validate agent count against tier limit
2. Encrypt Anthropic API key via Vault Transit (vault:v1:... ciphertext)
3. For each new agent:
   - Generate API key (32 bytes, hex-encoded)
   - Generate gateway token
   - Store in Vault KV at secret/openclaw/oc-{user}/{agent}
4. Store user-level Anthropic key at secret/openclaw/oc-{user}/_anthropic_key
5. Create Consul intentions:
   - oc-{user} → vertex-ai-proxy
   - oc-{user} → anthropic-proxy
6. Build and submit Nomad job "oc-{user}" with ALL agents in config
7. Container starts with new agent configuration

Eliminar Agente

remove_agent_flow.txt

1. Delete agent's Vault secret
2. If agents remain: rebuild and resubmit job with remaining agents
3. If no agents remain: stop the job, remove Consul intentions

Arquitectura del Contenedor

Cada usuario obtiene un unico contenedor gateway de OpenClaw que ejecuta todos sus agentes:

Imagen: ghcr.io/openclaw/openclaw:main (puerto 18789)
Usuario de ejecucion: node (UID 1000)
Configuracion: ~/.openclaw/openclaw.json (enlace simbolico al volumen persistente)
Red: Consul Connect modo bridge con sidecar Envoy
Almacenamiento: Volumen CSI montado en /openclaw-data

Secuencia de Inicio del Contenedor

El script _startup.sh del contenedor realiza estos pasos:

_startup.sh sequence

1. Create ~/.openclaw directory (symlink to /openclaw-data/oc-{user}/)
2. Copy openclaw.json config into ~/.openclaw/
3. Decrypt ANTHROPIC_API_KEY via Vault Transit API
   - Reads vault token from NOMAD_SECRETS_DIR
   - HTTP POST to VAULT_ADDR/v1/transit/decrypt/openclaw
4. Write per-agent auth-profiles.json files
   - ~/.openclaw/agents/{id}/agent/auth-profiles.json
5. Start background auto-approver for device pairing
6. Exec the OpenClaw gateway process

Almacenamiento de la Lista de Agentes

La lista de agentes se almacena en los metadatos del job de Nomad como una cadena separada por comas:

openclaw.agents = "manager,researcher,writer"

Esta es leida por la funcion ListAgents del API de gestion y se utiliza para reconstruir el job cuando se agregan o eliminan agentes.

Auto-Escalado

El Nomad Autoscaler monitorea la utilizacion de recursos a nivel de cluster y escala el Managed Instance Group de GCE:

Estrategia: target-value al 70% para asignacion de CPU y memoria
Rango de escala: 1-5 nodos (configurable)
Tiempo de enfriamiento: 5 minutos entre acciones de escalado
Reduccion: Drenaje de nodos con limite de 5 minutos, purga despues del drenaje

API de Gestion

El API de gestion es un servicio en Go con arquitectura por capas:

api_layers.txt

cmd/mgmt-api/main.go       → Entry point, wires dependencies
internal/handlers/         → HTTP handlers (user + agent CRUD)
internal/service/          → Business logic, saga provisioning
internal/nomad/            → Namespace, quota, job management
internal/vault/            → KV v2 + Transit encrypt/decrypt
internal/consul/           → Service mesh intentions
internal/config/           → Environment-based configuration

El API utiliza el patron saga para aprovisionamiento de multiples pasos con rollback automatico en caso de fallo.