📖 使用说明书 | ❓ FAQ | English | 中文
MaClaw（码卡龙） 是一个通用可自进化智能体平台——你的个人数智工作伙伴。它能理解你的意图、记住你的偏好、自主规划并执行复杂任务。无论是写商业计划、做竞品分析、审查合同、开发软件，还是管理远程服务器，它都能从需求梳理到成果交付全程陪你走完。基于 Wails + Go + React 构建，集结构化工作流、知识库（外脑）、长期记忆、技能扩展、多通道协作于一体，并通过 Agent 动态 UI + 结构化数据管理取代传统企业 MIS 系统的固定表单入口。
不只是聊天，而是替你干活。你说想法，它出成果。它有自己的知识库——你导入的文档和网页变成它的"外脑"，让它带着知识为你工作。
MaClaw 内置 19 种结构化工作流模板，覆盖从商业决策到技术实现的完整工作场景。每种工作流都遵循"需求确认 → 方案设计 → 分步执行"的质量闭环，确保产出物经过你的审阅和确认。
| 领域 | 工作流 |
|---|---|
| 商业与战略 | 商业计划书、竞品分析、项目提案、创新方案、招投标文件生成 |
| 研究与分析 | 文献综述、研究报告、实验设计、专利分析 |
| 合规与尽调 | 合同审查、尽职调查、合规审计 |
| 学术写作 | 基金申请书、论文写作 |
| 内容创作 | PPT 设计、活动策划 |
| 产品与技术 | 产品设计（PRD）、软件测试、软件开发 |
每个工作流按阶段推进，每个阶段产出文档后等待你确认，你可以修改、补充或跳过。不是一股脑把结果扔给你，而是和你一起把事情做对。
MaClaw 的终极目标之一是用 Agent + 自然语言交互取代传统企业 MIS 系统的固定菜单、固定页面和固定表单。用户不再需要知道"去哪个系统、打开哪个页面、填写哪些字段"，而是直接用自然语言、图片、语音、文件表达意图，系统自动完成从意图理解到结构化数据落库的全流程。
传统 MIS 的表单入口被 Agent 动态生成的受控界面取代：
- 动态表单生成：Agent 理解用户意图后，自动从 Schema 注册表生成参数录入界面（表单、向导、表格编辑器、审批确认等），无需预先开发固定页面
- 智能字段抽取：从自然语言、附件、图片、已有数据中自动抽取候选字段值，用户只需补全和确认
- 右侧 Task Panel：左侧对话 + 右侧结构化操作面板，对话负责理解和解释，面板负责精确录入和确认
- Adapter 自动推断：从 Skill/Tool/MCP 的 Schema、OpenAPI、函数签名中自动生成 UI 适配器，标准 Skill 无需修改
- 业务对象识别：用户说"昨天去杭州见客户，高铁 174，午餐 86"，系统自动识别为报销场景，生成报销单草稿
- 安全受控：所有界面由注册组件和 Schema 白名单渲染，LLM 不能直接生成任意前端代码，不能绕过校验、权限和审批
内置企业级结构化数据底座，替代传统 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 | MaClaw AG-UI + DataSrv |
|---|---|---|
| 入口 | 固定菜单 → 固定页面 → 固定表单 | 自然语言 → Agent 理解 → 动态 UI |
| 开发成本 | 每个业务场景需开发专用页面 | Schema 声明 + Adapter 自动推断 |
| 用户门槛 | 需要培训，记住操作路径 | 说人话即可，零学习成本 |
| 数据录入 | 手动逐字段填写 | Agent 从对话/附件自动抽取，用户确认 |
| 查询方式 | 固定筛选条件 | 自然语言查询，Agent 自动转换 |
| 扩展方式 | 改代码、改数据库、改页面 | 加模板、加 Schema、加业务操作定义 |
MaClaw 内置一套完整的知识库系统（外脑），基于 SQLite 构建，能将各类文档、网页、对话产出物解析为结构化知识，供 Agent 在工作中精准检索和引用：
- 多格式文档导入：支持 PDF、Word（.docx/.doc）、Excel（.xlsx/.xls/.csv）、PowerPoint（.pptx）、Markdown、纯文本等格式，批量导入整个目录或单文件
- 网页知识采集：输入 URL 自动抓取网页内容，支持批量 URL 导入、域名策略管理（允许/屏蔽）、链接自动发现
- 三层知识结构：原始文档 → 结构化节点（DocumentNode，保留标题/段落/表格/页码层级）→ 知识卡片（Card，提炼核心论断）→ 事实三元组（Fact，主语-谓语-宾语）
- LLM 蒸馏：导入文档后可选 LLM 蒸馏，自动提取实体、主题、标签、知识卡片和事实关系
- 全文检索 + 语义搜索：SQLite FTS5 全文索引 + 向量嵌入双重检索，支持按来源类型、域名、标签、质量等级多维度过滤
- 知识图谱：来源之间自动建立主题关联（Source Links），支持图谱可视化、路径查询、邻域探索
- 事实图谱：从知识卡片中提取的实体-关系-实体三元组，支持实体画像、关系查询、图谱浏览
- Context Pack：Agent 工作时自动从知识库中检索相关知识，打包为上下文注入 LLM，实现"带着知识干活"
- 版本追踪：每次刷新/更新自动保存版本快照，支持变更预览和历史回溯
- 质量管理：自动质量评分（A/B/C/D 等级）、敏感信息扫描、重复卡片检测与抑制、维护计划自动生成与执行
- 标签系统：手动标签 + 自动标签（基于文件路径和内容规则），支持按标签过滤和批量管理
- 导入导出：支持 JSONL 格式的完整快照导出/导入，可跨设备迁移知识库
- 多租户隔离：服务端部署时按 Owner/Tenant 隔离知识，互不干扰
与长期记忆的关系：知识库是"外脑"——存储你主动导入的文档和网页知识；长期记忆是"内脑"——自动记住对话中的偏好、习惯和项目进展。两者协同工作，Agent 在回答问题时同时检索两个系统。
MaClaw 拥有持久化的记忆系统，跨会话记住你的偏好、项目知识和工作习惯：
- 语义检索：BM25 + 向量双重索引，用自然语言就能找到之前的记忆
- 会话全文检索：基于 SQLite FTS5 的历史对话全文索引，所有对话自动持久化并建立全文索引，支持跨会话搜索、BM25 排序和关键词高亮，随时回溯任意一次对话的完整内容
- 自动沉淀：工作流产出物（需求文档、设计方案、任务列表）自动沉淀为长期记忆，对话历史截断后不丢失
- 知识图谱：相关记忆自动关联，形成结构化知识网络
- 记忆生命周期：置顶、归档、压缩、垃圾回收，自动管理记忆质量
- 多租户隔离：服务端部署时按用户隔离记忆，互不干扰
通过安装技能（Skill），MaClaw 可以获得新的工作能力，就像给手机装 App：
- 多格式支持：YAML 定义、Markdown 脚本、Claude SKILL.md 格式
- 多步骤工作流：顺序执行、条件分支、变量传递、输出捕获
- 三源市场：从 SkillHub（官方）、ClawHub（社区）、GitHub 搜索和安装
- 跨平台兼容：Windows / macOS / Linux 自动路径规范化和 Shell 适配
- 自我进化：
craft_tool可动态生成一次性自动化脚本，验证后可转化为可复用技能
通过 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 转化：一次性自动化脚本验证成功后可转化为永久技能
内置文档生成和处理能力：
- PDF 生成：从 Markdown 内容直接生成 PDF，工作流各阶段文档自动生成 PDF 版本通过 IM 发送
- Excel 读写：读取和写入 Excel 文件
- PPTX 读取：解析 PowerPoint 文件内容
- 文件发送：生成的文件可直接通过 IM 通道（飞书/微信/QQ）发送给用户
- Web 搜索：搜索互联网内容，返回标题、URL、摘要
- 网页抓取：抓取指定 URL 的正文内容，自动编码检测（GBK/UTF-8），支持 JS 渲染和长页面续读
- 屏幕截图：截取桌面屏幕并发送给用户，支持 IM 远程监督场景
- 语音消息识别：IM 通道收到的语音消息自动转换为 WAV 格式，支持 ASR 语音识别（内置 Moonshine 模型）
- 声纹识别：基于 ECAPA 嵌入的声纹注册与 1:N 身份识别（Hub 侧能力）
支持创建定时执行的自动化任务：
- 按日/周/月调度，支持一次性任务
- 自然语言描述任务内容，到时自动执行
- 暂停、恢复、删除任务
去中心化的智能体协作网络（实验性）：
- 节点发现、知识发布与搜索、积分系统
- 跨节点任务委派、Swarm 协作
- 声誉系统、争议仲裁、DAG 任务编排
全程记录 Agent 操作，支持合规审查：
- 工具调用、文件操作、SSH 命令等关键操作自动记录
- 可通过工具查询审计日志
三层融合意图分类系统，准确理解用户请求：
- Layer 1：关键词规则（<1ms）
- Layer 2：BM25 语义检索（<5ms）
- Layer 3：LLM 多轮对话确认（10-30s）
- 自动路由到对应工作流模板或直接执行
通过 Markdown 文件声明行为规则，无需改代码即可定制 MaClaw 的工作方式：
- 四种注入模式：始终注入、文件匹配注入、关键词匹配注入、手动引用
- 两级作用域：用户级（
~/.maclaw/steering/）和项目级（<project>/.maclaw/steering/） - Token 预算：智能控制规则注入量，不浪费上下文空间
- 热加载：修改后 30 秒内自动生效
MaClaw 不限于一种使用方式，你可以在多个入口与它协作：
| 形态 | 说明 |
|---|---|
| 桌面 AI 助手面板 | 原生 GUI，右侧 Markdown 预览区实时显示工作流文档，支持流式输出 |
| 终端 TUI | 命令行界面，支持聊天、记忆查看、技能管理、滚动条和流式显示 |
| 微信 / 飞书 / QQ / Telegram | 通过 IM 通道随时随地与 MaClaw 对话，手机上也能指挥它干活 |
| REST API（MaClawSrv） | 多租户 REST 服务，供外部程序、自动化平台和控制面板集成 |
| 模式 | 适用人群 | 特点 |
|---|---|---|
| 专业模式 | 开发者、研究人员 | 完整暴露所有工具、工作流、记忆系统、MCP 管理等高级功能 |
| 简洁模式 | 白领、日常用户 | 精简界面，聚焦对话式交互，零门槛上手 |
内置 SSH 客户端，直接在对话中管理远程服务器：
- 最多 10 个并发会话，支持密码/密钥/Agent 多种认证
- 同步执行、后台任务、文件上传下载
- 自动 sudo token 管理、Shell 响应性检测、连续失败自动清理
- 操作全程记录，满足审计要求
基于 Chrome DevTools Protocol 的浏览器操作能力：
- 页面导航、元素点击、文本输入、内容提取、截图
- 流程录制与回放，支持定时触发和参数化变量
- OCR 集成（RapidOCR + LLM 视觉模型）
直接操控本机桌面程序（记事本、Excel、计算器等任意原生应用），无需浏览器：
- Accessibility 元素树：跨平台（Windows/macOS/Linux）读取窗口控件结构，获取按钮、输入框、菜单等元素信息
- YOLO 视觉检测：内置 OmniParser V2 模型，从屏幕截图中检测可交互 UI 元素（按钮、图标、输入框），不依赖 Accessibility API
- 鼠标键盘操作：在指定坐标点击、输入文本
- 流程录制与回放：录制 GUI 操作序列，保存为可重放的流程，支持参数化覆盖和后台异步执行
- 状态观测与验证：
gui_observe返回窗口元素树 + OCR 文本（纯文本，不消耗 vision token）；gui_verify验证 GUI 状态是否满足条件（文本包含、元素存在、窗口存在等） - 多显示器支持：列出所有连接的显示器，支持指定显示器截图
编程是 MaClaw 的工作能力之一，通过编码工作流和外部编程工具协作完成：
- 结构化流程：需求分析 → 技术设计 → 任务拆分 → 逐任务执行 → 集成联调
- 多工具支持：Claude Code、Codex、Gemini CLI、OpenCode、CodeBuddy、Qoder CLI
- 编码 SubAgent：纯净上下文编码执行器，每个任务独立 context，不会因历史膨胀而失效
- Swarm 编排：大型任务可拆分给多个 AI 开发者并行执行，自动合并
通过 bash(background=true) 启动本机后台任务，系统自动捕获 PID 和日志路径：
- 非阻塞查询状态、阻塞等待完成、终止任务
- 与 SSH 后台任务管理对称的 Submit / Check / Wait / Kill 模式
直通任务（Passthrough Task）是为紧急运维、系统救援、快速操作设计的预注册命令执行机制。跳过 Agent 的意图理解和工作流编排，直接执行预定义的脚本或命令，适用于服务器宕机恢复、紧急部署回滚、批量操作等不能等待 AI 思考的场景。
- 预注册命令：将常用运维脚本（重启服务、清理日志、数据库备份、回滚部署等）注册为直通任务，一条命令即可触发
- 参数化模板：支持定义参数（必填/可选/默认值/示例），执行时动态填充，避免硬编码
- 确认机制：高风险操作默认需要用户确认（
confirm_required=true），防止误操作 - 超时控制：每个任务可设置执行超时（默认 120 秒），防止脚本挂起
- 审计追踪：每次执行自动记录审计日志（谁执行、什么时间、什么参数、退出码、耗时），满足合规要求
- 启用/禁用：可临时禁用某个直通任务，不删除定义
- 多入口触发：桌面面板
/runctl命令、IM 通道斜杠命令、Agent 工具调用（passthrough_task）均可触发 - 跨设备同步：通过 Hub 远程注册，IM 通道可直接触发桌面机器上的直通任务
典型使用场景：
| 场景 | 示例命令 |
|---|---|
| 服务器紧急重启 | /runctl restart-nginx |
| 数据库备份 | /runctl backup-db --target=production |
| 部署回滚 | /runctl rollback --version=v2.3.1 |
| 清理磁盘空间 | /runctl cleanup-logs --days=7 |
| 批量证书续期 | /runctl renew-certs --domain=*.example.com |
| 应急切换 DNS | /runctl switch-dns --target=backup |
| 步骤 | 内容 | 说明 |
|---|---|---|
| 注册账号 | 邮箱注册 | 输入邮箱完成注册，启用远程协作能力 |
| 选择模式 | 专业 / 简洁 | 随时可切换 |
| 配置 AI | 选择 LLM 服务商 | 输入 API Key 并测试连通性，也支持 OAuth 登录和免费体验 |
| 绑定 IM（可选） | 扫码绑定微信 | 绑定后可通过微信随时与 MaClaw 对话 |
- Windows：
MaClaw.exe - macOS：
MaClaw.app - Linux：
MaClaw.AppImage - 终端：
maclaw-tui
首次启动自动检测运行环境，缺少的组件会自动安装。
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
export MACLAW_ADMIN_SECRET="your-admin-secret-at-least-24-chars"
export MACLAW_TOKEN_SECRET="your-token-secret-at-least-32-chars"
go run ./MaClawSrvAPI 文档：
| 文档 | 说明 |
|---|---|
| README | 项目定位、接口分组、安全模型、数据布局 |
| API 对接手册（中文） | 完整字段级说明，含鉴权、分页、错误模型 |
| API Manual (English) | 英文版 API 手册 |
| 5 分钟快速接入 | 最短可用链路 |
| Quickstart (English) | 英文版快速接入 |
| 缺口分析 | 已实现能力与待补全功能 |
| Gap Analysis | 英文版缺口分析 |
| OpenAPI | 服务运行后访问 GET /openapi.json |
srvdemo 是基于 Go + Wails 的桌面客户端，演示 MaClawSrv 全部 API 的对接方式。一键初始化演示数据、Token 交换、配置管理、Instance/Session/Message/Run 全生命周期操作、Skill 和 MCP 管理。详见 srvdemo/README.md。
- 开源用途：用于开源项目时可自由使用
- 商业用途：需获得商业授权，联系 znsoft@163.com
- 作者：Dr. Daniel 人工智能大语言模型博士
- GitHub：RapidAI/MaClaw
- 产品网站：maclaw.top
本工具仅作为配置管理辅助，请确保遵守各模型厂商的服务条款。