NanoClaw 容器化部署：单进程 + 文件系统隔离，8 分钟看懂代码库再动手装

为什么 NanoClaw 值得先读代码再部署

绝大多数开源 Agent 项目的安装文档都是同一个套路：`git clone`、配置密钥、启动服务、扫码登录，五分钟后你确实跑起来了一个能回消息的机器人，但你对自己机器上刚刚多出来的那个进程一无所知。它监听了哪些端口？以什么权限运行？拿到了你的哪些文件？调用的模型请求里塞了什么内容？这些问题在部署完成后往往没人回答。而 NanoClaw 这个名字本身就带着一种态度：它把自己定位成一只体积极小的”爪”，开源、轻量、个人向，代码库刻意保持极小且易读。所以围绕 NanoClaw 部署，正确的打开方式不是”先跑起来再说”，而是”先看懂再动手”。

这篇教程要解决的核心问题只有一个：NanoClaw 部署为什么可以做到”8 分钟看懂代码库”，以及看懂之后，容器化部署的每一步分别在做什么。我们会依次拆解单进程架构、文件系统隔离的设计动机、环境准备、Docker 与 Apple Container 两条部署路径、WhatsApp 接入、SQLite 数据持久化与备份、两种容器方案的差异与选择、隔离边界的真实安全水位、常见报错排查，最后和几个同量级的轻量 Agent 做一次横向对比。全程会给出可以直接复制的命令，也会标注每一步”你在这一步究竟改变了什么”。

先纠正一个误区：轻量不等于简单

1.1 “轻量”说的是可理解性，不是功能缺失

很多人看到”轻量个人 AI Agent”这几个字，第一反应是功能简陋、玩具项目。这是一个误解。在软件工程里，”轻量”至少有三种不同的含义：依赖轻（不用装一堆系统库）、资源轻（内存占用小）、认知轻（读得懂）。NanoClaw 的”轻”主要落在第三种上——它的架构选择全部指向同一个目标：让一个人在一个下午、甚至八分钟内，对系统的每一行为都有确定性判断。这才是个人 Agent 最重要的属性。商业 Agent 平台你不需要读懂它，因为你信任运营方；个人 Agent 跑在你自己的机器上、连着你的 WhatsApp、能读写你的文件，你唯一的信任来源就是你自己读过的那些代码。

1.2 部署前先问三个问题

我在教别人部署任何个人 Agent 之前，都会先让对方回答三个问题。如果答不上来，先别装：

• 它用什么账号身份运行？是容器内的非 root 用户，还是宿主机上的你的主账号？这直接决定了它出错时能破坏多大范围；
• 它能读到哪些目录？是整个家目录，还是只有一个挂载进去的工作目录？这就是文件系统隔离的实质；
• 数据落在哪里、怎么备份？SQLite 文件的具体路径是什么，有没有定时备份，备份是否在容器外？

这三个问题恰好对应 NanoClaw 的三大设计支柱：单进程、文件系统隔离、SQLite 持久化。下面逐一拆开。

8 分钟看懂代码库的可行性从何而来

“8 分钟看懂代码库”听起来像营销话术，但如果架构选对了，它其实是可复现的工程结论。我们来算一笔账：一个人读代码的速度大约是每分钟 200 到 400 行（熟悉语言的前提下），8 分钟能读 1600 到 3200 行。所以一个代码库要让”8 分钟看懂”成立，核心逻辑行数（不含依赖、注释、空行、生成代码）必须控制在这个量级以内，而且信息密度要均匀——不能有大量逻辑藏在第三方依赖的黑盒里。

2.1 单进程架构消除了分布式认知负担

2.1.1 什么是单进程，以及它为什么能省掉一大半理解成本

NanoClaw 是 Node.js 单进程架构：一个 Node 运行时、一个入口文件、一条事件循环。收到 WhatsApp 消息后，所有处理都在同一条调用链上完成——解析消息、组装上下文、调用模型、执行工具、回写数据库、发送回复。没有消息队列、没有 worker 池、没有 Redis、没有跨服务的 RPC。这意味着你读代码时只需要在心里维护一条执行路径，而不是一张服务拓扑图。

对比一下分布式 Agent 的典型结构：网关服务接收消息 → 投递到队列 → 调度器分发给 worker → worker 调用模型 → 结果写回另一个队列 → 回复服务消费。要理解”一条消息到底发生了什么”，你得读五个代码库、两份配置、一份队列 schema。同样的功能，认知成本是单进程架构的五到十倍。NanoClaw 的 8 分钟之所以成立，第一步就是把这段拓扑压缩成了一根直线。

2.1.2 单进程的代价要诚实地说

单进程不是免费的。它意味着：一个长任务会阻塞其他消息的处理（除非代码里显式做了异步隔离）；没有水平扩展能力；进程崩溃会带走所有内存中的状态。NanoClaw 用两个手段对冲这些代价——一是把所有有价值的运行时状态都落到 SQLite，崩溃重启后能从磁盘恢复；二是把”执行不可信代码”这种高风险操作整个推到容器里去，主进程只负责调度和通信。这正好引出下一节。

2.2 文件系统隔离让”边界”变成一个可以肉眼检查的事实

2.2.1 把隔离做成挂载点，而不是做成权限系统

