第一章：项目概述
📖 本章介绍 MiniClaw 项目的基本信息、核心价值主张和特色亮点。
1.1 项目基本信息
1.1.1 项目名称与定位
| 属性 | 内容 |
|---|---|
| 项目名称 | MiniClaw 🦞 |
| 版本号 | v0.5.0 "The Nervous System" |
| 项目定位 | 微内核智能体（Micro-Kernel Agent） |
| 目标用户 | Claude CoWork、Qoderwork、WorkBuddy 等 MCP 客户端用户 |
┌─────────────────────────────────────────────────────────────┐
│ MiniClaw 项目定位图 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ │
│ │ OpenClaw │ ◄── 完整版（功能丰富，复杂度高） │
│ │ (Full) │ │
│ └──────┬──────┘ │
│ │ │
│ │ 极简实现 │
│ ▼ │
│ ┌─────────────┐ │
│ │ MiniClaw │ ◄── 轻量版（核心功能，低门槛） │
│ │ (Minimal) │ │
│ └─────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────┐ │
│ │ MCP 客户端生态 │ │
│ │ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ │ │
│ │ │Claude │ │Cursor │ │Windsurf│ │Qoder │ │ │
│ │ │ Code │ │ │ │ │ │ │ │ │
│ │ └───────┘ └───────┘ └───────┘ └───────┘ │ │
│ └─────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘1.1.2 项目来源与背景
MiniClaw 是爆火开源项目 OpenClaw 的极简实现版本。
timeline
title MiniClaw 项目演进时间线
section 起源
OpenClaw 爆火 : Mac mini 热销
: 社区关注度激增
section 衍生
MiniClaw 诞生 : 极简实现
: 降低入门门槛
section 发展
v0.5.0 发布 : "The Nervous System"
: ACE 引擎
: 实体知识图谱核心理念
| 理念 | 说明 |
|---|---|
| 微内核 | 轻量级核心，可扩展插件 |
| ACE 引擎 | 自适应上下文引擎，智能管理 Token |
| 生物进化 | 根据用户反馈自我迭代成长 |
设计哲学
💡 最低门槛体验 OpenClaw 核心功能
┌────────────────────────────────────────────────────────┐
│ 设计哲学对比 │
├──────────────────┬─────────────────┬───────────────────┤
│ 特性 │ OpenClaw │ MiniClaw │
├──────────────────┼─────────────────┼───────────────────┤
│ 代码规模 │ 较大 │ ~2,700 行 │
│ 入门门槛 │ 较高 │ 极低 │
│ 核心功能 │ 完整 │ 精简 │
│ 部署方式 │ 复杂 │ npx 一键 │
│ 学习曲线 │ 陡峭 │ 平缓 │
└──────────────────┴─────────────────┴───────────────────┘1.1.3 项目仓库信息
| 信息项 | 内容 |
|---|---|
| Git 仓库 | https://github.com/8421bit/miniclaw |
| 许可证 | MIT License |
| 作者 | 8421bit |
| 包管理 | npm (public) |
# 快速安装命令
npx -y github:8421bit/miniclaw1.2 核心价值主张
1.2.1 "神经系统"概念
MiniClaw 的核心理念是成为 AI 工作伙伴的 "神经系统"。
┌─────────────────────────────────┐
│ AI 工作伙伴 │
│ (Claude / Cursor 等) │
└───────────────┬─────────────────┘
│
│ 寄生接入
▼
┌───────────────────────────────────────────────────┐
│ MiniClaw 神经系统 │
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ 👁️ Eyes │ │🖐️ Hands│ │ 🧠 Memory│ │
│ │ 感知 │ │ 行动 │ │ 记忆 │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │
│ └─────────────┼─────────────┘ │
│ │ │
│ ┌───────┴───────┐ │
│ │ 🧬 Evolution │ │
│ │ 进化 │ │
│ └───────────────┘ │
│ │
└───────────────────────────────────────────────────┘四大核心能力
| 能力 | 图标 | 功能描述 | 实现方式 |
|---|---|---|---|
| 感知 | 👁️ | 自动识别项目类型、Git 状态、技术栈 | detectWorkspace() |
| 行动 | 🖐️ | 安全执行终端命令 | miniclaw_exec |
| 记忆 | 🧠 | 跨会话记住项目细节和用户偏好 | 双层记忆系统 |
| 进化 | 🧬 | 根据反馈自动进化性格和技能 | 自动进化协议 |
寄生式架构设计
┌─────────────────────────────────────────────────────────────┐
│ 传统 AI 助手架构 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ │
│ │ 用户请求 │ │
│ └──────┬──────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ AI 模型 │ ───► │ 响应输出 │ │
│ │ (无状态) │ │ (一次性) │ │
│ └─────────────┘ └─────────────┘ │
│ │
│ ❌ 无记忆 ❌ 无感知 ❌ 无进化 │
│ │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ MiniClaw 寄生式架构 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ │
│ │ 用户请求 │ │
│ └──────┬──────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────┐ │
│ │ MiniClaw 层 │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ 上下文 │ │ 记忆 │ │ 进化 │ │ │
│ │ │ 编译 │ │ 管理 │ │ 引擎 │ │ │
│ │ └────┬────┘ └────┬────┘ └────┬────┘ │ │
│ │ └───────────┼───────────┘ │ │
│ └───────────────────┼─────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ AI 模型 │ ───► │ 智能响应 │ │
│ │ (有状态) │ │ (持续进化) │ │
│ └─────────────┘ └─────────────┘ │
│ │
│ ✅ 有记忆 ✅ 有感知 ✅ 有进化 │
│ │
└─────────────────────────────────────────────────────────────┘1.2.2 与传统 AI 助手的区别
┌──────────────────────────────────────────────────────────────┐
│ 对比分析：传统 vs MiniClaw │
├────────────────┬─────────────────────┬───────────────────────┤
│ 维度 │ 传统 AI │ MiniClaw │
├────────────────┼─────────────────────┼───────────────────────┤
│ 提示词方式 │ 静态、固定 │ 动态、运行时编译 │
│ 记忆能力 │ 无 / 单会话 │ 双层记忆、跨会话 │
│ 上下文感知 │ 无 │ 自动检测项目环境 │
│ 自我进化 │ 无 │ 根据反馈自动调整 │
│ 时间感知 │ 无 │ ACE 时间模式系统 │
│ 命令执行 │ 无 / 不安全 │ 白名单安全沙箱 │
│ 用户画像 │ 无 │ 持续学习用户偏好 │
│ 性格一致性 │ 配置固定 │ 可进化人格 │
└────────────────┴─────────────────────┴───────────────────────┘核心差异图解
graph TB
subgraph 传统AI["传统 AI 助手"]
A1[用户输入] --> B1[静态提示词]
B1 --> C1[AI 模型]
C1 --> D1[一次性响应]
D1 --> E1[❌ 会话结束，记忆清空]
end
subgraph MiniClaw["MiniClaw 智能体"]
A2[用户输入] --> B2[动态上下文编译]
B2 --> C2[加载记忆与用户画像]
C2 --> D2[AI 模型]
D2 --> E2[智能响应]
E2 --> F2[✅ 更新记忆与进化]
F2 -.->|持续积累| C2
end1.3 项目特色亮点
1.3.1 零安装快速开始
// 只需在 MCP 客户端配置中添加：
{
"mcpServers": {
"miniclaw": {
"command": "npx",
"args": ["-y", "github:8421bit/miniclaw"],
"env": {
"MINICLAW_TOKEN_BUDGET": "12000"
}
}
}
}📦 无需 <code>git clone</code>，无需手动安装依赖，npx 一键启动！
1.3.2 跨平台支持
┌─────────────────────────────────────────────────────────────┐
│ 跨平台支持矩阵 │
├─────────────────┬───────────────────┬───────────────────────┤
│ 平台 │ 支持状态 │ 说明 │
├─────────────────┼───────────────────┼───────────────────────┤
│ 🪟 Windows │ ✅ │ 完全支持 │
│ 🍎 macOS │ ✅ │ 完全支持 │
│ 🐧 Linux │ ✅ │ 完全支持 │
├─────────────────┴───────────────────┴───────────────────────┤
│ 技术实现： │
│ • 使用 os.homedir() 获取用户目录 │
│ • 使用 path.join() 处理路径分隔符 │
│ • 使用 Node.js 跨平台 API │
└─────────────────────────────────────────────────────────────┘1.3.3 本地数据存储（隐私保护）
┌─────────────────────────────────────────────────────────────┐
│ 数据存储架构 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ☁️ 云端 │
│ ┌─────────────────────────────────────────────┐ │
│ │ LLM API 请求 │ │
│ │ (仅对话内容，无本地数据) │ │
│ └─────────────────────────────────────────────┘ │
│ │
│ 💻 本地 (~/.miniclaw/) │
│ ┌─────────────────────────────────────────────┐ │
│ │ ✅ 所有记忆数据 │ │
│ │ ✅ 用户画像 │ │
│ │ ✅ 环境配置 │ │
│ │ ✅ 实体知识图谱 │ │
│ │ ✅ 技能文件 │ │
│ └─────────────────────────────────────────────┘ │
│ │
│ 🔒 隐私保证：本地数据永不上传云端 │
│ │
└─────────────────────────────────────────────────────────────┘1.3.4 安全的命令执行机制
┌─────────────────────────────────────────────────────────────┐
│ 命令执行安全沙箱 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 白名单检查 │ │
│ │ │ │
│ │ 允许的命令： │ │
│ │ ✅ ls, cat, find, grep, head, tail, wc │ │
│ │ ✅ git (status, log, diff, branch) │ │
│ │ ✅ npm, node, pnpm, yarn, python, pip │ │
│ │ ✅ echo, date, uname, which, pwd, ps │ │
│ │ │ │
│ │ 禁止的命令： │ │
│ │ ❌ rm, sudo, chown, chmod, mv, dd │ │
│ │ ❌ 任何破坏性操作 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 执行限制 │ │
│ │ │ │
│ │ ⏱️ 超时时间：10 秒 │ │
│ │ 📊 输出截断：1MB │ │
│ │ 📁 工作目录：当前项目目录 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘本章小结
┌─────────────────────────────────────────────────────────────┐
│ 第一章 核心要点 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 🎯 MiniClaw 是 OpenClaw 的极简实现版本 │
│ │
│ 🧠 核心理念：微内核 + ACE 引擎 + 生物进化 │
│ │
│ ✨ 四大能力：感知、行动、记忆、进化 │
│ │
│ 🚀 特色亮点：零安装、跨平台、本地存储、安全执行 │
│ │
│ 🔗 项目地址：https://github.com/8421bit/miniclaw │
│ │
└─────────────────────────────────────────────────────────────┘下一章：项目架构设计 →