783 lines
30 KiB
Markdown
783 lines
30 KiB
Markdown
# NanoClaw 规范
|
||
|
||
一款个人 Claude 助手，支持多渠道、按会话持久化记忆、定时任务以及容器隔离的 agent（智能体）执行。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [架构](#架构)
|
||
2. [架构：渠道系统](#架构渠道系统)
|
||
3. [目录结构](#目录结构)
|
||
4. [配置](#配置)
|
||
5. [记忆系统](#记忆系统)
|
||
6. [会话管理](#session-管理)
|
||
7. [消息流转](#消息流转)
|
||
8. [命令](#命令)
|
||
9. [定时任务](#定时任务)
|
||
10. [MCP 服务器](#mcp-服务器)
|
||
11. [部署](#部署)
|
||
12. [安全考量](#安全考量)
|
||
|
||
---
|
||
|
||
## 架构
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────────┐
|
||
│ HOST（宿主机，macOS / Linux） │
|
||
│ （主 Node.js 进程） │
|
||
├──────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌──────────────────┐ ┌────────────────────┐ │
|
||
│ │ Channels │─────────────────▶│ SQLite 数据库 │ │
|
||
│ │ （渠道，启动时 │◀────────────────│ (messages.db) │ │
|
||
│ │ 自行注册） │ 存储/发送 └─────────┬──────────┘ │
|
||
│ └──────────────────┘ │ │
|
||
│ │ │
|
||
│ ┌─────────────────────────────────────────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌──────────────────┐ ┌──────────────────┐ ┌───────────────┐ │
|
||
│ │ Message Loop │ │ Scheduler Loop │ │ IPC Watcher │ │
|
||
│ │ （消息轮询循环） │ │ （调度器循环） │ │ （IPC 监听器） │ │
|
||
│ └────────┬─────────┘ └────────┬─────────┘ └───────────────┘ │
|
||
│ │ │ │
|
||
│ └───────────┬───────────┘ │
|
||
│ │ 启动容器 │
|
||
│ ▼ │
|
||
├──────────────────────────────────────────────────────────────────────┤
|
||
│ CONTAINER（容器，Linux VM） │
|
||
├──────────────────────────────────────────────────────────────────────┤
|
||
│ ┌──────────────────────────────────────────────────────────────┐ │
|
||
│ │ AGENT RUNNER（智能体运行器） │ │
|
||
│ │ │ │
|
||
│ │ 工作目录: /workspace/group（从宿主机挂载） │ │
|
||
│ │ 卷挂载: │ │
|
||
│ │ • groups/{name}/ → /workspace/group │ │
|
||
│ │ • groups/global/ → /workspace/global/（仅非主群组） │ │
|
||
│ │ • data/sessions/{group}/.claude/ → /home/node/.claude/ │ │
|
||
│ │ • 额外目录 → /workspace/extra/* │ │
|
||
│ │ │ │
|
||
│ │ 工具（所有群组）: │ │
|
||
│ │ • Bash（安全——在容器内沙箱化！） │ │
|
||
│ │ • Read, Write, Edit, Glob, Grep（文件操作） │ │
|
||
│ │ • WebSearch, WebFetch（互联网访问） │ │
|
||
│ │ • agent-browser（浏览器自动化） │ │
|
||
│ │ • mcp__nanoclaw__*（通过 IPC 的调度器工具） │ │
|
||
│ │ │ │
|
||
│ └──────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
└───────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 技术栈
|
||
|
||
| 组件 | 技术 | 用途 |
|
||
|-----------|------------|---------|
|
||
| Channel System | Channel registry (`src/channels/registry.ts`) | 渠道在启动时自行注册 |
|
||
| Message Storage | SQLite (better-sqlite3) | 存储消息供轮询 |
|
||
| Container Runtime | Containers（Linux VM） | 用于 agent 执行的隔离环境 |
|
||
| Agent | @anthropic-ai/claude-agent-sdk (0.2.29) | 带工具和 MCP 服务器的 Claude 运行环境 |
|
||
| Browser Automation | agent-browser + Chromium | Web 交互与截图 |
|
||
| Runtime | Node.js 20+ | 用于路由和调度的宿主机进程 |
|
||
|
||
---
|
||
|
||
## 架构：渠道系统
|
||
|
||
核心不含任何内置渠道——每个渠道（WhatsApp、Telegram、Slack、Discord、Gmail）作为 [Claude Code skill](https://code.claude.com/docs/en/skills) 安装，将渠道代码添加到您的 fork 中。渠道在启动时自行注册；已安装但缺少凭证的渠道会发出 WARN 日志并被跳过。
|
||
|
||
### 系统图
|
||
|
||
```mermaid
|
||
graph LR
|
||
subgraph Channels["渠道"]
|
||
WA[WhatsApp]
|
||
TG[Telegram]
|
||
SL[Slack]
|
||
DC[Discord]
|
||
New["其他渠道 (Signal, Gmail...)"]
|
||
end
|
||
|
||
subgraph Orchestrator["编排器 — index.ts"]
|
||
ML[Message Loop]
|
||
GQ[Group Queue]
|
||
RT[Router]
|
||
TS[Task Scheduler]
|
||
DB[(SQLite)]
|
||
end
|
||
|
||
subgraph Execution["容器执行"]
|
||
CR[Container Runner]
|
||
LC["Linux Container"]
|
||
IPC[IPC Watcher]
|
||
end
|
||
|
||
%% Flow
|
||
WA & TG & SL & DC & New -->|onMessage| ML
|
||
ML --> GQ
|
||
GQ -->|并发控制| CR
|
||
CR --> LC
|
||
LC -->|文件系统 IPC| IPC
|
||
IPC -->|任务与消息| RT
|
||
RT -->|Channel.sendMessage| Channels
|
||
TS -->|到期任务| CR
|
||
|
||
%% DB Connections
|
||
DB <--> ML
|
||
DB <--> TS
|
||
|
||
%% Styling for the dynamic channel
|
||
style New stroke-dasharray: 5 5,stroke-width:2px
|
||
```
|
||
|
||
### 渠道注册表
|
||
|
||
渠道系统建立在 `src/channels/registry.ts` 中的工厂注册表之上：
|
||
|
||
```typescript
|
||
export type ChannelFactory = (opts: ChannelOpts) => Channel | null;
|
||
|
||
const registry = new Map<string, ChannelFactory>();
|
||
|
||
export function registerChannel(name: string, factory: ChannelFactory): void {
|
||
registry.set(name, factory);
|
||
}
|
||
|
||
export function getChannelFactory(name: string): ChannelFactory | undefined {
|
||
return registry.get(name);
|
||
}
|
||
|
||
export function getRegisteredChannelNames(): string[] {
|
||
return [...registry.keys()];
|
||
}
|
||
```
|
||
|
||
每个工厂接收 `ChannelOpts`（包含回调 `onMessage`、`onChatMetadata` 和 `registeredGroups`），并返回一个 `Channel` 实例，如果该渠道的凭证未配置则返回 `null`。
|
||
|
||
### 渠道接口
|
||
|
||
每个渠道实现此接口（定义在 `src/types.ts` 中）：
|
||
|
||
```typescript
|
||
interface Channel {
|
||
name: string;
|
||
connect(): Promise<void>;
|
||
sendMessage(jid: string, text: string): Promise<void>;
|
||
isConnected(): boolean;
|
||
ownsJid(jid: string): boolean;
|
||
disconnect(): Promise<void>;
|
||
setTyping?(jid: string, isTyping: boolean): Promise<void>;
|
||
syncGroups?(force: boolean): Promise<void>;
|
||
}
|
||
```
|
||
|
||
### 自行注册模式
|
||
|
||
渠道使用 barrel 导入模式自行注册：
|
||
|
||
1. 每个渠道 skill 向 `src/channels/` 添加一个文件（例如 `whatsapp.ts`、`telegram.ts`），在模块加载时调用 `registerChannel()`：
|
||
|
||
```typescript
|
||
// src/channels/whatsapp.ts
|
||
import { registerChannel, ChannelOpts } from './registry.js';
|
||
|
||
export class WhatsAppChannel implements Channel { /* ... */ }
|
||
|
||
registerChannel('whatsapp', (opts: ChannelOpts) => {
|
||
// 如果凭证缺失则返回 null
|
||
if (!existsSync(authPath)) return null;
|
||
return new WhatsAppChannel(opts);
|
||
});
|
||
```
|
||
|
||
2. barrel 文件 `src/channels/index.ts` 导入所有渠道模块，触发注册：
|
||
|
||
```typescript
|
||
import './whatsapp.js';
|
||
import './telegram.js';
|
||
// ... 每个 skill 在此处添加其导入
|
||
```
|
||
|
||
3. 启动时，编排器（`src/index.ts`）循环遍历已注册的渠道，连接返回有效实例的渠道：
|
||
|
||
```typescript
|
||
for (const name of getRegisteredChannelNames()) {
|
||
const factory = getChannelFactory(name);
|
||
const channel = factory?.(channelOpts);
|
||
if (channel) {
|
||
await channel.connect();
|
||
channels.push(channel);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 关键文件
|
||
|
||
| 文件 | 用途 |
|
||
|------|---------|
|
||
| `src/channels/registry.ts` | 渠道工厂注册表 |
|
||
| `src/channels/index.ts` | 触发渠道自行注册的 barrel 导入 |
|
||
| `src/types.ts` | `Channel` 接口、`ChannelOpts`、消息类型 |
|
||
| `src/index.ts` | 编排器——实例化渠道、运行消息循环 |
|
||
| `src/router.ts` | 查找 JID 所属的渠道，格式化消息 |
|
||
|
||
### 添加新渠道
|
||
|
||
要添加新渠道，请向 `.claude/skills/add-<name>/` 贡献一个 skill，该 skill 需要：
|
||
|
||
1. 添加一个 `src/channels/<name>.ts` 文件，实现 `Channel` 接口
|
||
2. 在模块加载时调用 `registerChannel(name, factory)`
|
||
3. 如果凭证缺失，工厂返回 `null`
|
||
4. 向 `src/channels/index.ts` 添加一条导入行
|
||
|
||
请参考已有的 skills（`/add-whatsapp`、`/add-telegram`、`/add-slack`、`/add-discord`、`/add-gmail`）了解模式。
|
||
|
||
---
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
nanoclaw/
|
||
├── CLAUDE.md # Claude Code 的项目上下文
|
||
├── docs/
|
||
│ ├── SPEC.md # 本规范文档
|
||
│ ├── REQUIREMENTS.md # 架构决策
|
||
│ └── SECURITY.md # 安全模型
|
||
├── README.md # 用户文档
|
||
├── package.json # Node.js 依赖
|
||
├── tsconfig.json # TypeScript 配置
|
||
├── .mcp.json # MCP 服务器配置（参考）
|
||
├── .gitignore
|
||
│
|
||
├── src/
|
||
│ ├── index.ts # 编排器：状态、消息循环、agent 调用
|
||
│ ├── channels/
|
||
│ │ ├── registry.ts # 渠道工厂注册表
|
||
│ │ └── index.ts # 渠道自行注册的 barrel 导入
|
||
│ ├── ipc.ts # IPC 监听器与任务处理
|
||
│ ├── router.ts # 消息格式化和出站路由
|
||
│ ├── config.ts # 配置常量
|
||
│ ├── types.ts # TypeScript 接口（包含 Channel）
|
||
│ ├── logger.ts # Pino 日志器配置
|
||
│ ├── db.ts # SQLite 数据库初始化与查询
|
||
│ ├── group-queue.ts # 带全局并发限制的按群组队列
|
||
│ ├── mount-security.ts # 容器挂载白名单验证
|
||
│ ├── whatsapp-auth.ts # 独立的 WhatsApp 认证
|
||
│ ├── task-scheduler.ts # 到期时运行定时任务
|
||
│ └── container-runner.ts # 在容器中启动 agent
|
||
│
|
||
├── container/
|
||
│ ├── Dockerfile # 容器镜像（以 'node' 用户运行，包含 Claude Code CLI）
|
||
│ ├── build.sh # 容器镜像的构建脚本
|
||
│ ├── agent-runner/ # 在容器内运行的代码
|
||
│ │ ├── package.json
|
||
│ │ ├── tsconfig.json
|
||
│ │ └── src/
|
||
│ │ ├── index.ts # 入口点（查询循环、IPC 轮询、会话恢复）
|
||
│ │ └── ipc-mcp-stdio.ts # 基于 stdio 的 MCP 服务器，用于宿主机通信
|
||
│ └── skills/
|
||
│ └── agent-browser.md # 浏览器自动化 skill
|
||
│
|
||
├── dist/ # 编译后的 JavaScript（gitignored）
|
||
│
|
||
├── .claude/
|
||
│ └── skills/
|
||
│ ├── setup/SKILL.md # /setup - 首次安装
|
||
│ ├── customize/SKILL.md # /customize - 添加能力
|
||
│ ├── debug/SKILL.md # /debug - 容器调试
|
||
│ ├── add-telegram/SKILL.md # /add-telegram - Telegram 渠道
|
||
│ ├── add-gmail/SKILL.md # /add-gmail - Gmail 集成
|
||
│ ├── add-voice-transcription/ # /add-voice-transcription - Whisper
|
||
│ ├── x-integration/SKILL.md # /x-integration - X/Twitter
|
||
│ ├── convert-to-apple-container/ # /convert-to-apple-container - Apple Container 运行时
|
||
│ └── add-parallel/SKILL.md # /add-parallel - 并行 agent
|
||
│
|
||
├── groups/
|
||
│ ├── CLAUDE.md # 全局记忆（所有群组都读取此文件）
|
||
│ ├── {channel}_main/ # 主控制渠道（例如 whatsapp_main/）
|
||
│ │ ├── CLAUDE.md # 主渠道记忆
|
||
│ │ └── logs/ # 任务执行日志
|
||
│ └── {channel}_{group-name}/ # 按群组目录（注册时创建）
|
||
│ ├── CLAUDE.md # 群组专属记忆
|
||
│ ├── logs/ # 此群组的任务日志
|
||
│ └── *.md # agent 创建的文件
|
||
│
|
||
├── store/ # 本地数据（gitignored）
|
||
│ ├── auth/ # WhatsApp 认证状态
|
||
│ └── messages.db # SQLite 数据库（messages、chats、scheduled_tasks、task_run_logs、registered_groups、sessions、router_state）
|
||
│
|
||
├── data/ # 应用状态（gitignored）
|
||
│ ├── sessions/ # 按群组会话数据（.claude/ 目录，含 JSONL 对话记录）
|
||
│ ├── env/env # .env 的副本，用于挂载到容器
|
||
│ └── ipc/ # 容器 IPC（messages/、tasks/）
|
||
│
|
||
├── logs/ # 运行时日志（gitignored）
|
||
│ ├── nanoclaw.log # 宿主机 stdout
|
||
│ └── nanoclaw.error.log # 宿主机 stderr
|
||
│ # 注意：每个容器的日志在 groups/{folder}/logs/container-*.log
|
||
│
|
||
└── launchd/
|
||
└── com.nanoclaw.plist # macOS 服务配置
|
||
```
|
||
|
||
---
|
||
|
||
## 配置
|
||
|
||
配置常量在 `src/config.ts` 中定义：
|
||
|
||
```typescript
|
||
import path from 'path';
|
||
|
||
export const ASSISTANT_NAME = process.env.ASSISTANT_NAME || 'Andy';
|
||
|
||
// 路径必须是绝对路径（容器挂载需要）
|
||
const PROJECT_ROOT = process.cwd();
|
||
export const STORE_DIR = path.resolve(PROJECT_ROOT, 'store');
|
||
export const GROUPS_DIR = path.resolve(PROJECT_ROOT, 'groups');
|
||
export const DATA_DIR = path.resolve(PROJECT_ROOT, 'data');
|
||
|
||
// 容器配置
|
||
export const CONTAINER_IMAGE = process.env.CONTAINER_IMAGE || 'nanoclaw-agent:latest';
|
||
export const CONTAINER_TIMEOUT = parseInt(process.env.CONTAINER_TIMEOUT || '1800000', 10); // 默认30分钟
|
||
export const IDLE_TIMEOUT = parseInt(process.env.IDLE_TIMEOUT || '1800000', 10); // 30分钟——最后一次结果后保持容器存活
|
||
export const MAX_CONCURRENT_CONTAINERS = Math.max(1, parseInt(process.env.MAX_CONCURRENT_CONTAINERS || '5', 10) || 5);
|
||
|
||
export const TRIGGER_PATTERN = new RegExp(`^@${ASSISTANT_NAME}\\b`, 'i');
|
||
```
|
||
|
||
**注意：** 路径必须是绝对路径，容器卷挂载才能正常工作。
|
||
|
||
### 容器配置
|
||
|
||
群组可以通过 SQLite `registered_groups` 表中的 `containerConfig`（以 JSON 形式存储在 `container_config` 列中）挂载额外目录。注册示例：
|
||
|
||
```typescript
|
||
setRegisteredGroup("1234567890@g.us", {
|
||
name: "Dev Team",
|
||
folder: "whatsapp_dev-team",
|
||
trigger: "@Andy",
|
||
added_at: new Date().toISOString(),
|
||
containerConfig: {
|
||
additionalMounts: [
|
||
{
|
||
hostPath: "~/projects/webapp",
|
||
containerPath: "webapp",
|
||
readonly: false,
|
||
},
|
||
],
|
||
timeout: 600000,
|
||
},
|
||
});
|
||
```
|
||
|
||
目录命名遵循 `{channel}_{group-name}` 约定（例如 `whatsapp_family-chat`、`telegram_dev-team`）。主群组在注册时会设置 `isMain: true`。
|
||
|
||
额外挂载在容器内显示为 `/workspace/extra/{containerPath}`。
|
||
|
||
**挂载语法说明：** 读写挂载使用 `-v host:container`，但只读挂载需要使用 `--mount "type=bind,source=...,target=...,readonly"`（`:ro` 后缀可能不是所有运行时都支持）。
|
||
|
||
### Claude 认证
|
||
|
||
在项目根目录的 `.env` 文件中配置认证。有两种选择：
|
||
|
||
**选项1：Claude 订阅（OAuth token）**
|
||
```bash
|
||
CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
|
||
```
|
||
如果您已登录 Claude Code，可以从 `~/.claude/.credentials.json` 中提取 token。
|
||
|
||
**选项2：按用量付费的 API Key**
|
||
```bash
|
||
ANTHROPIC_API_KEY=sk-ant-api03-...
|
||
```
|
||
|
||
只有认证变量（`CLAUDE_CODE_OAUTH_TOKEN` 和 `ANTHROPIC_API_KEY`）从 `.env` 中提取并写入 `data/env/env`，然后挂载到容器中的 `/workspace/env-dir/env`，由入口点脚本加载。这确保 `.env` 中的其他环境变量不会暴露给 agent。此变通方案是必要的，因为某些容器运行时在使用 `-i`（带管道 stdin 的交互模式）时会丢失 `-e` 环境变量。
|
||
|
||
### 更改助手名称
|
||
|
||
设置 `ASSISTANT_NAME` 环境变量：
|
||
|
||
```bash
|
||
ASSISTANT_NAME=Bot pnpm start
|
||
```
|
||
|
||
或编辑 `src/config.ts` 中的默认值。这会更改：
|
||
- 触发模式（消息必须以 `@YourName` 开头）
|
||
- 响应前缀（自动添加 `YourName:`）
|
||
|
||
### launchd 中的占位符值
|
||
|
||
包含 `{{PLACEHOLDER}}` 值的文件需要进行配置：
|
||
- `{{PROJECT_ROOT}}` - nanoclaw 安装的绝对路径
|
||
- `{{NODE_PATH}}` - node 二进制文件的路径（通过 `which node` 检测）
|
||
- `{{HOME}}` - 用户的主目录
|
||
|
||
---
|
||
|
||
## 记忆系统
|
||
|
||
NanoClaw 使用基于 CLAUDE.md 文件的层级记忆系统。
|
||
|
||
### 记忆层级
|
||
|
||
| 层级 | 位置 | 读取者 | 写入者 | 用途 |
|
||
|-------|----------|---------|------------|---------|
|
||
| **全局** | `groups/CLAUDE.md` | 所有群组 | 仅主群组 | 在所有对话之间共享的偏好、事实、上下文 |
|
||
| **群组** | `groups/{name}/CLAUDE.md` | 该群组 | 该群组 | 群组专属上下文、对话记忆 |
|
||
| **文件** | `groups/{name}/*.md` | 该群组 | 该群组 | 对话过程中创建的笔记、研究、文档 |
|
||
|
||
### 记忆如何运作
|
||
|
||
1. **Agent 上下文加载**
|
||
- Agent 运行在 `groups/{group-name}/` 作为 `cwd`
|
||
- Claude Agent SDK 使用 `settingSources: ['project']` 自动加载：
|
||
- `../CLAUDE.md`（上级目录 = 全局记忆）
|
||
- `./CLAUDE.md`（当前目录 = 群组记忆）
|
||
|
||
2. **写入记忆**
|
||
- 当用户说"记住这个"，agent 写入 `./CLAUDE.md`
|
||
- 当用户说"全局记住这个"（仅主渠道），agent 写入 `../CLAUDE.md`
|
||
- Agent 可以在群组目录中创建 `notes.md`、`research.md` 等文件
|
||
|
||
3. **主渠道权限**
|
||
- 只有"主"群组（自我聊天）可以向全局记忆写入
|
||
- 主群组可以管理已注册的群组并为任何群组安排定时任务
|
||
- 主群组可以为任何群组配置额外的目录挂载
|
||
- 所有群组都有 Bash 访问权限（安全，因为在容器内运行）
|
||
|
||
---
|
||
|
||
## Session 管理
|
||
|
||
Session 实现了对话连续性——Claude 会记住你们之前谈过的内容。
|
||
|
||
### Session 如何运作
|
||
|
||
1. 每个群组在 SQLite 中有一个 session ID（`sessions` 表，按 `group_folder` 索引）
|
||
2. Session ID 传递给 Claude Agent SDK 的 `resume` 选项
|
||
3. Claude 以完整上下文继续对话
|
||
4. Session 对话记录以 JSONL 文件形式存储在 `data/sessions/{group}/.claude/`
|
||
|
||
---
|
||
|
||
## 消息流转
|
||
|
||
### 入站消息流程
|
||
|
||
```
|
||
1. 用户通过任何已连接的渠道发送消息
|
||
│
|
||
▼
|
||
2. 渠道接收消息（例如 WhatsApp 使用 Baileys，Telegram 使用 Bot API）
|
||
│
|
||
▼
|
||
3. 消息存入 SQLite（store/messages.db）
|
||
│
|
||
▼
|
||
4. 消息循环轮询 SQLite（每2秒）
|
||
│
|
||
▼
|
||
5. 路由检查：
|
||
├── chat_jid 是否在已注册群组中（SQLite）？→ 否：忽略
|
||
└── 消息是否匹配触发模式？→ 否：存储但不处理
|
||
│
|
||
▼
|
||
6. 路由追上对话：
|
||
├── 获取自上次 agent 交互以来的所有消息
|
||
├── 使用时间戳和发送者名称格式化
|
||
└── 构建包含完整对话上下文的 prompt
|
||
│
|
||
▼
|
||
7. 路由调用 Claude Agent SDK：
|
||
├── cwd: groups/{group-name}/
|
||
├── prompt: 对话历史 + 当前消息
|
||
├── resume: session_id（用于连续性）
|
||
└── mcpServers: nanoclaw（调度器）
|
||
│
|
||
▼
|
||
8. Claude 处理消息：
|
||
├── 读取 CLAUDE.md 文件获取上下文
|
||
└── 按需使用工具（搜索、邮件等）
|
||
│
|
||
▼
|
||
9. 路由在响应前添加助手名称前缀，并通过所属渠道发送
|
||
│
|
||
▼
|
||
10. 路由更新最后 agent 时间戳并保存 session ID
|
||
```
|
||
|
||
### 触发词匹配
|
||
|
||
消息必须以触发模式开头（默认：`@Andy`）：
|
||
- `@Andy what's the weather?` → ✅ 触发 Claude
|
||
- `@andy help me` → ✅ 触发（不区分大小写）
|
||
- `Hey @Andy` → ❌ 忽略（触发词不在开头）
|
||
- `What's up?` → ❌ 忽略（无触发词）
|
||
|
||
### 对话追上
|
||
|
||
当触发消息到达时，agent 会收到自上次在该聊天中交互以来的所有消息。每条消息都带有时间戳和发送者名称：
|
||
|
||
```
|
||
[Jan 31 2:32 PM] John: hey everyone, should we do pizza tonight?
|
||
[Jan 31 2:33 PM] Sarah: sounds good to me
|
||
[Jan 31 2:35 PM] John: @Andy what toppings do you recommend?
|
||
```
|
||
|
||
这使得 agent 能够理解对话上下文，即使它没有在每条消息中被提及。
|
||
|
||
---
|
||
|
||
## 命令
|
||
|
||
### 任何群组中可用的命令
|
||
|
||
| 命令 | 示例 | 效果 |
|
||
|---------|---------|--------|
|
||
| `@Assistant [message]` | `@Andy what's the weather?` | 与 Claude 对话 |
|
||
|
||
### 仅主渠道可用的命令
|
||
|
||
| 命令 | 示例 | 效果 |
|
||
|---------|---------|--------|
|
||
| `@Assistant add group "Name"` | `@Andy add group "Family Chat"` | 注册新群组 |
|
||
| `@Assistant remove group "Name"` | `@Andy remove group "Work Team"` | 取消注册群组 |
|
||
| `@Assistant list groups` | `@Andy list groups` | 显示已注册群组 |
|
||
| `@Assistant remember [fact]` | `@Andy remember I prefer dark mode` | 添加到全局记忆 |
|
||
|
||
---
|
||
|
||
## 定时任务
|
||
|
||
NanoClaw 内置调度器，将任务作为完整 agent 在其群组上下文中运行。
|
||
|
||
### 调度如何运作
|
||
|
||
1. **群组上下文**：在群组中创建的任务使用该群组的工作目录和记忆运行
|
||
2. **完整的 Agent 能力**：定时任务可以访问所有工具（WebSearch、文件操作等）
|
||
3. **可选的消息发送**：任务可以使用 `send_message` 工具向其群组发送消息，也可以静默完成
|
||
4. **主渠道权限**：主渠道可以为任何群组安排任务并查看所有任务
|
||
|
||
### 调度类型
|
||
|
||
| 类型 | 值格式 | 示例 |
|
||
|------|--------------|---------|
|
||
| `cron` | Cron 表达式 | `0 9 * * 1`（每周一上午9点） |
|
||
| `interval` | 毫秒 | `3600000`（每小时） |
|
||
| `once` | ISO 时间戳 | `2024-12-25T09:00:00Z` |
|
||
|
||
### 创建任务
|
||
|
||
```
|
||
User: @Andy remind me every Monday at 9am to review the weekly metrics
|
||
|
||
Claude: [调用 mcp__nanoclaw__schedule_task]
|
||
{
|
||
"prompt": "Send a reminder to review weekly metrics. Be encouraging!",
|
||
"schedule_type": "cron",
|
||
"schedule_value": "0 9 * * 1"
|
||
}
|
||
|
||
Claude: Done! I'll remind you every Monday at 9am.
|
||
```
|
||
|
||
### 一次性任务
|
||
|
||
```
|
||
User: @Andy at 5pm today, send me a summary of today's emails
|
||
|
||
Claude: [调用 mcp__nanoclaw__schedule_task]
|
||
{
|
||
"prompt": "Search for today's emails, summarize the important ones, and send the summary to the group.",
|
||
"schedule_type": "once",
|
||
"schedule_value": "2024-01-31T17:00:00Z"
|
||
}
|
||
```
|
||
|
||
### 管理任务
|
||
|
||
在任何群组中：
|
||
- `@Andy list my scheduled tasks` - 查看此群组的任务
|
||
- `@Andy pause task [id]` - 暂停任务
|
||
- `@Andy resume task [id]` - 恢复暂停的任务
|
||
- `@Andy cancel task [id]` - 删除任务
|
||
|
||
在主渠道中：
|
||
- `@Andy list all tasks` - 查看所有群组的任务
|
||
- `@Andy schedule task for "Family Chat": [prompt]` - 为其他群组安排任务
|
||
|
||
---
|
||
|
||
## MCP 服务器
|
||
|
||
### NanoClaw MCP（内置）
|
||
|
||
`nanoclaw` MCP 服务器在每次 agent 调用时动态创建，带有当前群组的上下文。
|
||
|
||
**可用工具：**
|
||
| 工具 | 用途 |
|
||
|------|---------|
|
||
| `schedule_task` | 安排定期或一次性任务 |
|
||
| `list_tasks` | 显示任务（本群组的任务，主群组则显示全部） |
|
||
| `get_task` | 获取任务详情和运行历史 |
|
||
| `update_task` | 修改任务的 prompt 或调度 |
|
||
| `pause_task` | 暂停任务 |
|
||
| `resume_task` | 恢复暂停的任务 |
|
||
| `cancel_task` | 删除任务 |
|
||
| `send_message` | 通过群组的渠道发送消息 |
|
||
|
||
---
|
||
|
||
## 部署
|
||
|
||
NanoClaw 作为单个 macOS launchd 服务运行。
|
||
|
||
### 启动序列
|
||
|
||
NanoClaw 启动时会：
|
||
1. **确保容器运行时正在运行**——如需要自动启动；终止前次运行遗留的 NanoClaw 孤儿容器
|
||
2. 初始化 SQLite 数据库（如果存在 JSON 文件则从中迁移）
|
||
3. 从 SQLite 加载状态（已注册群组、sessions、路由状态）
|
||
4. **连接渠道**——遍历已注册渠道，实例化有凭证的渠道，对每个调用 `connect()`
|
||
5. 一旦至少有一个渠道连接：
|
||
- 启动调度器循环
|
||
- 启动用于容器消息的 IPC 监听器
|
||
- 设置按群组队列及 `processGroupMessages`
|
||
- 恢复关闭前未处理的消息
|
||
- 启动消息轮询循环
|
||
|
||
### 服务：com.nanoclaw
|
||
|
||
**launchd/com.nanoclaw.plist:**
|
||
```xml
|
||
<?xml version="1.0" encoding="UTF-8"?>
|
||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "...">
|
||
<plist version="1.0">
|
||
<dict>
|
||
<key>Label</key>
|
||
<string>com.nanoclaw</string>
|
||
<key>ProgramArguments</key>
|
||
<array>
|
||
<string>{{NODE_PATH}}</string>
|
||
<string>{{PROJECT_ROOT}}/dist/index.js</string>
|
||
</array>
|
||
<key>WorkingDirectory</key>
|
||
<string>{{PROJECT_ROOT}}</string>
|
||
<key>RunAtLoad</key>
|
||
<true/>
|
||
<key>KeepAlive</key>
|
||
<true/>
|
||
<key>EnvironmentVariables</key>
|
||
<dict>
|
||
<key>PATH</key>
|
||
<string>{{HOME}}/.local/bin:/usr/local/bin:/usr/bin:/bin</string>
|
||
<key>HOME</key>
|
||
<string>{{HOME}}</string>
|
||
<key>ASSISTANT_NAME</key>
|
||
<string>Andy</string>
|
||
</dict>
|
||
<key>StandardOutPath</key>
|
||
<string>{{PROJECT_ROOT}}/logs/nanoclaw.log</string>
|
||
<key>StandardErrorPath</key>
|
||
<string>{{PROJECT_ROOT}}/logs/nanoclaw.error.log</string>
|
||
</dict>
|
||
</plist>
|
||
```
|
||
|
||
### 管理服务
|
||
|
||
```bash
|
||
# 安装服务
|
||
cp launchd/com.nanoclaw.plist ~/Library/LaunchAgents/
|
||
|
||
# 启动服务
|
||
launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
|
||
|
||
# 停止服务
|
||
launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
|
||
|
||
# 检查状态
|
||
launchctl list | grep nanoclaw
|
||
|
||
# 查看日志
|
||
tail -f logs/nanoclaw.log
|
||
```
|
||
|
||
---
|
||
|
||
## 安全考量
|
||
|
||
### 容器隔离
|
||
|
||
所有 agent 在容器（轻量级 Linux VM）内运行，提供：
|
||
- **文件系统隔离**：Agent 只能访问已挂载的目录
|
||
- **安全的 Bash 访问**：命令在容器内运行，而不是在您的 Mac 上
|
||
- **网络隔离**：可按容器配置（如需要）
|
||
- **进程隔离**：容器进程无法影响宿主机
|
||
- **非 root 用户**：容器以非特权 `node` 用户（uid 1000）运行
|
||
|
||
### Prompt 注入风险
|
||
|
||
WhatsApp 消息可能包含试图操纵 Claude 行为的恶意指令。
|
||
|
||
**缓解措施：**
|
||
- 容器隔离限制爆炸半径
|
||
- 仅处理已注册的群组
|
||
- 需要触发词（减少误处理）
|
||
- Agent 只能访问其群组挂载的目录
|
||
- 主群组可以按群组配置额外目录
|
||
- Claude 内置的安全训练
|
||
|
||
**建议：**
|
||
- 仅注册受信任的群组
|
||
- 仔细审查额外的目录挂载
|
||
- 定期审查定时任务
|
||
- 监控日志中的异常活动
|
||
|
||
### 凭证存储
|
||
|
||
| 凭证 | 存储位置 | 说明 |
|
||
|------------|------------------|-------|
|
||
| Claude CLI Auth | data/sessions/{group}/.claude/ | 按群组隔离，挂载到 /home/node/.claude/ |
|
||
| WhatsApp Session | store/auth/ | 自动创建，持续约20天 |
|
||
|
||
### 文件权限
|
||
|
||
groups/ 目录包含个人记忆，应加以保护：
|
||
```bash
|
||
chmod 700 groups/
|
||
```
|
||
|
||
---
|
||
|
||
## 故障排除
|
||
|
||
### 常见问题
|
||
|
||
| 问题 | 原因 | 解决方案 |
|
||
|-------|-------|----------|
|
||
| 消息无响应 | 服务未运行 | 检查 `launchctl list | grep nanoclaw` |
|
||
| "Claude Code process exited with code 1" | 容器运行时启动失败 | 检查日志；NanoClaw 会自动启动容器运行时，但可能失败 |
|
||
| "Claude Code process exited with code 1" | Session 挂载路径错误 | 确保挂载到 `/home/node/.claude/` 而非 `/root/.claude/` |
|
||
| Session 无法继续 | Session ID 未保存 | 检查 SQLite：`sqlite3 store/messages.db "SELECT * FROM sessions"` |
|
||
| Session 无法继续 | 挂载路径不匹配 | 容器用户是 `node`，HOME=/home/node；sessions 必须位于 `/home/node/.claude/` |
|
||
| "QR code expired" | WhatsApp session 过期 | 删除 store/auth/ 并重启 |
|
||
| "No groups registered" | 尚未添加群组 | 在主渠道中使用 `@Andy add group "Name"` |
|
||
|
||
### 日志位置
|
||
|
||
- `logs/nanoclaw.log` - stdout
|
||
- `logs/nanoclaw.error.log` - stderr
|
||
|
||
### 调试模式
|
||
|
||
手动运行以获取详细输出：
|
||
```bash
|
||
pnpm run dev
|
||
# 或
|
||
node dist/index.js
|
||
```
|