一个能够在各自容器中安全运行智能体的 AI 助手。轻量级，易于理解，并且完全可根据您的需求进行定制。

nanoclaw.dev  •   文档  •   中文  •   日语  •     •  

---

我为何构建 NanoClaw

OpenClaw 是一个令人印象深刻的项目，但如果将复杂的、我不了解的软件赋予对我生活的完全访问权限，我根本无法安心使用。OpenClaw 拥有近五十万行代码、53 个配置文件和 70 多个依赖项。其安全性仅停留在应用层（白名单、配对码），而非真正的操作系统级别隔离。所有内容都在一个共享内存的 Node 进程中运行。

NanoClaw 提供了相同的核心功能，但代码库小到足以让人完全理解：只有一个进程和少量文件。Claude 智能体运行在各自的 Linux 容器中，具备文件系统隔离，而不仅仅是通过权限检查来限制访问。

快速开始

gh repo fork qwibitai/nanoclaw --clone
cd nanoclaw
claude

不使用 GitHub CLI 的方法

1. 在 GitHub 上叉出 qwibitai/nanoclaw（点击“Fork”按钮）
2. git clone https://github.com/<your-username>/nanoclaw.git
3. cd nanoclaw
4. claude

然后运行 /setup。Claude Code 会处理一切：依赖项、身份验证、容器设置和服务配置。

注意：以 / 开头的命令（如 /setup、/add-whatsapp）是 Claude Code 技能。请在 claude CLI 提示符内输入，而不是在常规终端中。如果您尚未安装 Claude Code，请前往 claude.com/product/claude-code 获取。

理念

小到足以理解。 一个进程、几份源文件，没有微服务。如果您想彻底理解 NanoClaw 的整个代码库，只需让 Claude Code 带您逐行解读即可。

通过隔离确保安全。 智能体运行在 Linux 容器中（macOS 上为 Apple Container 或 Docker），它们只能看到被显式挂载的内容。即使提供 Bash 访问权限也十分安全，因为命令是在容器内部执行，而非在您的主机上。

专为个人用户打造。 NanoClaw 并非一个庞大的框架，而是能够精准适配每位用户需求的软件。它不会变得臃肿，而是设计成可定制的形态。您可以自行创建分支，并让 Claude Code 根据您的需求对其进行修改。

定制即代码变更。 无需繁琐的配置管理。想要不同的行为？直接修改代码即可。由于代码库足够小，因此可以放心地进行更改。

原生 AI 驱动。

• 无安装向导；Claude Code 将引导您完成设置。
• 无监控仪表盘；只需询问 Claude 当前状态即可。
• 无调试工具；描述问题后，Claude 即可为您修复。

技能优先于功能。 不再向核心代码库添加新功能（例如对 Telegram 的支持），而是由贡献者提交类似 /add-telegram 的 [Claude Code 技能]，这些技能可以直接应用于您的分支。最终您将获得干净的代码，恰好满足您的需求。

最佳平台，最佳模型。 NanoClaw 基于 Claude Agent SDK 构建，这意味着您直接运行的是 Claude Code。Claude Code 功能强大，其编码与问题解决能力使其能够灵活修改和扩展 NanoClaw，从而为每位用户量身定制解决方案。

支持的功能

• 多渠道消息传递：您可以通过 WhatsApp、Telegram、Discord、Slack 或 Gmail 与助手交流。使用 /add-whatsapp 或 /add-telegram 等技能添加更多渠道，也可同时运行多个渠道。
• 隔离的群组上下文：每个群组拥有独立的 CLAUDE.md 记忆、隔离的文件系统，并运行在专属容器沙盒中，仅挂载该群组的文件系统。
• 主通道：您的私人通道（自对话），用于管理员控制；所有群组完全隔离。
• 定时任务：定期运行的作业，可触发 Claude 并向您发送消息。
• 网络访问：从互联网搜索并获取内容。
• 容器隔离：智能体运行在 Docker（macOS/Linux）、Docker Sandboxes（微型 VM 隔离）或 Apple Container（macOS）中，实现沙盒化。
• 凭证安全：智能体绝不会持有原始 API 密钥。出站请求会通过 OneCLI 的 Agent Vault 路由，该工具会在请求时注入凭证，并对每个智能体实施策略和速率限制。
• 智能体集群：启动由专业智能体组成的团队，协作完成复杂任务。
• 可选集成：通过技能添加 Gmail（/add-gmail）等功能。

使用方法

使用触发词（默认为 @Andy）与您的助手对话：

@Andy 每工作日上午 9 点发送一次销售流程概览（可访问我的 Obsidian 库文件夹）
@Andy 每周五回顾过去一周的 Git 历史，若发现偏离则更新 README
@Andy 每周一上午 8 点，从 Hacker News 和 TechCrunch 搜集 AI 发展新闻，并向我发送简报

在主通道（您的自对话）中，您可以管理群组和任务：

@Andy 列出所有群组中的定时任务
@Andy 暂停周一的简报任务
@Andy 加入“家庭聊天”群组

自定义

NanoClaw 不使用配置文件。要进行更改，只需告诉 Claude Code 您的需求：

• “把触发词改成 @Bob”
• “以后回复时请更简短直接”
• “早上好时加入一句自定义问候语”
• “每周存储一次对话摘要”

或者运行 /customize 进行引导式修改。

由于代码库足够小，Claude 可以安全地对其进行修改。

贡献

不要添加功能，而是添加技能。

如果您想增加对 Telegram 的支持，不要直接向核心代码库提交 PR。相反，先 Fork NanoClaw，在分支上完成代码修改，然后提交 PR。我们会基于您的 PR 创建一个 skill/telegram 分支，其他用户可以将其合并到自己的分支中。

这样，用户只需在自己的分支上运行 /add-telegram，就能获得干净的代码，精确满足自身需求，而不会使系统变得臃肿以支持所有可能的用例。

技能征集

我们希望看到的技能：

通讯渠道

• /add-signal - 添加 Signal 作为通信渠道

需求

• macOS、Linux 或 Windows（通过 WSL2）
• Node.js 20+
• Claude Code
• Apple Container（macOS）或 Docker（macOS/Linux）

架构

通道 --> SQLite --> 轮询循环 --> 容器（Claude Agent SDK）--> 响应

单个 Node.js 进程。通道通过技能添加，并在启动时自动注册——编排器会连接所有已提供凭据的通道。代理在具有文件系统隔离的独立 Linux 容器中执行，仅可访问挂载的目录。每个组都有消息队列，并配备并发控制机制。进程间通信通过文件系统实现。

有关完整架构详情，请参阅文档网站。

关键文件：

• src/index.ts - 编排器：状态管理、消息循环、代理调用
• src/channels/registry.ts - 通道注册表（启动时自动注册）
• src/ipc.ts - IPC 监视与任务处理
• src/router.ts - 消息格式化与出站路由
• src/group-queue.ts - 带全局并发限制的组级队列
• src/container-runner.ts - 启动流式代理容器
• src/task-scheduler.ts - 执行计划任务
• src/db.ts - SQLite 操作（消息、群组、会话、状态）
• groups/*/CLAUDE.md - 每个群组的记忆

常见问题解答

为什么使用 Docker？

Docker 提供跨平台支持（macOS、Linux 甚至 Windows 通过 WSL2），并且拥有成熟的生态系统。在 macOS 上，您也可以选择切换到 Apple Container，通过 /convert-to-apple-container 实现更轻量级的原生运行时。为进一步增强隔离性，Docker Sandboxes 可以将每个容器运行在微型虚拟机中。

我可以在 Linux 或 Windows 上运行吗？

可以。Docker 是默认运行时，适用于 macOS、Linux 和 Windows（通过 WSL2）。只需运行 /setup 即可。

这安全吗？

代理运行在容器中，而非受应用层权限检查保护。它们只能访问明确挂载的目录。凭据永远不会进入容器——出站 API 请求会通过 OneCLI 的 Agent Vault 路由，该工具会在代理级别注入身份验证，并支持速率限制和访问策略。尽管如此，您仍需审查所运行的内容，但代码库足够小，您可以自行检查。完整的安全模型请参阅安全文档。

为什么没有配置文件？

我们不希望出现配置膨胀。每位用户都应自定义 NanoClaw，使代码完全符合其需求，而不是去配置一个通用系统。如果您更喜欢使用配置文件，可以让 Claude 来添加它们。

我可以使用第三方或开源模型吗？

可以。NanoClaw 支持任何兼容 Claude API 的模型端点。您可以在 .env 文件中设置以下环境变量：

ANTHROPIC_BASE_URL=https://your-api-endpoint.com
ANTHROPIC_AUTH_TOKEN=your-token-here

这样您就可以使用：

• 通过 Ollama 并借助 API 代理运行本地模型
• 在 Together AI、Fireworks 等平台上托管的开源模型
• 具有 Anthropic 兼容 API 的自定义模型部署

注意：为获得最佳兼容性，模型必须支持 Anthropic API 格式。

如何调试问题？

请教 Claude Code。“调度器为什么不运行？”“最近的日志里写了什么？”“为什么这条消息没有得到响应？”这就是支撑 NanoClaw 的 AI 原生方法。

为什么我的设置无法正常工作？

如果在设置过程中遇到问题，Claude 会尝试动态修复。若仍无效，请运行 claude，然后运行 /debug。如果 Claude 发现的问题可能影响其他用户，请提交 PR 修改 setup SKILL.md。

哪些更改会被合并到代码库中？

只有安全修复、错误修复以及明确的改进才会被接受并纳入基础配置。仅此而已。

其他内容（新功能、操作系统兼容性、硬件支持、增强功能）应作为技能贡献。这样做可以使基础系统保持最小化，并让每位用户都能根据自身需求定制安装，而无需继承不需要的功能。

社区

有问题？有想法？加入 Discord。

更改记录

有关破坏性变更，请参阅 CHANGELOG.md，或访问文档网站上的完整发布历史。

许可证

MIT

NanoClaw 快速上手指南

NanoClaw 是一个轻量级 AI 助手框架，专为在独立的 Linux 容器中安全运行 Agent 而设计。它代码精简、易于理解，并支持通过 Claude Code 进行完全定制化开发。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：macOS、Linux 或 Windows（需安装 WSL2）。
• Node.js：版本 20 或更高。
• 容器运行时：
  • macOS：推荐安装 Apple Container（更轻量），或使用 Docker Desktop。
  • Linux/Windows：必须安装 Docker Desktop。
• 核心工具：必须安装 Claude Code。
• 可选工具：GitHub CLI (gh) 可简化克隆步骤（若无则使用标准 git 命令）。

注意：本项目暂无官方国内镜像源，建议配置好网络环境后访问 GitHub 和 npm 源。

安装步骤

方法一：使用 GitHub CLI（推荐）

如果您已安装 gh 工具，可直接运行以下命令自动 Fork 并克隆项目：

gh repo fork qwibitai/nanoclaw --clone
cd nanoclaw
claude

方法二：手动安装

若未安装 GitHub CLI，请按以下步骤操作：

1. 在 GitHub 上 Fork qwibitai/nanoclaw 仓库。
2. 克隆您的仓库到本地：

   git clone https://github.com/<您的用户名>/nanoclaw.git
   

3. 进入项目目录：

   cd nanoclaw
   

4. 启动 Claude Code：

   claude
   

初始化配置

进入 claude 交互界面后，运行以下命令完成自动化设置：

/setup

说明：/setup 是 Claude Code Skill。该命令将自动处理依赖安装、身份认证、容器环境搭建及服务配置。请勿在普通终端中运行此命令。

基本使用

安装完成后，您可以通过设定的触发词（默认为 @Andy）与助手交互。NanoClaw 支持多频道消息（如 WhatsApp, Telegram, Discord 等），默认通过主频道（Self-chat）进行管理。

1. 下达指令示例

在 claude 对话框或已连接的聊天渠道中输入：

@Andy send an overview of the sales pipeline every weekday morning at 9am (has access to my Obsidian vault folder)
@Andy review the git history for the past week each Friday and update the README if there's drift
@Andy every Monday at 8am, compile news on AI developments from Hacker News and TechCrunch and message me a briefing

2. 管理任务与群组

在主频道中，您可以管理定时任务和隔离的群组上下文：

@Andy list all scheduled tasks across groups
@Andy pause the Monday briefing task
@Andy join the Family Chat group

3. 添加新功能（Skills）

NanoClaw 不通过配置文件修改行为，而是通过运行 Skills 来扩展功能。例如，添加 WhatsApp 或 Telegram 支持：

/add-whatsapp
/add-telegram

4. 个性化定制

直接告诉 Claude Code 您的需求，它会修改代码以适应您的习惯：

Change the trigger word to @Bob
Remember in the future to make responses shorter and more direct
Add a custom greeting when I say good morning

或者运行引导式定制命令：

/customize