Skill: zhenstaff/swarm-orchestrator (version 1.0.0)

--- name: swarm-orchestrator display_name: "Swarm Orchestrator / 群智调度器" description: AI Agent cluster orchestration platform - manage, schedule, and coordinate multiple AI agents locally with FastAPI backend and React dashboard version: 0.1.0 author: OpenClaw Team license: MIT tags: [orchestration, multi-agent, ai-agents, swarm, automation, fastapi, python, react, local-first] # Security & Requirements Declaration requires: # System tools (must be pre-installed) tools: - name: python version: ">=3.11" purpose: Backend runtime - name: node version: ">=18" purpose: Frontend build and runtime - name: redis version: ">=6" purpose: Task queue and caching - name: docker version: ">=20" purpose: Optional containerized deployment optional: true # Environment variables (all optional) env: - name: DATABASE_URL description: Database connection string default: "sqlite+aiosqlite:///./data/swarm.db" required: false sensitive: false - name: REDIS_URL description: Redis connection URL default: "redis://localhost:6379" required: false sensitive: false - name: SECRET_KEY description: Application secret key for sessions default: "generated-on-first-run" required: false sensitive: true - name: OPENAI_API_KEY description: Optional OpenAI API key for LLM agents required: false sensitive: true - name: ANTHROPIC_API_KEY description: Optional Anthropic API key for Claude agents required: false sensitive: true # Package to install packages: - name: openclaw-swarm-orchestrator source: npm version: "0.1.0" verified_repo: https://github.com/ZhenRobotics/openclaw-swarm-orchestrator verified_commit: acae6e5 install_command: "npm install -g openclaw-swarm-orchestrator" # Network & Security Policy network: external_servers: - description: "No external servers required for core functionality" - description: "Optional: OpenAI/Anthropic APIs if using LLM agents (user-controlled)" data_collection: none telemetry: none local_only: true # Installation verification verification: check_commands: - "swarm-orchestrator --version" - "curl http://localhost:8000/health" expected_files: - "~/.swarm-orchestrator/config.yml" - "./data/swarm.db" --- # 🇨🇳 中文版 # Swarm Orchestrator 技能 **状态：** 🟢 本地优先的 AI 智能体编排平台 **类型：** 自托管，无需外部依赖 **隐私：** 100% 本地处理（可选的大模型 API 调用除外） --- ## 🔒 安全与信任 ### 本技能的功能 - **本地运行** - 在您的机器上运行（后端 + 前端） - **无遥测** - 不收集数据 - **无需外部服务器** - 核心功能无需外部依赖 - **可选 API 密钥** - 仅在使用大模型智能体时需要（OpenAI/Claude） - **开源** - 所有代码可审计 ### 本技能不会做的事 - ❌ 不向外部服务器发送数据（可选的大模型 API 除外） - ❌ 不收集分析或遥测数据 - ❌ 不需要账号注册 - ❌ 不会未经许可访问您的文件 - ❌ 不会在您不知情的情况下运行后台进程 ### 数据存储 - **数据库：** SQLite 文件存储在 `./data/swarm.db`（仅本地） - **日志：** 文本文件存储在 `./logs/`（仅本地） - **缓存：** 本地 Redis（仅本地） - **无云同步** 或远程存储 --- ## 📋 概述 OpenClaw Swarm Orchestrator 是一个**本地优先**的平台，用于构建和管理多智能体 AI 系统。可以把它想象成协调多个 AI 智能体协同工作的"控制塔"。 ### 核心功能 - **智能体注册表** - 注册 LLM、工具、人类和自定义智能体 - **任务队列** - 基于优先级的任务分发与依赖管理 - **实时仪表板** - Web UI 监控智能体和任务 - **RESTful API** - 完整的 REST API 用于程序化控制 - **本地存储** - 所有数据保留在您的机器上 ### 架构 ``` ┌─────────────────┐ │ Web 仪表板 │ http://localhost:3000 │ (React UI) │ └────────┬────────┘ │ ┌────────▼────────┐ │ FastAPI 服务器 │ http://localhost:8000 │ (后端 API) │ └────────┬────────┘ │ ┌────────▼────────┐ │ 本地存储 │ │ • SQLite 数据库 │ ./data/swarm.db │ • Redis 缓存 │ localhost:6379 │ • 日志文件 │ ./logs/*.log └─────────────────┘ ``` --- ## 🚀 安装 ### 前置条件检查 安装前，请验证您已安装： ```bash # Python 3.11+ python --version # Node.js 18+ node --version # Redis redis-cli ping # 应该返回 PONG # (可选) Docker docker --version ``` ### 方法一：使用 Docker（推荐 - 最简单） **这是最安全的方法** - 所有内容都在容器中运行。 ```bash # 1. 克隆仓库（先检查代码！） git clone https://github.com/ZhenRobotics/openclaw-swarm-orchestrator.git cd openclaw-swarm-orchestrator # 2. 启动前查看 docker-compose.yml cat docker-compose.yml # 3. 启动服务 docker-compose up -d # 4. 验证 curl http://localhost:8000/health # 应该返回: {"status": "healthy"} ``` 访问： - **前端：** http://localhost:3000 - **后端 API：** http://localhost:8000 - **API 文档：** http://localhost:8000/docs ### 方法二：本地安装（用于开发） ```bash # 1. 通过 npm 安装（审查包后） npm view openclaw-swarm-orchestrator # 安装前查看 npm install -g openclaw-swarm-orchestrator # 2. 验证安装 swarm-orchestrator --version # 3. 启动服务（在不同终端中） # 终端 1: 启动 Redis redis-server # 终端 2: 启动后端 cd backend python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install -r requirements.txt uvicorn app.main:app --reload # 终端 3: 启动前端 cd frontend npm install npm run dev ``` ### 方法三：从源码安装（最透明） ```bash # 1. 克隆并检查 git clone https://github.com/ZhenRobotics/openclaw-swarm-orchestrator.git cd openclaw-swarm-orchestrator # 2. 验证提交哈希（安全检查） git log -1 --format="%H" # 应该是: acae6e5... (或最新发布标签) # 3. 运行前查看代码 cat backend/requirements.txt # 检查依赖 cat package.json # 检查 npm 依赖 cat docker-compose.yml # 检查容器配置 # 4. 安装依赖 cd backend && pip install -r requirements.txt cd ../frontend && npm install # 5. 运行（详细步骤见方法二） ``` --- ## ⚙️ 配置 ### 最小配置（仅本地） 在项目根目录创建 `.env`： ```bash # 最小配置 - 无需外部服务 DATABASE_URL=sqlite+aiosqlite:///./data/swarm.db REDIS_URL=redis://localhost:6379 SECRET_KEY=your-random-secret-key-here DEBUG=true ``` ### 可选：大模型智能体支持 如果您想使用大模型智能体（OpenAI、Anthropic），添加： ```bash # 可选 - 仅在使用大模型智能体时需要 OPENAI_API_KEY=sk-your-key-here ANTHROPIC_API_KEY=sk-ant-your-key-here ``` **⚠️ 安全提示：** - 仅在计划使用大模型智能体时添加 API 密钥 - 安全存储 `.env` 文件（不要提交到 git） - API 密钥永远不会发送到我们的服务器（仅发送到官方大模型提供商） --- ## 💻 基本使用 ### 1. 启动系统 ```bash # 使用 Docker docker-compose up -d # 或手动启动 redis-server & cd backend && uvicorn app.main:app --reload & cd frontend && npm run dev & ``` ### 2. 创建您的第一个智能体 **通过 Web UI：** 1. 打开 http://localhost:3000 2. 转到"智能体"页面 3. 点击"新建智能体" 4. 填写： - 名称："我的助手" - 类型："llm"（或"tool"、"human"、"custom"） - 配置：`{"model": "gpt-4"}`（如果使用大模型） **通过 API：** ```bash curl -X POST http://localhost:8000/api/agents \ -H "Content-Type: application/json" \ -d '{ "name": "我的助手", "type": "llm", "config": {"model": "gpt-4"} }' ``` ### 3. 创建任务 ```bash curl -X POST http://localhost:8000/api/tasks \ -H "Content-Type: application/json" \ -d '{ "title": "分析数据", "description": "处理销售报告", "priority": "high" }' ``` ### 4. 监控状态 **Web 仪表板：** http://localhost:3000 **API：** ```bash # 系统状态 curl http://localhost:8000/api/orchestrator/status # 列出智能体 curl http://localhost:8000/api/agents # 列出任务 curl http://localhost:8000/api/tasks ``` --- ## 🔧 智能体类型 ### 1. LLM 智能体（需要 API 密钥） 使用外部大模型 API（OpenAI、Anthropic）。 ```json { "name": "GPT-4 助手", "type": "llm", "config": { "model": "gpt-4", "temperature": 0.7 } } ``` **需要：** `OPENAI_API_KEY` 或 `ANTHROPIC_API_KEY` ### 2. 工具智能体（仅本地） 执行本地函数/脚本。 ```json { "name": "数据处理器", "type": "tool", "config": { "script_path": "./tools/process_data.py" } } ``` **无需外部服务。** ### 3. 人类智能体（仅本地） 人在回路工作流。 ```json { "name": "管理员审批", "type": "human", "config": { "notification": "email" } } ``` **无需外部服务。** ### 4. 自定义智能体（用户定义） 您定义行为。 ```python from swarm_orchestrator.base import BaseAgent class MyCustomAgent(BaseAgent): async def execute(self, task): # 您的自定义逻辑 return result ``` **无需外部服务。** --- ## 📊 监控与日志 ### Web 仪表板 访问 http://localhost:3000： - 实时智能体状态 - 任务队列监控 - 系统统计 - 执行日志 ### 日志文件 所有日志本地存储： ```bash # 应用日志 tail -f logs/swarm.log # Docker 日志（如果使用 Docker） docker-compose logs -f ``` --- ## 🔐 安全最佳实践 ### 1. API 密钥 - ✅ 存储在 `.env` 文件中（不在代码中） - ✅ 设置文件权限：`chmod 600 .env` - ✅ 将 `.env` 添加到 `.gitignore` - ✅ 永远不要将 API 密钥提交到 git ### 2. 网络安全 - ✅ 防火墙：阻止端口 8000、3000 的外部访问 - ✅ 开发时仅使用 localhost（不是 0.0.0.0） - ✅ 生产环境启用 HTTPS ### 3. 数据隐私 - ✅ 所有数据本地存储在 `./data/` - ✅ 数据库文件权限：`chmod 600 data/swarm.db` - ✅ 定期备份：`cp data/swarm.db backups/` --- ## 🐛 故障排除 ### 后端无法启动 ```bash # 检查 Python 版本 python --version # 必须是 3.11+ # 检查 Redis redis-cli ping # 必须返回 PONG # 检查日志 tail -f logs/swarm.log ``` ### 前端无法启动 ```bash # 检查 Node 版本 node --version # 必须是 18+ # 清除缓存 cd frontend rm -rf node_modules npm install ``` ### 端口冲突 ```bash # 检查端口 lsof -i :8000 # 后端 lsof -i :3000 # 前端 lsof -i :6379 # Redis # 如需终止进程 kill -9 <PID> ``` --- ## 📚 文档 - **主文档：** [README.md](https://github.com/ZhenRobotics/openclaw-swarm-orchestrator/blob/main/README.md) - **快速开始：** [QUICKSTART.md](https://github.com/ZhenRobotics/openclaw-swarm-orchestrator/blob/main/QUICKSTART.md) - **API 参考：** http://localhost:8000/docs（启动后端后） --- ## 🤝 支持与社区 - **问题反馈：** https://github.com/ZhenRobotics/openclaw-swarm-orchestrator/issues - **讨论：** https://github.com/ZhenRobotics/openclaw-swarm-orchestrator/discussions --- ## ✅ 安装前检查清单 使用本技能前： - [ ] 在 GitHub 上查看源代码 - [ ] 验证提交哈希：`acae6e5` - [ ] 检查 `requirements.txt` 和 `package.json` - [ ] 阅读上述安全策略 - [ ] 了解数据存储位置 - [ ] 知道需要哪些 API 密钥（如果有） - [ ] 首先在隔离环境中运行（可选） --- **版本：** 0.1.0 **状态：** Alpha - 活跃开发中 **本地优先：** ✅ 所有核心功能离线工作 **隐私：** ✅ 数据不离开您的机器（可选的大模型调用除外） --- # 🇬🇧 English Version # Swarm Orchestrator Skill **Status:** 🟢 Local-First AI Agent Orchestration Platform **Type:** Self-hosted, no external dependencies required **Privacy:** 100% local processing (except optional LLM API calls) --- ## 🔒 Security & Trust ### What This Skill Does - **Runs locally** on your machine (backend + frontend) - **No telemetry** or data collection - **No external servers** required for core functionality - **Optional API keys** only needed if you use LLM agents (OpenAI/Claude) - **Open source** - all code is auditable ### What This Skill Does NOT Do - ❌ Does not send data to external servers (except optional LLM APIs) - ❌ Does not collect analytics or telemetry - ❌ Does not require account registration - ❌ Does not access your files without permission - ❌ Does not run background processes without your knowledge ### Data Storage - **Database:** SQLite file in `./data/swarm.db` (local only) - **Logs:** Text files in `./logs/` (local only) - **Cache:** Redis on localhost (local only) - **No cloud sync** or remote storage --- ## 📋 Overview OpenClaw Swarm Orchestrator is a **local-first** platform for building and managing multi-agent AI systems. Think of it as a "control tower" for coordinating multiple AI agents working together. ### Core Features - **Agent Registry** - Register LLM, Tool, Human, and Custom agents - **Task Queue** - Priority-based task distribution with dependencies - **Real-time Dashboard** - Web UI to monitor agents and tasks - **RESTful API** - Complete REST API for programmatic control - **Local Storage** - All data stays on your machine ### Architecture ``` ┌─────────────────┐ │ Web Dashboard │ http://localhost:3000 │ (React UI) │ └────────┬────────┘ │ ┌────────▼────────┐ │ FastAPI Server │ http://localhost:8000 │ (Backend API) │ └────────┬────────┘ │ ┌────────▼────────┐ │ Local Storage │ │ • SQLite DB │ ./data/swarm.db │ • Redis Cache │ localhost:6379 │ • Log Files │ ./logs/*.log └─────────────────┘ ``` --- ## 🚀 Installation ### Prerequisites Check Before installing, verify you have: ```bash # Python 3.11+ python --version # Node.js 18+ node --version # Redis redis-cli ping # Should return PONG # (Optional) Docker docker --version ``` ### Method 1: Using Docker (Recommended - Easiest) **This is the safest method** - everything runs in containers. ```bash # 1. Clone repository (inspect code first!) git clone https://github.com/ZhenRobotics/openclaw-swarm-orchestrator.git cd openclaw-swarm-orchestrator # 2. Review docker-compose.yml before starting cat docker-compose.yml # 3. Start services docker-compose up -d # 4. Verify curl http://localhost:8000/health # Should return: {"status": "healthy"} ``` Access: - **Frontend:** http://localhost:3000 - **Backend API:** http://localhost:8000 - **API Docs:** http://localhost:8000/docs ### Method 2: Local Installation (For Development) ```bash # 1. Install via npm (after reviewing package) npm view openclaw-swarm-orchestrator # Review before installing npm install -g openclaw-swarm-orchestrator # 2. Verify installation swarm-orchestrator --version # 3. Start services (in separate terminals) # Terminal 1: Start Redis redis-server # Terminal 2: Start backend cd backend python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install -r requirements.txt uvicorn app.main:app --reload # Terminal 3: Start frontend cd frontend npm install npm run dev ``` ### Method 3: From Source (Most Transparent) ```bash # 1. Clone and inspect git clone https://github.com/ZhenRobotics/openclaw-swarm-orchestrator.git cd openclaw-swarm-orchestrator # 2. Verify commit hash (security check) git log -1 --format="%H" # Should be: acae6e5... (or latest release tag) # 3. Review code before running cat backend/requirements.txt # Check dependencies cat package.json # Check npm deps cat docker-compose.yml # Check container config # 4. Install dependencies cd backend && pip install -r requirements.txt cd ../frontend && npm install # 5. Run (see Method 2 for detailed steps) ``` --- ## ⚙️ Configuration ### Minimal Configuration (Local Only) Create `.env` in project root: ```bash # Minimal config - no external services needed DATABASE_URL=sqlite+aiosqlite:///./data/swarm.db REDIS_URL=redis://localhost:6379 SECRET_KEY=your-random-secret-key-here DEBUG=true ``` ### Optional: LLM Agent Support If you want to use LLM agents (OpenAI, Anthropic), add: ```bash # Optional - only if using LLM agents OPENAI_API_KEY=sk-your-key-here ANTHROPIC_API_KEY=sk-ant-your-key-here ``` **⚠️ Security Note:** - Only add API keys if you plan to use LLM agents - Store `.env` file securely (not in git) - API keys are never sent to our servers (only to official LLM providers) --- ## 💻 Basic Usage ### 1. Start the System ```bash # Using Docker docker-compose up -d # Or manually redis-server & cd backend && uvicorn app.main:app --reload & cd frontend && npm run dev & ``` ### 2. Create Your First Agent **Via Web UI:** 1. Open http://localhost:3000 2. Go to "Agents" page 3. Click "New Agent" 4. Fill in: - Name: "My Assistant" - Type: "llm" (or "tool", "human", "custom") - Config: `{"model": "gpt-4"}` (if using LLM) **Via API:** ```bash curl -X POST http://localhost:8000/api/agents \ -H "Content-Type: application/json" \ -d '{ "name": "My Assistant", "type": "llm", "config": {"model": "gpt-4"} }' ``` ### 3. Create a Task ```bash curl -X POST http://localhost:8000/api/tasks \ -H "Content-Type: application/json" \ -d '{ "title": "Analyze data", "description": "Process the sales report", "priority": "high" }' ``` ### 4. Monitor Status **Web Dashboard:** http://localhost:3000 **API:** ```bash # System status curl http://localhost:8000/api/orchestrator/status # List agents curl http://localhost:8000/api/agents # List tasks curl http://localhost:8000/api/tasks ``` --- ## 🔧 Agent Types ### 1. LLM Agents (Requires API Key) Uses external LLM APIs (OpenAI, Anthropic). ```json { "name": "GPT-4 Assistant", "type": "llm", "config": { "model": "gpt-4", "temperature": 0.7 } } ``` **Required:** `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` ### 2. Tool Agents (Local Only) Executes local functions/scripts. ```json { "name": "Data Processor", "type": "tool", "config": { "script_path": "./tools/process_data.py" } } ``` **No external services needed.** ### 3. Human Agents (Local Only) Human-in-the-loop workflows. ```json { "name": "Manager Approval", "type": "human", "config": { "notification": "email" } } ``` **No external services needed.** ### 4. Custom Agents (User-Defined) You define the behavior. ```python from swarm_orchestrator.base import BaseAgent class MyCustomAgent(BaseAgent): async def execute(self, task): # Your custom logic return result ``` **No external services needed.** --- ## 📊 Monitoring & Logs ### Web Dashboard Access at http://localhost:3000: - Real-time agent status - Task queue monitoring - System statistics - Execution logs ### Log Files All logs stored locally: ```bash # Application logs tail -f logs/swarm.log # Docker logs (if using Docker) docker-compose logs -f ``` --- ## 🔐 Security Best Practices ### 1. API Keys - ✅ Store in `.env` file (not in code) - ✅ Set file permissions: `chmod 600 .env` - ✅ Add `.env` to `.gitignore` - ✅ Never commit API keys to git ### 2. Network Security - ✅ Firewall: Block ports 8000, 3000 from external access - ✅ Use localhost only (not 0.0.0.0) for development - ✅ Enable HTTPS in production ### 3. Data Privacy - ✅ All data stored locally in `./data/` - ✅ Database file permissions: `chmod 600 data/swarm.db` - ✅ Regular backups: `cp data/swarm.db backups/` --- ## 🐛 Troubleshooting ### Backend won't start ```bash # Check Python version python --version # Must be 3.11+ # Check Redis redis-cli ping # Must return PONG # Check logs tail -f logs/swarm.log ``` ### Frontend won't start ```bash # Check Node version node --version # Must be 18+ # Clear cache cd frontend rm -rf node_modules npm install ``` ### Port conflicts ```bash # Check ports lsof -i :8000 # Backend lsof -i :3000 # Frontend lsof -i :6379 # Redis # Kill processes if needed kill -9 <PID> ``` --- ## 📚 Documentation - **Main Docs:** [README.md](https://github.com/ZhenRobotics/openclaw-swarm-orchestrator/blob/main/README.md) - **Quick Start:** [QUICKSTART.md](https://github.com/ZhenRobotics/openclaw-swarm-orchestrator/blob/main/QUICKSTART.md) - **API Reference:** http://localhost:8000/docs (after starting backend) --- ## 🤝 Support & Community - **Issues:** https://github.com/ZhenRobotics/openclaw-swarm-orchestrator/issues - **Discussions:** https://github.com/ZhenRobotics/openclaw-swarm-orchestrator/discussions --- ## ✅ Pre-Installation Checklist Before using this skill: - [ ] Review source code on GitHub - [ ] Verify commit hash: `acae6e5` - [ ] Check `requirements.txt` and `package.json` - [ ] Read security policy above - [ ] Understand data storage locations - [ ] Know which API keys you need (if any) - [ ] Run in isolated environment first (optional) --- **Version:** 0.1.0 **Status:** Alpha - Active Development **Local-First:** ✅ All core features work offline **Privacy:** ✅ No data leaves your machine (except optional LLM calls) --- *Built with privacy and transparency in mind. Inspect the code before you trust it.*


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)