# NanoClaw 需求

项目创建者的原始需求和设计决策。

---

## 为什么存在这个项目

这是 OpenClaw（原名 ClawBot）的轻量、安全的替代方案。那个项目变得臃肿至极——4 到 5 个不同的进程运行不同的网关，无穷无尽的配置文件，无穷无尽的集成。它是一个安全噩梦，agent 不在隔离的进程中运行；有各种漏洞百出的变通方案试图阻止它们访问不应访问的系统部分。任何人都不可能真正理解整个代码库。运行它基本上就是在赌运气。

NanoClaw 为您提供核心功能，没有那些混乱。

---

## 理念

### 小到可以读懂

整个代码库应该是您可以阅读和理解的东西。一个 Node.js 进程。少量源文件。没有微服务，没有消息队列，没有抽象层。

### 通过真正的隔离实现安全

不是通过应用级权限系统试图阻止 agent 访问东西，agent 运行在实际的 Linux 容器中。隔离在操作系统层面。Agent 只能看到显式挂载的内容。Bash 访问是安全的，因为命令在容器内运行，而不是在您的 Mac 上。

### 为个人用户构建

这不是一个框架或平台。它是为每个用户量身定制的软件。您 fork 仓库，添加您想要的渠道（WhatsApp、Telegram、Discord、Slack、Gmail），最终得到做您所需事情的干净代码。

### 定制 = 代码修改

没有配置膨胀。如果您想要不同的行为，修改代码。代码库足够小，这样做既安全又实用。极小部分内容如触发词在配置中。其他一切——只需修改代码做您想做的事。

### AI 原生开发

我不需要安装向导——Claude Code 引导设置。我不需要监控仪表板——我问 Claude Code 发生了什么。我不需要精心设计的日志 UI——我让 Claude 读日志。我不需要调试工具——我描述问题，Claude 修复它。

代码库假设您有一个 AI 协作者。它不需要过度自文档化或自调试，因为 Claude 始终在那里。

### Skills 优先于功能

当人们贡献时，他们不应该在支持 WhatsApp 的同时再添加"Telegram 支持"。他们应该贡献一个 skill，如 `/add-telegram`，来改造代码库。用户 fork 仓库，运行 skills 进行定制，最终得到做他们所需事情的干净代码——而不是一个试图同时支持每个人用例的臃肿系统。

---

## RFS（Request for Skills）

我们希望看到贡献的 skills：

### 通信渠道
- `/add-signal` - 添加 Signal 作为渠道
- `/add-matrix` - 添加 Matrix 集成

