7.6 KiB
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 文档。
愿景
一个可通过消息访问的个人 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 中，由路由器轮询
- 渠道在启动时自行注册——未配置的渠道被跳过并发出警告
调度器
- 内置调度器在宿主机上运行，启动容器执行任务
- 自定义
nanoclawMCP 服务器（容器内）提供调度工具 - 工具：
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）。