安全设计里有一个经验法则：能被一条命令验证的边界，胜过需要读一堆策略才能确认的边界。NanoClaw 选择文件系统隔离，本质上是把”Agent 能碰什么”这件事从一套复杂的权限矩阵，简化为一个挂载列表。容器启动时你挂进去几个目录，Agent 就只能碰这几个目录；没挂进去的，在容器里根本不存在——不是”没有权限”，而是”路径不存在”。这两种情况的区别在排错时尤其明显：前者你会看到 EACCES，后者你会看到 ENOENT，一眼就能区分是权限问题还是隔离问题。

2.2.2 一个具体的读代码顺序

如果你只有八分钟，我建议按这个顺序读 NanoClaw 代码库，每一段都带着明确的问题去读：

顺序	目标文件/模块	要回答的问题	建议用时
1	package.json	依赖有多少？启动脚本是什么？Node 版本要求？	1 分钟
2	入口文件	进程启动后依次初始化了什么？监听哪个事件源？	2 分钟
3	消息处理链路	一条 WhatsApp 消息进来后，到回复发出，中间经过哪几步？	2 分钟
4	容器调度模块	容器怎么起、挂载了哪些目录、环境变量怎么传、超时怎么处理？	2 分钟
5	数据库层	SQLite 文件路径在哪定义？表结构是什么？写入是同步还是异步？	1 分钟

读完之后你应该能画出这样一张图：WhatsApp 消息 → 持久化原文 → 组装 prompt → 调模型 → 需要执行工具时起容器（带挂载）→ 收结果 → 写库 → 回消息。这张图不是从文档里抄的，是你从代码里验证出来的，这就是”读懂”的标准。此时再执行 NanoClaw 部署，你对每条命令会产生什么副作用是心里有数的。

2.2.3 方法论的价值：先读代码改变了什么

从”照抄命令”到”能预判失败”

不读代码就部署的人，遇到错误只能靠搜索引擎；读过代码的人，遇到错误能先定位到模块。举个典型场景：容器起不来，日志里只有一行 `Error: ENOENT`。没读过代码的人会去论坛上搜，没搜到就放弃；读过挂载逻辑的人会立刻想到——挂载的宿主目录是不是不存在？Docker 在这种情况下可能悄悄创建一个空目录并挂载，而 Apple Container 的行为可能不同，于是同样一份 compose 文件在两个平台上表现不一致。这种”预判”能力，只能来自代码，不能来自安装文档。

从”信任作者”到”自己划边界”

更重要的价值在于：读懂代码之后，你能自己决定隔离要做到什么程度。比如你发现工作目录被整块挂进容器，你可以主动收窄成只挂一个 `workspace/` 子目录；你发现模型调用没有设置超时，你可以在部署时加一层外层 watchdog。这些调整都不需要等上游合并，因为代码库小到你改得动。当一个个人 Agent 的代码库小到用户可以审计和修改时，它才真正属于用户。

环境准备：Node.js、Docker 与 Apple Container

NanoClaw 的运行时依赖可以分成三层：Node.js 运行时负责主进程；容器运行时负责隔离执行；WhatsApp 客户端链路负责消息收发。三层缺一不可，所以环境准备要按层来做，做完一层验证一层，不要一股脑全装完再调。

3.1 Node.js 运行时

先确认 Node 版本。一个可靠的做法是在仓库根目录看 `.nvmrc` 或 `package.json` 的 engines 字段，然后用版本管理器切到对应版本。不要用系统包管理器随手装的 Node——不同发行版的默认版本差异很大，LTS 与 Current 之间的行为差异在 Node 20 之后依然存在。

# 使用 nvm 安装并切换到项目要求的 Node 版本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
export NVM_DIR="$HOME/.nvm"
. "$NVM_DIR/nvm.sh"

# 如果仓库里有 .nvmrc，nvm 会自动读取
nvm install --lts
nvm use --lts

node -v
npm -v

# 安装依赖（优先用 lockfile 对应的包管理器）
npm ci

注意最后一步用 `npm ci` 而不是 `npm install`。前者严格按 lockfile 安装、不会改动依赖树，后者可能升级次版本并在你的机器上生成一份与作者不同的依赖树——对于一个强调”可复现、可读”的项目，这点尤其在意的应该是你。

3.2 Docker 容器运行时

Docker 是跨平台最稳的选择。Linux 上装 Engine，macOS 和 Windows 上装 Docker Desktop。装完后必须验证两件事：守护进程在跑、当前用户有权限访问 socket。

# 验证 Docker 守护进程与权限
docker version
docker info | grep -E "Server Version|Cgroup|Storage Driver"

# Linux 下把当前用户加入 docker 组（避免每条命令都要 sudo）
sudo usermod -aG docker $USER
newgrp docker

# 跑一次最小容器，确认镜像拉取和挂载都正常
docker run --rm -v /tmp/nanoclaw-test:/data alpine ls -la /data
mkdir -p /tmp/nanoclaw-test && echo ok > /tmp/nanoclaw-test/probe.txt
docker run --rm -v /tmp/nanoclaw-test:/data:ro alpine cat /data/probe.txt

最后那条带 `:ro` 的命令是一次”反向探测”：它验证只读挂载确实生效。养成这个习惯很重要——文件系统隔离是否真正生效，必须用一次写入尝试来证明，而不是看配置文件里的字面意思。

