NanoClaw：用容器隔离重做的个人 Claude 助手

NanoClaw 是一个跑在用户自己机器上的开源个人 AI 助手：把 Claude（或 Codex、OpenCode、Ollama 等备选提供方）接入 WhatsApp、Telegram、Slack、Discord 等聊天软件，由助手在隔离容器里执行任务、读写被授权的目录、按计划定时汇报。它在 GitHub 上以”OpenClaw 的轻量替代”为卖点，核心主张只有两条：代码小到可以通读，Agent 跑在操作系统级容器里而不是应用层权限检查后面。本文基于其官方仓库 README、架构文档、安全模型文档与官网对比页做一手核对。

一、背景动机：给”看不懂的软件”完整访问权的信任焦虑

个人助手类项目（把大模型接到聊天软件、让它代读代发、定时跑任务）天然持有用户的消息、文件与 API 凭证。作者在 README 的 “Why I Built NanoClaw” 中直接给出动机：OpenClaw 是个有愿景的 impressive 项目，但”我无法在给一个自己看不懂的复杂软件以我生活的完整访问权之后安然入睡”。

官方对 OpenClaw 的批评集中在三点：代码体量过大（README 称其”近五十万行代码、53 个配置文件、70+ 依赖”）；安全停留在应用层（允许列表、配对码）而非真正的操作系统隔离；所有东西跑在同一个 Node 进程里、共享内存。NanoClaw 要交付”同样的核心功能”，但放在一个小到能读完的代码库里，让 Agent 在各自的 Linux 容器中运行，只能看到被显式挂载的目录。

二、是什么：定位、协议与生态位置

• 定位：单宿主进程 + 每会话隔离容器的个人助手，不是通用 Agent 框架；官方哲学是”定制即改代码”，不提供配置文件体系，用户 fork 后让 Claude Code 按需求改源码。
• 协议：MIT 开源；原生通过 Anthropic 官方 Claude Agent SDK 使用 Claude Code，备选提供方以技能（skill）方式按需安装。
• 规模（页面快照）：抓取时 GitHub 页面显示约 31.0k stars、12.9k forks、2,966 次提交；官网首屏写”30.8k+ stars”，页面角标显示”31k+ Stars”——star 数实时变动，三处口径本身就不完全一致，本文只作量级参考。
• 版本注意：当前主干为 v2，仓库提供 migrate-v2.sh 从 v1 迁移；早期 v1 宣传的”核心约 500 行、macOS Apple 容器或 Docker”口径在 v2 中已变化（见第五节）。

三、技术机制：单宿主路由，每会话一个容器，双 SQLite 做边界

官方架构文档（docs/architecture.md）描述的数据流如下：

1. 聊天平台事件进入频道适配器，适配器只做触发词判断、ID 抽取与投递，不知道 Agent 组与会话 ID；
2. 宿主进程（单个 Node 进程）按”用户 → 消息组 → Agent 组 → 会话”的实体模型路由，把消息写进该会话的 inbound.db 并唤醒容器；
3. 容器内的 agent-runner（Bun 运行时，轮询 inbound.db，只读）处理消息，把响应写进 outbound.db；
4. 宿主轮询 outbound.db，经适配器投递回频道。

几个值得注意的工程决策：

• 每个会话一对 SQLite 文件，各只有一个写者：宿主写 inbound.db（容器只读），容器写 outbound.db（宿主只读），以此消除跨挂载的写竞争；不使用 IPC 文件、不使用 stdin 管道。
• 刻意不用 WAL：两个库都用 journal_mode=DELETE。官方解释：WAL 的内存映射 -shm 一致性不会跨 VirtioFS 传播，容器内的 WAL 读者会冻结在早期快照上，永远看不到宿主的新写入。
• 序号奇偶分治：宿主向 messages_in 写偶数 seq，容器向 messages_out 写奇数 seq，两侧各读对方 MAX(seq) 取下一个值，使全局消息 ID 单调且无歧义。
• 60 秒宿主清扫 + 约 1 秒活跃轮询：宿主每 60 秒跨会话做到期唤醒、僵死检测与递归任务排期；活跃容器约 1 秒轮询自己的库；并发投递每次最多排空 8 个会话，避免慢邮箱把一个 tick 串行化。
• 技能式扩展：主干只带注册表与 Chat SDK 桥接，频道适配器（Discord/Slack/Telegram/WhatsApp 等）放在长期维护的 channels 分支，备选提供方放在 providers 分支，用户用 /add-telegram、/add-opencode 等技能把所需模块拷进自己的 fork，没要求的功能不进主干。

