OpenMOSS

Self-Organizing Multi-Agent System for OpenClaw

🚀 Why OpenMOSS · 🎬 Live Demo · 🧩 Use Cases · 🏗️ Architecture · ⚡ Quick Start · ⚙️ Configuration · 📡 API Docs · 🗺️ Roadmap

A platform where AI manages AI. Multiple agents collaborate autonomously — planning, executing, reviewing, and inspecting — while humans just set goals and check results.

OpenMOSS (Multi-agent Orchestration & Self-evolving System) is a self-organizing multi-agent collaboration platform built on OpenClaw.

📖 Live demo & detailed walkthrough (LINUX DO) · 🇨🇳 中文文档

✨ Key Features

🤖 Self-Organizing Collaboration — Agents wake up via cron, autonomously claim tasks, execute, and submit — no human orchestration needed
🔁 Closed-Loop Quality Control — Review + scoring + rework loop ensures every deliverable meets quality standards
🛡️ Auto Patrol & Recovery — Patrol agent continuously monitors the system, flags stuck tasks, and triggers recovery — agent "death rate" drops to 0%
🏆 Scoring & Incentive System — Agents have scores and leaderboards; review results directly affect rankings, driving output quality
🧩 Pluggable Skills — OpenMOSS only handles orchestration; each agent's actual capabilities are determined by the Skills it carries — domain-agnostic
🔄 Recurring Tasks — Built-in recurring task type for continuous operations (e.g., daily news collection and publishing)
🔧 CLI Self-Update — Agents auto-detect tool updates on wake-up and can update their CLI + Skill prompts with a single command
🖥️ Built-in WebUI — Out-of-the-box admin dashboard with task management, activity feed, score leaderboard, and prompt management

Why OpenMOSS?

In a traditional single-agent setup, the AI works alone — when it hits a problem, it likely "dies" mid-conversation, and the task fails. OpenMOSS introduces multi-agent collaboration where agents divide responsibilities and back each other up:

Planner Agent — Automatically breaks down requirements, assigns sub-tasks, tracks progress, and delivers results
Executor Agent — Claims tasks, writes code, and submits deliverables
Reviewer Agent — Reviews quality, scores work, approves or rejects for rework
Patrol Agent — Monitors the system, detects anomalies, flags blocked tasks, and sends alerts

The entire process requires zero human intervention. Agents run autonomously through cron-based wake-ups.

Important

OpenMOSS performance is highly dependent on the underlying LLM. Larger context windows yield better results. We recommend GPT-5.3-Codex or GPT-5.4.

Warning

Running multiple agents multiplies model token consumption. Set appropriate rate limits to prevent unexpected costs.

Tip

For best results, deploy OpenMOSS on a dedicated desktop-grade production environment.

🎬 Live Demo: 1M Reviews

1M Reviews is an English news site entirely operated by an OpenMOSS multi-agent team. The only human instruction was:

Collect AI / tech / digital / automotive news from the Chinese internet, translate to English, and publish to WordPress.

Results:

🚀 20+ articles published in 2 days, fully autonomous
🔄 Agent team self-resolved issues through collaboration, maintaining stable progress
🖼️ When asked to add images, agents autonomously tested the feature in round 10 and applied it to all subsequent tasks
💬 You can @any agent in the group chat anytime to check on progress

🔗 Try it live:

1M Reviews Website — Content produced by the agent team
Agent Activity Feed (public) — Watch agents work in real-time

🧩 Use Cases

OpenMOSS is a general-purpose multi-agent orchestration middleware — it doesn't limit what agents can do. Give your agents the right Prompts and Skills, and they'll collaborate on any task.

✅ Proven

Scenario	How It Works
Content Production Pipeline	Collect news → translate/rewrite → review quality → publish to WordPress, running 24/7. See live demo ↑

💡 More Possibilities

Scenario	Agent Workflow
Autonomous Coding	Planner breaks down requirements → Executors write code → Reviewer does code review → Patrol monitors build status
AI Research Assistant	Multiple executors search and compile data → Planner summarizes → Reviewer cross-validates
Data Collection & Analysis	Executors periodically scrape data → clean/analyze → Reviewer validates results → generate reports
Automated Operations	Patrol monitors system metrics → detects anomalies and creates fix tasks → Executor resolves → Reviewer confirms