> **注意：** Telegram、Slack、Discord、Gmail 和 Apple Container 的 skills 已经存在。完整列表请参见 [skills 文档](https://docs.nanoclaw.dev/integrations/skills-system)。

---

## 愿景

一个可通过消息访问的个人 Claude 助手，使用最少的自定义代码。

**核心组件：**
- **Claude Agent SDK** 作为核心 agent
- **容器（Containers）** 用于隔离的 agent 执行（Linux VM）
- **多渠道消息**（WhatsApp、Telegram、Discord、Slack、Gmail）——仅添加您需要的渠道
- **持久化记忆**——按对话和全局
- **定时任务**，运行 Claude 并能回复消息
- **Web 访问**，用于搜索和浏览
- **浏览器自动化**，通过 agent-browser

**实现方法：**
- 使用现有工具（渠道库、Claude Agent SDK、MCP 服务器）
- 最少的胶水代码
- 尽可能使用基于文件的系统（CLAUDE.md 用于记忆，目录用于群组）

---

## 架构决策

### 消息路由
- 路由器监听已连接的渠道，根据配置路由消息
- 仅处理来自已注册群组的消息
- 触发词：`@Andy` 前缀（不区分大小写），可通过 `ASSISTANT_NAME` 环境变量配置
- 未注册的群组完全被忽略

### 记忆系统
- **按群组记忆**：每个群组有一个带自己 `CLAUDE.md` 的目录
- **全局记忆**：根 `CLAUDE.md` 供所有群组读取，但只能从"主群组"（自我聊天）写入
- **文件**：群组可以在其目录中创建/读取文件并引用它们
- Agent 运行在群组的目录中，自动继承两个 CLAUDE.md 文件

### Session 管理
- 每个群组维护一个对话 session（通过 Claude Agent SDK）
- Sessions 在上下文过长时自动压缩，保留关键信息

### 容器隔离
- 所有 agent 在容器（轻量级 Linux VM）内运行
- 每次 agent 调用启动一个挂载了目录的容器
- 容器提供文件系统隔离——agent 只能看到已挂载的路径
- Bash 访问安全，因为命令在容器内运行，而非在宿主机上
- 通过 agent-browser 和容器中的 Chromium 进行浏览器自动化

### 定时任务
- 用户可以从任何群组要求 Claude 安排定期或一次性任务
- 任务在创建它们的群组上下文中作为完整 agent 运行
- 任务可以访问包括 Bash 在内的所有工具（在容器中安全）
- 任务可以选择性地通过 `send_message` 工具向群组发送消息，或静默完成
- 任务运行记录到数据库，包含持续时间和结果
- 调度类型：cron 表达式、间隔（毫秒）或一次性（ISO 时间戳）
- 从主群组：可以为任何群组安排任务，查看/管理所有任务
- 从其他群组：只能管理该群组的任务

### 群组管理
- 新群组通过主渠道显式添加
- 群组在 SQLite 中注册（通过主渠道或 IPC `register_group` 命令）
- 每个群组在 `groups/` 下获得一个专用目录
- 群组可以通过 `containerConfig` 挂载额外目录

### 主渠道权限
- 主渠道是管理员/控制群组（通常是自我聊天）
- 可以向全局记忆写入（`groups/CLAUDE.md`）
- 可以为任何群组安排定时任务
- 可以查看和管理所有群组的任务
- 可以为任何群组配置额外的目录挂载

---

## 集成点

### 渠道
- WhatsApp (baileys)、Telegram (grammy)、Discord (discord.js)、Slack (@slack/bolt)、Gmail (googleapis)
- 每个渠道存于单独的 fork 仓库中，通过 skills（例如 `/add-whatsapp`、`/add-telegram`）添加
- 消息存储在 SQLite 中，由路由器轮询
- 渠道在启动时自行注册——未配置的渠道被跳过并发出警告

### 调度器
- 内置调度器在宿主机上运行，启动容器执行任务
- 自定义 `nanoclaw` MCP 服务器（容器内）提供调度工具
- 工具：`schedule_task`、`list_tasks`、`pause_task`、`resume_task`、`cancel_task`、`send_message`
- 任务存储在 SQLite 中，带运行历史
- 调度器循环每分钟检查到期任务
- 任务在容器化的群组上下文中执行 Claude Agent SDK

### Web 访问
- 内置 WebSearch 和 WebFetch 工具
- 标准 Claude Agent SDK 能力

### 浏览器自动化
- 容器中的 agent-browser CLI 和 Chromium
- 基于快照的交互，带元素引用（@e1、@e2 等）
- 截图、PDF、视频录制
- 认证状态持久化

---

## 设置与定制

### 理念
- 最小化配置文件
- 通过 Claude Code 进行设置和定制
- 用户克隆仓库并运行 Claude Code 进行配置
- 每个用户得到精确匹配其需求的定制设置

### Skills
- `/setup` - 安装依赖，配置渠道，启动服务
- `/customize` - 通用 skill，用于添加能力
- `/update-nanoclaw` - 拉取上游更改，与定制合并

### 部署
- 运行在 macOS (launchd)、Linux (systemd) 或 Windows (WSL2) 上
- 单个 Node.js 进程处理一切

---

## 个人配置（参考）

以下是创建者的设置，存档于此供参考：

- **触发词**：`@Andy`（不区分大小写）
- **响应前缀**：`Andy:`
- **角色**：默认 Claude（无自定义个性）
- **主渠道**：自我聊天（在 WhatsApp 中给自己发消息）

---

## 项目名称

**NanoClaw** - 引用 Clawdbot（现为 OpenClaw）。