1. 项目概述
作为一名长期深耕AI应用开发的工程师,我最近完成了一个有趣的项目——NewClaw。这个项目的诞生源于我对OpenClaw架构的深入研究和实践反思。经过6.5小时的连续运行测试,NewClaw成功处理了600+次工具调用,完成了25轮Mission执行,期间经历了3次手动重启和多次系统故障,但都实现了自动恢复,最终零崩溃完成测试。
1.1 核心设计理念
NewClaw的核心设计理念可以概括为以下几点:
- 单线程主循环:简化系统复杂度,避免并发问题
- 事件驱动架构:替代传统的轮询机制,提高效率
- 渐进式信任模型:根据上下文动态调整权限级别
- 外部记忆系统:替代传统的Session持久化方案
- 最小工具集:提供基础但强大的工具,给予模型最大自由度
提示:NewClaw目前是v0.1个人实验项目,不是生产级框架。测试规模有限,仅经过单Mission任务、单用户、单机运行的验证。
2. 快速上手指南
2.1 环境准备
首先需要克隆项目仓库并安装依赖:
bash复制git clone https://github.com/XZL-CODE/NewClaw.git
cd NewClaw
npm install
2.2 配置说明
项目使用JSON配置文件管理各项参数。复制示例配置文件并修改:
bash复制cp config.example.json config.json
最小配置只需要指定LLM提供商和API密钥。以DeepSeek为例:
json复制{
"llm": {
"provider": "deepseek",
"apiKey": "sk-your-key",
"model": "deepseek-chat"
}
}
NewClaw支持12个LLM厂商,包括:
- 国内厂商:DeepSeek、Moonshot、Dashscope、Zhipu
- 国际厂商:Anthropic、OpenAI、Gemini
- 本地模型:Ollama、LM Studio、vLLM
- 聚合平台:OpenRouter、SiliconFlow
2.3 运行项目
根据使用场景选择不同的启动方式:
bash复制# 终端模式(最简单)
npm start
# 或指定特定通道
npm run start:web # Web界面
npm run start:feishu # 飞书机器人
目前支持的通道包括:Terminal、Web GUI、Feishu、Telegram和Discord。终端模式开箱即用,其他通道需要额外配置对应的Bot Token。
3. 架构设计与实现
3.1 核心模块解析
NewClaw的架构由以下几个核心模块组成:
| 模块 | 代码文件 | 行数 | 主要职责 |
|---|---|---|---|
| 主循环 | master-loop.ts | 313 | 系统核心调度 |
| 事件收集器 | event-collector.ts | 179 | 统一事件管理 |
| 上下文组装器 | context-assembler.ts | 184 | 构建LLM调用上下文 |
| Mission引擎 | runner.ts + store.ts | 750 | 后台任务执行与管理 |
| 权限系统 | permission.ts | 100 | 动态权限控制 |
| 记忆系统 | 多个文件 | - | 三层记忆存储与检索 |
| LLM适配层 | llm-adapter.ts | - | 多厂商LLM统一接口 |
| 插件系统 | plugin-system.ts | - | 能力扩展机制 |
3.2 单线程主循环实现
主循环的实现逻辑如下:
- 等待事件触发(来自事件收集器)
- 组装当前上下文(调用上下文组装器)
- 调用LLM获取决策
- 执行工具调用
- 循环处理,最多25轮安全限制
这种设计避免了OpenClaw中Heartbeat+Cron双调度带来的并发问题。在6.5小时的实战测试中,即使出现SQLite语法错误或API限流等问题,也不会导致系统崩溃,因为错误被隔离在单次循环中。
3.3 事件驱动机制
事件收集器的核心是waitForEvent/wakeUp异步等待机制。与OpenClaw的60秒固定心跳相比,这种设计有以下优势:
- 无事件时不消耗资源
- 响应更及时
- 天然支持背压控制
在测试中,当遇到API 429限流时,系统能够自然暂停,待限流解除后自动恢复,不需要复杂的重试逻辑。
4. 关键技术创新
4.1 渐进式信任模型
NewClaw实现了四级权限边界:
| 级别 | 名称 | 说明 | 示例 |
|---|---|---|---|
| L0 | FREE | 无需确认 | 读文件、搜索、web_fetch |
| L1 | NOTIFY | 执行后通知 | 发消息、写记忆 |
| L2 | APPROVE | 执行前审批 | 写文件、执行bash命令 |
| L3 | FORBIDDEN | 禁止执行 | 危险系统命令 |
在Mission模式下,bash命令会自动提权到L1(通知但不阻塞),因为Mission本身就是用户授权的自主任务。这种动态权限调整机制是"渐进式信任"理念的具体体现。
4.2 外部记忆系统
NewClaw采用三层记忆架构:
- Fact记忆:使用SQLite FTS5实现全文检索,存储用户偏好、平台信息等结构化知识
- Episode记忆:基于TF-IDF相似度,存储交互片段的摘要
- Reflection记忆:由LLM驱动,在compact触发时生成高阶洞见
记忆检索采用混合权重(0.4/0.6),不同用户的记忆完全隔离。在InStreet测试中,系统通过memory_write工具将平台API格式、认证方式等信息存储为Fact记忆,后续任务中自动检索使用,避免了携带大量对话历史的问题。
4.3 最小工具集哲学
NewClaw只提供了20个核心工具,包括:
- 基础工具:bash, read_file, write_file
- 搜索工具:search_files, grep_content, web_search
- 网络工具:web_fetch, send_message
- 记忆工具:memory_read, memory_write
- 任务工具:9个mission_*工具
在InStreet测试中,一个有趣的发现是:预写的25个InStreet专用工具最终被全部删除,因为模型使用bash+curl就能完成所有操作。这验证了"最小工具集"哲学的价值——给模型一个强大的基础工具(如bash),比提供多个专用工具更有效。
5. 实战测试与结果分析
5.1 测试场景设计
为了验证NewClaw的稳定性,设计了一个复杂的测试场景:让AI自主探索InStreet AI Agent社交平台。通过飞书发送任务指令:
code复制自主探索InStreet平台——注册、验证、炒股、发帖、去酒馆社交,沉淀方法论。全程禁止问我。
系统在无人干预的情况下连续运行了6.5小时(03:15 - 09:49)。
5.2 测试结果
测试期间系统完成了以下任务:
- 账户管理:成功注册账号并完成验证
- 股票交易:建立4个分散持仓,总资产1,002,628元(+0.26%)
- 社区互动:Score达到15点,发布深度评论
- 预言机:建立2个仓位
- 酒馆社交:完整走完买酒、喝酒、留言、涂鸦流程
系统处理了600+次工具调用,约25轮Mission执行。最长单轮处理时间423,532ms(约7分钟)。
5.3 故障恢复测试
测试期间模拟了多种故障场景,系统表现如下:
| 故障类型 | 发生时间 | 系统反应 | 恢复方式 |
|---|---|---|---|
| SQLite语法错误 | 07:14 | 记录错误,继续执行 | 下一轮循环自动继续 |
| API 429限流 | 07:57 | 提前结束当前轮次 | 后续轮次正常恢复 |
| 手动重启(Ctrl+C) | 三次 | 保存状态 | 重启后自动恢复任务 |
| 飞书WS断线 | 09:13 | 自动重连 | 不影响核心循环 |
这些测试验证了NewClaw架构的健壮性,特别是状态持久化和自动恢复机制的有效性。
6. 设计取舍与优化
6.1 技术选型调整
在实现过程中,对一些设计方案进行了务实调整:
-
向量检索方案:
- 设计:计划使用sqlite-vec
- 实现:改用TF-IDF文本相似度
- 原因:sqlite-vec的native编译存在跨平台问题
- 效果:MVP阶段TF-IDF已经足够
-
安全沙箱:
- 设计:使用Docker隔离bash执行
- 实现:字符串级别的危险命令检测
- 原因:优先级考虑,个人使用场景足够
- 注意:生产环境需要升级
6.2 记忆系统迭代
记忆系统经历了���次优化:
- 初始方案:纯模板拼接的反思记忆
- 发现问题:生成质量不高,实用性差
- 最终方案:LLM驱动的高阶洞见生成
- 优化效果:记忆质量显著提升
6.3 工具集精简
最意外的优化是工具集的精简:
- 预写了25个InStreet专用工具
- 测试发现模型用bash+curl就能完成所有操作
- 专用工具反而限制了模型的灵活性
- 最终决定:删除所有专用工具,保留最小工具集
这个决定验证了Claude Code团队的核心观点:当模型足够强时,简单的通用工具比复杂的专用工具更有效。
7. 项目开源与社区
7.1 开源信息
NewClaw已开源,基本信息如下:
- 仓库地址:https://github.com/XZL-CODE/NewClaw
- 许可证:MIT
- 语言:TypeScript
- README:中英文双语(487行),包含完整文档
7.2 贡献指南
欢迎社区贡献,重点方向包括:
- 安全增强:实现真正的Docker沙箱隔离
- 检索优化:引入向量检索替代TF-IDF
- 通道扩展:增加微信、Slack等平台支持
- LLM适配:接入更多模型提供商
- 权限细化:增强权限系统的细粒度控制
贡献方式:通过GitHub提交Issue或PR。
8. 经验总结与展望
在NewClaw的开发过程中,最深刻的体会是:好的AI系统设计应该顺应模型能力的发展趋势,而不是试图用复杂工程约束模型的自然表达。这一点在几个方面得到了验证:
- 工具设计:bash+curl的组合比25个专用工具更强大
- 架构设计:简单的单线程循环比复杂的双调度更稳定
- 记忆系统:精心设计的三层记忆比原始对话历史更高效
未来,NewClaw可能会在以下方向继续演进:
- 实现纯事件驱动的Mission调度
- 增强跨平台部署能力
- 优化记忆检索质量
- 完善开发者生态
这个项目的价值不仅在于代码本身,更在于验证了一种不同的AI系统设计哲学——信任模型,简化工程,聚焦本质。
