SemaClaw 是一个面向个人 AI Agent 的通用工程，构建在可复用的 Agent 运行时（sema-code-core）之上。它提供了将原始运行时变成一个真正可用的个人 AI 系统所需的全部周边设施 —— 权限管理、记忆系统、定时任务、多 Agent 编排、频道适配、Web UI 等等。它同时也是一个参考实现，是社区评估并改进其底层工程决策的起点。

SemaClaw 分析自身源码并自动生成了以上介绍动画 — 基于 frontend-slides 和 remotion skills（前序步骤使用 DeepSeek-Chat，Remotion 动画代码生成使用 Claude Sonnet 4.6）。 观看完整演示视频

核心亮点

• 三层上下文管理 —— 将工作上下文、长期记忆检索与按 Agent 划分的人格分区统一为同一个一致模型。
• Human-in-the-Loop 权限审批 —— PermissionBridge 是 harness 的原生原语，同时支持高风险工具调用的显式用户授权与 Agent 主动发起的澄清请求。
• 四层插件架构 —— MCP 工具、子 Agent、Skills、Hooks，每一层对应一个明确的工程关注点，构成一个有原则的扩展面。
• 插件市场 —— 从任意 Git 仓库或本地目录安装第三方插件包。每个插件可以将 Skills、子 Agent、Hooks 和 MCP 服务器打包在一起。插件默认关闭，在 Web UI 中逐个开启；支持添加多个来源并设置优先级排序。
• DAG Teams —— 两阶段混合编排框架：将 LLM 驱动的动态任务分解，与确定性 DAG 执行结合起来，支持持久 Agent 与虚拟 Agent 的混合编排，内置 5 个可开箱即用的虚拟 subagent。
• 可复用 Workflow —— 把重复性 routine 固化成声明式 DAG 定义（Markdown + YAML），混编 agent 步骤（隔离 persona 会话）与确定性 script 步骤。支持参数化输入、{{…}} 模板（依赖自动推断）、workflow / step 两级 guidance 规则层，以及每个 workflow 独立的持久 workspace。可在对话中通过内置 workflow skill 编写定义，再从 CLI（semaclaw workflow run）或 Web UI 的 workflow 面板触发 —— 实时 DAG 图 + 运行历史 + 行内调参。运行只起隔离 session，绝不打扰正在聊天的 Agent。
• 四模式定时任务 —— 纯通知 / 纯脚本 / 纯 Agent / 脚本+Agent 混合，按任务复杂度匹配执行模式，让 token 消耗与推理工作量成正比。
• Agentic Wiki —— 将任务输出转化为结构化、可检索的 wiki 条目，与 Agent 记忆共同建立索引，形成一个会持续复利、能反哺未来 Agent 会话的个人知识库。
• Workbench：HTML as throwaway UI —— 内置的 Agent 交付物渲染面板。LaunchUI 工具让 Agent 直接抛出交互式 HTML、富 Markdown、内嵌的 Web 服务（iframe）或 API 端点卡片 —— Web UI 工作台把每个 artifact 挂成可切换的历史 tab，免单独构建步骤。把"HTML 当一次性 UI"用起来：让 Agent 把结果展示给你，而不只是描述给你听。
• 多频道与 Web UI —— 内置 Telegram、飞书、QQ 适配器，配套 WebSocket Gateway 与 React Web UI。

推荐插件包 —— Overture

Overture 是一个示例插件市场，把 SemaClaw 进一步组装成可自我进化的个人 Agent 系统。从 插件市场 → 添加源 粘贴仓库 URL 即可安装。

• notation（记谱法） —— 数据飞轮 hook。把每次工具调用、用户与结果落成结构化日志，作为下面两条自进化循环的信号源。
• cadence（基因） & repertoire（剧目库） —— 两层自进化。cadence 演化 Agent 的基线基因（提示词、策略、默认启发式）；repertoire 演化技能库 —— 增删、打磨、退役单个 skill。
• timbre（音色） —— 人设插件包。每个 timbre 语气 / 价值取向 / 专业领域打包成一个可复用的人格档案，让任何 Agent 都能"换装"。把"Agent 是谁"和"Agent 会什么"解耦。

快速开始

方式 A —— 从 npm 安装（推荐）

# 1. 全局安装
npm install -g semaclaw

# 2. 启动
semaclaw

就这么简单。在浏览器打开 Web UI：http://127.0.0.1:18788/。

安装失败？ 参见 docs/INSTALL_TROUBLESHOOTING.md —— 收录了 macOS 上 sharp postinstall 失败等已知问题的修复步骤。

