什么是 NanoClaw
在 AI 代理框架日益复杂的今天，NanoClaw 带来了一种截然不同的设计思路。该项目诞生于一个核心观察：现有的大型 AI 框架（如 OpenClaw 的 434,453 行代码）对于个人用户而言过于庞大，难以审计、理解和定制。NanoClaw 采用极简主义架构，整个系统仅由 15 个源文件构成，代码量约 3,900 行，让用户能够在 8 分钟内完全理解整个代码库。
从技术架构层面来看，NanoClaw 是一个运行在单进程 Node.js 环境中的轻量级应用，无需微服务架构或消息代理，核心依赖数量控制在 10 个以内。项目采用 TypeScript 作为主要开发语言（占比 95.6%），构建于 @anthropic-ai/claude-agent-sdk (0.2.29) 之上，通过真实操作系统级容器隔离而非应用级权限检查来保障安全。这种设计使得每个 AI 代理会话都在独立的 Linux 容器中运行，拥有自己的文件系统、IPC 命名空间和进程空间。
在技术生态中，NanoClaw 已获得广泛认可。GitHub 仓库拥有 25.3k+ Stars 和 8.5k+ Forks，获得 57 位贡献者的参与，提交次数超过 424 次。项目被 VentureBeat、Fortune、The New Stack、CNBC 等主流科技媒体追踪报道。开源 MIT 许可证确保用户拥有对代码的完全访问权和修改权。
NanoClaw 的设计理念非常明确：为个人用户提供一个完全可审计、可理解和可定制的 AI 助手。与面向团队的大型框架不同，NanoClaw 从个人使用场景出发，让用户真正掌控自己的 AI 代理，而非被黑盒系统所限制。
- 极简代码库：15 个源文件，约 3,900 行代码，完全可审计
- 真实容器隔离：Linux 容器级安全，而非应用级权限检查
- 完全可理解性：8 分钟理解整个代码库，用户真正掌控 AI 行为
- AI 原生设置：无需配置文件，Claude Code 处理一切配置变更
- 多渠道消息支持：开箱支持 WhatsApp，可扩展 Telegram、Discord 等
NanoClaw 的核心特性
容器隔离架构
NanoClaw 的安全模型建立在真实的操作系统级容器隔离之上。当 AI 代理需要执行 bash 命令或文件操作时，这些操作运行在独立的 Linux 容器内（macOS 使用 Apple Container 或 Docker）。每个容器以非特权用户身份运行（uid 1000），仅能访问明确挂载的目录。容器采用 ephemeral 模式，每次调用都会创建全新环境，执行完毕后自动清理（--rm 参数），确保会话之间不会产生状态污染。
安全边界设计
安全边界的设计体现了纵深防御理念。NanoClaw 在 ~/.config/nanoclaw/mount-allowlist.json 位置维护挂载白名单，这个位置本身永远不会挂载到容器中，代理无法修改白名单配置。默认配置会阻止 .ssh、.gnupg、.aws、.gcloud、.kube、.docker 等敏感路径的挂载请求。系统还实现了符号链接解析逻辑，防止路径遍历攻击，并验证容器内的目标路径合法性。
凭证代理系统
凭证安全是 NanoClaw 架构的亮点设计。真实的 API 凭证永远不会进入容器内部，而是在主机上运行一个 HTTP 凭证代理。当容器内的应用需要调用外部 API 时，主机透明注入认证头，容器收到的是占位符 key，无法发现真实凭证的存在。这种设计从根本上消除了凭证泄露的风险。
分组隔离与 Agent Swarms
NanoClaw 支持多群组隔离运行，每个群组拥有独立的 CLAUDE.md 记忆、隔离的文件系统和容器沙箱。会话数据存储在 data/sessions/{group}/.claude/ 目录下，群组之间无法访问彼此的对话历史。更创新的是，NanoClaw 是首个支持 Agent Swarms 功能的个人 AI 助手，可以通过 /add-parallel 技能启动多个专业代理并行协作，处理复杂的多角度分析任务。
技能系统架构
功能扩展通过技能系统实现，避免主代码库膨胀。技能作为 git 分支管理，用户可以将官方技能分支合并到自己的仓库。技能分为 feature（功能扩展）、utility（工具类）、operational（运维类）、container（容器相关）四种类型。通过 /add-telegram、/add-gmail 等技能，可以快速添加新的消息渠道支持。
- 极简架构：单进程 Node.js，<10 个依赖，无微服务开销
- 真实隔离：OS 级容器隔离，而非脆弱的应用层沙箱
- 完全可审计：3,900 行代码覆盖所有安全边界逻辑
- 灵活扩展：技能系统支持按需添加功能，不影响核心稳定性
- Claude API key 必需：运行需要 Anthropic API 访问权限，产生用量费用
- 容器运行时依赖：需要 Docker 或 Apple Container 环境
- 技术门槛：虽然设置流程简化，仍需熟悉终端和基本命令行操作
NanoClaw 的应用场景
隐私敏感任务处理
对于涉及敏感数据的任务，NanoClaw 提供了本地运行加容器隔离的双重保障。AI 能力与本地执行环境相结合，确保数据不会离开用户的机器。容器无法访问主机上未显式挂载的目录，凭证代理机制防止 API key 泄露，适合处理财务记录、健康信息、商业机密等敏感内容。
可审计的 AI 使用
在需要对 AI 行为负责的场景中，可审计性至关重要。NanoClaw 的 15 个文件、约 3,900 行代码使得全面审查成为可能。安全研究员、合规团队或对 AI 决策有审计要求的行业（如金融、医疗）可以利用这一特性，深入理解 AI 代理在特定场景下的行为逻辑，验证安全边界是否按预期工作。
定时自动化调度
内置调度器支持 cron 表达式、间隔（毫秒级精度）、一次性三种调度类型。典型应用包括每日早间行业资讯简报、周末工作回顾、定期数据监控等任务。调度器采用原子声明机制防止重复执行，轮询间隔为 60 秒，在低资源消耗和及时响应之间取得平衡。
团队协作与家庭共享
分组隔离机制使得 NanoClaw 适合家庭或小团队共享使用场景。家庭组、工作组、项目组各自维护独立的上下文和记忆，互不干扰但可以协同工作。每个组拥有独立的 CLAUDE.md 配置，可以针对不同用途（如个人助理、代码审查、家庭事务）进行专门优化。
自定义扩展开发
借助 Claude Code 的代码生成能力，用户可以用自然语言描述需求，系统直接修改代码库实现功能。这种 AI 原生的开发体验降低了定制门槛，用户无需深入理解框架内部实现，只需表达期望的行为，Claude Code 会负责技术实现。
NanoClaw 特别适合以下用户：注重数据隐私的个人用户、需要完全控制 AI 行为的技术决策者、追求代码可审计性的安全团队、以及希望深入理解 AI 代理运作原理的开发者。如果你偏好开箱即用、无需配置的消费级 AI 产品，可能需要考虑其他选择。
技术架构与生态系统
核心技术栈
NanoClaw 的技术选型追求简洁与实用的平衡。项目以 TypeScript 为主要开发语言（95.6%），少量使用 Python（2.7%）处理特定任务。运行时环境要求 Node.js 20 以上版本，消息存储采用 SQLite（通过 better-sqlite3 实现），测试框架使用 Vitest。以下是 NanoClaw 与 OpenClaw 的架构对比：
| 指标 | NanoClaw | OpenClaw |
|---|---|---|
| 代码行数 | ~3,900 | 434,453 |
| 源文件数 | 15 | 数百个 |
| 依赖数量 | <10 | 70+ |
| 配置文件数 | 0 | 53 |
| 进程模型 | 单进程 | 微服务架构 |
第三方集成能力
NanoClaw 不绑定特定的 AI 模型提供商，支持通过自定义端点接入 Ollama、Together AI、Fireworks 等第三方推理服务。这种灵活性允许高级用户在本地运行开源模型，或根据成本和性能需求选择不同的推理服务提供商。容器运行时的选择同样灵活：macOS 系统支持 Apple Container（针对 Apple 芯片优化，提供更快的启动速度）和 Docker 两种方案，Linux 系统自动使用 Docker。
社区与生态
项目维护者 @gavrielc 通过 Discord 建立了活跃的社区讨论区，GitHub 上 57 位贡献者持续参与代码演进。项目采用标准的开源协作模式：清晰的贡献指南、规范的 changelog 更新、公开的 Issues 和 Pull Requests 流程。技能系统作为生态延伸，鼓励社区成员开发并分享自定义技能，通过 git 分支机制方便用户获取和集成。
快速开始与接入指南
系统要求
在开始安装前，请确认环境满足以下要求：Node.js 20 或更高版本、Claude Code 订阅（需从 claude.ai/download 获取）、以及容器运行时环境（macOS 用户建议 Apple Container 或 Docker Desktop，Linux 用户需要 Docker）。硬件方面需要确保有足够的资源运行容器，建议至少 4GB 可用内存。
安装步骤
NanoClaw 的安装流程设计为 AI 原生体验，无需手动编辑配置文件或运行复杂的命令序列。具体步骤如下：
- 克隆仓库：
git clone https://github.com/qwibitai/nanoclaw - 进入目录并启动 Claude Code：
cd nanoclaw && npx Claude Code - 在 Claude Code 中运行
/setup技能，跟随交互式提示完成配置 - 设置过程会自动处理依赖安装、消息渠道认证、容器运行时配置
- 服务启动后，通过配置的消息渠道发送测试消息验证连接
最佳实践
建议从主群组（Main Group）开始测试和熟悉基本功能，确认运行正常后再逐步添加 Telegram、Gmail 等扩展渠道。定期备份 ~/.config/nanoclaw/ 目录下的配置文件，使用版本控制管理自定义技能分支。监控容器资源使用情况，对于资源受限的环境可以调整容器的内存和 CPU 限制。
常见问题
NanoClaw 与 OpenClaw 在技术架构上有何本质区别？
两者代表了 AI 代理框架设计的两个极端。OpenClaw 采用单体架构，包含数百个源文件、数十个微服务和复杂的依赖关系，适合大型团队协作开发。相比之下，NanoClaw 追求最小化：单进程 Node.js 应用，所有逻辑在约 3,900 行代码内实现，无微服务、无消息代理、零配置文件。这种设计使 NanoClaw 高度可预测、易于调试，适合个人用户部署在个人设备上。
容器隔离如何防止 AI 代理访问主机敏感文件？
NanoClaw 使用 Linux 命名空间和 cgroups 实现容器隔离。容器仅能访问通过白名单显式挂载的目录，默认配置会阻止 .ssh、.aws、.gcloud、.kube 等敏感路径。挂载白名单本身存储在 ~/.config/nanoclaw/mount-allowlist.json，这个路径配置为永不挂载，确保代理无法修改访问控制规则。此外，容器以非 root 用户（uid 1000）身份运行，即使存在容器逃逸漏洞，攻击者也难以获得系统级权限。
凭证代理系统的工作原理是什么？如何保证 API key 安全？
当容器内的应用需要调用外部 API（如 Anthropic）时，请求首先发送到一个本地 HTTP 代理。这个代理运行在主机上，拥有访问真实 API key 的权限。代理拦截请求，注入正确的认证头后转发给外部服务。容器内部只持有占位符 key（如 CLAUDE_API_KEY_PLACEHOLDER），无法发现真实凭证的存在。即便攻击者获取了容器的完整访问权限，也只能看到无效的占位符。
NanoClaw 支持哪些消息协议和数据格式？
NanoClaw 开箱支持 WhatsApp，通过技能系统可扩展至 Telegram、Discord、Slack、Signal 和 Gmail。消息渠道采用自注册架构，新的渠道只需实现统一的接口定义即可集成。系统处理多种消息格式，包括文本、图片、语音（需语音转录技能）和文件附件。渠道配置通过 /add-{channel} 技能完成，无效凭证会自动跳过并记录 WARN 日志，不影响其他渠道运行。
技能系统的扩展机制如何工作？如何开发自定义技能？
技能是独立的 git 分支，官方维护的技能发布在 nanoclaw 仓库的不同分支上。用户运行 /add-{skillname} 技能，系统自动检出对应分支并合并到本地仓库。技能代码在容器启动时加载，可访问与主程序相同的 Claude Agent SDK 接口。开发自定义技能需要了解 TypeScript 基础，熟悉 git 分支操作，参考现有技能的结构创建新分支并提交 Pull Request 供官方审核。
分组隔离在技术上是如何实现的？不同组之间完全隔离吗？
分组隔离通过三个层面实现：会话存储隔离（每个组的数据存储在 data/sessions/{group}/.claude/ 下）、文件系统隔离（各组只能访问自己的挂载目录）、容器隔离（各组运行在独立的容器实例中）。IPC 通信按组身份验证，非主组成员无法向其他组发送消息或管理任务。信任模型将主组标记为信任域，其他组作为不信任域处理，主组可以向其他组发送消息，但反向需要额外授权。
调度器的性能表现如何？支持的最大并发任务数是多少？
调度器采用基于内存的简单轮询机制，轮询间隔固定为 60 秒。对于大多数个人使用场景（每日简报、周期性检查），这种设计完全满足需求。原子声明机制防止单次任务重复执行，即使轮询时前一次执行尚未完成也不会触发并发。最大并发任务数理论上受限于系统资源，但在实践中个人用户很少需要运行超过数十个定时任务。对于需要更高精度的场景（如毫秒级间隔），调度器也支持直接指定毫秒间隔。
NanoClaw 的代码可审计性具体体现在哪些方面？
可审计性是 NanoClaw 的核心设计目标。代码库精简至 15 个文件、约 3,900 行，任何具备基础编程能力的用户都可以在短时间内完成全面审查。具体可审计的方面包括：安全边界逻辑（所有挂载检查、路径验证、符号链接解析）、凭证处理流程（代理如何注入认证头、占位符如何替换）、分组隔离机制（会话存储、IPC 权限控制、容器生命周期）、调度器实现（原子声明、重复执行防止）。相比之下，大型框架即使提供审计工具也需要数周时间才能理解整体架构。
评论