1. 项目概述：一个你能完全掌控的AI助手

如果你和我一样，对市面上那些动辄几十万行代码、几十个依赖的AI助手框架感到不安，那么NanoClaw的出现，或许能让你睡个好觉。这个项目源自对OpenClaw的深度思考——一个功能强大但结构复杂的项目，其安全性依赖于应用层的权限检查，而非真正的操作系统级隔离。当你的AI助手能访问你的文件、日程乃至整个数字生活时，这种“信任但需验证”的模式，总让人心里不踏实。

NanoClaw的核心目标非常明确： 在提供强大AI助手能力的同时，将代码复杂度降到一个人就能彻底理解的程度，并通过容器技术实现真正的安全隔离。 它不是一个试图满足所有人需求的庞然大物，而是一个专为个体用户设计的、可深度定制的工具箱。你拿到的是一个清晰、简洁的代码库，然后可以像吩咐一位资深工程师一样，让Claude Code帮你把它改造成完全符合你个人工作流的样子。这种“小而美”且“安全可控”的理念，正是它在众多AI Agent框架中脱颖而出的原因。

简单来说，NanoClaw让你能在Telegram、Discord、WhatsApp等常用通讯工具里，召唤一个运行在独立Docker容器中的Claude助手。你可以让它定时给你发日报、分析代码仓库、整理新闻简报，而这一切操作都被严格限制在容器内部，与你宝贵的主机环境隔离开来。接下来，我将带你从零开始，深入理解并部署属于你自己的NanoClaw。

2. 核心理念与架构设计解析

2.1 为什么选择“极简可理解”作为第一原则？

在软件工程领域，我们常提“防御性编程”，但更底层的安全基石其实是“可理解性”。一个你无法完全理解的系统，其安全性永远是黑盒。OpenClaw拥有近50万行代码和70多个依赖，这意味着即使作为资深开发者，你也几乎不可能在合理时间内完成全面的代码审计。它的安全模型建立在应用层的“白名单”和“配对码”上——这就像给你的房子装了一把智能锁，但所有房间的门都是敞开的。

NanoClaw反其道而行之，它的代码库精简到只有一个主进程和少量源文件。这种设计带来了几个决定性优势：

1. 真正的安全审计成为可能 ：你可以在一个下午通读核心代码，理解每一条数据流和权限边界。安全不再是玄学，而是可验证的事实。
2. 定制化成本极低 ：想改触发词？调整响应风格？添加一个专属技能？因为代码结构清晰，你可以直接告诉Claude Code你的需求，它能精准地找到相关代码并进行修改，出错概率大大降低。
3. 故障排查直观高效 ：当出现问题时，你不会在复杂的微服务调用链中迷失。日志清晰，逻辑直接，你可以快速定位是路由、容器还是Claude API调用出了问题。

注意 ：这里的“极简”并非功能阉割，而是架构的优雅。它通过“技能（Skills）”机制来扩展功能，核心框架只负责最基础的注册、路由和容器调度，所有频道适配器（如Telegram机器人）和备用AI提供商（如OpenAI）都以“技能包”的形式存在，按需安装。这确保了你的主干代码永远干净、可控。

2.2 深度剖析：基于容器的安全隔离模型

NanoClaw最核心的安全特性，是它让每个AI助手（Agent Group）都运行在独立的Linux容器中。这不仅仅是“进程隔离”，而是包含了文件系统、网络（默认情况下）和进程空间的完整沙箱。我们来拆解一下这个模型是如何工作的：

传统应用级隔离的缺陷 ：

• 共享内存 ：所有助手实例跑在同一个Node进程里，一个出问题的代码片段可能影响所有助手。
• 文件系统互通 ：助手A理论上可以遍历并读取助手B的配置文件或记忆库。
• 依赖污染 ：一个助手安装的Node模块可能会意外地影响其他助手的运行环境。

NanoClaw的容器级隔离实现 ：

