KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #claude-code #codex #typescript #ai-agents #deepseek-harness #mcp #cli #rust

MaClaw

★ 137 Open GitHub ↗

下一代企业及自主进化智能体平台（GUI/TUI/Service/SDK)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# MaClaw（码卡龙）

[使用说明书](UserManual_CN.md) | [FAQ](faq.md) | [English](README_EN.md) | [中文](README.md)

**MaClaw（码卡龙）** 是一个**通用可自进化智能体平台**——你的个人数智工作伙伴。它能理解你的意图、记住你的偏好、自主规划并执行复杂任务。无论是写商业计划、做竞品分析、审查合同、开发软件，还是管理远程服务器，它都能从需求梳理到成果交付全程陪你走完。基于 Wails + Go + React 构建，集**结构化工作流、知识库（外脑）、长期记忆、技能扩展、多通道协作**于一体，并通过 **Agent 动态 UI + 结构化数据管理**取代传统企业 MIS 系统的固定表单入口。企业版提供**数字员工**能力——物理用户的数字分身和云端虚拟化员工，7×24 替代重复岗位，降低薪资成本。

> 不只是聊天，而是替你干活。你说想法，它出成果。它有自己的知识库——你导入的文档和网页变成它的"外脑"，让它带着知识为你工作。
>

## 它能做什么

MaClaw 内置 **38 种结构化工作流模板**（见 `corelib/workflow/v2` 的 `RegisterBuiltinTemplates`），覆盖从商业决策、学术申报到运维变更的完整工作场景。每种工作流都遵循「需求确认 → 方案设计 → 分步执行」的质量闭环，确保产出物经过你的审阅和确认。

| 领域 | 工作流 |
|------|--------|
| **商业与战略** | 商业计划、竞品分析、项目方案、创新方案、招投标文件、标书检查 |
| **研究与分析** | 文献综述、研究报告、实验设计、专利分析、论文复现 |
| **合规与尽调** | 合同审查、尽职调查、合规审计 |
| **学术写作与申请** | 基金申请、论文写作；长江学者 / 杰青 / 优青 / 国自然青年·面上·重点 申请书与对应评审 |
| **知识产权** | 中国专利申请、US Patent（USPTO）申请 |
| **升学规划** | 高考志愿填报参考 |
| **内容创作** | PPT 设计、活动策划 |
| **产品与技术** | 产品设计（PRD）、测试计划、编程项目、维护/重构 |
| **运维与变更** | 运维维护（intake → 只读采集 → 风险策略 → 受控执行） |

每个工作流按阶段推进，每个阶段产出文档后等待你确认，你可以修改、补充或跳过。不是一股脑把结果扔给你，而是和你一起把事情做对。

## 企业版特性：数字员工

> **用 AI 数字员工替代重复岗位，7×24 不间断运转，显著降低企业薪资成本，提升运营效率。**

MaClaw 企业版将 Agent 从"辅助工具"升级为"独立工位"——**数字员工**。一个数字员工就是一个 AI 驱动的虚拟岗位，能独立接受任务、执行业务、产出成果，并接入企业 IM/OA/CRM 等系统以"员工"身份参与协作。

数字员工统一为两种形态：

| 类型 | 定位 | 典型场景 |
|------|------|---------|
| **物理用户的数字分身** | 为真实员工创建的 AI 分身，代替本人处理日常事务 | 日常事务自动化、信息咨询代理、文档与报告生成、跨系统代办 |
| **云端虚拟化员工** | 无对应真人的纯 AI 岗位，独立承担业务职能 | 虚拟前台与客服、流程审批助手、数据录入与校验、知识库运维员 |

### 物理用户的数字分身

为企业中的真实员工创建 AI 分身，继承该员工的权限、知识和工作习惯：