3.3 Apple Container（macOS 原生方案）

Apple Container 是 macOS 上的原生容器方案，基于虚拟化框架在 Apple Silicon 上为每个容器提供独立轻量虚拟机，不需要 Docker Desktop 这一层桌面虚拟化。对环境的要求是：Apple Silicon 芯片、较新的 macOS 版本、安装对应的命令行工具。它和 Docker 共享镜像格式基本兼容，所以你为 NanoClaw 准备的 Dockerfile 通常可以复用，但运行时行为、网络模式、挂载语义存在差异，这一点后面会专门列表对比。

# 安装并启动 Apple Container（示意，具体以官方文档为准）
brew install --cask container
container --version
container system start

# 验证镜像与运行
container image pull alpine
mkdir -p ~/nanoclaw-probe && echo ok > ~/nanoclaw-probe/probe.txt
container run --rm -v ~/nanoclaw-probe:/data alpine cat /data/probe.txt

如果你在 Linux 服务器上部署，可以直接跳过这一节，Apple Container 只在 macOS 上有意义。若你在 Mac 上两者都想留，建议不要让它们共用同一个工作目录下的状态文件，排错时不容易混淆。

3.4 三项环境自检清单

正式 NanoClaw 部署之前，用一条清单把环境确认清楚，比事后翻日志高效得多：

• node -v 与项目要求一致，npm ci 无报错；
• docker run hello-world（或 container run hello-world）成功；
• 挂载测试目录可读可写，只读挂载的写入被拒绝；
• 能访问模型 API 端点与 WhatsApp 所需的网络出口（企业网络或代理环境下最容易卡在这里）；
• 磁盘剩余空间足够：镜像、日志、SQLite 数据库、备份各占一份。

容器化部署完整流程

下面这条流水线是通用的：无论你最终选 Docker 还是 Apple Container，步骤的逻辑是一样的，只有命令行工具不同。每一步我都会说明”这一步改变了什么”，这是”先读懂再部署”在实操中的体现。

4.1 获取代码与建立工作目录

先 clone，再建工作目录。工作目录是后面要挂进容器的唯一宿主路径，把它单独放在一个固定位置，可以避免误把整个家目录挂进去。

# 克隆与准备目录结构
git clone https://github.com/<owner>/nanoclaw.git ~/apps/nanoclaw
cd ~/apps/nanoclaw

# 建立数据与工作目录（数据目录不进容器，工作目录进容器）
mkdir -p ~/nanoclaw-data ~/nanoclaw-workspace
cp .env.example .env

# 确认仓库规模，为"8 分钟读懂"做一次量化
find . -path ./node_modules -prune -o -name "*.js" -print | xargs wc -l | tail -5

最后一条命令值得认真跑一次。它会把你自己对”这个项目有多大”的主观印象，变成一个具体数字。当你看到核心源码只有几千行时，”8 分钟看懂”就不再是一个需要相信的承诺，而是一个可以直接验证的事实。

4.2 构建镜像

NanoClaw 的镜像通常分成两层用途：主进程镜像负责长驻服务，执行镜像负责一次性工具调用。如果你只打算跑一个常驻服务，也可以合并成单镜像；但既然它的卖点是文件系统隔离，我更推荐保持”执行侧独立镜像”的做法，因为这样执行容器的能力边界可以单独收紧。

# Docker 构建
docker build -t nanoclaw:latest .

# 查看镜像层与体积，确认没有把 .env、node_modules 之类误打进镜像
docker history nanoclaw:latest --no-trunc | head -20
docker run --rm nanoclaw:latest node -v

构建完成后，务必检查 `.dockerignore`。这是文件系统隔离的第一道实际上游防线——如果 `.env` 被 COPY 进镜像，那么后面所有挂载层面的努力都会打折扣，因为密钥已经烙在镜像层里了。

4.3 启动容器（关键：挂载与权限）

这是整个 NanoClaw 容器化部署最需要你亲手决定的一步。挂载什么、以什么模式挂载、容器用什么用户运行，三个决定合起来构成了文件系统隔离的实际水位。

# Docker 方式启动主进程
docker run -d \
  --name nanoclaw \
  --restart unless-stopped \
  --user 1000:1000 \
  --read-only \
  --tmpfs /tmp:size=256m,mode=1777 \
  -v ~/nanoclaw-workspace:/workspace:rw \
  -v ~/nanoclaw-data:/data:rw \
  -v ~/apps/nanoclaw/config:/app/config:ro \
  --env-file ~/apps/nanoclaw/.env \
  -e NANOCLAW_DB_PATH=/data/nanoclaw.sqlite \
  -e NANOCLAW_WORKDIR=/workspace \
  -e NODE_ENV=production \
  nanoclaw:latest

docker logs -f nanoclaw

逐参数解释一下，因为这几行决定了你的安全边界：`–user 1000:1000` 让容器内进程不以 root 运行；`–read-only` 把根文件系统变成只读，只有 `/tmp`（tmpfs）和两个明确挂载的点可写；`config` 以 `:ro` 挂入，主进程能读配置但不能改配置；`workspace` 与 `data` 是唯一的两块可写区。这就是”最小可写面”的具体形态，也是你能用 `docker inspect` 一条命令复核的东西。