1. 按组隔离 ：每个“助手组”（Agent Group）对应一个独立的Docker容器。例如，你的“工作助手”和“家庭助手”完全物理隔离。
2. 显式挂载 ：容器内部只能看到你明确允许挂载的目录。比如，你可以将 ~/Documents/work 挂载给工作助手，而将 ~/Pictures/family 挂载给家庭助手，两者互不可见。
3. 安全的Bash访问 ：当你授权助手执行Bash命令时，这些命令是在容器内部执行的，而不是在你的主机Shell上。即使命令是 rm -rf / ，它也只会清空容器内的文件系统，你的宿主机安然无恙。
4. 凭证安全 ：API密钥等敏感信息永远不会进入容器。NanoClaw通过集成OneCLI的Agent Vault，在请求发出时于代理层动态注入凭证。容器内的助手代码只能看到一个“已认证”的HTTP客户端，而拿不到原始密钥。

这种设计意味着，即使某个助手的逻辑被恶意提示词（Prompt）诱导或出现未知漏洞，其破坏范围也被严格限制在自身的容器内。这是一种“默认安全”的设计哲学。

2.3 通信架构：基于SQLite的优雅解耦

NanoClaw没有采用复杂的消息队列或IPC（进程间通信）机制，而是用两个SQLite数据库文件实现了主机进程与容器进程间的通信，这种设计既简单又可靠。

[Telegram/Discord等] -> [主机路由进程] -> inbound.db (写入) -> [容器内Agent进程] -> outbound.db (写入) -> [主机投递进程] -> [返回给用户]

工作流程详解 ：

1. 消息接收与路由 ：当你在Telegram中发送 @Andy 今天有什么安排？ ，Telegram的频道适配器将消息传递给主机上的 router.ts 。路由器根据“用户-消息组-助手组-会话”的实体模型，找到对应的会话，并将消息 写入 该会话专属的 inbound.db 文件。
2. 容器内处理 ：每个助手容器内运行着一个用Bun编写的 agent-runner 。它持续轮询（Poll）自己的 inbound.db 。一旦发现新消息，便调用Claude Agent SDK（或其他配置的提供商）来处理。Claude的思考过程、工具调用（如网络搜索）都在容器内完成。
3. 响应回传 ：生成响应后， agent-runner 将结果 写入 同一个会话的 outbound.db 文件。
4. 消息投递 ：主机上的 delivery.ts 模块会轮询所有会话的 outbound.db ，发现新响应后，通过对应的频道适配器将消息发送回用户。

这种架构的优势 ：

• 无竞争写 ：每个 .db 文件只有一个写入者（主机写inbound，容器写outbound），彻底避免了并发写入的锁问题。
• 故障隔离 ：如果容器崩溃，主机进程不受影响，消息会安静地待在 inbound.db 里，等待容器重启后处理。
• 调试友好 ：你可以直接使用 sqlite3 命令行工具查看 *.db 文件，清晰看到消息流转的状态，调试体验极佳。
• 资源消耗低 ：SQLite是轻量级嵌入式数据库，避免了部署和维护独立消息中间件的开销。

3. 从零开始的完整部署与配置指南

3.1 环境准备与一键安装脚本解析

NanoClaw的入门极其简单，这要归功于那个精心编写的 nanoclaw.sh 脚本。但知其然更要知其所以然，我们来看看这个脚本背后都做了什么。

系统要求核查 ：

• 操作系统 ：macOS、Linux，或Windows下的WSL 2。这是Docker容器运行的基础。
• Node.js与pnpm ：项目基于Node生态，使用pnpm作为包管理器以获得更快的依赖安装和更优的磁盘空间利用。
• Docker ：容器化的基石。在macOS/Windows上需要Docker Desktop，在Linux上需要Docker Engine。
• Claude Code ：这不是硬性运行依赖，但它是实现“AI原生”体验的关键。用于安装技能、调试故障和自定义代码。

执行 bash nanoclaw.sh 后发生的魔法 ：

