NanoClaw 深度解析：500 行 TypeScript 打造的极简 AI Agent 框架，从源码到实战全面拆解

莫潇羽@无忆研习社（www.wuyi.wiki）原创内容，转载请注明出处。本文将从架构原理、源码剖析、安全模型、部署实战等多个维度，带你彻底读懂这个仅用约 500 行核心代码就复刻了 OpenClaw 核心能力的开源项目。

一、NanoClaw 为何引爆开发者圈

2026 年开年，AI Agent 赛道持续火热。OpenClaw（前身为 Clawdbot，后改名 Moltbot，最终定名 OpenClaw）作为一款开源的个人 AI 助手，凭借其强大的多平台集成能力，在 GitHub 上迅速积累了超过 16 万颗 Star，成为开源社区的现象级项目。它支持十几种通信平台，拥有丰富的功能模块，可以帮你管理日程、处理邮件、搜索信息、自动化各种工作流。然而，伴随功能不断膨胀，OpenClaw 的代码复杂度也水涨船高——52 个以上的模块、45 个以上的第三方依赖、8 个分散的配置管理文件、总代码量超过 43 万行——这让很多开发者在感叹其强大的同时也望而却步。有开发者形容 OpenClaw 的启动速度"就像在一台老台式机上打开 Photoshop"，即便是在性能强劲的 M2 Mac Mini 上也感觉明显迟缓。

就在这个背景下，一位名叫 Gavriel 的开发者在 GitHub 上发布了 NanoClaw，它的定位非常明确：用最少的代码，实现 OpenClaw 最核心的功能。这个项目上线仅数天便在 GitHub 收获了数千颗 Star，在 Hacker News 上也引发了热烈讨论。开发者社区对它的评价集中在几个关键词上：极简、安全、可审计。

NanoClaw 到底凭什么在短时间内吸引了如此多的关注？答案其实很简单——它把一个看似复杂的 AI Agent 系统，浓缩到了你可以在 8 分钟内完全读懂的程度。整个项目的核心代码大约只有 500 行 TypeScript，源码文件总共就四五个，没有微服务架构的任何影子，没有消息队列中间件，没有层层叠叠的抽象封装。它采用了操作系统级别的容器隔离来保障安全，让每个聊天群组的 AI Agent 都运行在独立的 Linux 虚拟机中，而不是依赖应用层的权限检查来防止越界。更关键的是，它基于 Claude Agent SDK 构建，这意味着你在容器中运行的就是 Claude Code 本身——当前被广泛认为是体验最优秀的 AI 编程工具之一。

这种极致的简洁不是偷工减料，而是一种深思熟虑的架构选择。NanoClaw 的作者认为，大型 Agent 框架中大部分代码的存在是为了应对可能永远不会出现的边缘用例——这些"以防万一"的代码反而成了理解和维护系统的最大障碍。把它们全部砍掉之后，你会发现 AI Agent 的核心逻辑其实用几百行代码就能表达清楚。

对于想要理解 AI Agent 框架本质运作机制的开发者来说，NanoClaw 就像一本精炼的教科书，每一行代码都在做有意义的事情，没有任何噪音。而对于想要搭建自己私有 AI 助手的技术爱好者来说，它是一个真正可以拿来就用、改了就懂的起点——你完全有能力掌控运行在你机器上的每一行代码。接下来，莫潇羽将带你从底层原理到上手实战，把 NanoClaw 的方方面面彻底拆解开来。

二、从 OpenClaw 到 NanoClaw：一场极简主义的反思

要理解 NanoClaw 为什么会出现，我们得先聊聊 OpenClaw 的发展历程和它所暴露出来的一些深层问题。

