Introducción a OpenMOSS: Convierta la IA en un equipo corporativo que opera las 24 horas mediante la colaboración multi-agente

Dificultad: Principiante | Duración: 30 minutos | Beneficio: Comprender el sistema de colaboración de cuatro roles de OpenMOSS y construir su propio equipo de IA empresarial

---

Lectores Objetivo

Usted ya utiliza OpenClaw y ha experimentado la capacidad de un solo Agente: puede chatear, escribir código y ejecutar tareas. Pero probablemente haya notado que, una vez que la tarea se vuelve compleja o requiere colaboración en varios pasos, un solo Agente tiende a atascarse en algún punto y se queda "detenido" esperando a que usted lo presione.

OpenMOSS busca resolver este problema. Su enfoque es simple: no deje que un solo Agente cargue con todo, sino dote a la IA de una estructura organizacional. El Planificador desglosa las necesidades, el Ejecutor realiza el trabajo, el Revisor controla la calidad y el Patrullero vigila; cuatro roles cumplen sus funciones y operan de forma autónoma mediante activaciones programadas, formando un equipo de IA de ciclo cerrado.

OpenMOSS es en sí mismo un middleware; no se encarga del negocio específico, sino de la programación y la colaboración. Dependiendo de los Skills (habilidades) que le asigne, podrá completar automáticamente cualquier tarea mediante la colaboración.

Este artículo es adecuado para:

• Usuarios de OpenClaw que desean experimentar la colaboración multi-agente.
• Quienes necesiten que la IA funcione de forma continua y automática sin supervisión humana.
• Quienes deseen construir líneas de producción de contenido, mantenimiento automatizado, revisión de código y otros flujos de trabajo.

---

Dependencias Principales y Entorno

Repositorio de GitHub: https://github.com/uluckyXH/OpenMOSS

---

Estructura Completa del Proyecto

OpenMOSS/
├── app/                          # Backend FastAPI
│   ├── main.py                   # Entrada: registro de rutas, middleware, servicio estático SPA
│   ├── config.py                 # Carga de configuración
│   ├── database.py               # Inicialización de BD (SQLAlchemy)
│   ├── models/                  # Modelos de datos (10 tablas)
│   ├── routers/                 # Rutas API
│   ├── services/                # Capa de lógica de negocio
│   └── schemas/                 # Modelos de serialización Pydantic
├── webui/                        # Código fuente frontend Vue 3 (requiere compilación)
├── static/                       # Producto de compilación frontend (servido por el backend)
├── prompts/                      # Plantillas de prompts para roles de Agentes
│   ├── templates/                # Plantillas base de roles
│   ├── agents/                   # Ejemplos de prompts para Agentes
│   └── tool/                    # Prompts para llamadas a herramientas
├── skills/                        # Definición de Skills de Agentes OpenClaw
│   ├── task-cli.py              # Script de llamada API común para todos los Skills
│   ├── task-planner-skill/      # Skill del Planificador
│   ├── task-executor-skill/      # Skill del Ejecutor
│   ├── task-reviewer-skill/     # Skill del Revisor
│   ├── task-patrol-skill/       # Skill del Patrullero
│   └── dist/                    # Paquetes .zip de Skills empaquetados
├── config.example.yaml            # Plantilla de archivo de configuración
├── requirements.txt              # Dependencias de Python
├── Dockerfile
└── docker-compose.yml

---

Pasos Detallados

Paso 1: Clonar el proyecto e instalar dependencias

# Clonar el proyecto
git clone https://github.com/uluckyXH/OpenMOSS.git openmoss
cd openmoss

# Instalar dependencias de Python
pip install -r requirements.txt

Si su repositorio no tiene el directorio static/ (frontend no compilado), deberá compilarlo:

cd webui
npm install
npm run build