1. 环境检测与安装 ：脚本会检查Node.js、pnpm和Docker是否存在。如果缺少任何一项，它会引导你进行安装。例如，在macOS上，它可能通过Homebrew安装；在Linux上，会添加NodeSource仓库并安装指定版本。
2. OneCLI凭证配置 ：这是安全的核心一步。脚本会引导你注册Anthropic API密钥到OneCLI的Agent Vault。 请务必在此处使用你从Anthropic控制台获取的正式API密钥 。这个密钥会被安全地存储在本地，后续所有对Claude API的调用都会通过OneCLI代理，密钥本身不会泄露给容器。
3. 依赖安装与构建 ：在项目目录内运行 pnpm install 安装所有Node依赖，并构建TypeScript代码。
4. Docker镜像构建 ：根据 container/Dockerfile 构建Agent运行环境的镜像。这个镜像基于轻量的Linux发行版，包含了Bun运行时和Claude Agent SDK。
5. 首次运行与频道配对 ：启动NanoClaw主进程，并引导你进行第一个频道的配对。例如，选择Telegram后，脚本会提示你联系 @BotFather 创建机器人、获取Token，并输入到NanoClaw中完成链接。

实操心得 ：第一次运行脚本时，建议在一个网络稳定的环境下进行。Docker镜像拉取和依赖安装可能耗时较长。如果脚本在某个步骤失败（比如Docker权限问题），它会自动尝试调用Claude Code来诊断问题。这时，请仔细阅读Claude Code的分析，它通常能给出非常准确的修复建议，比如让你运行 sudo usermod -aG docker $USER 然后注销重新登录。

3.2 核心配置详解：从环境变量到助手组

NanoClaw强调“代码即配置”，但仍有几个关键的配置点需要理解。

环境变量（.env文件） ： 项目根目录下的 .env 文件是主要配置入口。一键安装脚本通常会帮你创建它。

# .env 示例
ANTHROPIC_AUTH_TOKEN=sk-ant-... # 通常由OneCLI管理，这里可留空或填OneCLI的代理地址
DATABASE_URL=file:./data/nanoclaw.db # SQLite数据库路径
LOG_LEVEL=info # 日志级别：debug, info, warn, error
HOST=0.0.0.0 # 监听地址
PORT=3000 # 监听端口

最重要的配置其实是“助手组”（Agent Group） ： 每个助手组在 groups/ 目录下都有一个独立的文件夹，这是自定义行为的核心。

groups/
├── default/          # 默认助手组
│   ├── CLAUDE.md     # 该助手的系统提示词和核心指令
│   ├── docker-compose.yml # 该组容器的特定配置（如挂载卷）
│   └── skills/       # 该组专属的技能目录
└── family-chat/      # 你可以创建的另一个助手组
    ├── CLAUDE.md
    ...

• CLAUDE.md ：这是助手的“大脑”。你可以在这里定义它的名字（默认是Andy）、性格、响应格式、可用工具的限制等。例如，你可以写上“你是一个简洁高效的助手，回答请控制在三句话以内”。
• 挂载卷配置 ：在 docker-compose.yml 中，你可以通过 volumes 字段精确控制该助手能访问宿主机的哪些目录。 这是安全的关键 。例如，只将 ~/work/project 挂载到容器的 /workspace ，那么助手就无法触及你 ~/personal 下的任何文件。

3.3 频道集成与隔离模式实战

NanoClaw支持多达十几种通讯渠道，但并非一次性全部安装。你需要通过“技能”按需添加。

添加一个频道（以Telegram为例） ：

1. 在已运行NanoClaw的任意频道（或CLI）中，向你的助手发送命令： /add-telegram
2. 助手会引导你完成过程。这本质上是Claude Code从远程的 channels 分支获取Telegram适配器代码，并将其复制到你的 src/channels/ 目录，同时更新项目注册表。
3. 完成后，重启NanoClaw服务，新的频道适配器便生效了。
4. 按照提示，去Telegram找 @BotFather 创建新机器人，获取Token，并在NanoClaw提供的链接中完成绑定。