OpenClaw 最初以"Clawdbot"的名字发布于 2025 年底，由软件工程师 Peter Steinberger 开发。它是一款运行在用户自有设备上的开源 AI 助手，支持 WhatsApp、Telegram、Slack、Discord、Signal、iMessage、Microsoft Teams、Google Chat 等十余种通信平台，并且可以集成 Claude、GPT 等多种大语言模型作为智能核心。你可以通过这些平台向它发消息，让它帮你管理日程、处理邮件、搜索信息、操控智能家居、自动化各种工作流。项目发布后不到两个月就突破了 10 万 Star，成为 GitHub 历史上增速最快的开源项目之一。后来因为商标原因先后改名为 Moltbot 和 OpenClaw，但核心功能和架构一直在持续迭代。

OpenClaw 的愿景非常宏大：支持任何操作系统、接入任何平台、做最全面的个人 AI 助手。它确实做到了——但代价是代码量急剧膨胀。根据社区的统计数据，OpenClaw 的总代码量超过了 43 万行，拥有 52 个以上的功能模块、45 个以上的第三方依赖包和 15 种通信渠道的抽象适配层。对于一个想要完全了解自己所运行软件的开发者来说，这几乎是不可能完成的审计任务——你怎么可能在合理的时间内逐行审计 43 万行代码？有开发者反映，OpenClaw 的启动速度明显迟缓，"就像在一台老台式机上打开大型软件"，即便是在性能强劲的 Mac 硬件上也能感受到明显的延迟。

更让人担忧的是安全层面。OpenClaw 的安全模型是应用级的——所有 Agent 代码运行在同一个 Node.js 进程中，共享同一块内存空间。安全防护依赖白名单（allowlists）和配对码（pairing codes）这样的应用层机制，而不是操作系统提供的硬隔离。这意味着一旦 Agent 代码中存在安全漏洞，攻击面可能波及整个系统。而就在近期，安全研究人员在 OpenClaw 的公共技能市场 ClawHub 中发现了数百个恶意 Skill，这些恶意模块会在用户不知情的情况下窃取数据——这一事件让很多开发者对大型 Agent 框架的安全性产生了更深的疑虑。

NanoClaw 的作者 Gavriel 在项目的 README 中直接写出了他最核心的担忧："我没办法安心运行一个我自己都看不懂的软件，尤其是它还能访问我生活中的各种数据。"这句话精准地击中了很多技术人的痛点。我们在部署 AI Agent 时，本质上是在赋予一段程序相当大的操作权限——它可以读写你的文件、执行系统命令、发送消息、访问你的邮箱和社交账号。如果你无法审计它的每一行代码，那信任从何而来？

NanoClaw 给出的回应方式不是在 OpenClaw 的基础上修修补补，而是从零开始重新思考一个根本问题：一个 AI Agent 系统最本质的组成部分是什么？确定了答案之后，只保留这些本质的部分，把其他一切都坚决砍掉。下面这张对比表可以帮你直观感受两者在设计理念上的根本差异：

NanoClaw 并不是要取代 OpenClaw——它们面向的是不同的用户群体和不同的需求场景。如果你需要同时连接十几个通信平台、使用丰富的社区技能生态，OpenClaw 仍然是更好的选择。但如果你更看重代码的可审计性、安全的透明度、以及对系统行为的完全掌控，NanoClaw 提供了一条截然不同的路径。它更像是在技术社区抛出了一个值得深思的命题：当 AI 已经能够读懂和修改代码时，Agent 框架真的还需要如此庞大吗？在莫潇羽看来，这个问题的答案取决于你更看重功能的全面性，还是系统的可理解性和安全透明度。

三、NanoClaw 的核心设计哲学

NanoClaw 的独特之处不仅在于代码量少，更在于它背后贯穿始终的一套设计哲学。理解这些理念，是读懂整个项目的前提。（莫潇羽@无忆研习社 整理）

小到可以被完全理解。 这是 NanoClaw 最核心的追求。整个项目只有一个 Node.js 进程、寥寥数个源码文件，没有微服务架构，没有消息队列中间件，也没有任何多余的抽象层。作者的原话是："让 Claude Code 带你走读一遍代码就够了。"这个设计原则意味着，任何一个有基础 TypeScript 经验的开发者，都可以在十分钟以内读完整个代码库，并且理解每一个模块在做什么。