* **日常事务自动化**：邮件分类与回复草稿、会议纪要整理、日报/周报自动生成、待办事项跟踪与提醒
* **信息咨询代理**：同事/客户发来咨询时，数字分身根据知识库和历史对话自动应答，本人不在线时代为处理
* **文档与报告生成**：根据数据源和模板自动生成分析报告、项目汇报、商务文档，发送至指定审批人
* **跨系统代办**：代替员工在 OA、CRM、ERP 等系统中执行流程操作（提交审批、录入数据、查询状态），通过 MCP/API 连接企业内部系统

### 云端虚拟化员工

无需对应真人的独立 AI 岗位，直接部署到业务流程中承担职能角色：

* **虚拟前台与客服**：7×24 在线接待客户咨询、产品介绍、问题解答、工单创建，支持多通道（微信/飞书/网页/电话转文本）
* **流程审批助手**：自动审核报销单据（金额校验、发票验真、政策合规）、合同条款初审、采购询价比对，将结果提交人工终审
* **数据录入与校验**：从邮件/附件/扫描件中自动提取结构化数据、核对一致性、标记异常，减少人工录入错误
* **知识库运维员**：定期扫描企业知识源（文档库/Wiki/共享盘），自动发现新增/变更内容，更新知识库索引，维护知识质量评分

### 与传统方案的对比

| 维度 | 传统人力外包 | RPA 机器人 | MaClaw 数字员工 |
|------|-----------|-----------|---------------|
| **理解能力** | 强（人类） | 无（规则脚本） | 强（LLM 语义理解） |
| **适应变化** | 中（需重新培训） | 弱（界面改动即失效） | 强（自动适配，自我修复） |
| **7×24 可用** | 否（需轮班） | 是 | 是 |
| **边际成本** | 线性增长 | 低 | 极低（一份部署，多实例复用） |
| **知识积累** | 人员离职即丢失 | 无 | 持久化（长期记忆 + 知识库） |
| **合规审计** | 依赖人工记录 | 有限 | 全链路自动审计 |

### 部署与管理

* **MaClawSrv 多租户**：每个数字员工是一个 Instance，共享租户的知识库和配置，按角色分配权限
* **IM 通道绑定**：数字员工可绑定独立的企业微信/飞书账号，对外以"员工"身份与客户、同事交互
* **工作台监控**：管理员可查看所有数字员工的在线状态、任务执行记录、异常告警
* **人工兜底**：遇到超出能力范围的请求时，自动升级到对应真人处理，并记录学习

## 核心能力

### 企业 MIS 替代——Agent 动态 UI + 结构化数据管理

MaClaw 的终极目标之一是**用 Agent + 自然语言交互取代传统企业 MIS 系统的固定菜单、固定页面和固定表单**。用户不再需要知道"去哪个系统、打开哪个页面、填写哪些字段"，而是直接用自然语言、图片、语音、文件表达意图，系统自动完成从意图理解到结构化数据落库的全流程。

#### Agent 动态 UI（AG-UI）

传统 MIS 的表单入口被 Agent 动态生成的受控界面取代：

* **动态表单生成**：Agent 理解用户意图后，自动从 Schema 注册表生成参数录入界面（表单、向导、表格编辑器、审批确认等），无需预先开发固定页面
* **智能字段抽取**：从自然语言、附件、图片、已有数据中自动抽取候选字段值，用户只需补全和确认
* **右侧 Task Panel**：左侧对话 + 右侧结构化操作面板，对话负责理解和解释，面板负责精确录入和确认
* **Adapter 自动推断**：从 Skill/Tool/MCP 的 Schema、OpenAPI、函数签名中自动生成 UI 适配器，标准 Skill 无需修改
* **业务对象识别**：用户说"昨天去杭州见客户，高铁 174，午餐 86"，系统自动识别为报销场景，生成报销单草稿
* **安全受控**：所有界面由注册组件和 Schema 白名单渲染，LLM 不能直接生成任意前端代码，不能绕过校验、权限和审批

#### 结构化数据管理（MaClawDataSrv）

内置企业级结构化数据底座，替代传统 MIS 的数据库层：

