目录

起因

MyClaw是什么

技术选型

核心功能

核心设计

Agent循环

工具系统

记忆系统

外部通道

浏览器自动化

自动化任务

一些设计决策

为什么不用TypeScript

为什么默认用免费模型

项目结构

快速开始

---

起因

前段时间我在研究AI Agent相关的开源项目，发现了OpenClaw这个项目。说实话，第一眼看到它的时候我是很兴奋的——功能太全了！22个消息渠道、原生移动端应用、语音唤醒、Docker沙箱...简直是Agent界的瑞士军刀。

但当我真正想把它部署起来自己用的时候，问题来了。

太重了。

对于我这种只想在个人电脑上跑一个智能助手的用户来说，OpenClaw就像是用航母去钓鱼——能是能，但真的有必要吗？光是理解它的Gateway、CLI、节点这些概念就花了我不少时间，更别说还要配置各种依赖。

于是我就想：能不能做一个"够用就好"的版本？

MyClaw是什么

MyClaw是我基于OpenClaw的理念重新实现的一个个人Agent平台。简单来说，它保留了OpenClaw最核心的能力，但把架构彻底简化了。

github地址：https://github.com/hrhcode/myclaw ⭐ 觉得有用的话，点个Star支持一下呗~

核心差异大概是这样：

维度	OpenClaw	MyClaw
架构	CLI-First，单进程 Gateway + WS 控制平面	Web-First，前后端分离（FastAPI + React），浏览器完成全部操作
上手门槛	需要命令行基础，openclaw wizard 引导	零命令行，打开浏览器即用
技术栈	TypeScript / Node.js	Python + React，后端原生适配 AI/数据处理
可视化	Control UI 为辅助入口	所有页面均为一等公民，会话、记忆、通道、自动化全部可视化
Agent 防循环	Pi Agent RPC 模式	4 层防卡死：迭代上限、进度签名、循环检测、熔断器
记忆系统	单一记忆插件槽位	完整管线：向量 + BM25 混合搜索 + MMR 重排 + 时间衰减 + Evergreen
工作会话	基于渠道的会话模型	独立工作会话，每会话独立配置模型、工具集、工作目录、记忆策略
学习曲线	需理解 Gateway / CLI / 节点等概念	直觉式操作，类似使用普通 Web 应用
使用成本	需自行配置模型和 API Key	默认使用免费模型（GLM-4-Flash），零成本即可运行

最大的改变是代码量的精简。OpenClaw有5,769个TypeScript文件，52.2 万行代码，是一个功能极其丰富的企业级项目。而MyClaw只保留了核心能力，后端约1.7万行Python，前端约0.9万行TypeScript，总计不到3万行代码。对于想学习AI Agent源码的开发者来说，这个代码量更容易上手阅读和二次开发。

技术选型

后端我选了Python + FastAPI。原因很简单：AI相关的生态Python最完善，各种SDK、模型调用库都是Python优先的。FastAPI的异步支持也很好，配合aiosqlite做数据库操作，性能完全够用。

前端用React 19 + TypeScript + Vite + TailwindCSS。这套组合现在很成熟了，开发体验不错。状态管理直接用React Context，没上Redux——单用户应用，没必要那么复杂。

数据库选SQLite，轻量够用。但加了一个关键扩展：sqlite-vec，支持向量搜索。这样记忆系统就可以直接在SQLite里做向量检索，不用额外部署向量数据库。

核心功能

模块	能力
智能聊天	SSE 流式响应、完整工具调用轨迹、/new /reset /compact /status 命令、自动上下文压缩
智能记忆	双层记忆（短期消息 + 长期记忆）；混合检索（向量 + BM25）+ MMR 重排 + 时间衰减 + Evergreen
外部通道	QQ 官方机器人接入，支持频道/私信/群消息/@触发；三级会话映射；WebSocket 实时消息路由
浏览器自动化	基于 Playwright 的完整控制：导航/点击/输入/滚动/截图/下拉选择/键盘模拟/等待条件
自动化任务	固定间隔 / 每日 / 每周调度，结果写入工作会话，可视化管理
Skills	自动发现本地 skills，按工作会话独立启停，支持 AGENTS.md / TOOLS.md 项目级提示
MCP 服务	内置 MCP 服务管理页面，可视化配置和管理
工具系统	5 种预设配置（MINIMAL / STANDARD / CODING / MESSAGING / FULL），allow/deny 白名单，超时控制，敏感字段自动隐藏

核心设计

Agent循环

这是整个系统的心脏。核心逻辑在controller.py里，大概做了这几件事：

1. 接收用户消息，构建系统提示

2. 调用LLM，等待响应