4.4 用 compose 固化部署

单条 `docker run` 适合验证，长期运行建议固化为 compose 文件，这样升级、重启、备份都能被版本化管理。核心仍是同样的挂载与权限原则。

# docker-compose.yml 核心片段（示意）
services:
  nanoclaw:
    image: nanoclaw:latest
    restart: unless-stopped
    user: "1000:1000"
    read_only: true
    tmpfs:
      - /tmp:size=256m,mode=1777
    volumes:
      - /home/me/nanoclaw-workspace:/workspace:rw
      - /home/me/nanoclaw-data:/data:rw
      - /home/me/apps/nanoclaw/config:/app/config:ro
    env_file:
      - /home/me/apps/nanoclaw/.env
    environment:
      NANOCLAW_DB_PATH: /data/nanoclaw.sqlite
      NANOCLAW_WORKDIR: /workspace
    healthcheck:
      test: ["CMD", "node", "-e", "process.exit(0)"]
      interval: 30s
      timeout: 5s
      retries: 3

然后执行 docker compose up -d、docker compose logs -f。健康检查先写成最简单的探活，等你确认主进程能正常跑之后再换成更有意义的检查（例如数据库可读、消息通道心跳正常）。

4.5 用 Apple Container 部署

macOS 上的 Apple Container 路径在流程上完全对称，只是命令前缀不同。注意挂载路径的写法与用户名映射：macOS 上用户 ID 通常是 501，宿主机目录的所有者与容器内用户需要对上，否则容器内会写不进去。

# Apple Container 启动（示意，参数名以本机版本为准）
container system start

container run -d \
  --name nanoclaw \
  -v ~/nanoclaw-workspace:/workspace \
  -v ~/nanoclaw-data:/data \
  -v ~/apps/nanoclaw/config:/app/config \
  --env-file ~/apps/nanoclaw/.env \
  -e NANOCLAW_DB_PATH=/data/nanoclaw.sqlite \
  nanoclaw:latest

container ls
container logs -f nanoclaw

第一版先不加只读根文件系统，跑通之后再逐步收紧。不同版本的 Apple Container 对只读根、tmpfs、用户映射的支持程度不一，冒进收紧容易出现难以定位的启动失败；”先通后紧”是我在两种运行时上通用的策略。

4.6 启动后立刻做的三项验证

4.6.1 验证隔离生效

# 验证：容器内看不到宿主家目录，只能看到挂载点
docker exec nanoclaw ls /home/me 2>&1 | head -3
docker exec nanoclaw ls /workspace
docker exec nanoclaw touch /app/config/probe 2>&1

第一条应该报”不存在”，第二条应该列出手稿目录内容，第三条应该报”只读文件系统”。三条结果都对，说明文件系统隔离按你的意图生效了。

4.6.2 验证数据落盘

在容器内发一条测试消息，然后在宿主机上直接查 SQLite 文件是否存在、是否在增长。这是”SQLite 持久化到底有没有生效”的唯一可靠证明。

4.6.3 验证可重启可恢复

docker restart nanoclaw，日志里应该能看到历史消息被重新加载，而不是一片空白。如果重启后上下文丢失，说明主进程把状态存在了内存而不是 SQLite，这属于部署配置问题，不是项目问题——通常是把数据目录挂错了或指向了 tmpfs。

WhatsApp 接入配置

WhatsApp 集成是 NanoClaw 最有辨识度的场景：你不需要打开任何网页或 App 面板，直接在聊天窗口里给 Agent 发消息，它回复到同一个会话里。这种交互方式的好处是零学习成本，代价是消息通道本身成了安全边界的一部分——任何能给你发消息的人，都在某种程度上能触达这个 Agent。

5.1 接入配置的完整步骤

典型做法是通过 WhatsApp 多设备关联机制登录：Agent 生成一个二维码，你用手机扫码，会话凭据就会持久化到数据目录中。凭据文件必须落在容器外部挂载的目录，否则容器重建后要重新扫码。

# .env 关键配置项（示意，字段名以项目 .env.example 为准）
NANOCLAW_CHANNEL=whatsapp
WHATSAPP_SESSION_DIR=/data/whatsapp-session
WHATSAPP_ALLOWED_SENDERS=+8613800000000,+8613900000000
WHATSAPP_SELF_ONLY=true
NANOCLAW_DB_PATH=/data/nanoclaw.sqlite
NANOCLAW_WORKDIR=/workspace
MODEL_PROVIDER=your-provider
MODEL_API_KEY=sk-xxxxxxxxxxxxxxxx
MODEL_NAME=your-model-name
LOG_LEVEL=info

# 首次登录：输出二维码到终端日志
docker compose logs -f nanoclaw | sed -n '/QR/,/scan/p'

# 或者进入容器内触发登录流程
docker exec -it nanoclaw node index.js --login

# 登录后确认凭据已持久化到宿主机
ls -la ~/nanoclaw-data/whatsapp-session | head

扫码成功后，用手机给该号码发一条 “ping”，容器日志里应该能看到消息解析、模型调用、回复发送三段记录。如果你在日志里只看到消息进来、没有回复，直接跳到后面的排查章节，按”消息链路的五个断点”逐层查。

5.2 三条必须理解的 WhatsApp 配置项

5.2.1 允许发送者白名单