* **业务数据集**：支持销售（客户/商机/订单）、财务（费用/发票/付款/凭证）、HR（员工/考勤/薪资）、法务（合同）、采购（供应商/采购单）、库存（物料/仓库/出入库）、固定资产等完整企业数据结构
* **模板一键初始化**：内置 30+ 企业 MIS 模板（客户管理、销售订单、费用报销、薪资、合同、采购、库存等），一键创建数据集和字段定义
* **业务操作目录**：Agent 不直接操作底层 CRUD，而是通过业务操作（expense_submit、order_upsert、contract_status_update 等）执行，自带校验、审批和审计
* **业务视图**：预定义的查询视图（订单概览、客户目录、费用审核、合同登记等），控制字段投影和权限，Agent 查询时不暴露底层 SQL
* **仪表盘与报表**：内置业务仪表盘和报表，Agent 可直接运行并返回结果
* **治理与审批**：业务规则引擎（金额阈值、重复检测、必填校验）+ 审批流程（pending → approve/reject）+ 操作计划（高风险操作需管理员确认）
* **全链路审计**：每次结构化提交记录完整审计日志（原始输入、Agent 抽取结果、用户修改、最终数据、校验结果、审批结果）
* **多引擎支持**：本地 SQLite（个人/小团队）→ PostgreSQL（团队/企业），同一 API 无缝切换
* **Agent 友好 API**：Agent 通过 `mis_data` 工具调用业务操作，支持 dry-run 预检、业务意图解析、能力发现、操作计划生成

#### 与传统 MIS 的对比

| 维度 | 传统 MIS | MaClaw AG-UI + DataSrv |
|------|---------|----------------------|
| **入口** | 固定菜单 → 固定页面 → 固定表单 | 自然语言 → Agent 理解 → 动态 UI |
| **开发成本** | 每个业务场景需开发专用页面 | Schema 声明 + Adapter 自动推断 |
| **用户门槛** | 需要培训，记住操作路径 | 说人话即可，零学习成本 |
| **数据录入** | 手动逐字段填写 | Agent 从对话/附件自动抽取，用户确认 |
| **查询方式** | 固定筛选条件 | 自然语言查询，Agent 自动转换 |
| **扩展方式** | 改代码、改数据库、改页面 | 加模板、加 Schema、加业务操作定义 |

### 知识库（外脑）——结构化知识管理引擎

MaClaw 内置一套完整的知识库系统（外脑），基于 SQLite 构建，能将各类文档、网页、对话产出物解析为结构化知识，供 Agent 在工作中精准检索和引用：

* **多格式文档导入**：支持 PDF、Word（.docx/.doc）、Excel（.xlsx/.xls/.csv）、PowerPoint（.pptx/.ppt）、Markdown、纯文本等，可批量导入目录或单文件；Office 解析走内置原生路径，无需本机安装 Word
* **文档内图片资产**：导入时抽取文档内嵌图片，经 OCR / 视觉描述后可索引；Agent 可通过 `knowledge_image_search` 按语义检索图片
* **网页知识采集**：输入 URL 自动抓取，支持批量 URL、域名策略（允许/屏蔽）、链接发现
* **三层知识结构**：原始文档 → 结构化节点（DocumentNode，保留标题/段落/表格/页码层级）→ 知识卡片（Card）→ 事实三元组（Fact）
* **LLM 蒸馏**：导入后可选蒸馏，提取实体、主题、标签、知识卡片与事实关系
* **全文检索 + 语义搜索**：SQLite FTS5 + 向量嵌入双重检索，可按来源类型、域名、标签、质量等级过滤
* **知识图谱 / 事实图谱**：来源主题关联（路径、邻域）与实体-关系三元组（实体画像、关系查询）
* **Context Pack**：Agent 工作时自动检索相关知识注入 LLM 上下文
* **版本与质量**：刷新快照、变更预览；质量评分、敏感扫描、重复卡片抑制、维护计划
* **标签与迁移**：手动/自动标签；JSONL 快照导出导入；Hub 侧支持知识分享导入（`knowledge_share_to_hub` / `knowledge_import_hub_share`）
* **多租户隔离**：服务端部署时按 Owner/Tenant 隔离