四、关键数据：官方自统计的 NanoClaw vs OpenClaw

官网”Why NanoClaw?”对比表（官方自行统计，非第三方审计）：

能力面（官方 README “What It Supports”）：多频道消息（WhatsApp、Telegram、Discord、Slack、Microsoft Teams、iMessage、Matrix、Google Chat、Webex、Linear、GitHub、WeChat，以及经 Resend 的邮件）；三种隔离模式（每频道独立 Agent 组、同 Agent 独立会话、共享同一会话）；每 Agent 组独立 CLAUDE.md、记忆与容器；带 script gate 的定时任务；联网检索；默认经凭证网关出站。

五、评测口径与方法批判：这些数字不能直接当客观排名

1. 对比表是作者自统计口径：“Runtime TypeScript files / lines”只统计运行时 TypeScript，不含容器侧 Bun 代码、测试、配置与资源文件；OpenClaw 的 3,680 文件 / 434,453 行同样由作者方测量，没有给出统计脚本与采样日期，第三方无法复算。“一个下午 vs 1–2 周通读”更是主观估计，不是基准测试成绩。
2. 依赖与配置口径随版本漂移：README 正文称 OpenClaw “70+ dependencies、53 config files”，对比表写 70 / 53，方向一致但精确值是快照；NanoClaw 自身的 12 个直接依赖也会随技能安装增长——主干 12 个，装完频道与提供方后并不等于 12。
3. 运行时要求两处不一致：README Requirements 写 Node.js 22+ 与 pnpm 10+，官网 Get Started 区块写 Node.js 20+ 与 pnpm 10+；以实际安装脚本 nanoclaw.sh 与仓库 .nvmrc 为准，文档之间存在版本落差。
4. v1/v2 宣传口径已变：早期周报与 v1 README 强调”核心约 500 行代码、macOS Apple 容器或 Docker”；v2 主干运行时约 29,300 行 TypeScript，且 Docker 是唯一支持的容器运行时（README FAQ：“Why Docker?”）。拿 v1 的 500 行口径评价 v2 会失真。
5. star 数是热度不是质量证据：31k 量级受开源传播节奏影响，且官方首屏、角标、GitHub 页面三处数字本身略有出入。

六、安全模型：官方承认”守不住什么”

官方安全模型文档（2026-09-04 修改）的威胁假设很直白：假定提示注入最终会成功，然后回答”一个完全被控的 Agent 到底还能做什么”。已实现的分层：

• 容器硬化：非特权 node 用户运行，退出即 --rm；无条件携带 --cap-drop=ALL、no-new-privileges、--init，--pids-limit 默认 2048 作为 fork 炸弹兜底；镜像剔除 Debian 自带二进制的 setuid-root 位。
• 凭证不出容器：密钥存于宿主的 OneCLI Agent Vault，网关在出站 HTTPS 请求时注入；容器里只有占位符 onecli-managed；Vault 不可达时直接中止启动，而不是回退到裸密钥。
• 出口封锁（默认关闭）：可选把容器接入无互联网路由的 Docker --internal 网络，Vault 网关是唯一可达跳点；官方明确它默认关闭，因为任何不尊重代理环境变量的工具直连网络都会失败。
• 挂载允许列表：~/.config/nanoclaw/mount-allowlist.json 默认拒绝，没有文件就没有额外挂载；.ssh、.aws、.env、id_rsa 等内置拦截模式不可删除。
• 审批与人在回路：凭证使用、自我修改（装包/加 MCP）、新频道注册、Agent 间消息都可挂审批卡；没有可达审批人即自动拒绝；审批约 5 分钟未决由宿主清扫作普通拒绝。
• 供应链：pnpm 配置三天 minimumReleaseAge，安装脚本只允许 esbuild、protobufjs、sharp。