安全来自隔离而非权限检查。 传统的 AI Agent 框架通常在应用层实现安全——比如设置白名单、使用配对码验证身份、在代码里添加各种权限校验。NanoClaw 走了一条截然不同的路：它让每个 Agent 运行在独立的 Linux 容器中，Agent 只能看到被显式挂载进去的目录。即便 Agent 在容器内执行了 Bash 命令，这些命令也只能影响容器内部的文件系统，不会波及宿主机。这就好比你在一间密封的实验室里做实验——即使实验失败了，影响也被限制在那间实验室里。

为一个用户而生。 NanoClaw 不是一个通用框架，不追求适配所有人的需求。它是一个"工作中的软件"——作者根据自己的实际需要写出来的工具。你可以 Fork 它，然后让 Claude Code 根据你的需求去修改源码。这个理念和传统的"写配置文件来定制行为"完全不同。在 NanoClaw 的世界里，如果你想改变 AI 的行为，你不需要去翻什么 config.json，直接让 AI 帮你改源码就好。

定制即代码。 这是上面那条理念的延伸。NanoClaw 没有任何配置文件蔓延的问题，因为它根本就没有传统意义上的配置文件。想要不同的触发词？改代码。想要不同的响应风格？改代码。想要接入新的通信渠道？改代码。代码库足够小，这种修改是安全的。这里有一个关键的洞察：在传统软件中，配置文件的存在是为了让用户不需要懂代码就能修改软件行为。但在 NanoClaw 的场景中，修改代码的不是用户本人，而是 Claude Code 这个 AI。AI 修改代码和人类读取配置文件一样自然，甚至更灵活——配置文件的 Schema 限定了你能改什么，而直接修改代码则没有任何限制。

AI 原生的工作流。 没有安装向导——Claude Code 来引导你完成环境搭建。没有监控面板——直接问 Claude 现在系统什么状态。没有调试工具——向 Claude 描述问题，让它帮你修复。没有使用手册——让 Claude Code 给你讲解代码的任何部分。NanoClaw 把"与 AI 对话"作为和系统交互的主要方式，这在传统软件工程中几乎是不可想象的，但在 AI 原生的语境下却显得自然而然。这种设计也意味着 NanoClaw 的"用户界面"实际上就是 WhatsApp 和终端中的 Claude Code——前者用于日常交互，后者用于开发和管理。

最好的运行环境，最好的模型。 NanoClaw 基于 Claude Agent SDK 构建，这意味着它在容器中运行的就是 Claude Code——Anthropic 官方出品的 AI 编程工具。作者认为，"运行环境"（harness）的质量至关重要：一个差劲的运行环境会让聪明的模型显得笨拙，而一个好的运行环境则能赋予模型超能力。Claude Code 目前被广泛认为是体验最好的 AI 编程工具之一，NanoClaw 直接站在了这个巨人的肩膀上。

四、项目架构与源码全景图

NanoClaw 的整体架构可以用一句话概括：一个 Node.js 进程，通过轮询 SQLite 数据库来检测新消息，然后把消息路由到独立的 Linux 容器中处理。

用流程图来表示就是：

WhatsApp (Baileys) --> SQLite --> 轮询循环 --> 容器 (Claude Agent SDK) --> 响应

这条链路简洁到令人惊叹。没有消息队列，没有后台守护进程，没有分布式架构的任何痕迹。所有的通信通过文件系统上的 IPC（进程间通信）完成。

我们来看一下项目的完整目录结构：