**与长期记忆的关系**：知识库是"外脑"——存储你主动导入的文档和网页知识；长期记忆是"内脑"——自动记住对话中的偏好、习惯和项目进展。两者协同工作，Agent 在回答问题时同时检索两个系统。

### 长期记忆——它记得你的一切

MaClaw 拥有持久化的记忆系统，跨会话记住你的偏好、项目知识和工作习惯：

* **语义检索**：BM25 + 向量双重索引，用自然语言就能找到之前的记忆
* **会话全文检索**：基于 SQLite FTS5 的历史对话全文索引，所有对话自动持久化并建立全文索引，支持跨会话搜索、BM25 排序和关键词高亮，随时回溯任意一次对话的完整内容
* **自动沉淀**：工作流产出物（需求文档、设计方案、任务列表）自动沉淀为长期记忆，对话历史截断后不丢失
* **知识图谱**：相关记忆自动关联，形成结构化知识网络
* **记忆生命周期**：置顶、归档、压缩、垃圾回收，自动管理记忆质量
* **多租户隔离**：服务端部署时按用户隔离记忆，互不干扰

### 专家系统——按角色约束能力与风格

桌面端内置可切换的**专家（Expert）**会话策略（见 `gui/expert_*.go`），用角色提示词 + 工具/技能能力档位约束 Agent 行为，而不是永远同一套通用助手：

* **内置专家**：论文润色专家、论文翻译专家、PPT 制作专家（可重置为出厂定义）
* **能力档位**：`full` / `advisor` / `docs` / `office` / `custom`，按档位限制可用工具与技能风险级别
* **自定义专家**：用户可新建、编辑、导入/导出专家包；支持会话级策略覆盖
* **优化与市场**：可对专家定义做优化；与 Hub 侧专家能力对接（内置专家默认不上推 Hub）

### 技能系统——能力可无限扩展

通过安装技能（Skill），MaClaw 可以获得新的工作能力，就像给手机装 App：

* **多格式支持**：YAML 定义、Markdown 脚本、Claude SKILL.md 格式
* **多步骤工作流**：顺序执行、条件分支、变量传递、输出捕获
* **三源市场**：从 SkillHub（官方）、ClawHub（社区）、GitHub 搜索和安装
* **跨平台兼容**：Windows / macOS / Linux 自动路径规范化和 Shell 适配
* **自我进化**：`craft_tool` 可动态生成一次性自动化脚本，验证后可转化为可复用技能
* **技能维护计划**：只读维护计划、审批后执行（标记审查、归档陈旧技能、排队修复等）

### MCP 集成——连接外部世界

通过 Model Context Protocol（MCP）接入外部工具和服务：

* **动态发现**：自动发现 MCP Server 提供的工具
* **本地 + 远程**：支持 Stdio 本地协议和 HTTP 远程协议
* **健康监控**：自动检测 MCP Server 状态
* **无限扩展**：任何支持 MCP 的服务都可以成为 MaClaw 的能力

### 工具路由——智能匹配最佳工具

MaClaw 内置 40+ 工具，通过混合检索智能选择当前任务最需要的工具组合：

* **混合检索**：BM25 + 向量语义双重匹配
* **条件激活**：SSH、浏览器等工具按上下文关键词按需激活，不污染简单任务的工具列表
* **渐进式暴露**：核心工具始终可用，低频工具通过 `discover_tool` 按需加载
* **使用反馈闭环**：工具调用的成功/失败/重试记录回流到路由决策，高失败率工具自动降权

### 自我进化——能力缺口自动补全

MaClaw 不只是被动执行，它能主动发现自身能力不足并自动补全：