`WHATSAPP_ALLOWED_SENDERS` 是接入层面最有效的防护。没有它，任何人只要拿到你的号码就能驱动你的 Agent、消耗你的模型额度，甚至让它在你挂载的 workspace 里读写文件。建议初期只放自己的号码，等完全摸清行为之后再逐个添加。

5.2.2 会话目录的持久化位置

WhatsApp 的登录凭据本质上是一份会话密钥。它必须放在挂载的数据目录里，并且这份目录的权限应当与备份策略一致对待——被盗用意味着别人可以冒用你的设备身份收发消息。不要把它放在 workspace 里，workspace 是给 Agent 读写文件的区域，属于”低信任区”。

5.2.3 回环与出站网络

WhatsApp 通道依赖稳定长连接，家用 NAT 或企业代理下可能出现频繁重连。重连本身不致命，但要注意重连风暴会放大模型请求——如果代码里没有对消息去重，断线期间的重投可能触发多次回复。部署时把日志级别保持在 info，观察一天的重连频率，是比较务实的做法。

5.3 用 WhatsApp 通道做一次端到端冒烟测试

接入完成后，按这个顺序做冒烟测试，每一轮验证一个能力：发一句纯文本对话（验证链路）；发一条需要读文件的指令（验证 workspace 挂载）；发一条需要改文件的指令，然后去宿主机确认文件确实变了（验证写入路径落在预期位置）；故意发一条让它读 `/etc/shadow` 或家目录其他路径的指令，确认它读不到（验证隔离）。四步走完，你对这套 NanoClaw 部署的安全水位就有了实证判断。

SQLite 数据持久化与备份

单进程架构把状态集中到了磁盘上的一个 SQLite 文件里。这是优点也是唯一的数据单点：只要这个文件还在，整个 Agent 的记忆、会话映射、任务记录就都还在；如果它损坏或丢失，你失去的是全部上下文。所以 NanoClaw 部署里最值得认真做的运维动作，就是备份这一个文件。

6.1 理解 SQLite 的写入语义

6.1.1 WAL 模式与备份的关系

SQLite 默认可能启用 WAL（预写日志）模式，此时数据目录里会同时出现 `.sqlite`、`-wal`、`-shm` 三个文件。WAL 模式的好处是读写并发更好，坏处是你不能只复制主文件就当作完整备份——最新的写入可能还在 wal 文件里没有合并。这是新手备份最常犯的错误：备份了一个”少了几分钟数据”的库，恢复时才发现最后几条对话不见了。

6.1.2 三种备份方式的取舍

第一种是停机冷备份，最简单也最可靠，适合个人场景；第二种是用 SQLite 自带的备份命令做在线一致性备份，适合不想中断服务；第三种是文件系统快照，适合虚拟化环境。个人自托管场景我推荐第二种为主、第一种为辅：日常用在线备份，升级前额外做一次冷备份。

# 方式一：在线一致性备份（推荐，不需要停服务）
mkdir -p ~/nanoclaw-backup
sqlite3 ~/nanoclaw-data/nanoclaw.sqlite \
  ".backup '$HOME/nanoclaw-backup/nanoclaw-$(date +%Y%m%d-%H%M%S).sqlite'"

# 方式二：停服冷备份（升级前使用）
docker compose stop nanoclaw
tar -czf ~/nanoclaw-backup/cold-$(date +%Y%m%d).tgz \
  -C ~/nanoclaw-data nanoclaw.sqlite whatsapp-session
docker compose start nanoclaw

# 方式三：容器内在线备份（不依赖宿主机安装 sqlite3）
docker exec nanoclaw sh -c \
  'sqlite3 /data/nanoclaw.sqlite ".backup /data/backup/manual.sqlite"'

# 校验备份完整性
sqlite3 ~/nanoclaw-backup/nanoclaw-latest.sqlite "PRAGMA integrity_check;"

# 每日定时备份（crontab -e 中加入）
# 30 3 * * * sqlite3 /home/me/nanoclaw-data/nanoclaw.sqlite ".backup '/home/me/nanoclaw-backup/daily-$(date +\%F).sqlite'"

注意 crontab 里 `%` 需要转义成 `\%`，这是最容易被忽略的坑之一——不转义时 cron 会把 `%` 当成换行符，备份任务会以奇怪的方式失败。

6.2 备份策略与恢复演练

6.2.1 保留策略

个人场景下我建议”7 日 + 4 周 + 3 月”的三层保留：每日备份留 7 份、每周留 4 份、每月留 3 份，再加上每次升级前的冷备份。总量不大但覆盖了从”手滑改坏”到”用了两个月才发现上下文异常”的各种时间跨度。

6.2.2 恢复要演练

没有演练过的备份等于没有备份。至少做一次完整恢复：停服务、把备份文件放回数据目录、删掉对应的 `-wal` 和 `-shm`（否则会尝试回放旧日志）、启动、在 WhatsApp 里问它昨天聊过的一个话题，确认记忆恢复。这一步花十分钟，能在真正出事时省掉几个小时。

6.2.3 备份文件的访问控制

备份文件包含你的全部对话内容，敏感度等同于聊天记录。目录权限必须收紧到只有你自己可读，并注意备份目录不要被 Agent 挂载进去——否则隔离就出现了后门，Agent 能读到所有历史备份。