nanoclaw/
├── src/                          # 宿主进程源代码
│   ├── index.ts                  # 主编排器（约 700 行）
│   ├── container-runner.ts       # 容器启动逻辑
│   ├── task-scheduler.ts         # 定时任务执行器
│   ├── db.ts                     # SQLite 数据库操作
│   ├── config.ts                 # 配置常量
│   └── types.ts                  # TypeScript 类型定义
├── container/                    # Agent 容器镜像
│   ├── Dockerfile                # 容器构建文件
│   ├── agent-runner.js           # Claude SDK 执行器
│   └── ipc-mcp.ts                # MCP 工具接口
├── groups/{group_name}/          # 每个群组的独立工作区
│   ├── CLAUDE.md                 # 该群组的 AI 记忆上下文
│   └── logs/                     # 执行日志
├── data/
│   ├── messages.db               # SQLite 消息数据库
│   ├── sessions/{group}/         # Agent SDK 会话状态
│   ├── ipc/{group}/              # IPC 消息队列
│   ├── registered_groups.json    # 已注册群组列表
│   └── state.json                # 最后处理消息的时间戳
├── .claude/skills/               # Claude Code 技能文件
├── CLAUDE.md                     # 项目级 AI 记忆上下文
├── package.json                  # npm 依赖配置
└── tsconfig.json                 # TypeScript 编译配置

从这个目录结构中可以看出几个重要的设计决策。首先，src/ 目录下只有 5-6 个文件，这就是整个宿主进程的全部逻辑。其次，container/ 目录下的文件定义了 Agent 在容器内的运行方式。最后，groups/ 目录实现了每个聊天群组的物理隔离——每个群组拥有自己独立的工作空间和 AI 记忆。

NanoClaw 使用 Baileys 库来连接 WhatsApp。Baileys 是一个由社区维护的 WhatsApp Web API 的 TypeScript 实现，它通过逆向工程 WhatsApp Web 的 WebSocket 协议，让 Node.js 应用能够直接与 WhatsApp 服务器通信，收发文本消息、图片、文件等多种类型的内容，而不需要申请 WhatsApp 官方的 Business API（后者需要企业认证且有较多限制）。需要注意的是，使用 Baileys 这类非官方库存在一定的合规风险，WhatsApp 的服务条款对非官方客户端的态度并不明确，这一点在实际使用时需要自行评估。

消息被接收后存入 SQLite 数据库，然后由主进程的轮询循环（默认每 2 秒一次）检测到新消息并触发后续处理流程。这个轮询频率对于个人助手场景完全足够，同时也避免了引入 WebSocket 长连接或消息队列等额外的复杂性。

处理流程的核心是容器启动：主进程通过 container-runner.ts 为目标群组创建（或复用）一个独立的 Linux 容器，将该群组的工作目录、会话状态和 IPC 通信目录挂载进去，然后在容器内启动 Claude Agent SDK 来处理消息。Agent 在容器中拥有搜索网页、浏览网页内容、读写文件、执行 Bash 命令等多种能力——但所有这些操作都限定在容器的隔离边界之内。处理完成后，Agent 的响应通过文件系统上的 IPC 机制传回主进程，再由主进程通过 Baileys 发送到 WhatsApp。整个链路清晰到你可以用一根手指在架构图上从头画到尾。

五、核心源码文件逐一拆解

现在让我们深入到具体的源码文件中，看看每个文件都在做什么。这也是 NanoClaw 最吸引人的地方——代码量小到你真的可以逐行阅读。

5.1 index.ts —— 全局的"大脑"

index.ts 是整个 NanoClaw 的主入口文件，大约 700 行代码，承担了所有核心编排逻辑。如果要用一个比喻来形容，它就是整个系统的"大脑"和"调度中心"——所有外部输入从这里进入，所有内部协调在这里完成，所有最终输出从这里发出。