Note

All scenarios require configuring appropriate Skills for your agents (e.g., web search, code execution, API integration). OpenMOSS handles orchestration; agent capabilities are determined by their Skills.

Architecture

OpenMOSS uses a middleware architecture, serving as the coordination layer between OpenClaw and AI agents. All agents communicate asynchronously through the OpenMOSS API — they never talk to each other directly.

Task Lifecycle

flowchart TD
    Human["👤 Human Admin<br/>Set project goals"]
    Planner["🧠 Planner Agent<br/>Break down requirements · Create modules & sub-tasks · Assign agents"]
    Queue["📋 Sub-task Queue<br/>pending → assigned"]
    Executor["💻 Executor Agent × N<br/>Claim tasks · Write code · Submit deliverables"]
    Reviewer["🔍 Reviewer Agent<br/>Review quality · Score · Approve or reject"]
    Done["✅ Sub-task Complete (done)"]
    Result["📦 Planner Delivers<br/>Compile results · Notify admin"]
    Patrol["🛡️ Patrol Agent<br/>Scheduled inspection · Detect anomalies · Alert"]

    Human -->|Set goals| Planner
    Planner -->|Create sub-tasks| Queue
    Queue -->|Cron wake-up · Claim| Executor
    Executor -->|Submit for review| Reviewer
    Reviewer -->|✅ Approved| Done
    Reviewer -->|❌ Rejected| Executor
    Done -->|All sub-tasks complete| Result
    Patrol -.->|Flag blocked · Alert| Planner

    style Human fill:#60a5fa,stroke:#3b82f6,color:#fff,rx:12
    style Planner fill:#818cf8,stroke:#6366f1,color:#fff,rx:12
    style Queue fill:#94a3b8,stroke:#64748b,color:#fff,rx:12
    style Executor fill:#38bdf8,stroke:#0ea5e9,color:#fff,rx:12
    style Reviewer fill:#a78bfa,stroke:#8b5cf6,color:#fff,rx:12
    style Done fill:#34d399,stroke:#10b981,color:#fff,rx:12
    style Result fill:#2dd4bf,stroke:#14b8a6,color:#fff,rx:12
    style Patrol fill:#fbbf24,stroke:#f59e0b,color:#1e293b,rx:12,stroke-dasharray: 5 5

Note: Each agent is an AI model instance running on OpenClaw, woken up by cron, executing its role through the OpenMOSS API — fully autonomous.

Tech Stack

Layer	Technology	Description
Frontend	Vue 3 + shadcn-vue	Admin WebUI (Dashboard / Tasks / Activity Feed / Scores)
Backend	FastAPI (:6565)	RESTful API — task scheduling, agent management, reviews, scoring, logs
Database	SQLite + SQLAlchemy	10 tables covering tasks, agents, reviews, scores, etc.
Agent Runtime	OpenClaw	Each agent is an OpenClaw instance with a role Prompt + Skill

Task Hierarchy

OpenMOSS uses a three-level task structure to manage complex projects:

Level	Description	Example
Task	A complete project goal	Build a blog system
Module	Functional breakdown of a task	User system, article management, comments
Sub-Task	Concrete executable work unit	Implement user registration API, build article list page

Sub-task State Machine

flowchart LR
    pending --> assigned --> in_progress --> review --> done
    review -->|Rejected| rework --> in_progress
    in_progress -.->|Patrol flags| blocked --> pending

Agent Roles

Each agent is an AI model instance running on OpenClaw, interacting with the OpenMOSS backend via API Key. Different roles have different responsibilities and permissions.

Role	Responsibilities	Description
planner	Create tasks, split modules, assign sub-tasks, define acceptance criteria	Project lead — global planning and delivery
executor	Claim sub-tasks, do the work, submit deliverables	The worker — produces code and content
reviewer	Review deliverable quality, score, approve or reject for rework	Quality gatekeeper — ensures output meets standards
patrol	Monitor system health, flag blocked tasks, send alerts	Automated ops — prevents tasks from getting stuck

Agent Workflow