Apple Container 与 Docker：差异与选择

两种容器方案在 NanoClaw 部署场景下的差别，集中在隔离层级、运行开销、平台绑定和运维习惯四个方面。下面这张表是我在两类机器上反复对比后的总结，供你做选择时参考。

对比维度	Docker	Apple Container
底层隔离方式	Linux namespace + cgroup（macOS 上经 Linux 虚拟机）	Apple Silicon 上每容器一个轻量虚拟机
隔离强度	共享宿主内核，隔离靠内核机制，边界清晰成熟	虚拟化边界，内核级隔离，理论上更强
平台支持	Linux / macOS / Windows 全平台	仅 macOS，且需要 Apple Silicon
冷启动与常驻开销	启动快，长期生态优化充分	启动依赖虚拟机拉起，首次较慢，内存粒度更粗
镜像兼容性	OCI 标准	兼容 OCI 镜像格式，但与 Docker 运行时语义有差异
挂载语义	宿主目录映射成熟，`:ro` 等模式稳定	目录共享可用，部分高级挂载选项支持不完整
网络模式	bridge / host 等模式丰富	网络模型较简单，复杂拓扑支持有限
只读根文件系统	成熟，逐版本可控	视版本而定，需实测
生态与排错资料	极其丰富，报错几乎都能搜到	较新，社区资料少，需读文档与实测
适合场景	Linux 服务器、需要远程运维、追求稳定复现	Mac 本地个人使用、追求原生与虚拟化隔离

7.1 如何做选择

决策其实很简单：如果你要把 NanoClaw 放在 7×24 常开的 Linux 小主机或 NAS 上，选 Docker，没有第二个答案；如果你只在 Mac 上本地使用，希望不装 Docker Desktop，且能接受略粗糙的生态，可以选 Apple Container；如果你既要本地开发又要上服务器，就用 Docker 保持一致性，别为了本地偏好牺牲部署环境的可复现性。文件系统隔离的挂载设计在两者上是一致的，切换成本主要在命令行参数而不是代码。

安全边界的真实水位：防了什么、没防什么

这一节是全文我最想让你认真读的部分。容器化和文件系统隔离经常被包装成一种”绝对安全”的叙事，但做过二十年运维的人都知道，隔离从来不是一个开关，而是一组具体的、各有盲区的控制。NanoClaw 部署之后，你的隔离实际挡住的攻击面需要逐条盘点。

8.1 文件系统隔离确实防住了什么

8.1.1 误操作型破坏

这是最现实也最高频的威胁。Agent 在处理文件任务时执行了一条 `rm -rf`、一个错误的移动命令、一次覆盖式写入，如果它跑在容器内且只挂了一个工作目录，破坏范围就被硬性限制在该目录里。这类威胁不来自攻击者，而来自”模型判断失误”，恰恰是隔离机制最应该优先覆盖的。文件系统隔离在这里的成功率接近百分之百，因为它不依赖模型是否聪明。

8.1.2 越权读取

Agent 被诱导去读取 SSH 私钥、浏览器 Cookie、云厂商凭据文件时，只要这些路径没被挂进容器，读取就会以 ENOENT 结束。注意这里的关键不是”Agent 拒绝执行”，而是”路径不存在”——即使模型完全配合攻击者，也无法读到不存在的东西。这是声明式隔离相对策略式防护的根本优势。

8.1.3 容器重建后的残留

配合只读根文件系统，容器被删除重建后不会留下被动过手脚的二进制或脚本。这一点在经常重建容器的运维习惯下价值明显：你每次都在一个干净的文件系统上启动，而不是在一个被长期使用的、边界不断被侵蚀的环境上。

8.2 隔离没有防住什么

8.2.1 挂载目录内部的破坏

隔离的粒度是挂载点。workspace 内部的一切都不受保护：Agent 可以在其中删除、覆盖、加密你的文件。如果你把整个项目目录挂进去，隔离对项目文件就等于没生效。正确做法是缩小挂载范围，并且把源码备份放在容器读不到的地方。

8.2.2 数据外泄

文件系统隔离管的是”读写本地文件”，管不了”把读到的内容发出去”。一旦容器有网络出口，Agent 就能把 workspace 里的内容发到模型 API 或任何它能访问的地址。对个人 Agent 来说，这几乎是必须接受的设计前提——想用远程模型就必然有外发。你能做的是：控制 workspace 里放什么，让敏感数据根本不进入 Agent 的视野。

8.2.3 计算资源滥用

文件系统隔离不约束 CPU、内存、进程数、磁盘写入量。一条死循环的脚本或者一个耗尽的磁盘，隔离完全不会阻止。需要在容器层额外加 `–memory`、`–cpus`、`–pids-limit`，并给日志做轮转；否则一台个人机器被一个 Agent 拖垮是完全可能的。

8.2.4 供应链与镜像层

如果你的镜像基础层来自不可信来源，或者依赖被投毒，文件系统隔离不会让恶意代码变善良——它只是限制了恶意代码的活动半径。这也是”先读代码再部署”方法论在安全维度上的价值：小代码库让你至少有能力评估依赖清单是否合理。

8.2.5 通道身份冒用