* **能力缺口检测**：Agent 遇到无法完成的任务时，自动搜索 SkillHub 寻找匹配的技能并安装
* **技能自修复**：技能执行失败后，LLM 自动分析错误原因并修补技能定义（修复步骤、参数、路径等），修复结果持久化
* **Nudge 系统**：复杂任务完成后，系统建议将成功的操作序列封装为可复用技能，推动技能库有机增长
* **craft_tool 转化**：一次性自动化脚本验证成功后可转化为永久技能
* **经验学习治理**：`experience_learning` 以只读/草稿方式检查记忆维护、路由自进化、工具恢复与 A2A 讨论痕迹等，不直接执行破坏性变更

### 办公文档处理

统一 `office` 工具（内置原生解析，无需 Python / 本机 Office）与专用产出工具：

* **读文档**：`read_document` 自动识别 PDF / Word / Excel / PPT 等；也可按格式显式读取
* **Excel 读写**：读取与写入表格（大表默认行数上限，可分页）
* **PPT**：读取 `.pptx`；PPT 设计工作流与「PPT 制作专家」通过 pptx 技能生成真正的 `.pptx` 文件
* **PDF 生成**：`generate_pdf` / `office generate_pdf` 将 Markdown 渲染为 PDF 并交付
* **文件交付**：`send_file` / `send_to_im` / `open` — 桌面预览、IM 回传或系统默认程序打开

### 信息获取

* **Web 搜索**：`web_search` 返回标题、URL、摘要；搜索 API 失效时自动降级为页面抓取，必要时用真实浏览器兜底
* **网页抓取**：`web_fetch` 提取正文，自动编码检测（GBK/UTF-8 等），可选 JS 渲染，长页面 `offset` 续读
* **文件下载**：`download_file` 将 HTTP(S) 资源落到当前工作目录；内置反爬升级链（请求头 → TLS 指纹 → 浏览器会话 cookie，可选 `via_browser`）
* **屏幕截图**：截取桌面（可指定显示器）并发送给用户，支持 IM 远程监督

### 语音：ASR 转写 + TTS 播报

* **本地 ASR（SenseVoice）**：默认模型为 `sensevoice-small-q8.gguf`（自动下载到 `~/.maclaw/models`），IM 语音与本机音频文件转写；推荐 16 kHz mono WAV
* **说话人分离**：启用后多人音频按说话人分段标注；可传 `known_speakers` 提高准确度
* **会议纪要**：`asr` 工具 `for_minutes=true` 走 map-reduce 草稿；桌面 `record_audio` 支持长时会议录音界面
* **本地 TTS（Kokoro）**：`tts` 工具将文本合成为语音；IM 以语音气泡发送，桌面面板播放；多音色（中文/英文），模型空闲自动卸载

### 定时任务

支持创建定时执行的自动化任务：

* 按日/周/月调度，支持一次性任务
* 自然语言描述任务内容，到时自动执行
* 暂停、恢复、立即运行、删除；可配置推送到 IM 目标（含蓝信群解析）

### 长期目标（Goal）

`goal` 工具管理持久化长时间运行目标：创建后系统在预算内持续推进，直至完成或失败；仅在用户明确要求时创建，不从普通聊天隐式推断。

### 审计日志

全程记录 Agent 操作，支持合规审查：

* 工具调用、文件操作、SSH 命令等关键操作自动记录
* 可通过 `query_audit_log` 按时间、工具名、风险等级查询

### 意图理解

三层融合意图分类系统，准确理解用户请求：

* **Layer 1**：关键词规则（<1ms）
* **Layer 2**：BM25 语义检索（<5ms）
* **Layer 3**：LLM 多轮对话确认（10-30s）
* 自动路由到对应工作流模板或直接执行；部分模板（如维护/重构）标记为 SemanticOnly，仅经 IUM LLM 激活

### 行为定制——Steering 规则系统

通过 Markdown 文件声明行为规则，无需改代码即可定制 MaClaw 的工作方式：