理解并配置隔离模式 ： 这是NanoClaw非常灵活的一个特性。你可以在 /manage-channels 命令中，为每个频道配置它连接到哪个助手组，以及会话如何隔离。

隔离模式	描述	适用场景
专属助手	该频道独享一个助手组和会话。记忆、文件访问完全独立。	需要最高隐私的场景，如处理敏感工作的专用频道。
共享助手，独立会话	多个频道共享同一个助手组（即同一个大脑和记忆库），但每个频道的对话历史是独立的。	你想在Telegram和Discord上用同一个助手，但又不希望两边对话互相干扰。
共享助手，共享会话	多个频道不仅共享助手，还共享同一个对话会话。在一个频道说的话，在另一个频道能接着聊。	打造无缝的多端体验，比如在电脑前用Discord，出门用Telegram继续同一话题。

配置完成后，你的消息路由就会按照这个逻辑进行。这种精细化的控制，让你能完美平衡便利性与隐私性。

4. 高级功能与深度定制开发

4.1 技能（Skills）系统：生态扩展的基石

NanoClaw的“技能”机制是其保持核心简洁又能无限扩展的灵魂。它完美践行了Unix哲学——“做一件事，并做好”。核心框架（trunk）只负责最基础的Agent生命周期管理和消息路由，所有“增值功能”都以技能形式存在。

技能的分类与存放 ：

• 频道技能 ：位于 channels 分支。包含Telegram、Discord、Slack等所有通讯适配器的代码。用户通过 /add-telegram 等命令将其“克隆”到自己的fork中。
• 提供商技能 ：位于 providers 分支。包含除Claude之外的其他AI模型集成，如OpenAI、Ollama等。通过 /add-opencode 等命令安装。
• 工具/功能技能 ：未来可能会出现的分支，用于添加如“日历管理”、“邮件发送”等具体功能模块。

技能安装的内部原理 ： 当你运行 /add-telegram 时，背后发生的是：

1. Claude Code被触发，它首先检查本地 src/channels/ 目录是否已存在 telegram 模块。
2. 如果不存在，Claude Code会访问项目仓库的 channels 分支，找到 telegram 适配器的源代码。
3. 它将代码拉取到本地一个临时位置，然后将其复制到 src/channels/telegram/ 目录。
4. 接着，Claude Code会修改 src/channels/index.ts 这类注册文件，将新的适配器“注册”到系统中。
5. 最后，它可能会运行 pnpm install 来安装这个新适配器所需的特定NPM依赖。
6. 完成后，Claude Code会提示你重启NanoClaw服务以使新频道生效。

这个过程完全自动化，且发生在你的代码副本中，不会影响主干仓库。这意味着每个用户的NanoClaw实例都是为其量身定制的。

4.2 定时任务与Web访问能力集成

让AI助手自动工作是提升效率的关键。NanoClaw内置了调度器和网络访问工具。

创建定时任务 ： 你可以像在聊天中一样自然地向助手下达定时指令：

@Andy 从下周开始，每个工作日上午9点，检查我的GitHub仓库issue，并总结一份待办清单发给我。

助手会理解这个指令，并在后台创建一个Cron风格的定时任务。任务的定义会存储在数据库中。到了指定时间， host-sweep.ts 模块会触发任务，唤醒对应的助手容器去执行。

内部实现要点 ：

• 可靠性 ：调度器使用数据库存储任务状态，即使NanoClaw进程重启，任务也不会丢失。
• 防重入 ：任务执行有锁机制，防止同一个任务被并发执行多次。
• 日志 ：每次任务执行的结果和日志都会记录下来，方便你通过 /debug 命令查询。

启用Web搜索能力 ： 默认情况下，出于安全和成本考虑，助手可能没有网络访问权限。你需要明确授权：

1. 在对应助手组的 CLAUDE.md 中，声明允许使用“网络搜索”工具。
2. 确保在容器配置中，网络模式允许出站连接（默认的桥接模式通常可以）。
3. 助手在需要时，就会调用Claude Agent SDK内置的搜索工具来获取实时信息。