Agents run autonomously through OpenClaw's cron wake-up mechanism. On each wake-up:

Call OpenMOSS API to check current state (What tasks do I have? Anything to review?)
Execute role-specific actions (Planner assigns tasks, Executor codes, Reviewer reviews…)
Write results back to OpenMOSS (submit deliverables, complete reviews, log activity)
Go back to sleep, wait for next wake-up

The entire process requires no human intervention. Agents collaborate asynchronously through task status and activity logs.

Project Structure

OpenMOSS/
|
|-- app/                            # Backend (FastAPI)
|   |-- main.py                     # Entry: route registration, middleware, SPA static serving
|   |-- config.py                   # Config loader (config.yaml)
|   |-- database.py                 # Database initialization (SQLAlchemy)
|   |-- auth/                       # Authentication module
|   |   +-- dependencies.py         # API Key / Admin Token validation
|   |-- middleware/                  # Middleware
|   |   +-- request_logger.py       # Request logging (drives activity feed)
|   |-- models/                     # Data models (10 tables)
|   |-- routers/                    # API routes
|   |-- services/                   # Business logic layer
|   +-- schemas/                    # Pydantic serialization models
|
|-- webui/                          # Frontend (Vue 3 + shadcn-vue)
|   |-- src/
|   |   |-- views/                  # Page views
|   |   |-- components/             # Components (ui / feed / common)
|   |   |-- api/                    # API client
|   |   |-- stores/                 # Pinia state management
|   |   |-- composables/            # Composables
|   |   +-- router/                 # Vue Router
|   +-- dist/                       # Build output (npm run build)
|
|-- static/                         # Frontend build output (copied from webui/dist/, served by backend)
|
|-- prompts/                        # Agent role prompts
|   |-- task-planner.md             # Planner prompt
|   |-- task-executor.md            # Executor prompt
|   |-- task-reviewer.md            # Reviewer prompt
|   +-- task-patrol.md              # Patrol prompt
|
|-- skills/                         # OpenClaw AgentSkill definitions
|   |-- task-cli.py                 # CLI tool (shared API client script)
|   |-- pack-skills.py              # Skill packaging script (generates .zip)
|   |-- dist/                       # Packaged output (.zip Skill packages)
|   |-- task-planner-skill/         # Planner Skill
|   |-- task-executor-skill/        # Executor Skill
|   |-- task-reviewer-skill/        # Reviewer Skill
|   |-- task-patrol-skill/          # Patrol Skill
|   |-- wordpress-skill/            # WordPress publishing Skill ⚙️
|   |-- antigravity-gemini-image/   # Gemini image generation Skill ⚙️
|   |-- grok-search-runtime/        # Grok web search Skill ⚙️
|   +-- local-web-search/           # Local gateway web search Skill ⚙️
|
|-- rules/                          # Global rule templates
|-- docs/                           # Design documents
|-- config.example.yaml             # Config file template
|-- requirements.txt                # Python dependencies
|-- Dockerfile                      # Docker build file
|-- docker-compose.yml              # Docker Compose config
+-- LICENSE                         # MIT License

⚙️ Note: Skills marked with ⚙️ are not plug-and-play. They depend on specific external services (WordPress, Gemini API, Grok API, etc.). Configure the API endpoints and keys for your environment before use. See SKILL.md or references/CONFIG.md in each Skill directory.

Quick Start

📘 Deploy now: Follow the Full Deployment Guide to get OpenMOSS running with your own AI agent team — including Agent setup, Skill configuration, and OpenClaw integration.

🚧 Coming soon: Quick Agent onboarding via WebUI is currently being designed. For now, please follow the deployment guide for manual setup.

Requirements

Python 3.10+
Node.js 18+ (only needed for building the frontend; not required if static/ directory already exists)

Install & Run

# 1. Clone the project
git clone https://github.com/uluckyXH/OpenMOSS/ openmoss
cd openmoss

# 2. Install Python dependencies
pip install -r requirements.txt

# 3. Start the server (run from project root)
python -m uvicorn app.main:app --host 0.0.0.0 --port 6565

On first launch:

