一个本地优先的多 Agent 助手平台：把对话、工具执行、审批和定时任务放进同一个工作流，让任务更稳定地落地。
- 可追踪的执行闭环：从规划、步骤执行、审批到总结，全程带事件流与状态回放，不是“只会聊天”的黑盒。
- 多 Agent 协作工作台：按角色管理 Agent 的技能、工具、锦囊和文档，支持持续沉淀可复用的执行能力。
- 高风险操作可控：命令与文件写入具备策略门禁，支持人工确认，降低误操作成本。
- 自动化任务可运营：内置 Cron 调度、执行报告与渠道通知（飞书/钉钉），适合长期例行任务。
- 模型层解耦：统一管理多 Provider 与模型，支持本地模型发现，便于按场景切换成本与效果。
推荐优先使用桌面版；需要本地体验服务时使用 Docker；需要开发或调试时使用源码启动。
- 下载对应平台的桌面安装包并安装。
- macOS 使用
.dmg，Windows 使用.msi。 - 安装后可一键启动，无需手动配置 JDK、Node.js 或 MySQL。
本地打包：
# macOS Apple Silicon
TARGET_ARCH=arm64 ./scripts/build-desktop-macos.sh
# macOS Intel x64
TARGET_ARCH=x64 ./scripts/build-desktop-macos.sh
# Windows x64
TARGET_ARCH=x64 ./scripts/build-desktop-windows-x64.sh适合希望“拉代码后直接跑起来”的场景，默认使用 H2 file 模式，不依赖 MySQL。
- 可选：在项目根目录创建
.env，写入你需要的变量，例如DASHSCOPE_API_KEY、LLM_MODEL_CONFIG_ENCRYPTION_KEY。 - 启动前后端：
docker compose up --build -d- 打开：
- 前端：
http://127.0.0.1:5173 - 后端 API：
http://127.0.0.1:8080
- 停止：
docker compose down说明：
- 后端数据持久化到 Docker volume：
nomoclaw_data - 前端容器通过 Nginx 反向代理
/api到后端容器 - 如需清空数据并重置：
docker compose down -v
环境要求：
- 后端：JDK 21+，MySQL 8+（开发/测试可使用 H2 file 模式）
- 前端：Node.js 20+，pnpm 10+
- 配置环境变量：
cp .env.example .env
cp web/.env.example web/.env-
初始化数据库：执行
src/main/resources/db/schema-mysql.sql -
启动后端：
./mvnw spring-boot:run默认：http://127.0.0.1:8080
- 启动前端：
cd web
pnpm install
pnpm dev默认：http://127.0.0.1:5173
说明：
- 本地 MySQL 开发默认走 Maven
prod-full（activeByDefault），会包含mysql-connector-j与flyway-mysql。 - 桌面发版默认脚本走
prod-lite（H2），用于精简打包体积。
使用 H2 file 模式：
SPRING_PROFILES_ACTIVE=h2 ./mvnw spring-boot:run- H2 数据文件默认位于：
${NOMOCLAW_ROOT_DIR}/data/nomoclaw - 本模式用于开发/测试兼容验证，不作为生产主库建议
启动桌面版或前后端服务后：
- 打开
http://127.0.0.1:5173，进入/发起一条聊天消息。 - 进入
/agents，为当前 Agent 保存一条锦囊并查看内容。 - 进入
/cron，创建一个定时任务并查看执行结果面板。
后端：
./mvnw -DskipTests compile
./mvnw test前端：
cd web
pnpm dev
pnpm build桌面版：
./scripts/build-desktop-macos.sh
./scripts/build-desktop-windows-x64.sh使用者：
- 接口文档（中文）：
docs/api.md - API docs (English):
docs/api.en.md
开发者：
- 架构文档：
docs/architecture/ARCHITECTURE.md - 前端架构：
docs/architecture/FRONTEND.md - 前端 API 设计：
docs/architecture/FRONTEND-API.md - 桌面端生命周期（Tauri）：
docs/architecture/DESKTOP-TAURI-LIFECYCLE.md
运维与配置：
- 核心配置：
src/main/resources/application.yml - 常用环境变量：
MYSQL_URL、MYSQL_USER、MYSQL_PASSWORD、NOMOCLAW_ROOT_DIR、DASHSCOPE_API_KEY、LLM_MODEL_CONFIG_ENCRYPTION_KEY、FEISHU_APP_ID、FEISHU_APP_SECRET、DINGTALK_CLIENT_ID、DINGTALK_CLIENT_SECRET、DINGTALK_ROBOT_CODE
- 知识库融合到 Agent 助手（从“锦囊/文档/技能”走向统一检索入口），提升回答一致性与可追溯性。
- 工作流融合到 Agent 助手（从对话执行扩展到可编排流程），将高频任务沉淀为可复用流程。
- 多 Agent 协作功能，支持任务拆解、分工执行与协同交付。
- 插件功能，支持按需扩展外部系统能力与业务集成。
- 中控中心（多 Agent 节点状态、产出摘要、Token 消耗监控），实现运行可观测与成本可管理。
- 默认仅允许本机访问
/api（agent.api.local-only-enabled: true）。 - 生产环境建议配置
LLM_MODEL_CONFIG_ENCRYPTION_KEY，避免模型 API Key 明文存储。
请先阅读 CONTRIBUTING.md。