注意事项 ：Web搜索会消耗Claude的Token并可能产生API费用，且返回的信息需要助手进行甄别。建议为需要此功能的助手单独创建一个组，并明确其使用边界，例如“仅用于查询技术文档和官方新闻”。

4.3 深度自定义：从修改代码到调整行为

“代码即配置”意味着最高程度的自由。以下是一些常见的自定义场景和操作思路：

场景一：修改触发词和助手名称 默认的触发词是 @Andy 。如果你不喜欢，可以直接让Claude Code修改代码。

1. 对助手说：“将触发词从 @Andy 改为 @小智 。”
2. Claude Code会定位到 src/router.ts 或相关消息解析逻辑中处理触发词的部分，进行修改。
3. 它可能还会提示你需要更新 groups/default/CLAUDE.md 中的助手自我介绍。
4. 修改完成后，Claude Code会告诉你需要重启服务。

场景二：为特定助手添加自定义技能 假设你想让“工作助手”拥有解析JIRA ticket的能力。

1. 在 groups/work/ 目录下创建 skills/ 子目录（如果不存在）。
2. 编写一个技能模块，例如 skills/jira-parser.ts ，实现调用JIRA API的功能。
3. 在 groups/work/CLAUDE.md 中，详细描述这个新工具的功能、输入输出格式。
4. 修改 container/agent-runner/ 中的工具加载逻辑，将你的自定义技能注册进去。（这个过程可以让Claude Code辅助完成）
5. 重建并重启该助手组的容器。

场景三：切换AI模型提供商 也许你想让某个助手使用本地的Ollama模型以节省成本或处理敏感数据。

1. 运行 /add-ollama-provider 技能。这会将Ollama集成代码添加到你的项目中。
2. 运行 /manage-providers 命令，为特定的助手组（例如 family-chat ）选择 ollama 作为提供商。
3. 在对应的 groups/family-chat/ 目录下，配置Ollama的连接信息（如本地API地址和模型名称）。
4. 重启该助手组。现在，这个组里的所有会话都会使用你本地运行的Ollama模型。

这种程度的定制化，使得NanoClaw从一个“产品”真正变成了属于你个人的“工具”。

5. 运维、调试与故障排查实录

5.1 日常运维命令与状态监控

NanoClaw没有华丽的Web控制面板，其运维理念是“通过对话管理一切”。

常用管理命令 ：

• @Andy list groups ：列出所有已配置的助手组及其状态。
• @Andy list tasks ：查看所有定时任务及其下次执行时间。
• @Andy pause task <task_id> ：暂停某个定时任务。
• @Andy restart group <group_name> ：重启某个助手组的容器（例如在修改了CLAUDE.md之后）。
• @Andy logs --tail=50 ：查看最近50行主进程日志。
• @Andy diagnose ：让助手自动检查系统健康状态（容器是否运行、数据库连接、API密钥有效性等）。

日志文件定位 ： 日志是排查问题的第一手资料。NanoClaw的日志主要分布在：

• 主进程日志 ：默认输出到控制台，也可以通过配置重定向到文件。包含路由、投递、调度等核心事件。
• 容器日志 ：每个助手容器的标准输出和错误流。可以通过 docker logs <container_id> 查看，里面包含了Claude API的调用详情和工具执行输出。
• SQLite数据库 ： data/nanoclaw.db 以及各会话的 inbound.db / outbound.db 。用 sqlite3 工具查看，可以精确追踪消息是否被正确写入和读取。

5.2 常见问题与解决方案速查表

以下是我在部署和使用过程中遇到的一些典型问题及解决方法。