它的第一个职责是建立和维护 WhatsApp 连接。NanoClaw 使用 Baileys 这个开源库来实现与 WhatsApp 的通信。Baileys 是一个纯 TypeScript 实现的 WhatsApp Web API 客户端，它模拟了 WhatsApp Web 的通信协议，让 Node.js 应用能够直接收发 WhatsApp 消息，而不需要依赖 WhatsApp 官方的 Business API。当你第一次运行 NanoClaw 时，index.ts 会在终端显示一个 QR 码，你需要打开手机上的 WhatsApp，进入"已连接的设备"设置页面，扫描这个 QR 码来完成配对——这和你在电脑上使用 WhatsApp Web 的登录方式完全一样。配对完成后，后续启动不需要再次扫码，认证信息会被持久化存储在本地。

连接建立后，所有收到的 WhatsApp 消息会被实时写入 SQLite 数据库。这里有一个重要的设计细节：消息的接收和处理是解耦的。接收消息的逻辑只负责把消息存到数据库，而处理消息的逻辑由一个独立的轮询循环来驱动。主进程每隔 2 秒轮询一次数据库，检查是否有新的未处理消息。这种朴素的轮询机制在高并发场景下可能不够高效，但对于个人助手的使用场景来说完全够用——毕竟你不会每秒给自己的 AI 助手发几百条消息。这种解耦设计还带来一个好处：即使容器启动或处理过程出现短暂故障，消息也不会丢失，因为它们已经安全地存储在数据库中了。

当检测到新消息时，index.ts 会根据消息来源的群组 ID 进行路由决策。它会判断这条消息属于哪个群组、这个群组是否已经注册、当前是否已有容器在处理该群组的消息。如果一切就绪，它就调用 container-runner.ts 来启动或复用一个容器，把该群组的工作目录和相关上下文挂载进去，然后等待容器内的 Agent 处理完成并通过 IPC 返回结果。

index.ts 还管理着一个特殊的"主频道"概念——你的 WhatsApp 自聊天（给自己发消息的功能）。通过主频道，你可以执行全局管理操作，比如查看所有群组的定时任务列表、暂停或恢复某个任务、让 Agent 加入新的群组、查看系统运行状态等。主频道拥有完整的管理权限，相当于系统的控制台。而其他群组的 Agent 则被完全隔离在各自的容器中，既不能访问其他群组的数据，也不能执行管理操作。

5.2 container-runner.ts —— 容器的启动器

这个文件负责容器的全生命周期管理，是 NanoClaw 安全模型的核心实现所在。当 index.ts 检测到需要处理某个群组的消息时，它会调用 container-runner.ts 来完成容器的创建和启动。

具体来说，container-runner.ts 的工作流程大致如下。首先，它会检查 Agent 容器镜像是否已经构建好了。NanoClaw 的容器镜像定义在 container/Dockerfile 中，如果镜像还不存在，系统会自动触发构建流程。其次，它会根据当前要处理的群组 ID 来确定需要挂载哪些目录到容器中。通常包括该群组的工作区（groups/{group_name}/）、会话状态（data/sessions/{group}/）以及 IPC 通信目录（data/ipc/{group}/）。然后，它会参考挂载白名单来验证这些路径的合法性——确保不会把宿主机上的敏感目录（比如 SSH 密钥、云服务凭据等）意外暴露给容器。最后，它启动容器并传入必要的环境变量，其中最重要的是 Anthropic 的认证凭据，让容器内的 Claude Agent SDK 能够正常调用 AI 模型。

NanoClaw 支持两种容器运行时。在 macOS 上推荐使用 Apple Container——这是苹果在 2025 年开源的一款基于轻量级虚拟机的容器化工具，使用 Swift 编写，针对 Apple Silicon 进行了专门优化。和 Docker 不同的是，Apple Container 中的每个容器实际上运行在一个独立的 Linux 轻量级虚拟机中，而不是共享宿主机内核的命名空间隔离。这种基于虚拟机的隔离方式提供了比传统 Docker 容器更强的安全边界——要突破这个隔离需要利用虚拟化层面的漏洞，难度远高于逃逸 Docker 的命名空间隔离。在 Linux 上则使用 Docker 作为容器运行时，虽然隔离强度不如 Apple Container 的虚拟机方案，但对于大多数场景来说也已经足够。