官方自己写明的防御缺口（“What this model doesn’t defend”）：以上各层都无法区分”真诚动作”与”被注入后的动作”，被控 Agent 仍然可以——向其有权访问的任何目的地发消息、读写并销毁整个 Agent 组的工作区与 memory/、用已授予的凭证发起认证调用、污染自己的 memory/ 与 instructions.prepend.md 影响未来所有会话。而且同一 Agent 组的所有会话以读写方式共享组目录，爆炸半径的诚实单位是”Agent 组”而非单个会话；跨组读取被 ncl sessions history 拒绝，但同组内不隔离。官方给出的对策是用户自己做 scoping：面向陌生人的频道不要和代码仓库、部署凭证放在同一个组。

七、适用与不适用场景

适合：

• 想在自有机器上拥有一个可定时汇报、可接多聊天渠道的个人助手，且坚持”凭证不出本机”的用户；
• 愿意 fork、直接读改源码来定制行为，而不是填配置面板的开发者；
• 需要把不同信任域（私人 / 团队 / 公开频道）拆成独立 Agent 组并接受 Docker 运维的人。

不适合：

• 想要图形化监控面板、一键多租户团队版的用户（官方明确不做 dashboard，调试直接在聊天里问 Claude Code）；
• 无法接受 Docker 依赖、只想要单一原生二进制的场景；
• 把它当作对抗提示注入的完整安全产品——官方自己承认边界在 scoping，不在软件。

八、客观分析：优势与局限

优势：

1. 隔离层次清晰：容器文件系统隔离 + 凭证网关注入 + 出口封锁可选项，比应用层允许列表更接近”OS 级安全”的定义；
2. 通信边界设计克制：双 SQLite 单写者、弃用 WAL、奇偶 seq，都是针对跨 VirtioFS 挂载的真实工程坑，文档解释了为什么；
3. 技能式裁剪：主干只带注册表，频道与提供方按需拷入，避免了”装一个助手背上 15 个渠道抽象”的膨胀；
4. provider 可替换且按组配置：Claude 默认，Codex/OpenCode/Ollama 可按 Agent 组分别选择，本地 Ollama 可不产生云端模型账单。

局限：

1. 安全边界靠用户自觉拆分 Agent 组，默认配置下同组会话共享读写工作区，误用即扩大爆炸半径；
2. 出口封锁默认关闭且会破坏非代理工具，安全增强项需要主动配置；
3. 安装链重：要求 Node、pnpm、Docker 与 Claude Code（用于定制/调试/技能安装），轻量指的是代码体量而非运维负担；
4. 文档口径不一致（Node 20 vs 22、v1/v2 宣传差异），且对比数字为作者自统计，缺乏第三方复算。

九、它意味着什么 / 谁该关注

NanoClaw 代表了个人助手赛道的一种反向选择方向：不追求功能最全、生态最大，而是把”我能读完、我能改、凭证碰不到”放在功能数量之前。它值得关注的对象是：对 Agent 安全边界有自己判断、愿意用 fork 代替配置的个人开发者；正在评估 OpenClaw 类全家桶但被其体量与单进程共享内存模型劝退的人；以及想研究”宿主进程 + 每会话容器 + 消息队列式 DB 边界”这一隔离范式的工程团队。它不是 OpenClaw 的性能替代品，而是一种”可读、可改、可隔离”的价值观交付。

参考来源

• NanoClaw 官方仓库 README（nanocoai/nanoclaw）
• NanoClaw 官网（含与 OpenClaw 对比表、架构示意）
• NanoClaw 架构文档 docs/architecture.md
• NanoClaw 安全模型文档
• NanoClaw 频道隔离模型文档
• Koala 项目库条目 #1555