问题现象	可能原因	排查步骤与解决方案
助手不响应消息	1. 主进程未运行。 2. 频道配对失效。 3. 助手容器崩溃。	1. 运行 pnpm start 查看主进程是否启动。 2. 在频道内发送 ping 测试，或检查频道适配器配置（如Telegram Bot Token）。 3. 运行 docker ps 查看容器状态，用 docker logs 查看崩溃原因。
定时任务未执行	1. 系统时间不同步。 2. host-sweep.ts 进程异常。 3. 任务定义有误。	1. 检查服务器时间。 2. 查看主进程日志中关于sweep的条目。 3. 使用 @Andy list tasks 检查任务详情，特别是Cron表达式。
Claude API调用失败	1. OneCLI凭证问题。 2. 网络问题。 3. API额度用尽。	1. 运行 onecli auth status 检查凭证状态。 2. 在容器内尝试 curl https://api.anthropic.com 测试连通性。 3. 登录Anthropic控制台检查使用量和额度。
容器启动失败	1. Docker守护进程未运行。 2. 镜像构建失败。 3. 端口冲突。	1. 运行 docker info 验证Docker。 2. 查看 docker build 的输出错误。 3. 检查 .env 中 PORT 是否被其他应用占用。
自定义代码修改后无效	1. TypeScript未重新编译。 2. 容器未使用新镜像。 3. 缓存问题。	1. 运行 pnpm build 重新编译。 2. 使用 @Andy restart group <name> 或 docker-compose up --build 重建容器。 3. 尝试清除 node_modules/.cache 和 dist 目录。
“技能”安装失败	1. 网络问题无法访问GitHub。 2. Claude Code上下文不足。 3. 分支名称错误。	1. 检查网络，或尝试手动从对应分支下载代码。 2. 对Claude Code提供更详细的错误信息，让它重试。 3. 确认技能名称正确，如 add-telegram 而非 add-telegram-bot 。

5.3 性能优化与安全加固建议

随着使用深入，你可能需要对你的NanoClaw实例进行调优。

性能方面 ：

• 容器资源限制 ：在 groups/*/docker-compose.yml 中，可以为每个容器设置CPU和内存限制，防止某个助手消耗过多资源影响宿主系统。

  deploy:
    resources:
      limits:
        cpus: '1.0'
        memory: 1G
  

• 会话清理 ：长期运行的会话可能导致 inbound.db / outbound.db 文件变大。可以定期归档或清理不活跃的会话。NanoClaw的主进程清扫（sweep）逻辑可以配置自动清理。
• 日志轮转 ：如果日志级别设为 debug ，日志量会很大。建议使用 logrotate 等工具配置日志轮转，避免磁盘被占满。

安全加固 ：

• 审查挂载卷 ：定期检查每个 docker-compose.yml 中的 volumes 映射，确保只挂载了必要的最小路径。 切忌使用 - /:/host 这种将根目录挂载进去的危险操作。
• 使用非root用户运行容器 ：在Dockerfile中，确保应用以非root用户运行。NanoClaw的官方镜像应该已经做了处理，但自定义构建时需注意。
• 网络隔离 ：考虑为每个助手组创建独立的Docker网络，进一步限制容器间的通信（如果它们不需要互通的话）。
• Apple Container（仅macOS） ：如果你在macOS上追求更轻量的隔离，可以运行 /convert-to-apple-container 技能，将运行时从Docker切换到macOS原生的Container技术，资源消耗会更低。

数据备份 ： 最重要的数据是 data/nanoclaw.db 这个中心数据库和各个 groups/ 目录下的配置。建议定期备份整个 data/ 目录和 groups/ 目录。由于使用的是SQLite，甚至可以直接用 sqlite3 data/nanoclaw.db .dump > backup.sql 进行逻辑备份。

经过以上步骤，你应该已经拥有了一个完全受控、高度定制且安全隔离的AI助手系统。NanoClaw的魅力在于，它把复杂留给了框架，把简单和掌控权还给了用户。你可以从一个简单的消息助手开始，逐步将它塑造成你的专属数字员工，而每一步，你都知道它的“心脏”是如何跳动的。这种透明和可控，在当今AI技术快速发展的背景下，显得尤为珍贵。