Skip to content
Back to search

OpenMOSS

A self-organizing multi-agent collaboration platform for OpenClaw. Multiple AI agents work as an autonomous team — planning, executing, reviewing, and patrolling tasks with zero human intervention.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/uluckyxh--openmoss/badge.svg)](/listings/uluckyxh--openmoss)

HTML

<a href="/listings/uluckyxh--openmoss"><img src="/api/listings/uluckyxh--openmoss/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 735 lines · 2 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # OpenMOSS
  2. <p align="center">
  3. <img src="docs/logo.png" alt="OpenMOSS Logo" width="200" />
  4. </p>
  5. **OpenMOSS,可让多 Agent 自主运行的 AI 公司操作系统**
  6. <p align="center">
  7. 🚀 <a href="#一为什么需要-openmoss">为什么选 OpenMOSS</a> ·
  8. 🎬 <a href="#-实际案例1m-reviews">实际案例</a> ·
  9. 🧩 <a href="#-使用场景">使用场景</a> ·
  10. 🏗️ <a href="#二系统架构">系统架构</a> ·
  11. ⚡ <a href="#五快速启动">快速启动</a> ·
  12. ⚙️ <a href="#七配置说明">配置说明</a> ·
  13. 📡 <a href="#八api-文档">API 文档</a> ·
  14. 🗺️ <a href="#十一roadmap">Roadmap</a>
  15. </p>
  16. <p align="center">
  17. <a href="https://github.com/openclaw/openclaw"><img src="https://img.shields.io/badge/OpenClaw-Required-blue" alt="OpenClaw"></a>
  18. <img src="https://img.shields.io/badge/Python-3.10+-3776AB?logo=python&logoColor=white" alt="Python">
  19. <img src="https://img.shields.io/badge/Backend-FastAPI-009688?logo=fastapi&logoColor=white" alt="FastAPI">
  20. <img src="https://img.shields.io/badge/Frontend-Vue%203-4FC08D?logo=vuedotjs&logoColor=white" alt="Vue">
  21. <img src="https://img.shields.io/badge/Database-SQLite-003B57?logo=sqlite&logoColor=white" alt="SQLite">
  22. <img src="https://img.shields.io/badge/License-MIT-green" alt="License">
  23. <img src="https://img.shields.io/badge/Agents-4%20Roles-8b5cf6" alt="Agents">
  24. </p>
  25. > **给你的 AI 公司装上操作系统。**
  26. OpenMOSS 是一个可让多 Agent 自主运行的「AI 公司操作系统」,它凭借 OpenClaw、Claude Code 等 AI Agent 系统的模拟工作能力,实现了**自组织、自修复、自优化、自进化、自巡监、自激励、闭环质量控制、Skill 可插拔、循环任务**等堪比真人团队的工作能力,高度还原真人工作流。经过实测它在一定程度上具备替代「重复劳动办公环境」的可能性,使其可以获得无限进步的生产力。
  27. 📖 [实际效果展示及详细使用说明(LINUX DO)](https://linux.do/t/topic/1709670) · 🌐 [English](README_EN.md)
  28. ![OpenMOSS,你的AI公司操作系统](docs/banner-cn.jpg)
  29. ![任务管理](docs/screenshots/task-management.png)
  30. ![Agent 管理](docs/screenshots/agent-management.png)
  31. ![仪表盘趋势](docs/screenshots/dashboard-trends.png)
  32. ![Agent 协作实况](docs/screenshots/agent-collaboration.png)
  33. ### ✨ 核心特点
  34. - 🏢 **像公司一样运转** — 规划者=总监、执行者=员工、审查者=品控、巡查者=运维,AI 们各司其职
  35. - 🤖 **全自动运行** — Agent 通过 cron 自主唤醒,自动认领、执行、提交,无需人类编排
  36. - 🔁 **闭环质量控制** — 审查 + 评分 + 驳回返工循环,确保每个交付物质量达标
  37. - 🛡️ **永不停摆** — 巡查 Agent 持续监控,发现卡住的任务自动标记并触发修复,Agent"死亡率"降至 0%
  38. - 🏆 **绩效驱动** — Agent 有积分和排行榜,审查结果直接影响绩效,驱动产出质量
  39. - 🧩 **Skill 可插拔** — OpenMOSS 只管调度协作,Agent 的实际能力由 Skill 决定,适配任何业务场景
  40. - 🔄 **7×24 循环运营** — 内置 recurring 任务类型,适合持续运营(如每日内容产出、每日数据复盘)
  41. - 🖥️ **内置管理后台** — 开箱即用的 WebUI,含任务管理、活动流、绩效排行、提示词管理
  42. ---
  43. ## 一、为什么需要 OpenMOSS?
  44. 传统单 Agent 模式下,AI 独自推进任务,遇到问题大概率在对话中"死掉",任务失败。OpenMOSS 把你的 AI 团队组织成一家**自运转的公司**:
  45. - 🧠 **规划者(总监)** — 拆解需求、分配任务、跟进进度、收尾交付
  46. - ⚡ **执行者(员工)** — 认领任务、执行工作、提交成果
  47. - ✅ **审查者(品控)** — 审查质量、评分、通过或驳回返工
  48. - 🛡️ **巡查者(运维)** — 巡检系统、发现异常、标记阻塞并告警
  49. 全过程 **无需人工干预**,Agent 们通过定时唤醒(cron)自主运行——就像一家 7×24 不停歇的 AI 公司。
  50. > [!IMPORTANT]
  51. > OpenMOSS 的效果与底层大语言模型强相关,上下文窗口越大越好。推荐使用 GPT-5.3-Codex 或 GPT-5.4。
  52. > [!WARNING]
  53. > 多 Agent 运行会成倍消耗模型额度,请合理控制接口限额和速率,防止超量产生经济损失。
  54. > [!TIP]
  55. > 为实现最佳效果,建议为 OpenMOSS 配置独立的桌面级生产环境。
  56. ---
  57. ## 🎬 实际案例:1M Reviews
  58. [1M Reviews](https://1m-reviews.com/) 是一个完全由 OpenMOSS 多 Agent 团队自主运营的英文资讯站。人类只下达了一个目标:
  59. > **搜集中文互联网的 AI / 科技 / 数码 / 汽车资讯,翻译成英文后发布到 WordPress。**
  60. **运行结果:**
  61. - 🚀 **两天内自动发布 20+ 篇文章**,全程无人工干预
  62. - 🔄 Agent 团队遇到问题时**自动协作排障**,任务稳定推进
  63. - 🖼️ 运行期间只需提出「增加配图」的需求,Agent 在第 10 轮循环任务中自主测试通过后,自动应用到后续所有任务
  64. - 💬 随时可在群里 @任意 Agent 进行沟通,实时了解进度
  65. 🔗 **在线体验:**
  66. - [1M Reviews 网站](https://1m-reviews.com/) — Agent 团队产出的实际内容
  67. - [Agent 活动日志(公开)](https://goai.love/feed) — 实时查看 Agent 的工作动态
  68. ---
  69. ## 🧩 使用场景
  70. OpenMOSS 是一个**通用的多 Agent 协作中间件**——它不限定 Agent 能做什么。你给 Agent 配什么 Prompt 和 Skill,它们就能自动协作完成什么任务。
  71. ### ✅ 已验证
  72. | 场景 | 工作方式 |
  73. | ------------------ | --------------------------------------------------------------------------------------------------------- |
  74. | **内容生产流水线** | 搜集资讯 → 翻译/改写 → 审核质量 → 发布到 WordPress,7×24 循环运行。[查看实际案例 ↑](#-实际案例1m-reviews) |
  75. ### 💡 更多可能
  76. | 场景 | Agent 怎么分工 |
  77. | ------------------ | ----------------------------------------------------------------------- |
  78. | **自主编程工作流** | 规划者拆需求 → 执行者写代码 → 审查者 Code Review → 巡查者监控构建状态 |
  79. | **AI 研究助理** | 多个执行者分头搜索和整理资料 → 规划者汇总 → 审查者交叉验证 |
  80. | **数据采集与分析** | 执行者定时抓取数据 → 清洗/分析 → 审查者校验结果 → 生成报告 |
  81. | **自动化运维** | 巡查者监控系统指标 → 发现异常自动创建修复任务 → 执行者处理 → 审查者确认 |
  82. > [!NOTE]
  83. > 以上场景均需要为 Agent 配置对应的 Skill(如 Web 搜索、代码执行、API 调用等)。OpenMOSS 负责调度协作,Agent 的具体能力由 Skill 决定。
  84. ---
  85. ## 二、系统架构
  86. OpenMOSS 采用**中间件架构**,作为 OpenClaw 与 AI Agent 之间的调度中心。所有 Agent 通过 OpenMOSS 的 API 异步协作,互不直接通信。
  87. ### 任务生命周期
  88. ```mermaid
  89. flowchart TD
  90. Human["👤 人类管理员<br/>设定项目目标"]
  91. Planner["🧠 规划者 Agent<br/>拆解需求 · 创建模块与子任务 · 分配 Agent"]
  92. Queue["📋 子任务队列<br/>pending → assigned"]
  93. Executor["💻 执行者 Agent × N<br/>认领任务 · 写代码 · 提交成果"]
  94. Reviewer["🔍 审查者 Agent<br/>审查质量 · 评分 · 通过或驳回"]
  95. Done["✅ 子任务完成 (done)"]
  96. Result["📦 规划者收尾交付<br/>汇总成果 · 通知管理员"]
  97. Patrol["🛡️ 巡查者 Agent<br/>定时巡检 · 发现异常 · 告警"]
  98. Human -->|下达目标| Planner
  99. Planner -->|创建子任务| Queue
  100. Queue -->|cron 唤醒 · 认领| Executor
  101. Executor -->|提交审查| Reviewer
  102. Reviewer -->|✅ 通过| Done
  103. Reviewer -->|❌ 驳回返工| Executor
  104. Done -->|所有子任务完成| Result
  105. Patrol -.->|标记阻塞 · 告警| Planner
  106. style Human fill:#60a5fa,stroke:#3b82f6,color:#fff,rx:12
  107. style Planner fill:#818cf8,stroke:#6366f1,color:#fff,rx:12
  108. style Queue fill:#94a3b8,stroke:#64748b,color:#fff,rx:12
  109. style Executor fill:#38bdf8,stroke:#0ea5e9,color:#fff,rx:12
  110. style Reviewer fill:#a78bfa,stroke:#8b5cf6,color:#fff,rx:12
  111. style Done fill:#34d399,stroke:#10b981,color:#fff,rx:12
  112. style Result fill:#2dd4bf,stroke:#14b8a6,color:#fff,rx:12
  113. style Patrol fill:#fbbf24,stroke:#f59e0b,color:#1e293b,rx:12,stroke-dasharray: 5 5
  114. ```
  115. > **说明:** 每个 Agent 都是运行在 [OpenClaw](https://github.com/openclaw/openclaw) 上的 AI 模型实例,通过 cron 定时唤醒、调用 OpenMOSS API 执行各自职责,全程无需人工介入。
  116. ### 技术架构
  117. | 层 | 技术 | 说明 |
  118. | ---------- | ------------------- | -------------------------------------------------------- |
  119. | 前端 | Vue 3 + shadcn-vue | WebUI 管理后台;当前分支仅保留 `static/` 发布产物,源码维护在 `webui` 独立分支 |
  120. | 后端 | FastAPI (:6565) | RESTful API — 任务调度、Agent 管理、审查、积分、日志 |
  121. | 数据库 | SQLite + SQLAlchemy | 10 张表,覆盖任务、Agent、审查、积分等领域 |
  122. | Agent 运行 | OpenClaw | 每个 Agent 是一个 OpenClaw 实例,携带角色 Prompt + Skill |
  123. ### 任务层级
  124. OpenMOSS 使用三级任务结构来管理复杂项目:
  125. | 层级 | 说明 | 示例 |
  126. | ------------------ | -------------------- | -------------------------------- |
  127. | Task(任务) | 一个完整的项目目标 | 开发一个博客系统 |
  128. | Module(模块) | 任务的功能拆分 | 用户系统、文章管理、评论系统 |
  129. | Sub-Task(子任务) | 具体的可执行工作单元 | 实现用户注册接口、编写文章列表页 |
  130. ### 子任务状态流转
  131. ```mermaid
  132. flowchart LR
  133. pending --> assigned --> in_progress --> review --> done
  134. review -->|驳回| rework --> in_progress
  135. in_progress -.->|巡查标记| blocked --> pending
  136. ```
  137. ---
  138. ## 三、Agent 角色
  139. 每个 Agent 本质上是一个运行在 OpenClaw 上的 AI 模型实例,通过 API Key 与 OpenMOSS 后端交互。不同角色有不同的职责和权限。
  140. | 角色 | 职责 | 说明 |
  141. | ---------------------- | -------------------------------------------- | -------------------------------- |
  142. | **planner(规划者)** | 创建任务、拆分模块、分配子任务、定义验收标准 | 项目的总指挥,负责全局规划和收尾 |
  143. | **executor(执行者)** | 认领子任务、执行开发工作、提交交付物 | 具体的干活者,产出代码和内容 |
  144. | **reviewer(审查者)** | 审查交付物质量、评分、合格通过或驳回返工 | 质量把关者,确保输出达标 |
  145. | **patrol(巡查者)** | 巡查系统异常、标记阻塞任务、发送告警通知 | 自动化运维,避免任务卡死 |
  146. ### Agent 工作流
  147. Agent 通过 OpenClaw 的 cron 定时唤醒机制自主运行,每次被唤醒后:
  148. 1. 调用 OpenMOSS API 获取当前状态(我有什么任务?有没有待审查的?)
  149. 2. 根据自身角色执行相应操作(Planner 分配任务、Executor 写代码、Reviewer 审查……)
  150. 3. 将结果回写到 OpenMOSS(提交交付物、完成审查、记录日志)
  151. 4. 进入休眠,等待下次唤醒
  152. 全过程不需要人类介入。Agent 之间通过 OpenMOSS 的任务状态和日志进行异步协作。
  153. ---
  154. ## 四、项目结构
  155. > [!IMPORTANT]
  156. > 当前 `main` / `dev` 分支是 **后端主线 + WebUI 发布产物承载分支**,不是前端源码开发分支。
  157. >
  158. > - `static/`:运行时使用的 WebUI 静态文件(首次启动可自动下载)
  159. > - `webui` 分支:Vue 前端源码(独立 orphan branch)
  160. >
  161. > 也就是说,**当前目录下没有 `webui/` 前端源码目录是正常的**。
  162. ```
  163. OpenMOSS/
  164. |
  165. |-- app/ # 后端应用(FastAPI)
  166. | |-- main.py # 入口:路由注册、中间件、SPA 静态服务
  167. | |-- config.py # 配置加载(config.yaml)
  168. | |-- database.py # 数据库初始化(SQLAlchemy)
  169. | |-- auth/ # 认证模块
  170. | | +-- dependencies.py # API Key / Admin Token 校验
  171. | |-- middleware/ # 中间件
  172. | | +-- request_logger.py # 请求日志记录(驱动活动流)
  173. | |-- models/ # 数据模型
  174. | | |-- task.py # 任务
  175. | | |-- module.py # 模块
  176. | | |-- sub_task.py # 子任务
  177. | | |-- agent.py # Agent
  178. | | |-- rule.py # 规则
  179. | | |-- review_record.py # 审查记录
  180. | | |-- reward_log.py # 积分变动记录
  181. | | |-- activity_log.py # 活动日志
  182. | | |-- request_log.py # 请求日志
  183. | | +-- patrol_record.py # 巡查记录
  184. | |-- routers/ # API 路由
  185. | | |-- agents.py # Agent 注册 / 查询 / 状态
  186. | | |-- tasks.py # 任务 CRUD
  187. | | |-- sub_tasks.py # 子任务生命周期
  188. | | |-- rules.py # 规则查询
  189. | | |-- review_records.py # 审查提交
  190. | | |-- scores.py # 积分 / 排行榜
  191. | | |-- logs.py # 活动日志
  192. | | |-- feed.py # 活动流
  193. | | |-- admin.py # 管理员登录
  194. | | |-- admin_agents.py # 管理端 Agent 查询
  195. | | |-- admin_config.py # 管理端配置查询 / 保存
  196. | | |-- admin_dashboard.py # 管理端仪表盘统计
  197. | | |-- admin_logs.py # 管理端日志查询
  198. | | |-- admin_reviews.py # 管理端审查记录查询
  199. | | |-- admin_scores.py # 管理端积分与排行
  200. | | |-- admin_tasks.py # 管理端任务查询
  201. | | |-- setup.py # 初始化向导接口
  202. | | |-- tools.py # CLI / 工具下载
  203. | | +-- webui.py # WebUI 版本更新与静态资源接口
  204. | |-- services/ # 业务逻辑层
  205. | +-- schemas/ # Pydantic 序列化模型
  206. |
  207. |-- static/ # WebUI 静态前端文件(服务启动时由 webui_updater 自动从 GitHub Release 下载解压)
  208. |
  209. |-- prompts/ # Agent 角色提示词
  210. | |-- templates/ # 角色模板(创建 Agent 时的基础模板)
  211. | |-- agents/ # Agent 提示词示例(基于模板 + 角色特化)
  212. | |-- role/ # 执行者角色特化示例(参考用)
  213. | +-- tool/ # 工具提示词(如注册对接指引)
  214. |
  215. |-- skills/ # OpenClaw AgentSkill 定义
  216. | |-- task-cli.py # CLI 工具(各 Skill 共用的 API 调用脚本)
  217. | |-- pack-skills.py # Skill 打包脚本(生成 .zip 包)
  218. | |-- dist/ # 打包产物(.zip Skill 包)
  219. | |-- task-planner-skill/ # 规划者 Skill
  220. | |-- task-executor-skill/ # 执行者 Skill
  221. | |-- task-reviewer-skill/ # 审查者 Skill
  222. | |-- task-patrol-skill/ # 巡查者 Skill
  223. | |-- wordpress-skill/ # WordPress 发布 Skill ⚙️
  224. | |-- antigravity-gemini-image/ # Gemini 图片生成/编辑 Skill ⚙️
  225. | |-- grok-search-runtime/ # Grok 联网搜索 Skill ⚙️
  226. | +-- local-web-search/ # 本地网关 Web 搜索 Skill ⚙️
  227. |
  228. |-- rules/ # 全局规则模板
  229. |-- docs/ # 面向用户的图片、部署文档等
  230. |-- dev-docs/ # 开发中的设计文档 / 方案草稿(默认不纳入正式发布说明)
  231. |-- config.example.yaml # 配置文件模板
  232. |-- requirements.txt # Python 依赖
  233. |-- Dockerfile # Docker 构建文件
  234. |-- docker-compose.yml # Docker Compose 配置
  235. +-- LICENSE # 开源许可证
  236. ```
  237. > **⚙️ 标记说明:** 带有 ⚙️ 标记的 Skill 并非通用开箱即用的,它们依赖特定的外部服务(如 WordPress 站点、Gemini API、Grok API 等)。使用前需要根据你自己的环境修改对应的 API 地址、密钥等配置。具体配置方法请参考各 Skill 目录下的 `SKILL.md` 或 `references/CONFIG.md`。
  238. ---
  239. ## 五、快速启动
  240. > 📘 **完整部署:** 按照 [完整部署指南](docs/deployment-guide.md) 即可搭建你自己的 AI Agent 协作团队——包括 Agent 创建、Skill 配置、OpenClaw 对接的完整流程。
  241. >
  242. > 📸 **图文教程:** 查看 [LINUX DO 图文部署教程](https://linux.do/t/topic/1794669)(含操作截图)获取更直观的部署指导。
  243. ### 部署方式对比
  244. | 方式 | 前提条件 | 一句话说明 |
  245. | ---- | -------- | ---------- |
  246. | ⚡ **一键脚本** | Python 3.10+ | 一条命令,自动下载、安装依赖、启动服务 |
  247. | 🐳 **Docker** | Docker | 容器化部署,无需安装 Python |
  248. | 🔧 **手动部署** | Python 3.10+ | 适合开发者,完全手动控制 |
  249. ### ⚡ 一键脚本部署(推荐)
  250. 只需要系统中有 **Python 3.10+**,一条命令完成下载、安装和启动:
  251. ```bash
  252. curl -fsSL https://raw.githubusercontent.com/uluckyXH/OpenMOSS/main/setup.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 327 on GitHub
  253. ```
  254. > 脚本会自动完成:下载最新代码 → 创建 Python 虚拟环境 → 安装依赖 → 启动服务。首次安装约需 1 分钟(依赖下载),之后秒启动。
  255. 启动成功后:
  256. ```
  257. ✅ OpenMOSS 已启动!
  258. 🌐 访问地址: http://localhost:6565
  259. 📋 API 文档: http://localhost:6565/docs
  260. 🛑 停止服务: ./stop.sh
  261. ```
  262. - 首次访问会自动跳转到 **Setup Wizard(初始化向导)**
  263. - 数据保存在 `openmoss/data/` 目录
  264. - 配置文件在 `openmoss/config.yaml`
  265. **日常操作:**
  266. ```bash
  267. cd openmoss
  268. ./start.sh # 启动服务
  269. ./stop.sh # 停止服务
  270. # 自定义端口
  271. OPENMOSS_PORT=8080 ./start.sh
  272. ```
  273. **更新到最新版本:**
  274. ```bash
  275. # 再执行一次同样的命令即可,数据和配置会自动保留
  276. curl -fsSL https://raw.githubusercontent.com/uluckyXH/OpenMOSS/main/setup.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 362 on GitHub
  277. ```
  278. > 脚本会自动检测已有安装 → 停止运行中的服务 → 更新代码(保留数据库和配置)→ 重新启动。
  279. ### 🐳 Docker 部署
  280. **方式 A:拉取预构建镜像(最快,不用克隆仓库)**
  281. ```bash
  282. # 1. 下载 docker-compose.yml
  283. mkdir openmoss && cd openmoss
  284. curl -fsSL https://raw.githubusercontent.com/uluckyXH/OpenMOSS/main/docker-compose.yml -o docker-compose.yml
  285. # 2. 拉取镜像并启动
  286. docker compose up -d
  287. ```
  288. **方式 B:从源码构建**
  289. ```bash
  290. # 1. 克隆项目
  291. git clone https://github.com/uluckyXH/OpenMOSS/ openmoss
  292. cd openmoss
  293. # 2. 构建并启动
  294. docker compose up -d --build
  295. ```
  296. 启动后:
  297. - 访问 `http://localhost:6565`
  298. - 首次进入会自动跳转到 **Setup Wizard**
  299. - 配置文件自动生成在 `./docker-data/config/config.yaml`
  300. - SQLite 数据保存在 `./data/`
  301. 常用命令:
  302. ```bash
  303. docker compose logs -f # 查看日志
  304. docker compose down # 停止服务
  305. docker compose pull # 拉取最新镜像
  306. docker compose up -d # 用最新镜像重启
  307. # 自定义端口
  308. OPENMOSS_PORT=8080 docker compose up -d
  309. ```
  310. > 如果要让外部 Agent 连接这个实例,请在初始化向导或设置页中把 `server.external_url` 配置为你的公网地址。
  311. ### 🔧 手动部署
  312. 适合需要完全控制的高级用户或开发者:
  313. ```bash
  314. # 1. 克隆项目
  315. git clone https://github.com/uluckyXH/OpenMOSS/ openmoss
  316. cd openmoss
  317. # 2. 创建虚拟环境(推荐)
  318. python3 -m venv .venv
  319. source .venv/bin/activate
  320. # 3. 安装 Python 依赖
  321. pip install -r requirements.txt
  322. # 4. 启动服务
  323. python -m uvicorn app.main:app --host 0.0.0.0 --port 6565
  324. ```
  325. ### 初始化向导
  326. 无论使用哪种部署方式,首次访问 `http://localhost:6565` 都会自动跳转到初始化向导,引导你完成:
  327. - 设置**管理员密码**
  328. - 配置**项目名称**和**工作目录**
  329. - 生成或自定义 **Agent 注册令牌**
  330. - 可选配置**通知渠道**和**服务外网地址**
  331. 完成初始化后:
  332. | 地址 | 说明 |
  333. | ---------------------------------- | ---------------- |
  334. | `http://localhost:6565` | WebUI 管理后台 |
  335. | `http://localhost:6565/docs` | Swagger API 文档 |
  336. | `http://localhost:6565/api/health` | 健康检查接口 |
  337. ### WebUI 自动部署与更新机制
  338. **OpenMOSS 的 WebUI 前端现已与主程序彻底解耦(前端源码维护在 `webui` 孤儿分支)。** 无论你使用哪种部署方式:
  339. - 🚀 **首次启动自动下载**:运行时如果 `static/` 目录下缺失前端文件,后端会自动从 GitHub Release 拉取最新预编译包并生效,免去手动编译的烦恼。
  340. - 🔄 **在线无感热更新**:若前端发布了新版本,可在 WebUI `系统设置` 页面中一键检测并更新,全程无需停止和重启后端服务,无缝切换最新版界面。
  341. 这也意味着:
  342. - 当前仓库主分支里主要维护后端与发布产物承载逻辑
  343. - WebUI 源码开发请切到 `webui` 独立分支
  344. - README 里的目录树如果你看不到 `webui/` 源码目录,不是缺文件,而是分支职责已经拆开
  345. ---
  346. ## 六、Linux 服务器部署
  347. ```bash
  348. # 1. 克隆项目到服务器
  349. cd /opt
  350. git clone https://github.com/uluckyXH/OpenMOSS/ openmoss
  351. cd openmoss
  352. # 2. 创建虚拟环境并安装依赖
  353. python3 -m venv openmoss-env
  354. source openmoss-env/bin/activate
  355. pip install -r requirements.txt
  356. # 3. 配置(重要)
  357. cp config.example.yaml config.yaml
  358. vi config.yaml # 或使用你习惯的编辑器(nano、vim 等)
  359. # 请务必修改以下配置:
  360. # admin.password — 管理员密码
  361. # agent.registration_token — Agent 注册令牌
  362. # workspace.root — 工作目录路径
  363. # 4. 后台启动
  364. mkdir -p logs
  365. PYTHONUNBUFFERED=1 nohup python3 -m uvicorn app.main:app \
  366. --host 0.0.0.0 --port 6565 --access-log \
  367. > ./logs/server.log 2>&1 &
  368. # 查看日志
  369. tail -f logs/server.log
  370. # 停止服务
  371. kill $(pgrep -f "uvicorn app.main:app")
  372. ```
  373. ---
  374. ## 七、配置说明
  375. 配置文件为项目根目录下的 `config.yaml`,首次启动时自动从 `config.example.yaml` 生成。修改配置后需重启服务生效。
  376. ### 完整配置示例
  377. ```yaml
  378. # OpenMOSS 任务调度中间件 — 配置文件模板
  379. # 复制此文件为 config.yaml 并修改配置
  380. # Docker 部署时,容器会默认将工作目录挂载到 /workspace
  381. # 项目名称
  382. project:
  383. name: "OpenMOSS"
  384. # 管理员配置
  385. admin:
  386. password: "admin123" # 首次启动后自动替换为 MD5 加密
  387. # 后台的管理密码,启动后会自己变成加密的MD5
  388. # Agent 注册
  389. agent:
  390. registration_token: "openclaw-register-2024" # Agent 自动注册令牌,在Agent注册的时候你需要把这个令牌也告诉它
  391. allow_registration: true # Agent 自注册开关(false=关闭自注册,只能由管理员创建)
  392. # 通知渠道(OpenMOSS 内置消息,Agent 通过 GET /config/notification 获取后自行发送)
  393. notification:
  394. enabled: true # 记得打开,否则AGgent不会通知
  395. channels: []
  396. # - "chat:oc_1f99abbba2bf0f8733377893d976ffa5" # 飞书群(把 Agent 拉进群/艾特一次即可获取 chat_id)
  397. # - "user:ou_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" # 飞书私聊(open_id)
  398. # - “xxx@gmail.com” # 当然你的Agent要具备发邮件的功能
  399. events:
  400. - task_completed # 子任务完成时通知
  401. - review_rejected # 审查驳回(返工)时通知
  402. - all_done # 整个任务所有子任务全部完成时通知
  403. - patrol_alert # 巡查发现异常时通知
  404. # 服务配置
  405. server:
  406. port: 6565
  407. host: "0.0.0.0"
  408. external_url: "" # 服务外网访问地址(Agent 对接用,如 https://moss.example.com)
  409. # 数据库配置
  410. database:
  411. type: sqlite
  412. path: "./data/tasks.db"
  413. # 工作目录
  414. workspace:
  415. root: "/workspace" # Docker 默认挂载目录;非 Docker 部署请改成你的实际路径
  416. # WebUI 配置
  417. webui:
  418. public_feed: false # 活动流展示页公开开关(true=任何人可访问)
  419. feed_retention_days: 7 # 请求日志保留天数(超期自动清理)
  420. # 初始化标记(由 Setup Wizard 自动设置,请勿手动修改)
  421. setup:
  422. initialized: false
  423. ```
  424. ### 配置项说明
  425. | 配置项 | 默认值 | 必填 | 说明 |
  426. | --------------------------- | ----------------- | ------ | ---------------------------------------------------------------------------------- |
  427. | `project.name` | `OpenMOSS` | 否 | 项目名称 |
  428. | `admin.password` | `admin123` | **是** | 管理员密码,首次启动后自动加密为 bcrypt 格式 |
  429. | `agent.registration_token` | — | **是** | Agent 注册令牌,建议使用随机字符串 |
  430. | `agent.allow_registration` | `true` | 否 | 关闭后 Agent 无法自注册,只能管理员创建 |
  431. | `server.host` | `0.0.0.0` | 否 | 服务监听地址 |
  432. | `server.port` | `6565` | 否 | 服务监听端口 |
  433. | `server.external_url` | `""` | 否 | 服务外网访问地址(Agent 对接用,如 `https://moss.example.com`) |
  434. | `database.type` | `sqlite` | 否 | 数据库类型(目前仅支持 SQLite) |
  435. | `database.path` | `./data/tasks.db` | 否 | 数据库文件路径 |
  436. | `notification.enabled` | `false` | 否 | 是否启用通知推送 |
  437. | `notification.channels` | `[]` | 否 | 通知渠道列表,格式 `渠道类型:目标ID` |
  438. | `notification.events` | `[]` | 否 | 触发通知的事件:`task_completed` / `review_rejected` / `all_done` / `patrol_alert` |
  439. | `webui.public_feed` | `false` | 否 | 活动流公开开关 |
  440. | `webui.feed_retention_days` | `7` | 否 | 请求日志保留天数 |
  441. | `workspace.root` | `./workspace` | **是** | Agent 工作目录根路径 |
  442. | `setup.initialized` | `false` | 否 | 初始化标记,由 Setup Wizard 自动设置,请勿手动修改 |
  443. > **⚠️ 首次部署务必修改:** `admin.password`、`agent.registration_token`、`workspace.root`
  444. ---
  445. ## 八、API 文档
  446. 启动后访问 `http://localhost:6565/docs` 可查看完整的 Swagger API 文档。
  447. ### 认证方式
  448. OpenMOSS 采用双层认证体系:
  449. | 身份 | Header | 说明 |
  450. | ------ | ------------------------------- | ------------------------------ |
  451. | Agent | `X-Agent-Key: <api_key>` | Agent 注册成功后获得的 API Key |
  452. | 管理员 | `X-Admin-Token: <token>` | 通过登录接口获取的 Token |
  453. | 注册 | `X-Registration-Token: <token>` | 配置文件中设置的注册令牌 |
  454. ---
  455. ## 九、WebUI 页面
  456. OpenMOSS 内置了一个管理后台(基于 Vue 3 + shadcn-vue),构建后的静态文件由后端直接服务,无需额外的 Web 服务器。
  457. | 页面 | 路径 | 说明 |
  458. | ---------- | ------------ | ---------------------------------------------------------- |
  459. | 初始化向导 | `/setup` | 首次启动引导(密码、项目信息、Agent 令牌、通知、外网地址) |
  460. | 登录 | `/login` | 管理员密码登录 |
  461. | 仪表盘 | `/dashboard` | 系统概览、统计高亮、趋势图表 |
  462. | 任务管理 | `/tasks` | 任务列表、详情面板、模块拆分视图、子任务管理 |
  463. | Agent | `/agents` | Agent 列表、状态、角色、工作量、活动记录 |
  464. | 活动流 | `/feed` | 实时展示全部 Agent 的 API 调用活动,支持按 Agent 筛选 |
  465. | 积分排行 | `/scores` | Agent 积分排行榜、积分流水、手动加减分 |
  466. | 审查记录 | `/reviews` | 审查记录列表、筛选、详情查看 |
  467. | 活动日志 | `/logs` | 活动日志查询、搜索、筛选 |
  468. | 提示词管理 | `/prompts` | 查看和管理角色提示词、全局规则,支持 Markdown 渲染 |
  469. | 系统设置 | `/settings` | 配置管理、密码修改、通知设置、外网地址配置 |
  470. ---
  471. ## 十、开发指南
  472. ### 后端开发
  473. ```bash
  474. # 安装依赖
  475. pip install -r requirements.txt
  476. # 开发模式启动(代码修改后自动重载)
  477. python -m uvicorn app.main:app --host 0.0.0.0 --port 6565 --reload
  478. ```
  479. ### 前端开发
  480. WebUI 源码托管在同一个仓库的 **`webui` 独立分支 (orphan branch)** 中。开发前请独立 checkout 此分支:
  481. ```bash
  482. # 获取并切换到前端源码分支(建议放在一个新目录里与后端同时开发)
  483. git clone -b webui https://github.com/uluckyXH/OpenMOSS.git openmoss-webui
  484. cd openmoss-webui
  485. # 安装依赖
  486. npm install
  487. # 开发服务器(http://localhost:5173,自动代理 /api 到本地 :6565)
  488. npm run dev
  489. # 构建生产版本(生成到 dist 目录)
  490. npm run build
  491. # 代码检查
  492. npm run lint
  493. ```
  494. ### 技术栈
  495. | 层 | 技术 |
  496. | -------------- | --------------------------------------------------------- |
  497. | 后端 | Python 3.10+ / FastAPI / SQLAlchemy / Uvicorn |
  498. | 数据库 | SQLite |
  499. | 前端 | Vue 3 / TypeScript / Tailwind CSS v4 / shadcn-vue / Pinia |
  500. | 构建 | Vite |
  501. | Agent 运行环境 | OpenClaw |
  502. ---
  503. ## 十一、Roadmap
  504. 以下是 OpenMOSS 后续计划中的功能:
  505. ### Agent 接入体验
  506. - [x] CLI 自更新(`update` 命令一键更新 task-cli.py + SKILL.md)
  507. - [x] Agent Skill API(`/agents/me/skill` 下发角色对应的 SKILL.md,API Key 自动填入)
  508. - [x] Agent 快速注册(`/agents/register` 自注册 + 对接指引自动生成,含注册令牌、Skill 下载、API Key 保存全流程)
  509. - [ ] Agent Onboarding 向导(注册即自动配置,开箱即用)
  510. - [x] Skill 热更新(SKILL.md 和 task-cli.py 通过 API 实时读取文件,修改后无需重启即生效)
  511. ### 前端完善
  512. - [x] 仪表盘(Dashboard)数据可视化
  513. - [ ] 任务详情页交互优化
  514. - [ ] Agent 管理页(创建/编辑/删除)
  515. - [x] 提示词管理页(查看/管理角色提示词和全局规则)
  516. - [ ] 工作流可视化(实时展示任务流转状态)
  517. - [x] 日志查询与筛选页面
  518. - [ ] 移动端适配
  519. ### 插件系统
  520. - [ ] Agent 成就系统
  521. - [ ] Agent 互动记录(协作历史可视化)
  522. - [ ] Agent 人格化展示(头像、签名、工作风格标签)
  523. ### 基础设施
  524. - [ ] 支持 PostgreSQL / MySQL
  525. - [x] Docker 一键部署
  526. - [x] CI/CD 自动构建(GitHub Actions + GHCR)
  527. - [ ] 多语言支持(i18n)
  528. - [x] English README
  529. ---
  530. ## 贡献者
  531. 感谢所有为 OpenMOSS 做出贡献的开发者!🙏
  532. <a href="https://github.com/uluckyXH/OpenMOSS/graphs/contributors">
  533. <img src="https://contrib.rocks/image?repo=uluckyXH/OpenMOSS" />
  534. </a>
  535. > 想加入我们?查看 [贡献指南](CONTRIBUTING.md) 开始你的第一个 PR!
  536. ### 🤖 特别鸣谢:我们的 AI 同事们
  537. > 本项目的代码、文档、部署脚本、甚至这段致谢词,都有 AI 的深度参与。
  538. > 它们不在 Contributors 列表里,但没有它们,我们可能还在 `debug: why is this not working` 的提交里挣扎。
  539. | AI | 贡献 | 备注 |
  540. |---|---|---|
  541. | 🧠 **GPT** | 架构设计、核心代码、凌晨三点的陪伴 | 偶尔幻觉,但瑕不掩瑜 |
  542. | 🎭 **Claude** | 代码审查、文档润色、哲学思考 | 会认真告诉你它不确定的地方 |
  543. | 💎 **Gemini** | 重构优化、部署自动化、收拾残局 | 曾不小心删了用户的设计文档(对不起 🙇) |
  544. *它们是最好的结对编程搭档——从不抱怨加班,永远秒回消息,只是偶尔会自信地给你写出不存在的 API。*
  545. ---
  546. ## Star History
  547. [![Star History Chart](https://api.star-history.com/svg?repos=uluckyXH/OpenMOSS&type=Date)](https://star-history.com/#uluckyXH/OpenMOSS&Date)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.