NanoClaw：回到初心，构建属于你的 OpenClaw
引言
OpenClaw 早已不只是开发者的玩具。越来越多的普通用户开始尝试这个 AI 助手，但安装配置过程却成了一大门槛——各种依赖冲突、环境配置、权限问题让人望而却步。
NanoClaw 的诞生正是为了解决这个痛点：让 Claude Code 来帮你完成整个安装部署。你不需要手动编辑配置文件，也不需要理解复杂的依赖关系，只需简单的自然语言交互，AI 就能自动搞定一切。
当然，这引出了另一个问题：普通用户往往连 Claude Code 都没有，甚至可能不知道如何打开命令行。所以 NanoClaw 的定位更偏向于有技术背景、追求极简和安全的用户群体。
除了安装门槛，OpenClaw 还面临另一个困境：经过持续的功能堆砌，它已经变成了一座"人类难以读完的屎山"。其中大量需求可能是 Peter 个人或国外用户特有的，对于普通用户来说反而成了负担。
NanoClaw 选择了一条不同的路：回到 OpenClaw 的初心，用极简主义重构核心功能，打造最小可用原型。每个用户都可以从这个"最小公约数"出发，构建属于自己的定制化 “OpenClaw”。
今天我们要介绍的 NanoClaw，正是这样一次回归初心的实践。相比 OpenClaw 近 73 万行的核心代码，NanoClaw 仅用约 7500 行 TypeScript 就实现了核心功能，主打安全隔离和简洁易懂两大特性。本文将深入剖析 NanoClaw 的架构设计、安装流程和核心机制。
一、项目概览
1.1 什么是 NanoClaw？
NanoClaw 是一个轻量级 AI 助手，可以简单理解为"运行在容器中的 Claude Code"。它的核心理念是：小巧，安全、可定制。
| 特性 | 说明 |
|---|---|
| 小巧易懂 | 单一进程，少量源文件。无微服务、无消息队列、无复杂抽象层 |
| 安全隔离 | Agent 运行在 Linux 容器中（macOS 用 Apple Container 或 Docker），只能看到被明确挂载的内容 |
| 为单一用户打造 | 不是框架，是可工作的软件，完全符合个人需求 |
| 定制即代码修改 | 没有繁杂的配置文件，想要不同行为直接修改代码 |
| AI 原生 | 由 Claude Code 指导安装，无需传统安装向导 |
1.2 与 OpenClaw 的对比
| 维度 | OpenClaw | NanoClaw |
|---|---|---|
| 代码量 | ~728,000 行 (src/) | ~7,500 行 (src/) |
| 模块数量 | 52+ 个模块 | 少数几个核心文件 |
| 依赖项 | 45+ 个 | 极少数 |
| 配置文件 | 8 个配置管理文件 | 无配置文件 |
| 理解时间 | 数小时 | 8 分钟内 |
| 安全级别 | 应用级（白名单，配对码） | 操作系统级隔离（容器） |
| 渠道支持 | 15+ 个渠道 | 多渠道（WhatsApp/Telegram/Discord/Slack/Gmail） |
从对比中可以清晰看出，NanoClaw 选择了做减法的设计哲学——去掉一切不必要的抽象，让代码本身成为最好的文档。
二、快速开始
2.1 安装方式：为什么用 Claude 来部署？
NanoClaw 的安装过程充分体现了"AI 原生"的设计理念。你可能会问：为什么要用 Claude Code 来部署，而不是传统的安装脚本或 Docker Compose？
传统部署的痛点：
- 环境差异：每个人的系统环境不同（macOS/Linux/WSL），同样的脚本经常报错
- 依赖地狱：Node.js 版本、容器运行时、权限配置环环相扣，一步出错全盘皆输
- 黑盒问题：脚本执行失败时，普通用户根本不知道哪里出了问题
- 配置繁琐：需要手动编辑多个配置文件，格式稍有不对就启动失败
AI 部署的优势：
- 智能适配：Claude 能根据你的具体环境动态调整安装策略
- 实时诊断：遇到问题时可以交互式询问，而不是直接崩溃退出
- 自然语言配置：用大白话告诉 AI 你想要什么，它帮你翻译成正确的配置
- 渐进式引导：每一步都有确认和解释，你知道系统在做什么
安装命令：
git clone https://github.com/qwibitai/nanoclaw.git
cd nanoclaw
claude
进入 Claude Code 后，只需运行：
/setup
Claude Code 会自动处理：依赖安装、身份验证、容器设置，服务配置。整个过程无需手动编辑配置文件。
2.2 运行方式
claude
启动后，通过 WhatsApp 发送消息与它对话（使用触发词 @Andy）。
2.3 系统要求
- 操作系统: macOS 或 Linux (Windows 可通过 WSL2)
- Node.js: 20+ (推荐 22)
- Claude Code: 必须安装
- 容器运行时: Apple Container (macOS) 或 Docker (macOS/Linux)
三、Setup 模块详解
Setup 是 NanoClaw 的安装向导核心，位于 .claude/skills/setup/ 目录下，包含 15 个精心设计的 TypeScript 文件。
3.1 核心文件功能
| 文件 | 职责 |
|---|---|
index.ts |
入口文件，负责调度各个步骤 |
environment.ts |
检查环境：OS、Node、Docker/Apple Container、已有配置 |
platform.ts |
平台检测：WSL、headless、命令是否存在 |
container.ts |
构建容器镜像并测试运行 |
whatsapp-auth.ts |
WhatsApp 认证流程（QR 码或配对码） |
groups.ts |
初始化群组 |
register.ts |
注册服务 |
mounts.ts |
配置挂载白名单 |
service.ts |
配置开机启动（launchd/systemd） |
verify.ts |
验证安装 |
3.2 安装步骤顺序
运行 /setup 时，Claude Code 按顺序执行以下步骤：
environment → container → whatsapp-auth → groups → register → mounts → service → verify
3.3 关键部署步骤详解
整个安装过程被分解为多个独立的检查和配置环节。Claude Code 会逐步引导你完成每一步，确保系统环境满足要求。
3.3.1 容器环境准备
这一步负责准备 AI Agent 的运行环境。NanoClaw 依赖容器技术来实现安全隔离，所以需要确保 Docker 或 Apple Container 已正确安装并可用。
Claude Code 会自动检测你系统中安装了什么容器运行时，帮你处理镜像拉取和配置。如果遇到网络问题导致镜像下载失败，它会建议切换镜像源或自动重试。同时它会检查磁盘空间是否充足，避免构建过程中因为空间不足而失败。
3.3.2 WhatsApp 认证
这是 NanoClaw 与用户建立连接的关键步骤。通过 WhatsApp，你可以随时随地与你的 AI 助手对话。
Claude Code 会引导你完成 WhatsApp 账号的认证，支持 QR 码扫描和配对码两种方式。它会实时显示认证状态，如果遇到问题会给出具体的原因分析和解决方案。整个过程就像有一个经验丰富的工程师在旁边指导你一样。
3.3.3 挂载目录配置
这是 NanoClaw 安全模型的核心设计。每个 AI Agent 都运行在独立的容器中，只能访问你明确授权的目录。这个设计确保了即使 AI 出了问题，也不会影响到系统的其他部分。
在这一步，Claude Code 会了解你的使用场景——比如你想让它访问哪些项目文件夹、文档目录等，然后帮你配置最小必要的访问权限。它不会一股脑地把整个硬盘都挂载进去，而是根据实际需求来设置。
3.3.4 服务注册与开机启动
配置好之后，还需要让 NanoClaw 能够在系统启动时自动运行，不需要每次手动启动。
在 macOS 上，这需要创建一个 launchd 服务配置；在 Linux 上则是 systemd。Claude Code 会根据你的操作系统自动生成正确的配置文件，处理各种权限问题，确保服务能够正常注册并开机自启。
3.3.5 环境检查汇总
| 检查项 | 说明 | 作用 |
|---|---|---|
| PLATFORM | macOS / Linux / WSL | 识别操作系统，选择对应的安装逻辑 |
| CONTAINER_RUNTIME | Docker / Apple Container | 检测可用的容器运行时 |
| NODE_VERSION | 要求 20+ | 确保 Node.js 版本满足要求 |
| ENV_FILE | .env 是否存在 | 管理敏感配置和凭证 |
| AUTH_STORE | 认证凭证目录 | 存储 WhatsApp 等服务的认证信息 |
| REGISTERED_GROUPS | 已注册群组 | 管理对话群组及其配置 |
| IS_HEADLESS | 是否无显示器 | 在服务器环境下跳过需要显示器的步骤 |
| SERVICE_MANAGER | launchd / systemd | 注册开机自启动服务 |
四、核心架构设计
4.1 单一进程架构
NanoClaw 的核心文件结构极其精简：
src/
├── index.ts # 编排器：状态、消息循环、Agent 调用
├── channels/
│ └── whatsapp.ts # WhatsApp 连接、认证、收发
├── ipc.ts # IPC watcher 和任务处理
├── router.ts # 消息格式化和出站路由
├── config.ts # 触发模式、路径、间隔
├── container-runner.ts # 生成带挂载的 Agent 容器
├── task-scheduler.ts # 运行定时任务
└── db.ts # SQLite 操作
这种设计的优势在于：所有逻辑都在眼前，没有隐藏的魔法。
4.2 容器隔离安全模型
这是 NanoClaw 最核心的安全机制。即使 Agent 通过 Bash 访问系统，所有命令都在容器内执行，无法触及宿主机上未被挂载的文件。
4.3 Agent Swarms（智能体集群）
NanoClaw 是首个支持 Agent Swarms 的 AI 助手，可轻松组建智能体团队，在聊天中高效协作。
重要前提：NanoClaw 的 Agent Swarms 不是独立实现的功能，而是基于 Anthropic Claude Agent SDK 的 Agent Teams 能力，加上 NanoClaw 特有的容器隔离和多通道支持。
工作流程：
用户请求 → NanoClaw (消息入口) → Container Runner (创建隔离容器) → Claude Agent SDK (处理 Agent Teams) → 多个 Subagents 并行协作
关键限制：
- Teammates 不能创建自己的 teams 或 teammates（不可递归）
- 需要设置环境变量
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1启用
| 特性 | Claude Code Agent Teams | NanoClaw Swarms |
|---|---|---|
| 隔离级别 | 进程级 | 容器级（更强） |
| 持久化 | 内存 | SQLite + 文件系统 |
| 消息通道 | 终端 | WhatsApp/Telegram |
| Telegram 支持 | 单身份 | 多 Bot 独立身份 |
| 定时任务 | 不支持 | task-scheduler.ts |
| 记忆存储 | 会话级 | conversations/ 长期保存 |
4.4 计划任务支持
通过 task-scheduler.ts 管理周期性自动执行任务，适合定时报告、数据同步等场景。
五、Skills 技能系统
这里需要澄清一个重要概念：NanoClaw 的 Skills 是提供给 Claude Code 使用的，而不是 NanoClaw 本身的功能模块。
要理解这一点，关键在于区分 NanoClaw 的两层架构：
- NanoClaw 运行时层：负责消息接收、容器管理、定时任务、持久化存储
- Claude Code 执行层：负责理解用户意图、调用工具、执行 Skills
换句话说，NanoClaw 搭建了一个"舞台"，但真正在"舞台上表演"的是 Claude Code。Skills 就是 Claude Code 的"剧本"——告诉它遇到什么情况该怎么处理。
放在项目 .claude/skills/ 目录下的 Skills，NanoClaw 和 Claude Code 都能用。Claude Code 在容器中执行时，会自动加载这些 Skills 来扩展自己的能力。
5.2 NanoClaw 内置的 Claude Code Skills
| Skill | 功能 | 使用场景 |
|---|---|---|
/setup |
首次安装、认证、服务配置 | 新用户初始化 |
/customize |
添加渠道、集成、改变行为 | 个性化定制 |
/debug |
容器问题、日志、故障排查 | 运维排错 |
/update |
拉取上游更新、合并自定义、运行迁移 | 版本升级 |
5.3 “自由生长"的设计理念
NanoClaw 采用一种独特的协作模式：
- Claude Code 负责开发运维：安装、调试、更新都由 AI 自动完成
- NanoClaw 核心保持极简：只做消息路由、容器管理、持久化存储
- 用户与 AI 协作完成任务：你想要什么功能，直接告诉 Claude，它帮你实现
这意味着 NanoClaw 不是一个"成品软件”，而是一个可进化的生命体。它的能力边界不是由开发者预设的，而是由用户和 AI 共同探索出来的。
六、NanoClaw 的内置能力
除了依赖 Claude Code 的 Skills，NanoClaw 核心本身也提供了一些基础能力。
6.1 内置工具（Tools）
| 工具 | 功能 | 对应源文件 |
|---|---|---|
| Bash | 在容器中执行 shell 命令 | container-runner.ts |
| Read/Write/Edit | 文件系统操作（受挂载白名单限制） | container-runner.ts |
| IPC Watcher | 监听任务文件变化，触发 Agent 执行 | ipc.ts |
| Database | SQLite 读写操作 | db.ts |
| Message Router | 发送消息到 WhatsApp/Telegram | router.ts + channels/*.ts |
6.2 与 OpenClaw 能力的对比
| OpenClaw 能力 | NanoClaw 处理方式 | 说明 |
|---|---|---|
| Memory 记忆系统 | ❌ 核心不包含 | 需要用户通过 Skills 自行实现 |
| Heartbeat 心跳任务 | ⚠️ 部分支持 | task-scheduler.ts 支持定时任务 |
| Cron 定时任务 | ✅ 原生支持 | task-scheduler.ts |
| Multi-channel 多渠道 | ⚠️ 多渠道 | WhatsApp/Telegram/Discord/Slack/Gmail |
| RAG 知识库 | ❌ 不包含 | 需要用户自行集成 |
| Self-improvement 自我改进 | ❌ 不包含 | NanoClaw 保持极简 |
6.4 设计哲学：最小公约数
NanoClaw 刻意不内置太多高级功能，原因如下：
- 保持核心精简：每个内置功能都是维护负担
- 避免预设需求：Peter 需要的 ≠ 你需要的
- 鼓励定制化：用 Skills 构建你自己的 “OpenClaw”
- AI 原生思维：复杂功能交给 Claude Code 动态实现
七、与 OpenClaw 生态的兼容性
7.1 兼容性分析
| 维度 | 兼容程度 | 说明 |
|---|---|---|
| Skills API | ⚠️ 部分兼容 | 基础工具兼容，高级功能依赖 OpenClaw 运行时 |
| 配置文件格式 | ❌ 不兼容 | NanoClaw 无配置文件 |
| 数据库 Schema | ❌ 不兼容 | PostgreSQL vs SQLite |
| 渠道适配器 | ❌ 不兼容 | 架构完全不同 |
| Memory 存储 | ❌ 不兼容 | 无法直接迁移 |
7.5 总结
NanoClaw 不是 OpenClaw 的 drop-in 替代品。它的设计哲学是：
“给我一个最小可用的核心，剩下的我自己来。”
如果你已经深度依赖 OpenClaw 的生态（几十个 Skills、复杂的记忆系统、多渠道路由），迁移到 NanoClaw 需要一定工作量。
但如果你想要：
- 一个自己能完全理解的代码库
- 没有黑盒魔法，所有逻辑清晰可见
- 从零开始构建真正属于自己的 AI 助手
那么 NanoClaw 是一个更好的起点。
八、总结
NanoClaw 是对 OpenClaw 的一次成功的精简重构，其核心价值体现在三个方面：
- 安全性：通过容器隔离实现 OS 级安全，而非应用级权限检查。这是架构层面的根本差异。
- 可理解性：代码量小，8 分钟即可理解全貌。没有复杂的抽象层，每个功能都清晰可见。
- 可定制性：直接修改代码即可改变行为，无需在几十个配置文件中寻找正确的参数。
此外，AI 原生的设计理念让安装和使用变得异常简单——自然语言交互即可完成所有操作。
如果你是一位追求简洁，安全、可控的个人用户，NanoClaw 值得一试。
参考资料
- GitHub: https://github.com/qwibitai/nanoclaw
- 官网: https://nanoclaw.dev
- Discord: https://discord.gg/VDdww8qS42