3. 如果LLM返回工具调用，执行工具

4. 把工具结果回传给LLM

5. 循环直到LLM返回最终答案

为了避免Agent陷入死循环，我设计了4层防护：

• 迭代上限：最多循环N次

• 进度签名：检测是否在做重复的事情

• 循环检测：识别相同的工具调用模式

• 熔断器：连续失败后自动停止

工具系统

工具系统分三层：注册、执行、过滤。

注册层负责发现和注册工具，新工具只需要继承基类就能自动被发现。执行层负责实际调用工具，支持超时控制。过滤层根据预设配置决定哪些工具可用。

记忆系统

这个我花了不少心思。记忆分两层：

• 短期记忆：最近的消息历史

• 长期记忆：持久化存储的重要信息

检索时使用混合策略：向量相似度 + BM25文本匹配 + MMR重排 + 时间衰减。这样既能找到语义相近的内容，也能找到关键词匹配的内容，还能避免返回太相似的结果。

还有一个Evergreen机制：对于一些长期有效的信息（比如用户的偏好），可以标记为"常青"，检索时优先返回。

外部通道

目前实现了QQ官方机器人的接入。支持频道消息、私信、群消息，可以通过@触发。消息通过WebSocket实时路由到对应的工作会话。

浏览器自动化

基于Playwright实现。支持导航、点击、输入、滚动、截图、下拉选择、键盘模拟、等待条件等操作。可以让Agent自动操作网页，比如定时抢票、自动填表等。

自动化任务

支持三种调度方式：固定间隔、每日、每周。任务执行结果会写入指定的工作会话，方便查看历史记录。

一些设计决策

为什么不用TypeScript

OpenClaw用的是TypeScript，我一开始也考虑过沿用。但后来发现，AI相关的很多库Python生态更完善。比如智谱的SDK、向量嵌入的sentence-transformers，Python都有现成的。用Python可以少踩很多坑。

为什么默认用免费模型

我觉得降低使用门槛很重要。很多人想试试AI Agent，但一想到要花钱买API额度就犹豫了。MyClaw默认使用智谱GLM-4-Flash，这个模型目前免费，配合一个API Key就能跑起来。用户可以先免费体验，觉得好用再换其他模型。

项目结构

myclaw/
├─ frontend/
│  ├─ src/
│  │  ├─ components/
│  │  │  ├─ chat/             # 聊天页
│  │  │  ├─ channels/         # 通道管理页
│  │  │  ├─ conversations/    # 聊天记录页
│  │  │  ├─ sessions/         # 工作会话页
│  │  │  ├─ automations/      # 自动化页
│  │  │  ├─ memory/           # 记忆页
│  │  │  ├─ settings/         # 设置页
│  │  │  ├─ tools/            # 工具页
│  │  │  └─ layout/           # 布局组件
│  │  ├─ contexts/            # React Context (AppContext, ThemeContext)
│  │  ├─ hooks/               # 自定义 Hooks
│  │  ├─ services/            # API 层 (axios + fetch SSE)
│  │  └─ types/               # TypeScript 类型定义
│  └─ package.json
├─ backend/
│  ├─ app/
│  │  ├─ agent_loop/          # Agent 执行引擎 (controller.py + prompting.py)
│  │  ├─ api/                 # API 路由 (挂载在 /api 下)
│  │  ├─ channels/            # 通道系统 (base, gateway, manager, registry)
│  │  │  └─ qq/               # QQ 官方机器人通道实现
│  │  ├─ core/                # 核心配置
│  │  ├─ dao/                 # 数据访问层
│  │  ├─ models/              # ORM 模型
│  │  ├─ schemas/             # Pydantic Schema
│  │  ├─ services/            # 业务逻辑层
│  │  ├─ tools/               # 工具系统 (registry → executor → profiles)
│  │  └─ main.py              # 应用入口
│  ├─ tests/                  # 单元测试
│  └─ requirements.txt
├─ docs/                      # 项目文档 + 截图资源
├─ start_all.ps1              # Windows 一键启动脚本
└─ README.md

快速开始

仓库地址：https://github.com/hrhcode/myclaw （⭐ Star一下，开源不易，感谢支持！）

环境要求：Python 3.10+、Node.js 18+

# 安装依赖
cd backend && pip install -r requirements.txt
cd frontend && npm install

# 启动（Windows一键）
.\start_all.ps1

# 或者分别启动
cd backend && python start_server.py
cd frontend && npm run dev

然后打开web端在配置页面配置 智谱 API Key 和 OpenRouter ApiKey（使用openrouter的免费向量模型进行记忆系统的向量化处理）就可以开始使用了。