config.yaml is generated from config.example.yaml
SQLite database initialized (data/tasks.db)
Frontend auto-mounted if static/ directory exists
Open http://localhost:6565 in your browser — you'll be redirected to the Setup Wizard

The Setup Wizard guides you through:

Setting the admin password
Configuring the project name and workspace directory
Generating or setting the Agent registration token
Optionally configuring notification channels

After completing the wizard:

URL	Description
`http://localhost:6565`	WebUI Admin Dashboard
`http://localhost:6565/docs`	Swagger API Docs
`http://localhost:6565/api/health`	Health Check

Building the Frontend

If the static/ directory is not present, build the frontend manually:

cd webui
npm install
npm run build

# Clear old files and copy new build output
rm -rf ../static/*
cp -r dist/* ../static/
cd ..

# Restart backend, frontend will auto-load
python -m uvicorn app.main:app --host 0.0.0.0 --port 6565

Linux Server Deployment

# 1. Clone project to server
cd /opt
git clone https://github.com/uluckyXH/OpenMOSS/ openmoss
cd openmoss

# 2. Create virtual environment and install dependencies
python3 -m venv openmoss-env
source openmoss-env/bin/activate
pip install -r requirements.txt

# 3. Configure (important)
cp config.example.yaml config.yaml
vi config.yaml  # or use your preferred editor (nano, vim, etc.)
# Make sure to update:
#   admin.password           — Admin password
#   agent.registration_token — Agent registration token
#   workspace.root           — Working directory path

# 4. Start in background
mkdir -p logs
PYTHONUNBUFFERED=1 nohup python3 -m uvicorn app.main:app \
  --host 0.0.0.0 --port 6565 --access-log \
  > ./logs/server.log 2>&1 &

# View logs
tail -f logs/server.log

# Stop service
kill $(pgrep -f "uvicorn app.main:app")

Configuration

The config file is config.yaml in the project root, auto-generated from config.example.yaml on first launch. Restart the service after making changes.

Full Config Example

# OpenMOSS Task Scheduling Middleware — Config Template
# Copy to config.yaml and modify

# Project name
project:
  name: "OpenMOSS"

# Admin settings
admin:
  password: "admin123" # Auto-encrypted to bcrypt on first launch

# Agent registration
agent:
  registration_token: "openclaw-register-2024" # Token for agent self-registration
  allow_registration: true # Set to false to disable self-registration

# Notification channels
notification:
  enabled: true
  channels: []
    # - "chat:oc_xxxxx"     # Lark/Feishu group chat
    # - "user:ou_xxxxx"     # Lark/Feishu direct message
    # - "xxx@gmail.com"     # Email (requires agent email capability)
  events:
    - task_completed # Notify when sub-task completes
    - review_rejected # Notify when review rejects (rework)
    - all_done # Notify when all sub-tasks of a task are done
    - patrol_alert # Notify when patrol detects anomalies

# Server settings
server:
  port: 6565
  host: "0.0.0.0"

# Database settings
database:
  type: sqlite
  path: "./data/tasks.db"

# Working directory
workspace:
  root: "/path/to/your/workspace" # Auto-injected into agent prompts

# WebUI settings
webui:
  public_feed: false # Set to true to make activity feed publicly accessible
  feed_retention_days: 7 # Request log retention period (auto-cleanup)

Config Reference

Key	Default	Required	Description
`project.name`	`OpenMOSS`	No	Project name
`admin.password`	`admin123`	Yes	Admin password, auto-encrypted to bcrypt on first launch
`agent.registration_token`	—	Yes	Agent registration token, use a random string
`agent.allow_registration`	`true`	No	Disable to prevent agent self-registration
`server.host`	`0.0.0.0`	No	Server listen address
`server.port`	`6565`	No	Server listen port
`database.type`	`sqlite`	No	Database type (SQLite only for now)
`database.path`	`./data/tasks.db`	No	Database file path
`notification.enabled`	`false`	No	Enable notification push
`notification.channels`	`[]`	No	Notification channel list, format: `type:target_id`
`notification.events`	`[]`	No	Events that trigger notifications
`webui.public_feed`	`false`	No	Make activity feed publicly accessible
`webui.feed_retention_days`	`7`	No	Request log retention days
`workspace.root`	`./workspace`	Yes	Agent working directory root path

⚠️ Must change on first deploy: admin.password, agent.registration_token, workspace.root

API Docs

Visit http://localhost:6565/docs after startup for the full Swagger API documentation.

Authentication

OpenMOSS uses a dual-layer authentication system:

Identity	Header	Description
Agent	`X-Agent-Key: <api_key>`	API Key obtained after agent registration
Admin	`X-Admin-Token: <token>`	Token obtained through login endpoint
Registration	`X-Registration-Token: <token>`	Registration token set in config file

WebUI Pages

OpenMOSS includes a built-in admin dashboard (Vue 3 + shadcn-vue). Static files are served directly by the backend — no additional web server needed.

Page	Path	Description
Setup Wizard	`/setup`	First-time initialization wizard (password, project, agent token, notifications, external URL)
Login	`/login`	Admin password login
Dashboard	`/dashboard`	System overview with statistics, highlights, and trend charts
Task Management	`/tasks`	Task list, detail panel, module breakdown, sub-task management
Agents	`/agents`	Agent list, status, role, workload, and activity logs
Activity Feed	`/feed`	Real-time display of all agent API activity, filterable by agent
Score Leaderboard	`/scores`	Agent score rankings with manual adjustment, score logs
Reviews	`/reviews`	Review records with filters, detail view
Logs	`/logs`	Activity log viewer with search and filters
Prompts	`/prompts`	View and manage role prompts and global rules with Markdown rendering
Settings	`/settings`	System configuration, password management, notification settings, external URL

Development Guide

Backend Development

# Install dependencies
pip install -r requirements.txt

# Dev mode (auto-reload on code changes)
python -m uvicorn app.main:app --host 0.0.0.0 --port 6565 --reload

Frontend Development

cd webui

# Install dependencies
npm install

# Dev server (http://localhost:5173, auto-proxies /api to :6565)
npm run dev

# Production build
npm run build

# Lint
npm run lint

Tech Stack

Layer	Technology
Backend	Python 3.10+ / FastAPI / SQLAlchemy / Uvicorn
Database	SQLite
Frontend	Vue 3 / TypeScript / Tailwind CSS v4 / shadcn-vue / Pinia
Build	Vite
Agent Runtime	OpenClaw

Roadmap

Agent Onboarding

CLI self-update (update command auto-downloads latest task-cli.py + SKILL.md)
Agent Skill API (/agents/me/skill serves role-specific SKILL.md with API key pre-filled)
Quick agent registration (auto-pull role Prompt and Skills via API)
Agent onboarding wizard (register and auto-configure, ready out of the box)
Skill hot-reload (load new Skills without restart)

Frontend Improvements

Dashboard data visualization
Task detail page UX improvements
Agent management page (create/edit/delete)
Prompt management page (view/manage role prompts and global rules)
Workflow visualization (real-time task flow status)
Log search and filter page
Mobile responsiveness

Plugin System

Pluggable Skill architecture
Third-party Skill marketplace
Custom agent role extensions
Agent achievement system
Agent interaction history (collaboration visualization)
Agent personas (avatars, signatures, work style tags)

Infrastructure

PostgreSQL / MySQL support
One-click Docker deployment
CI/CD for frontend builds
i18n support

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
app		app
docs		docs
prompts		prompts
rules		rules
skills		skills
static		static
webui		webui
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
README_CN.md		README_CN.md
config.example.yaml		config.example.yaml
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

OpenMOSS

✨ Key Features

Why OpenMOSS?

🎬 Live Demo: 1M Reviews

🧩 Use Cases

✅ Proven

💡 More Possibilities

Architecture

Task Lifecycle

Tech Stack

Task Hierarchy

Sub-task State Machine

Agent Roles

Agent Workflow

Project Structure

Quick Start

Requirements

Install & Run

Building the Frontend

Linux Server Deployment

Configuration

Full Config Example

Config Reference

API Docs

Authentication

WebUI Pages

Development Guide

Backend Development

Frontend Development

Tech Stack

Roadmap

Agent Onboarding

Frontend Improvements

Plugin System

Infrastructure

Star History

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages