nanocoai/nanoclaw · 上手攻略

• 仓库：nanocoai/nanoclaw
• 链接：https://github.com/nanocoai/nanoclaw
• 分类：ai / agent
• 作者：Jay
• 更新：2026-07-10

🎯 是什么

NanoClaw 是一个安全隔离的个人 AI 助手运行框架，让你在本地机器上运行一个 AI Agent，通过 Telegram、WhatsApp、Discord、Slack 等常用聊天软件与它对话。每个 Agent 运行在独立的 Linux 容器（Docker） 中，拥有自己的文件系统和工作区，实现真正的操作系统级隔离。

它的核心设计哲学是小到可以理解，安全靠隔离实现——整个代码库只有少量源文件，而不像 OpenClaw 那样有近 50 万行代码。Agent 默认由 Anthropic Claude Agent SDK（即 Claude Code）驱动，同时支持 OpenAI Codex、OpenRouter（Google/DeepSeek）等替代 Provider。

相当于：把 OpenClaw 的核心功能用几百行代码重新实现，塞进 Docker 容器，再配上你最习惯的聊天软件作为界面。

关键数字：Stars 30,177、周增 +49（2026-07）、代码库仅少量文件、容器级隔离

🧩 解决什么问题

⚡ 快速安装

系统要求

• macOS 或 Linux（Windows 用 WSL2）
• Node.js 20+、pnpm 10+（安装脚本会在缺失时自动安装）
• Docker Desktop（macOS/Windows）或 Docker Engine（Linux）
• Claude Code（用于安装过程中的错误恢复和所有定制操作）

安装步骤

# 1. 克隆仓库（建议用 nanoclaw-v2 作为目录名，与 v1 并存）
git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
cd nanoclaw-v2

# 2. 运行安装脚本（一步到位，自动安装依赖、配对第一个渠道）
bash nanoclaw.sh

nanoclaw.sh 会依次： 1. 检查并安装 Node.js、pnpm、Docker（缺失时） 2. 向 OneCLI 注册 Anthropic 凭据 3. 构建 Agent Docker 容器 4. 引导你配对第一个聊天渠道（Telegram / Discord / WhatsApp / CLI） 5. 如果任何步骤失败，自动调用 Claude Code 诊断并从断点恢复

⚠️ 务必在全新终端窗口中运行脚本，不要在已有的 Claude Code 会话内运行，因为脚本需要真实的交互式 shell I/O。

从 v1 迁移到 v2

git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
cd nanoclaw-v2
bash migrate-v2.sh

migrate-v2.sh 会找到你的 v1 安装目录，迁移状态数据，然后调用 Claude Code 完成需要人工判断的部分（所有者初始化、CLAUDE.local.md 清理等）。v1 目录保持不变。

🔧 核心用法

1. 添加聊天渠道

在 NanoClaw 运行的终端中（或发消息给 Agent），使用技能命令：

# 添加 Telegram
/add-telegram

# 添加 Discord
/add-discord

# 添加 WhatsApp
/add-whatsapp

# 添加 Slack
/add-slack

每个渠道适配器通过技能安装，不会往主干里塞代码，保持代码库精简。

2. 与 Agent 对话（触发词）

默认触发词：@Andy（可自定义）

@Andy 每个工作日早上 9 点给我发一份销售渠道概览
@Andy 每周五回顾过去一周的 git 历史，如果与 README 有出入就更新它
@Andy 每周一早上 8 点从 Hacker News 收集 AI 资讯并发给我一份简报

3. 管理 Agent 群组和计划任务

@Andy 列出所有群组里的计划任务
@Andy 暂停周一简报任务
@Andy 加入"家庭聊天"群组

4. 定制行为（改代码，不写配置）

直接告诉 Claude Code 你想要什么：

把触发词改成 @Bob
回答请更简短、更直接
我说"早上好"时加一个自定义问候
每周保存一次会话摘要

或者运行引导式定制：

/customize

5. 隔离模式配置

NanoClaw 支持三种隔离模式，通过 /manage-channels 按渠道选择：

6. 多 Agent 团队（Multi-Agent Swarm）

一个 Agent 可以派生同伴 Agent（各自有独立沙箱和记忆），协同完成复杂任务：

@Andy 派一个 Agent 研究竞品，另一个整理成表格发给我

7. 替代 Provider（可选）

默认用 Claude Code（Anthropic）。也可以安装其他 Provider：

# OpenAI Codex（需要 ChatGPT 订阅或 API Key）
/add-codex

# OpenRouter（Google、DeepSeek 等）
/add-opencode

# 本地开源模型（Ollama）
/add-ollama-provider

Provider 可以按 Agent 群组单独配置。

🏗 架构简析

消息应用 → 主机进程（路由器） → inbound.db
        → 容器（Bun + Claude Agent SDK） → outbound.db → 主机进程（投递） → 消息应用

• 单一 Node 主机进程：负责路由、数据库轮询、渠道适配器管理
• 每个会话两个 SQLite 文件（inbound.db / outbound.db），单一写入者，无跨挂载锁争用
• Agent 在 Docker 容器内运行：文件系统隔离，只能看到明确挂载的内容
• OneCLI Agent Vault：凭据在请求时注入，Agent 进程不持有明文密钥

核心文件（src/）： - index.ts —— 入口：数据库初始化、渠道适配器、投递轮询 - router.ts —— 入站路由：消息组 → Agent 组 → 会话 - delivery.ts —— 出站投递 - container-runner.ts —— 为每个 Agent 组启动容器 - db/ —— 中心数据库（用户、角色、Agent 组、消息组） - channels/ —— 渠道适配器基础设施（通过技能安装）

🧩 Agent 模板

创建可复用的 Agent 模板（包含指令 + MCP 工具 + 技能，不含密钥）：

ncl groups create --template .

模板保存到本地 templates/ 目录，可以从公共模板库复制。

⚠️ 坑与注意

1. 必须安装 Docker——NanoClaw 的核心价值就是容器隔离，没有 Docker 就没有隔离。Linux/macOS 原生支持，Windows 必须用 WSL2
2. Claude Code 是必需工具——安装、定制、/add-* 技能、错误恢复都需要 Claude Code。它不是可选依赖
3. Windows 支持仅限 WSL2——原生 Windows Docker 不支持，官方推荐 WSL2
4. WhatsApp 需要手机在线——WhatsApp 的 Baileys 适配器在首次配对时需要扫描 QR 码（手机在线）
5. 不是应用级安全——NanoClaw 比 OpenClaw 更安全，指的是容器级隔离；但如果你给 Agent 挂载了敏感目录，容器内的 Agent 仍然可以读写那些内容
6. 更新需要手动——NanoClaw 没有自动更新机制，每次更新需要 git pull 后重建
7. OneCLI 账号依赖——凭据托管在 OneCLI 上，Agent Vault 功能依赖这个外部服务

🔄 与同类对比

NanoClaw 最大优势：极简代码 + Docker 容器隔离 + Claude Code 原生驱动，安全可审计，同时保持极好的可定制性。缺点是需要自己托管、维护，有学习成本。

✅ 一句话推荐

如果你认可 OpenClaw 的愿景但无法信任一个 50 万行代码的单体应用，NanoClaw 用几百行代码实现了同样的核心功能——每个 Agent 在独立 Docker 容器中运行，拿它当日常助手或者定制成专属工作流，既安全又透明。