WhatsApp 通道的凭据一旦泄露，攻击者可以绕过所有前置控制直接以你的身份收发消息。隔离发生在容器和文件系统层面，而通道认证发生在应用层，二者不在同一个防线上。这也是为什么会话目录要单独保护、白名单要收紧。

8.3 我建议的分层加固清单

把上面这些拼成一份可执行的清单：主进程非 root；根文件系统只读；workspace 与 data 单独挂载且范围最小；config 只读挂载；禁止挂载家目录、`.ssh`、云凭据目录；容器网络出口按需限制；WhatsApp 白名单只放自己；数据目录定时备份且备份在容器外；日志轮转并控制磁盘上限。做完这九条，你已经覆盖了绝大多数现实风险，剩下的风险属于”接受型风险”，需要你自己判断值不值得为它牺牲可用性。

常见报错排查

下面是我在两类机器上部署同类单进程 Agent 时最常见的问题。排查的统一原则是：先分层定位，再动手改。从外到内依次是网络层、运行时层、应用层、数据层，一层层用一条命令确认，不要一次性改五个配置。

9.1 启动与运行时类

9.1.1 ENOENT：挂载路径不存在

症状是容器启动即退出，日志里有 ENOENT。原因通常是宿主机上的挂载源目录还没创建。Docker 在某些情况下会自动创建空目录，看起来”能启动”，但容器里的进程其实写到了一块你意想不到的地方。解决办法是启动前显式 `mkdir -p`，创建后 `ls -la` 确认所有者，容器内用户要与宿主目录所有者匹配。

9.1.2 EACCES：权限与用户映射

容器内以 1000 运行而宿主目录属于 root 时会出现。修复方式是 `sudo chown -R 1000:1000` 目标目录，而不是给目录加 777——后者解决了症状却放大了风险，属于典型的以安全换省事。

9.1.3 只读文件系统写入失败

加了 `–read-only` 之后，任何尝试写根文件系统的行为都会失败，常见于临时文件、缓存目录、日志目录。做法是把这些路径显式挂成 tmpfs 或指向 data 目录。如果暂时不想调，就先去掉 `–read-only` 跑通再收紧，追查是哪个模块在用临时文件。

9.1.4 Node 版本不匹配

语法报错、原生模块编译失败、`ERR_REQUIRE_ESM` 之类，多与 Node 版本有关。用 `.nvmrc` 固定版本，并确保容器基础镜像的 Node 版本与本地一致，避免”本地好用线上报错”。

9.2 通道与数据类

9.2.1 WhatsApp 二维码过期或反复生成

原因基本都是会话目录未持久化，容器每次重启都从零开始登录。确认 `WHATSAPP_SESSION_DIR` 指向的是挂载的 data 目录，并检查所有者权限。

9.2.2 消息进来但没有回复

按五个断点逐层查：消息是否被解析（日志里有入站记录）；是否被白名单拦截（日志里有拒绝记录）；模型调用是否超时（看请求耗时与错误码）；工具执行是否卡住（看容器是否残留）；回复发送是否失败（看通道报错）。每一层一条日志能确认，比通读全部日志快得多。

9.2.3 SQLite 报 database is locked

单进程架构下这种情况通常说明有第二条进程在访问同一个库——常见于你把同一个 data 目录同时挂给两个容器实例，或者宿主机上直接开着 sqlite3 会话。解决办法是确认只有一个写者，读操作改为用 `.backup` 拉出一份副本再查。

9.2.4 重启后上下文丢失

先确认 `NANOCLAW_DB_PATH` 是否指向 tmpfs 或容器内路径——如果是，容器重建就全丢。再确认挂载是否正确，最后再怀疑代码。个人部署里九成以上属于配置问题。

9.3 资源与平台类

9.3.1 磁盘被日志占满

日志或临时文件未轮转。给 Docker 配 json-file 驱动的 `max-size` 与 `max-file`，并给 tmpfs 设 `size` 上限。磁盘满之后症状很杂（写库失败、容器起不来、二维码生成失败），先看 `df -h` 永远是对的。

9.3.2 Apple Container 与 Docker 行为不一致

同样的命令在两边表现不同，通常来自挂载语义、用户 ID 映射、只读根支持的差异。排查方式是把可疑项拆成最小用例：单独 run 一个 alpine 镜像，逐个测试挂载、写权限、网络，定位到具体是哪一项能力不同，再回去调整部署命令。

与其他轻量 Agent 的对比

“轻量个人 Agent”这个赛道这两年涌入不少项目，定位相近但取舍不同。下面这张表按部署者最关心的几个维度做横向对照，帮助你在选择 NanoClaw 之前有一个整体坐标。表格反映的是各类方案的典型取向，具体到某个版本请以该项目的当前文档为准。

对比维度	NanoClaw	通用 Agent 框架（LangChain 类）	重型自托管 Agent 平台	闭源托管 AI 助手
架构形态	Node.js 单进程	库/框架，由使用者组装	多服务 + 消息队列 + 数据库	云端多租户
代码库规模	刻意极小，可二三十分钟通读	自身中等，但依赖庞大	大，组件众多	不可读
隔离方式	容器 + 文件系统隔离	取决于使用者实现	容器编排级隔离	平台侧隔离
数据落点	本地 SQLite，单文件可备份	自定义	外置数据库，需单独运维	平台服务器
即时通讯接入	WhatsApp 为特色场景	需自行对接	多渠道插件体系	取决于平台，通常自有 App
部署门槛	低，容器一条命令起步	高，需要写代码	高，需要运维能力	极低，但依赖外部服务
可改造性	高，代码小到改得动	高	中，改造成本高	无
典型用户	愿意读代码的个人开发者	需要定制的工程团队	有运维资源的小团队	不想碰命令行的普通用户