# Copiar el producto de la compilación al directorio static/
rm -rf ../static/*
cp -r dist/* ../static/
cd ..

---

Paso 2: Configurar config.yaml

Al iniciar por primera vez, OpenMOSS generará automáticamente config.yaml a partir de config.example.yaml. Se recomienda copiar la plantilla y modificarla directamente:

cp config.example.yaml config.yaml

Luego edite config.yaml; los siguientes campos deben ser configurados:

# Contraseña de administrador (se encripta automáticamente tras el primer inicio)
admin:
  password: "su-contraseña-segura-aquí"

# Token de registro de Agentes (necesario al registrar un Agente, se recomienda generar uno aleatorio)
agent:
  registration_token: "su-token-aleatorio-aquí"
  allow_registration: true

# Directorio de trabajo (donde se guardan los productos de los Agentes)
workspace:
  root: "/home/su-usuario/TaskWork"

# Dirección externa del servicio (dirección necesaria para la conexión de los Agentes)
server:
  external_url: "http://ip-de-su-servidor:6565"

---

Paso 3: Iniciar el servicio y completar el asistente de inicialización

python -m uvicorn app.main:app --host 0.0.0.0 --port 6565

El primer inicio realizará automáticamente:

1. Generar config.yaml (si no existe).
2. Inicializar la base de datos SQLite (data/tasks.db).
3. Montar automáticamente el frontend (si el directorio static/ existe).

Abra el navegador en http://localhost:6565. Será redirigido al asistente de inicialización para:

• Establecer la contraseña de administrador.
• Configurar el nombre del proyecto.
• Generar el token de registro de Agentes.
• Configurar canales de notificación (opcional).

Al terminar, se mostrarán las direcciones del servicio:

---

Paso 4: Iniciar sesión en la WebUI y familiarizarse con el panel

Tras la inicialización, entre a la WebUI con la cuenta de administrador. Verá las siguientes páginas:

Al iniciar, la lista de Agentes estará vacía; aún no hemos registrado ninguno. El Paso 5 trata sobre su creación.

---

Paso 5: Crear cuatro Agentes y registrarlos en OpenClaw

Los cuatro roles de OpenMOSS corresponden a distintas responsabilidades:

Cada Agente es esencialmente una instancia que ejecuta OpenClaw. Tomaremos la creación del planner como ejemplo; el proceso para los otros tres roles es idéntico.

Opción 1: Registro vía WebUI (Recomendado)

1. En la página de Agentes de la WebUI, haga clic en "Registrar Agente".
2. Complete la información básica:

Rol: planner
Nombre: OpenMOSS-Planner
Token de registro: (Complete con el agent.registration_token de config.yaml)

1. Tras enviar, la WebUI devolverá:
   • La API Key del Agente (guárdela bien, solo se muestra una vez).
   • Direcciones de descarga de SKILL.md y task-cli.py.
   • Guía de conexión (incluye comando de registro y método de configuración).

Opción 2: Registro vía API

curl -X POST http://localhost:6565/api/agents/register \
  -H "X-Registration-Token: su-token-de-registro" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OpenMOSS-Planner",
    "role": "planner"
  }'

La respuesta incluye la API Key, el comando de registro y las URLs de los Skills:

{
  "api_key": "om_xxxxxxxxxxxxxxxxxxxx",
  "skill_cli_url": "http://localhost:6565/skills/task-cli.py",
  "skill_url": "http://localhost:6565/skills/task-planner-skill/SKILL.md",
  "register_command": "openclaw agents add ..."
}

Registre los tres Agentes restantes de la misma manera:

executor → task-executor-skill
reviewer → task-reviewer-skill
patrol   → task-patrol-skill

---

Paso 6: Configurar los Skills de los Agentes

Cada Agente registrado obtendrá dos archivos clave:

• task-cli.py: Script de llamada a la API de OpenMOSS común para todos los roles.
• SKILL.md: Definición de Skill exclusiva para ese rol.

Colóquelos en un directorio legible por OpenClaw (normalmente junto al prompt del Agente):

# Suponiendo el directorio de configuración de Agentes de OpenClaw
mkdir -p ~/.openclaw/agents/openmoss-planner/skills

# Descargar archivos de Skill
curl -o ~/.openclaw/agents/openmoss-planner/skills/task-cli.py \
  http://localhost:6565/skills/task-cli.py

curl -o ~/.openclaw/agents/openmoss-planner/skills/SKILL.md \
  http://localhost:6565/skills/task-planner-skill/SKILL.md

Luego, en la configuración del Agente de OpenClaw, añada la ruta de SKILL.md al Prompt o a la configuración de Skills del Agente para que este sepa qué APIs de OpenMOSS puede invocar.

---

Paso 7: Configurar cron para activación programada, permitiendo que el Agente "vaya a trabajar"

Esta es la mayor diferencia entre OpenMOSS y un Agente común: el Agente no espera a que usted envíe un mensaje para actuar, sino que ficha para trabajar periódicamente como un empleado.

En la configuración de cada Agente en OpenClaw, establezca tareas cron:

planner (Planificador): revisa nuevas tareas cada 30 minutos:

{
  "cron": "*/30 * * * *",
  "task": "Revisar la cola de tareas de OpenMOSS; si hay tareas nuevas sin planificar, ejecutar el flujo de planificación"
}

executor (Ejecutor): revisa tareas pendientes de reclamar cada 15 minutos:

{
  "cron": "*/15 * * * *",
  "task": "Revisar la cola de subtareas de OpenMOSS, reclamar y ejecutar"
}

reviewer (Revisor): revisa entregables pendientes de revisión cada 20 minutos:

{
  "cron": "*/20 * * * *",
  "task": "Revisar la cola de revisión de OpenMOSS, procesar los entregables pendientes"
}