* **四种注入模式**：始终注入、文件匹配注入、关键词匹配注入、手动引用
* **两级作用域**：用户级（`~/.maclaw/steering/`）和项目级（`<project>/.maclaw/steering/`）
* **Token 预算**：智能控制规则注入量，不浪费上下文空间
* **热加载**：修改后 30 秒内自动生效

## 多形态交互

MaClaw 不限于一种使用方式，你可以在多个入口与它协作：

| 形态 | 说明 |
|------|------|
| **桌面 AI 助手面板** | 原生 GUI，流式输出、工作流文档预览、专家切换、知识库与设置面板 |
| **终端 TUI** | 命令行界面，支持聊天、记忆查看、技能管理、滚动条和流式显示 |
| **微信 / 飞书 / QQ / Telegram / 蓝信（Lansenger）** | 本机或经 Hub 绑定 IM；蓝信支持群策略、@ 触发、群知识源与文件发送 |
| **Hub PWA / 移动端** | 自托管 Hub 提供 `/app` PWA 入口，跨设备会话与远程协作 |
| **VS Code ACP** | 内置 ACP Host 与 VS Code 扩展资产，可在编辑器侧对接编码工作台 |
| **第三方设备网关** | 本机 HTTP 网关（默认 `127.0.0.1:18777`）对接 ESP32 等硬件终端（语音配对、消息轮询） |
| **REST API（MaClawSrv）** | 多租户 REST 服务，供外部程序、自动化平台和控制面板集成 |

## 执行能力

### SSH 远程管理

内置 SSH 客户端，直接在对话中管理远程服务器：

* 最多 10 个并发会话，支持密码/密钥/Agent 多种认证
* 同步执行、后台任务、文件上传下载
* 自动 sudo token 管理、Shell 响应性检测、连续失败自动清理
* 操作全程记录，满足审计要求

### 浏览器自动化

基于 Chrome DevTools Protocol 的浏览器操作能力：

* 页面导航、元素点击、文本输入、内容提取、截图
* 流程录制与回放，支持定时触发和参数化变量
* OCR 集成（内置原生 PP-OCRv6 引擎，模型自动下载、无需 Python，另支持 LLM 视觉模型）。模型档位可在设置界面的 OCR 面板直接选择，也可通过 config.json 的 `ocr_model_tier` 配置：`tiny`（最快）/ `small`（默认，均衡）/ `medium`（最准）；`ocr_enabled` 控制 OCR 工具开关

### 桌面 GUI 自动化与 Computer Use

直接操控本机桌面程序（任意原生应用），无需浏览器。代码中分两套互补工具面：

**GUI 自动化（`gui_*`）**

* **Accessibility 元素树**：跨平台读取窗口控件结构
* **流程录制与回放**：`gui_record_*` / `gui_replay`，支持参数化与异步执行
* **观测与验证**：`gui_observe`（元素树 + OCR 文本）、`gui_verify`、多显示器截图

**Computer Use（`computer_*`，可在设置中开关）**

* **文本优先观测**：`computer_observe` / `computer_find` 结合 Accessibility、OmniParser（YOLO）与本地 PP-OCR，供非多模态模型使用
* **操作原语**：`computer_click` / `computer_type` / `computer_key` / `computer_scroll` / `computer_wait` / `computer_focus` / `computer_done`
* **Playbook**：`computer_playbook` 将成功操作序列固化为可复用剧本
* **目标应用策略与日志**：可限制可操作应用，自动清理 Computer Use 操作日志

### 软件开发

编程是 MaClaw 的工作能力之一，通过编码工作流、纯编码任务与外部编程工具协作完成：