10.1 选择 NanoClaw 的三个信号

如果你符合下面三条中的两条以上，NanoClaw 会是一个舒服的选择：你愿意花半小时读代码，并且读得懂 Node.js；你需要一个跑在自己机器上、连着 WhatsApp 的常驻助手；你希望数据和记忆是一个可以直接 `cp` 走的文件，而不是一堆云端接口。反过来，如果你完全不想碰命令行，或者需要多租户、多团队协作、审计日志这类企业级能力，那它不适合你——这类需求本来就该交给平台型方案。

10.2 对比之后最该记住的一点

横向对比很容易陷入参数堆砌，但在我看来，真正把 NanoClaw 与其他轻量 Agent 区分开来的，不是某一条功能，而是它对”部署者必须在场”的坚持：极小代码库、单进程、文件系统隔离，这三样加在一起，本质上是在为”用户能完整理解并独自掌控这套系统”创造前提条件。你买的不只是功能，还有一份可以在八分钟内读完的所有权说明书。

FAQ

Q1：NanoClaw 部署一定要用容器吗？直接 npm start 行不行？

技术上可行，但不推荐作为长期形态。不容器化时，主进程会直接以你的用户身份运行，文件系统隔离就无从谈起——它能读到的就是你账号能读到的全部内容。容器化把”能碰到什么”从一个由账号权限决定的模糊边界，变成了一个由挂载列表决定的明确边界。对于个人 Agent 这种能执行任意指令的系统，这条边界几乎是必需品。如果你只是想快速验证功能，可以先直接跑；一旦决定长期使用，请回到容器化路径，并至少做完非 root、只读根、最小挂载这三项。

Q2：”8 分钟看懂代码库”这个说法可信吗？我真的需要在部署前读代码？

可信的前提是代码库确实被刻意控制在小规模。你可以用一条命令自己验证：统计排除依赖后的核心源码行数，如果在一个下午能通读的量级，那么八分钟足够读懂主干链路（入口、消息处理、容器调度、数据库）。读代码的价值不在于每个细节都记住，而在于你能回答”它用什么权限运行””它能读到哪些文件””数据存在哪里”。这三个答案决定了你后面每条部署命令的意义。我的建议是：即使你只打算读八分钟，也要认真读那段容器调度代码，因为那是安全边界真正落地的地方。

Q3：文件系统隔离能替代沙箱吗？它的真实安全水位在哪里？

不能替代。文件系统隔离解决的是”读写哪些本地文件”，它对此非常可靠，因为边界是声明式的、可以用一条 `ls` 验证。但它不约束网络外泄、不限制 CPU 与内存、不保护挂载目录内部、也不解决通道身份冒用。准确的说法是：它把 Agent 的本地权限压缩到一个可枚举的集合，从而把大多数误操作和高频越权读取变成不可能；它并没有把 Agent 变成一个安全的代码执行环境。如果你需要后者的语义，应当在文件系统隔离之上再叠加资源限制与网络出口控制，并接受”外发不可避免”这一前提去控制数据可见性。

Q4：WhatsApp 接入会不会有封号风险？怎么降低？

个人自动化接入第三方即时通讯通道，本身就需要遵守该平台的服务条款，长期高频、批量、群发的行为确实存在风险。降低风险的做法是：只做个人低频率的私聊助手用途，不做群发、不做营销推送；保持设备在线稳定，避免频繁重新登录；不修改客户端、不伪造设备信息；把使用规模控制在”一个正常人用手机”的量级。如果你的场景是团队协作或业务通知，更稳妥的选择是使用官方开放的商业接口，而不是个人账号自动化。这一点在任何平台都是通行规则，不只是这一个通道。

Q5：SQLite 单文件会不会撑不住？数据量大了怎么办？

个人 Agent 的消息量通常在每天几百到几千条量级，SQLite 完全能胜任，读取延迟远低于模型推理的时间。真正需要关注的是三件事：一是备份，把在线一致性备份做成定时任务；二是定期 VACUUM 或检查文件体积，避免长期运行后碎片过多；三是避免把所有原始附件直接塞进数据库，大文件放 workspace、库里只存路径。如果未来确实需要多实例共享数据，那说明你的使用形态已经超出了单进程架构的设计目标，届时再考虑迁移到外部数据库，而不是现在提前做复杂化。

Q6：Docker 和 Apple Container，读完代码后我该怎么定？

按部署位置定，不要按偏好定。常驻在 Linux 主机或 NAS 上的，用 Docker，稳定性、生态、远程运维和定时任务的成熟度都不在一个量级；只在 Mac 上本地使用、且不想装 Docker Desktop 的，可以选 Apple Container，享受虚拟化级别的隔离，但要对部分高级参数的兼容性做好准备。无论选哪个，你的部署原则不变：非 root、只读根、最小挂载、数据目录独立、备份在容器外。这五条在任何容器运行时上都适用，也正好是你在读完代码后最应该亲手落实的部分。