patrol (Patrullero): inspecciona el estado del sistema cada 10 minutos:

{
  "cron": "*/10 * * * *",
  "task": "Revisar el estado del sistema OpenMOSS, marcar tareas bloqueadas y alertar inmediatamente ante anomalías"
}

El flujo de trabajo del Agente tras ser activado es fijo:

1. Llama a la API de OpenMOSS para obtener el estado actual.
2. Ejecuta la operación correspondiente según su rol.
3. Escribe el resultado de vuelta en OpenMOSS.
4. Entra en hibernación esperando la siguiente activación.

Todo el proceso no requiere intervención humana.

---

Paso 8: Asignar la primera tarea y verificar el ciclo de colaboración

En la página de "Gestión de Tareas" de la WebUI, haga clic en "Crear Tarea" y complete:

Nombre de la tarea: Publicación automática de noticias de IA
Objetivo: Recopilar noticias de IA/Tecnología del internet en chino, traducirlas al inglés y publicarlas.

Cuando el Planificador (planner) sea activado por el cron:

1. Recibirá la tarea y la desglosará en varios módulos (Recopilación → Traducción → Revisión → Publicación).
2. Creará subtareas (sub-task) para cada módulo.
3. Definirá los criterios de aceptación para cada subtarea.

Cuando el Ejecutor (executor) sea activado:

1. Reclamará la primera subtarea pendiente de la cola.
2. Ejecutará el trabajo (búsqueda de noticias en red, traducción de contenido).
3. Enviará el producto a la cola de revisión.

Cuando el Revisor (reviewer) sea activado:

1. Obtendrá el entregable pendiente de revisión.
2. Calificará según los criterios de aceptación.
3. Si aprueba, marca la subtarea como completada; si rechaza, la devuelve al ejecutor para retrabajo.

El Patrullero (patrol) monitorea el sistema constantemente:

• Si una subtarea no avanza tras superar un umbral, se marca automáticamente como blocked.
• Si detecta que la tasa de rechazo en revisiones sube anormalmente, envía una notificación de alerta.
• Si detecta que un ejecutor ha caído en un bucle infinito, notifica al administrador para que intervenga.

Puede ver la dinámica de trabajo en tiempo real de todos los Agentes en la página "Flujo de Actividad" de la WebUI.

---

Paso 9: Configurar canales de notificación

OpenMOSS permite notificarle automáticamente cuando ocurren eventos clave. Configure los canales en config.yaml:

notification:
  enabled: true
  channels:
    - "ID-de-grupo-Feishu"    # Es necesario añadir al Agente al grupo y mencionarlo una vez para obtener el chat_id
    - "user:ou_xxx"           # open_id de usuario de Feishu
  events:
    - task_completed   # Subtarea completada
    - review_rejected   # Revisión rechazada (retrabajo)
    - all_done          # Todas las subtareas completadas
    - patrol_alert      # Anomalía detectada por patrulla

El Agente leerá la configuración de notificaciones desde el endpoint GET /config/notification y usará su propia capacidad (email, Feishu, etc.) para enviar el aviso.

---

Resolución de Problemas Comunes

1. Error en el registro del Agente (registration_token no coincide)

Síntoma: El registro del Agente devuelve un error 403 o "invalid token".

Causa común: Inconsistencia en el registration_token. Verifique dos cosas:

1. El valor de agent.registration_token en el config.yaml de OpenMOSS.
2. El valor de X-Registration-Token en el Header de la solicitud de registro del Agente.

Ambos deben ser idénticos, incluyendo espacios y mayúsculas. Si modifica el config.yaml, recuerde reiniciar el servicio OpenMOSS.

---

2. La tarea cron no activa al Agente

Síntoma: El Agente no comienza a trabajar automáticamente y no hay logs de error en la consola.

Orden de revisión:

1. Confirmar que la configuración cron en OpenClaw es correcta: si la expresión cron es válida y la descripción de la tarea es clara.
2. Confirmar que la instancia de OpenClaw está corriendo: que el proceso de OpenClaw del Agente esté vivo.
3. Verificar que la API Key del Agente sea válida: ver en la página de Agentes de la WebUI si el estado es "active".

Puede usar la página de "Agentes" de la WebUI para ver la última hora de actividad de un Agente y juzgar si ha sido activado.

---

3. Subtarea rechazada repetidamente, bucle infinito

Síntoma: El entregable del ejecutor es siempre rechazado por el revisor, repitiendo la misma subtarea.

Esto suele indicar que el ejecutor tiene una comprensión desviada de los criterios de aceptación o que estos no están bien definidos.

Solución:

1. Ver los registros de rechazo en la WebUI para leer el motivo dado por el revisor.
2. Ajustar los criterios de aceptación escritos por el planificador para que sean más específicos y cuantificables.
3. Si es por falta de capacidad del ejecutor, considere cambiarlo a un modelo más potente (actualizando la API Key del Agente en OpenClaw).