* **结构化流程**：需求分析 → 技术设计 → 任务拆分 → 逐任务执行 → 验收（`coding` 工作流）；轻量维护走 `maintenance` 三阶段
* **本地 / 远程编码**：需求阶段可选本地目录或 SSH 远程工作目录（密码字段敏感、用后清除）
* **多工具支持**：Claude Code、Codex、OpenCode、CodeBuddy、iFlow、Kilo（配置项 `active_tool`）
* **编码 SubAgent / 工作台**：独立 context 的编码执行器；`.coding_workbench.json` 粘性任务状态；ACP 对接 VS Code
* **并行与 Swarm**：`parallel_execute` 分批并发编程任务；大型任务可拆给多个 AI 开发者并行执行并合并
* **远程编码会话工具**：`list_sessions` / `send_input` / `get_session_output` / `interrupt_session` / `kill_session` 等

### 本机后台进程管理

通过 `bash(background=true)` 启动本机后台任务，系统自动捕获 PID 和日志路径：

* 非阻塞查询状态、阻塞等待完成、终止任务
* 与 SSH 后台任务管理对称的 Submit / Check / Wait / Kill 模式

### 直通任务——紧急场景下的一键执行

直通任务（Passthrough Task）是为**紧急运维、系统救援、快速操作**设计的预注册命令执行机制。跳过 Agent 的意图理解和工作流编排，直接执行预定义的脚本或命令。

* **预注册命令**：脚本/可执行文件 + 参数模板（`${param}`），支持 auto/powershell/cmd/bash/python/node/direct 等 runtime
* **参数化与确认**：参数定义（必填/可选/默认值）；高风险默认 `confirm_required=true`
* **超时与审计**：默认 120 秒超时；执行写入审计日志；可启用/禁用而不删除定义
* **入口分工**：
  * **执行**：桌面 / IM 斜杠命令 `/run <name> ...`（远程执行常需 `--confirm`）
  * **注册表管理**：`/runctl` 以及 Agent 工具 `passthrough_task`（list/save/delete/export 等，**不执行脚本**）
* **跨设备**：IM 可触发已注册在桌面端的直通任务

**典型使用场景**：

| 场景 | 示例命令 |
|------|---------|
| 服务器紧急重启 | `/run restart-nginx --confirm` |
| 数据库备份 | `/run backup-db --target=production --confirm` |
| 部署回滚 | `/run rollback --version=v2.3.1 --confirm` |
| 清理磁盘空间 | `/run cleanup-logs --days=7 --confirm` |
| 导出注册命令到 IM | `/runctl export backup-db` |

## Hub 远程协作与多智能体

[Hub](hub/) 是可自托管的远程控制与协作服务（桌面端注册后连接）：

* **身份与设备**：Hub 本地身份、设备会话摘要/事件上报
* **IM 路由与智能路由**：多通道消息协调、设备网关、能力发现
* **数字资产与知识分享**：知识库主机、分享导入、备份合并
* **专家与讨论**：Hub 侧专家存储；**A2A 群组讨论**（`corelib/a2a` + 桌面 `group_discussion`）— 多 Agent 会诊、邀请、决策策略（多数/一致）
* **工作流审批与市场**：Hub 工作流运行时、审批确认、市场上架
* **PWA**：`/app` 移动/浏览器入口；支持备份与灾难恢复命令
* **高可用**：可对接多个 Hub Center 地址（见 `docs/hubcenter-ha-3nodes.md`）

桌面 Agent 还可使用 `switch_llm_provider`（换脑子）、`set_nickname`（Hub 群聊昵称）、`im_message` 主动向 IM 目标推送文本/文件。

## 硬件伴侣与第三方设备网关

* **第三方网关**：桌面开启后监听本地端口（默认 `127.0.0.1:18777`），提供设备配对（含语音配对 + SenseVoice 提取数字）、消息轮询与媒体交换协议，供 IoT / 自研客户端接入
* **ClawMate / ESP32**：仓库内 [ClawMateMaker](ClawMateMaker/) 为 ESP32-S3 固件刷写与诊断工具；[esp32s3-maclaw-client](esp32s3-maclaw-client/)、[iot-agentos](iot-agentos/) 为设备固件与 AgentOS 相关实现
* **协议约束**：刷写工具仅接受签名发布包与 nonce-bound protocol:2 运行时身份自动匹配（详见 ClawMateMaker 文档）