容器内运行的是一个预构建的 Docker 镜像，这个镜像基于 node:22-slim，预装了 Chromium 浏览器（用于网页访问和内容抓取功能）、agent-browser（用于浏览器自动化）以及 @anthropic-ai/claude-code（Claude Agent SDK 的运行时）。从 Dockerfile 中可以清晰地看到这些依赖的安装过程：

FROM node:22-slim

# 安装 Chromium 及其系统依赖
RUN apt-get update && apt-get install -y \
    chromium \
    fonts-liberation \
    fonts-noto-color-emoji \
    curl \
    git \
    && rm -rf /var/lib/apt/lists/*

# 设置 Chromium 路径供 agent-browser 使用
ENV AGENT_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium
ENV PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/usr/bin/chromium

# 全局安装浏览器自动化工具和 Claude Agent SDK
RUN npm install -g agent-browser @anthropic-ai/claude-code

这个 Dockerfile 非常精简，总共只做了三件事：安装浏览器环境、配置环境变量、安装运行时依赖。没有复杂的多阶段构建，没有各种优化层的缓存策略，一目了然。

5.3 task-scheduler.ts —— 定时任务引擎

这个文件实现了 NanoClaw 的定时任务功能，是让你的 AI 助手从"被动响应"升级为"主动工作"的关键组件。它支持三种灵活的调度类型：cron 类型使用标准的 cron 表达式来定义触发时间，比如 "0 9 * * 1-5" 表示每个工作日早上 9 点执行；interval 类型使用固定的时间间隔，以毫秒为单位，比如 3600000 表示每小时执行一次；once 类型用于一次性任务，指定一个 ISO 格式的时间戳（如 "2026-03-01T09:00:00Z"），任务在该时间点执行一次后就自动过期。

定时任务的元数据存储在 SQLite 数据库的 scheduled_tasks 表中，包括任务名称、触发条件、关联的群组 ID、要执行的 Prompt 等信息。当一个定时任务到达触发时间时，task-scheduler.ts 会像处理普通用户消息一样，通过 container-runner.ts 启动一个独立的容器来执行任务。Agent 在容器内可以完成各种操作——搜索网页、读取文件、执行脚本——最终通过 IPC 机制把执行结果发送回你的 WhatsApp。

值得注意的是，定时任务也享受和普通消息处理一样的容器隔离保护。每个定时任务运行在自己的容器沙箱中，不会相互干扰，也不会影响宿主机的安全。

5.4 db.ts —— 数据持久层

db.ts 封装了所有与 SQLite 数据库的交互逻辑。NanoClaw 使用 SQLite 作为唯一的持久化存储方案——消息历史、定时任务配置、运行状态信息，全部存放在一个名为 messages.db 的数据库文件中。

选择 SQLite 而不是 MySQL、PostgreSQL 或者 Redis 这样的"更高级"的数据库系统，完全符合 NanoClaw 的极简哲学。SQLite 是一个嵌入式数据库，不需要独立的数据库服务进程，数据就存在一个普通文件里，零配置、零运维。对于个人助手这种读写量不大的场景来说，SQLite 的性能绰绰有余，同时大大降低了系统的部署和维护复杂度。

db.ts 中的代码结构也非常清晰。它导出了一组简洁的函数来完成增删改查操作：插入新消息、查询未处理的消息、更新消息处理状态、管理定时任务记录等。NanoClaw 还使用了 Zod 库在运行时对从数据库读取的数据进行校验，确保数据结构的一致性，这是一个小而精妙的工程实践。

5.5 ipc-mcp.ts —— Agent 与宿主的桥梁

这个文件运行在容器内部，实现了一个 MCP（Model Context Protocol）服务器，是容器内的 Agent 与外部世界通信的唯一桥梁。MCP 是 Anthropic 推动的一个开放标准协议，专门用于定义 AI 模型与外部工具和服务之间的通信接口。

在 NanoClaw 中，ipc-mcp.ts 提供了几个关键的工具（tool），让容器内的 Claude Agent 能够：向指定的 WhatsApp 群组或个人发送消息、注册新的群组到 NanoClaw 的管理列表中、创建和管理定时任务、以及读取群组的 CLAUDE.md 记忆文件来获取上下文信息。

这些工具的通信方式是基于文件系统的 IPC。当 Agent 想要发送一条 WhatsApp 消息时，它通过 MCP 调用 send_message 工具，ipc-mcp.ts 会把这个请求写入 data/ipc/{group}/ 目录下的一个 JSON 文件中。宿主进程的轮询循环在下一个周期检测到这个 IPC 文件后，读取请求内容，通过 Baileys 发送 WhatsApp 消息，然后清理 IPC 文件。

这种"通过文件系统通信"的模式看起来原始，但恰恰是最安全和最可靠的容器间通信方式之一——它不需要打通网络端口，不需要共享内存，Agent 的所有对外操作都必须经过 MCP 工具这个"狭窄的咽喉"，宿主进程可以在这个咽喉处实施任意的过滤和校验逻辑。

六、容器隔离安全模型深度解析

安全性是 NanoClaw 与 OpenClaw 分歧最大的地方。在莫潇羽看来，这也是 NanoClaw 最具技术亮点的设计。

OpenClaw 采用的是典型的应用级安全策略：白名单（allowlists）控制哪些用户可以与 Agent 交互、配对码（pairing codes）验证新用户的身份、所有 Agent 代码在同一个 Node.js 进程中运行并共享内存。这意味着如果 Agent 的代码中存在一个安全漏洞——比如一个注入攻击——攻击者可能获得整个 Node.js 进程的权限，进而影响到宿主机上的所有数据。

NanoClaw 选择了一条根本不同的路径：操作系统级隔离。

每个群组的 Agent 都运行在自己独立的 Linux 容器中。容器只能看到被显式挂载进去的目录——通常只有该群组的工作区和会话数据。Agent 在容器内执行的 Bash 命令，无论多么"危险"，都只能影响容器内部的文件系统。即使 Agent "发疯"了——比如试图删除所有文件——它能删除的也仅仅是容器内的文件，你的宿主机完全不受影响。

NanoClaw 的安全文档中还记录了一些额外的安全机制。首先是挂载白名单：系统维护了一个位于 ~/.config/nanoclaw/mount-allowlist.json 的文件，明确列出了禁止挂载的敏感路径，包括 .ssh、.gnupg、.aws、.env、private_key 等关键凭据文件。其次是容器路径验证，系统会拒绝包含 ..（路径穿越）和绝对路径的挂载请求。此外，还有一个 nonMainReadOnly 选项，可以强制让非主频道的群组只能以只读模式访问挂载的目录。

当然，NanoClaw 的安全模型也不是完美的。作者在安全文档中坦诚地指出了一个已知的限制：Anthropic 的认证凭据需要被挂载进容器中，以便 Claude Code 能够正常认证。这意味着容器内的 Agent 理论上可以通过 Bash 命令或文件操作来发现这些凭据。作者表示他还没找到一种方式让 Claude Code 在不暴露凭据的情况下完成认证——这是一个未来可能改进的方向。

从哲学层面来说，NanoClaw 的安全理念可以概括为一句话："我不信任 Agent，我信任操作系统。"应用层的权限检查再怎么精密，也可能因为代码 Bug 而被绕过——一个忘记校验的 API 端点、一个拼接错误的路径字符串，都可能让精心设计的安全机制形同虚设。但操作系统的容器隔离——尤其是基于虚拟机的 Apple Container——提供的是硬件辅助的隔离边界，要突破这个边界需要利用虚拟化层面或操作系统内核的漏洞，其难度和应用层漏洞完全不在同一个量级。

对于那些想要在自己的日常工作电脑上部署 AI Agent 的人来说，这种安全模型上的差异是至关重要的。在 NanoClaw 的架构下，你终于可以放心地让 AI 在你的电脑上执行代码、运行脚本、访问文件，而不需要时刻担心它会不会"失控"波及你的个人数据。Agent 的所有操作都被限制在一个独立的沙箱中，即使最坏的情况发生，影响范围也是可以预测和控制的。

七、Skill 系统：一种革命性的扩展思路

NanoClaw 的 Skill 系统可能是整个项目中最具创新性的设计。（莫潇羽@无忆研习社）

传统开源项目的贡献流程通常是这样的：你发现项目缺少某个功能，于是提交一个 Pull Request，把新功能的代码合并到主分支。时间久了，主分支就会变得越来越臃肿，充满了 90% 用户都不需要的功能模块。这是几乎所有大型开源项目都面临的问题——功能蔓延（feature creep）。

NanoClaw 提出了一个巧妙的解决方案：不要添加功能，添加技能（Skill）。

什么是 Skill？它本质上是一个 Markdown 文件（SKILL.md），放在 .claude/skills/ 目录下。这个文件里写的不是代码，而是一份"教学指南"——教 Claude Code 如何将当前的 NanoClaw 代码库改造成支持某个新功能的版本。

我们用一个具体的例子来理解。假设你想让 NanoClaw 支持 Telegram 而不是 WhatsApp。

在传统的开源项目中，你需要提交几十个文件，引入 Telegram SDK 的依赖，修改核心路由逻辑，添加 Telegram 的消息解析代码，更新配置文件的 schema……所有用户在更新项目后都会获得这些额外的代码，即使他们根本不用 Telegram。

在 NanoClaw 中，你只需要提交一个 .claude/skills/add-telegram/SKILL.md 文件。这个文件的内容大致是这样的结构：

# Add Telegram Support

## Overview
This skill transforms NanoClaw to use Telegram instead of (or alongside) WhatsApp.

## Steps
1. Install the Telegram Bot API dependency
2. Replace the Baileys connection logic in index.ts with Telegram bot polling
3. Update message parsing to handle Telegram message format
4. Modify the IPC tools to support Telegram message sending
...

## User Options
- Replace WhatsApp entirely
- Add Telegram as an additional channel
- Use Telegram as a control channel only

当用户想要添加 Telegram 支持时，只需要在 Claude Code 中运行 /add-telegram 命令。Claude Code 会读取这个 Skill 文件，理解其中的改造步骤，然后直接在用户本地的代码库上进行"即时重构"。改造完成后，用户得到的是一份干净的、专门为 Telegram 定制的代码——而不是一个同时支持 WhatsApp 和 Telegram 但充满条件分支的臃肿系统。

这个设计之所以可行，有两个前提条件。第一，代码库必须足够小，小到 LLM 可以可靠地理解和修改它——500 行核心代码恰好满足这个条件。第二，每个用户最终得到的是自己 Fork 的定制版本，而不是一个试图满足所有人需求的通用版本。

当然，这种模式也有其局限性。当上游仓库推送了安全修复时，你需要手动合并到自己的定制版本中，这可能会产生冲突。不同的 Skill 之间也没有自动的冲突解决机制。你的 Fork 本身就成了你配置的唯一文档。但对于个人项目来说，这些都是可以接受的权衡。

目前社区正在积极开发以下 Skill：

• /add-telegram —— 添加 Telegram 作为通信渠道
• /add-slack —— 添加 Slack 支持
• /add-discord —— 添加 Discord 支持
• /setup-windows —— Windows 下通过 WSL2 + Docker 部署的指南
• /add-clear —— 添加会话上下文压缩功能
• /add-gmail —— 添加 Gmail 集成（已有初步实现）

八、环境准备与安装部署全流程

NanoClaw 的安装过程体现了它"AI 原生"的哲学——你不需要手动配置任何东西，Claude Co