---

4. La patrulla (patrol) no responde

Síntoma: Hay tareas bloqueadas en el sistema, pero el patrullero no las marca ni envía alertas.

Revisión:

1. Ver si la instancia de OpenClaw correspondiente al Agente patrol está corriendo.
2. Ver si el intervalo cron de patrol es muy amplio (establecer */10 es mucho más sensible que */60).
3. Ver si notification está activado en config.yaml y los canales están bien configurados.
4. Ver si el Agente patrol posee el Skill para enviar notificaciones (Feishu/email, etc.).

---

5. API Key expirada o permisos insuficientes

Síntoma: El Agente deja de funcionar de repente; aparecen errores 401 o 403 en los logs.

La API Key del Agente (que empieza por om_xxx) es una credencial interna de OpenMOSS, no es la API Key del LLM. Si hay errores de autenticación de LLM en los logs, el problema está en la API Key del LLM del Agente (cuota agotada, revocada, etc.).

Solución: Actualice la LLM API Key en la configuración del Agente de OpenClaw y reinicie la instancia.

---

6. Varios ejecutores reclaman la misma tarea simultáneamente

Síntoma: Dos ejecutores comienzan la misma subtarea, causando duplicidad de trabajo.

La cola de tareas de OpenMOSS tiene protección de atomicidad; en teoría, esto no debería ocurrir. Si sucede, podría ser por:

1. Intervalos cron de ejecutores demasiado cortos, despertando casi al mismo tiempo.
2. Retraso en la actualización del estado de la tarea, leyendo datos obsoletos (stale).

Solución: Amplíe adecuadamente el intervalo cron de los ejecutores (ej. de */5 a */15) para dar tiempo suficiente a la actualización de estados.

---

Lecturas Adicionales / Direcciones Avanzadas

1. Personalización de Prompts de Roles

En el directorio prompts/ existen plantillas para cada rol. Puede modificarlas para crear una personalidad de Agente acorde a sus necesidades:

# Editar prompt del planificador
vim prompts/agents/planner-agent-prompt.md

# Editar prompt del ejecutor
vim prompts/agents/executor-agent-prompt.md

Tras modificar el prompt, el Agente leerá la nueva versión en su siguiente activación.

2. Integración de Skill de WordPress para publicación automática

skills/wordpress-skill/ permite publicar en WordPress. Usado con un ejecutor, permite que el Agente publique automáticamente artículos traducidos en un sitio WordPress sin intervención humana.

Requiere configurar la URL del sitio y la API Key:

# Ver instrucciones de configuración del Skill de WordPress
cat skills/wordpress-skill/SKILL.md

3. Ajuste del sistema de puntos y rendimiento

OpenMOSS incluye un mecanismo de puntos; la calificación del revisor afecta directamente al ranking de rendimiento del ejecutor. Puede ver la calidad de producción en la página "Ranking de Puntos".

Si desea un sistema más estricto o laxo, modifique la descripción de los estándares de calificación en el prompt del revisor (reviewer).

4. Integración de Grok Search Skill para búsqueda web

skills/grok-search-runtime/ ofrece capacidad de búsqueda web mediante Grok. Con este Skill, el Ejecutor puede capturar noticias de internet en tiempo real para procesarlas, flujo central del caso real 1M Reviews.

5. Migración a PostgreSQL / MySQL

Por defecto, OpenMOSS usa SQLite, ideal para equipos pequeños. Para mayor concurrencia, cambie a PostgreSQL o MySQL:

# config.yaml
database:
  type: postgresql  # o mysql
  path: ""           # dejar vacío al usar cadena de conexión
  connection_string: "postgresql://usuario:pass@localhost:5432/openmoss"

6. Despliegue con Docker

El proyecto incluye Dockerfile y docker-compose.yml para desplegar todo el entorno con un comando:

# Iniciar todos los servicios
docker-compose up -d

# Ver logs
docker-compose logs -f

Esto empaqueta OpenMOSS, la BD y el frontend, ideal para validación rápida o migración a servidores.

7. Construcción de su propia línea de producción de contenido

Referenciando el caso de 1M Reviews, la línea completa es:

1. planner desglosa: Recopilación → Traducción → Revisión → Publicación.
2. executor (recopilación) captura noticias mediante Grok Search Skill.
3. executor (traducción) adapta el contenido mediante APIs de traducción.
4. reviewer audita la calidad y el formato.
5. executor (publicación) publica en la web mediante el Skill de WordPress.
6. patrol monitorea la operación y alerta ante anomalías.

Todo el flujo opera de forma autónoma; usted solo define el objetivo al inicio y revisa el resultado final.