## 快速开始

### 安装后四步上手

| 步骤 | 内容 | 说明 |
|------|------|------|
| **注册账号** | 邮箱注册 | 输入邮箱完成注册，启用远程协作能力 |
| **选择模式** | 专业 / 简洁 | 随时可切换 |
| **配置 AI** | 选择 LLM 服务商 | 输入 API Key 并测试连通性，也支持 OAuth 登录和免费体验 |
| **绑定 IM（可选）** | 扫码绑定微信等 | 绑定后可通过 IM 随时与 MaClaw 对话 |

### 运行

* Windows：`MaClaw.exe`
* macOS：`MaClaw.app`
* Linux：`MaClaw.AppImage`
* 终端：`maclaw-tui`

首次启动自动检测运行环境，缺少的组件会自动安装。

## MaClawSrv — REST Agent 服务

[MaClawSrv](MaClawSrv/) 是 MaClaw 的多租户 REST 服务入口，将 Agent 能力以标准 HTTP API 的形式暴露给外部程序。

**核心特点**：

* **多租户隔离**：数据按 `tenant → user` 层级隔离，同一用户下可同时运行多个 instance
* **共享用户数据**：同一用户的所有 instance 共享配置、记忆、Skill、MCP 状态
* **安全优先**：管理端 + 用户端双层鉴权；凭证 scrypt 摘要存储；支持 TLS
* **完整 API 覆盖**：Admin 控制面板、用户配置、Instance/Session/Message/Run 运行时、Skill/MCP 生命周期、异步 Job、Usage/Audit/Dashboard、知识库 API 等

```bash
export MACLAW_ADMIN_SECRET="your-admin-secret-at-least-24-chars"
export MACLAW_TOKEN_SECRET="your-token-secret-at-least-32-chars"
go run ./MaClawSrv
```

**API 文档**：

| 文档 | 说明 |
|------|------|
| [README](MaClawSrv/README.md) | 项目定位、接口分组、安全模型、数据布局 |
| [API 对接手册（中文）](MaClawSrv/API_MANUAL.zh-CN.md) | 完整字段级说明，含鉴权、分页、错误模型 |
| [API Manual (English)](MaClawSrv/API_MANUAL.md) | 英文版 API 手册 |
| [5 分钟快速接入](MaClawSrv/QUICKSTART.zh-CN.md) | 最短可用链路 |
| [Quickstart (English)](MaClawSrv/QUICKSTART.md) | 英文版快速接入 |
| [缺口分析](MaClawSrv/GAP_ANALYSIS.zh-CN.md) | 已实现能力与待补全功能 |
| [Gap Analysis](MaClawSrv/GAP_ANALYSIS.md) | 英文版缺口分析 |
| OpenAPI | 服务运行后访问 `GET /openapi.json` |

## MaClawDataSrv — 结构化数据服务

[datasrv](datasrv/) 为独立可构建模块（`maclaw-data-srv`），实现企业 MIS 结构化数据底座：SQLite 存储、业务操作与治理、HTTP API、OpenAPI 与内嵌 Web Console。默认监听 `127.0.0.1:18180`；Windows 安装器可注册为系统服务。详见 [datasrv/README.md](datasrv/README.md)。

## 授权许可（Dual License）

* **开源用途**：用于开源项目时可自由使用 （适用于GPL协议）
* **商业用途**：联系并获得免费商业授权许可，联系 **znsoft@163.com**  （适用 码卡龙商业授权许 V1.0)

## 关于

* **作者**：Dr. Daniel 人工智能大语言模型博士
* **GitHub**：[RapidAI/MaClaw](https://github.com/rapidai/maclaw)
* **产品网站**：[maclaw.top](https://maclaw.top)

---
*本工具仅作为配置管理辅助，请确保遵守各模型厂商的服务条款。*

MaClaw

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README