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) · 🇨🇳 中文文档

• 🤖 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

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.

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

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.

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.

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.

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

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

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.

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

1. Call OpenMOSS API to check current state (What tasks do I have? Anything to review?)
2. Execute role-specific actions (Planner assigns tasks, Executor codes, Reviewer reviews…)
3. Write results back to OpenMOSS (submit deliverables, complete reviews, log activity)
4. 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.

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.

📘 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.

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

# 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:

1. config.yaml is generated from config.example.yaml
2. SQLite database initialized (data/tasks.db)
3. Frontend auto-mounted if static/ directory exists
4. 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:

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

# 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")

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.

# 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)

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

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

OpenMOSS uses a dual-layer authentication system:

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

# 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

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

• 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)

• 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

• 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)

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

MIT © 2026 小黄, 动动枪