Arquitectura del sistema

La vista detallada: el modelo de 8 capas, los procesos en runtime, la disposición de directorios, las rutas de comunicación y la topología de despliegue.

Propósito

Esta página es la referencia de la arquitectura técnica del lab. Complementa la Vista general del sistema de alto nivel con detalles concretos sobre procesos, puertos, directorios y rutas de comunicación.

El modelo de 8 capas

El lab está organizado en 8 capas. Cada capa tiene una única responsabilidad, un contrato claro con las capas adyacentes y es testeable de forma independiente.

Loading diagram…

El modelo de 8 capas — una pila de arriba abajo desde la Interfaz de usuario hasta la capa Externa; las líneas punteadas son las capas interiores leyendo y escribiendo el Estado.

Capa	Nombre	Responsabilidad
1	Interfaz de usuario	Entrada/salida en lenguaje natural. Sesiones, prompts, resultados.
2	Coordinación	Resolución de intent, enrutado, memoria, sesión, skills.
3	Agente	Roles especializados (Research, Coding, Media, Web).
4	Framework	Orquestación de dominio (Research Framework, Coding sub-agent).
5	Herramienta	Capacidades tipadas y deterministas (herramientas CLI, adaptadores MCP).
6	Adaptador	Traducción específica del proveedor (Tavily, DuckDuckGo, etc.).
7	Estado	Memoria, sesiones, skills, artefactos, audit trail.
8	Externa	Proveedores de modelo, proveedores de búsqueda, servicios de streaming, dispositivos.

El contrato entre capas adyacentes está documentado en la página Framework.

Procesos en runtime

El lab tiene los siguientes procesos en runtime:

Proceso	Propietario	Puerto	Vida útil	Política de reinicio
Coordinator gateway	Coordinator	18789	Siempre activo	launchd / systemd
Scout gateway	Research Worker + Media Agent	18790	Siempre activo	launchd / systemd
Coding sub-agent	Coding Assistant	n/a	Por invocación	Re-spawned cada llamada
Browser (Chromium)	Web Agent	18800	Bajo demanda	Reiniciado tras crash
Media Lab Server	Coordinator (o cualquier agente)	8765	Bajo demanda	Manual o launchd
Procesos de herramientas	Varios	n/a	Por llamada	Re-spawned cada llamada

Los dos gateways son los únicos procesos de larga duración. Todo lo demás es de vida corta.

Disposición de directorios

La disposición de directorios del lab es:

{workspace-root}/
├── .openclaw/                  ← estado del framework
│   ├── openclaw.json           ← config principal
│   ├── workspace/              ← workspace principal (Coordinator)
│   ├── workspace-scout/        ← workspace del Scout
│   ├── agents/                 ← configs de agentes
│   ├── plugin-skills/          ← skills empaquetados
│   └── media/                  ← salidas del Media Lab
│       └── outbound/
├── devclaw-tools/              ← repos de herramientas
│   ├── audio-server/           ← Media Lab Server
│   ├── stack-template/         ← plantilla de proyecto
│   └── tools/                  ← herramientas varias
├── movie-scraper-tools/        ← toolkit multimedia
│   ├── tools/
│   │   ├── torrent-finder/
│   │   ├── subtitle-finder/
│   │   ├── dubbed-finder/
│   │   └── media-info/
│   ├── tools.json
│   └── SKILL.md
├── scoute-research-framework/  ← research framework
│   ├── scout/
│   │   ├── orchestrator/
│   │   ├── phases/
│   │   ├── schemas/
│   │   └── tools/
│   ├── docs/
│   └── pyproject.toml
├── stack_inicial_proyectos/    ← plantilla Next.js
│   └── front-end/nextjs/
├── reports_test/               ← artefactos de investigación
├── Audits/                     ← informes de auditoría
├── Codex/                      ← logs del coding sub-agent
└── comandos_terminal/          ← cheatsheets

La disposición es el resultado de la iteración. Los directorios más importantes son .openclaw/ (estado del framework), devclaw-tools/ y movie-scraper-tools/ (los repos de herramientas) y scoute-research-framework/ (el research framework).

Rutas de comunicación

Los agentes se comunican a través de las siguientes rutas:

Desde	Hacia	Ruta
Coordinator	Research Worker	HTTP POST a `127.0.0.1:18790/<endpoint>`
Coordinator	Media Agent	HTTP POST a `127.0.0.1:18790/<endpoint>`
Coordinator	Web Agent	Llamada en proceso a la herramienta browser
Coordinator	Coding Assistant	Llamada en proceso al coding sub-agent
Research Worker	Coordinator	Respuesta HTTP (síncrona)
Media Agent	Coordinator	Respuesta HTTP (síncrona)
Web Agent	Coordinator	Retorno en proceso
Coding Assistant	Coordinator	Retorno en proceso
Research Worker	Research Framework	Llamada en proceso al orquestador
Coding Assistant	Coding sub-agent	Invocación CLI (`codex exec ...`)
Research Framework	Adaptadores	Llamada en proceso a funciones de adaptador
Adaptadores	Externo	HTTP / HTTPS a APIs de proveedores

Las rutas son unidireccionales cuando es posible. La ruta de respuesta refleja la ruta de petición.

Ficheros de configuración

La configuración del lab está repartida entre varios ficheros:

Fichero	Propósito
`.openclaw/openclaw.json`	Config principal del framework (modelo, puertos, rutas).
`.openclaw/agents/main/agent/models.json`	Config de modelo del Coordinator.
`.openclaw/agents/scout/agent/models.json`	Config de modelo del Scout.
`{project}/tools.json`	El tool registry de un proyecto.
`scoute-research-framework/config/*.json`	Config de adaptadores del research framework.
`~/.codex/config.toml`	Config del coding sub-agent (sandbox, trust).
`~/Library/LaunchAgents/*.plist`	Las unidades de launchd (macOS).
`/etc/systemd/system/*.service`	Las unidades de systemd (Linux).

Los cambios de configuración los hace el Coordinator y requieren autorización explícita del usuario.

Topología de despliegue

El lab es un despliegue en un único host. Todos los procesos se ejecutan en la máquina del usuario. El único acceso a red es hacia proveedores externos (modelo, búsqueda, streaming).

Loading diagram…

Despliegue en un único host — dos gateways, un coding sub-agent, un navegador, un media server, más proveedores externos.

El host es la máquina del usuario (típicamente un MacBook Pro en macOS). El host tiene:

Un coordinator gateway en el puerto 18789.
Un Scout gateway en el puerto 18790.
Un coding sub-agent invocado bajo demanda.
Un navegador (Chromium) en el puerto CDP 18800.
Un Media Lab Server en el puerto 8765.

El host tiene acceso a red al proveedor del modelo (sobre HTTPS) y a la red local (mDNS para descubrimiento de dispositivos).

Dominios de fallo

Los dominios de fallo del lab son:

Dominio	Qué puede fallar
Coordinator gateway	Todo el enrutado; el usuario está desconectado.
Scout gateway	Investigación y multimedia; el usuario está parcialmente desconectado.
Coding sub-agent	Una invocación; los reintentos gestionan fallos transitorios.
Browser	El Web Agent; el Coordinator puede reiniciar el navegador.
Media Lab Server	Generación; el Coordinator puede reiniciar el servidor.
Model provider	Todas las llamadas al modelo; el framework reintenta con backoff.
Search provider	Un adaptador; el framework recurre a otro.
Streaming service	Una fuente; el Media Agent prueba la siguiente.
Dispositivo	Reproducción; el Media Agent surface el error.

Los dominios de fallo están diseñados para ser pequeños. Un fallo en un dominio no se propaga a otros.

Rendimiento

El rendimiento del lab está acotado por:

Latencia del modelo. El tiempo de respuesta del Coordinator está dominado por el tiempo de respuesta del proveedor de modelo.
Latencia de adaptadores. El tiempo de respuesta del Research Framework está dominado por el tiempo de respuesta de los adaptadores de búsqueda.
Latencia de herramientas. El tiempo de respuesta del Coding Assistant está dominado por el tiempo de respuesta del coding sub-agent.

El lab no busca respuesta en tiempo real. Busca respuesta acotada y predecible. Una petición típica se completa en 5-30 segundos; una misión de investigación en 2-5 minutos.