首次启动需配置 LLM。 SemaClaw 不内置任何模型。打开 Web UI → 设置 → LLM，添加一个 provider profile（OpenAI / Anthropic / DeepSeek / Qwen / ……），填写 baseURL、apiKey、modelName 。配置会持久化到 ~/.semaclaw/config.json，并同步写入 ~/.semaclaw/semaclaw-model.conf。在至少有一个 active profile 之前，任何调用 LLM 的 Agent 运行都会失败。

如需启用消息频道（Telegram / 飞书 / QQ / 微信），在启动 semaclaw 之前，在当前工作目录创建 .env 文件即可。完整环境变量列表请参考 docs/QUICK_START.md。

方式 B —— 从源码构建

# 1. 克隆
git clone https://github.com/midea-ai/SemaClaw.git
cd SemaClaw

# 2. 安装与构建
npm install
npm run build
npm run build:web

# 3. 配置环境变量（可选）
cp .env.example .env
# 编辑 .env 以启用消息频道（Telegram / 飞书 / QQ / 微信）。
# 如果不配置任何频道，SemaClaw 将以 Web UI 单机模式启动。

# 4. 启动
npm start

启动后，在浏览器打开 Web UI：http://127.0.0.1:18788/，然后进入 设置 → LLM 至少添加一个 active 的 provider profile（参见方式 A 中的说明）。

完整使用说明（环境变量、CLI 命令、运行时目录布局、架构细节）请参考 docs/QUICK_START.md。

文档

| 文档 | 说明 | |---|---| | 快速开始与使用指南 | 安装、配置、CLI 命令、运行时布局、MCP 工具说明 | | 插件市场使用指南 | 添加插件来源，发现并启用包含 Skills / 子 Agent / Hooks / MCP 的插件包 | | Hooks 使用指南 | 用 shell 脚本或 LLM 拦截 agent 生命周期事件 | | Workflow 指南 | 编写可复用的 agent + script DAG workflow：定义格式、模板语法、observe 输出 | | 远程访问指南 | 通过反向代理（Nginx / Caddy）安全暴露 Web UI | | 技术报告 | SemaClaw: A Step Towards General-Purpose Personal AI Agents through Harness Engineering | | 贡献指南 | 即将发布 |

项目结构

semaclaw/
├── src/
│   ├── agent/          # Agent 生命周期、bridges、权限路由
│   ├── channels/       # Telegram / 飞书 / QQ 适配器
│   ├── gateway/        # GroupManager、MessageRouter、WebSocket Gateway
│   ├── mcp/            # MCP servers（admin / schedule / memory / dispatch / ...）
│   ├── memory/         # FTS5 + 向量混合搜索、每日日志
│   ├── scheduler/      # Cron / interval / once 调度
│   ├── workflow/       # 可复用 workflow 引擎（registry、DAG executor、run store）
│   ├── wiki/           # Git 驱动的个人知识库
│   ├── marketplace/    # 插件市场（来源管理、插件发现、MCP/Skills/子 Agent 注入）
│   └── clawhub/        # ClaWHub 技能市场集成
├── web/                # React + Vite Web UI
├── skills/             # 内置技能
└── docs/               # 详细文档

参与贡献

欢迎贡献。SemaClaw 的目的是推动个人 AI Agent 领域的共享工程基础 —— issue、PR、设计讨论都同样有价值。详情请见 CONTRIBUTING.md （即将发布）。

开源协议

MIT © AIRC Sema Team

关于 Logo

SemaClaw 的 logo 是一匹背上长着 Claw 钳形翅膀的马。设计灵感来自"以梦为马"—— 希望这个 AI harness 能承载用户天马行空的想象力，载着他们去任何想去的地方。

名字本身也藏了几层含义：

• Sema 取自 semantic（语义）的开头，而 ma 与中文「马」同音；
• harness 这个词的本意正是「马具」—— 有驾驭约束的意思；
• Claw（钳）与中文「钱」谐音，所以这匹马背上长着 Claw 翅膀，也藏着一份小小的祝福：马上有钱 🐎💰。

愿这个项目能让每一位使用者都既能驰骋想象，也能马到功成。

致谢

SemaClaw 构建在 sema-code-core 之上 —— 它提供了底层 Agent 运行时。在产品形态上，SemaClaw 也受到了 OpenClaw 的启发，并接入了来自同一项目的 ClaWHub 插件市场。同时感谢本项目所依赖的更广阔的开源生态，包括 Model Context Protocol、grammY 等许多优秀项目。

SemaClaw 的目标不是定义个人 AI Agent 的最终架构 —— 而是推动一个共享的工程基础，让更好的架构能够在它之上被构建出来。