中枢神经系统类比
大多数人认为AI助手是独立的大脑——一个处理和响应的单一实体。clawbot不同： 它的架构像生物神经系统一样。你的大脑（AI模型）不会直接控制肌肉； 信号通过神经（通道）传递，由脊髓（Gateway）处理，并通过运动神经元（系统工具）执行。
这种分布式架构是clawbot能够同时监听WhatsApp、通过Telegram响应、执行shell命令 和更新其内存——全部并行进行的原因。传统的单体AI无法做到这一点，因为每个功能都紧密耦合。 clawbot的模块化设计将每个组件视为通过定义良好的协议进行通信的独立服务。
clawbot系统架构
组件深入解析：每个部分如何运作
🌐 Gateway：中央指挥
Gateway是clawbot的心脏——一个永不休眠的持久Node.js进程。为什么使用专用服务 而不是在每个通道中直接运行AI？ 三个关键原因：
- 统一状态：所有通道的对话历史的单一真实来源
- 资源效率：与AI API的单一连接，而非15+个独立连接
- 故障隔离：如果WhatsApp崩溃，Telegram仍然可以工作——通道是可替换的插件
Gateway通过WebSocket而非HTTP通信。为什么？ HTTP要求客户端不断 询问"有更新吗？"（轮询）。WebSocket维护持久的双向连接——Gateway可以在消息就绪时立即 推送到通道，实现实时流式响应。
💬 通道：感官接口
通道是独立的进程，在消息平台协议和Gateway的统一消息格式之间进行转换。 将它们视为协议适配器——WhatsApp使用Baileys，Telegram使用 Bot API，但两者都以相同的JSON结构向Gateway呈现消息。
这种抽象很强大：添加新的消息平台只需要编写一个通道插件，而不需要修改 整个系统。每个通道都是沙箱化的——如果崩溃，Gateway会自动尝试重新连接 而不影响其他通道。
🧠 AI模型路由器：智能骨干
clawbot不会将你锁定在单一AI提供商。模型路由器实现动态提供商选择： 为复杂推理选择Claude，为创意任务选择GPT-4，或为隐私关键操作选择本地Ollama——全部 在同一对话中。
这在技术上如何工作？ 每个AI提供商都有一个标准化接口（遵循OpenAI Completion API模式）。路由器维护到所有配置的提供商的连接池，根据配置的首选项路由请求， 并在提供商不可用时处理自动故障转移。
高级：自定义模型路由逻辑
你可以在~/.clawbot/clawbot.json中配置自定义路由规则：
- 将编码任务路由到Claude（更擅长编程）
- 将创意写作路由到GPT-4（更富想象力）
- 将敏感数据处理路由到本地Ollama（零外部传输）
- 如果主提供商失败，自动回退到次要提供商
💾 持久化内存：对话状态管理
与每次请求之间都会遗忘一切的无状态AI API不同，clawbot维护持久的对话历史
存储在~/.clawbot/conversations/的Markdown文件中。每个对话都是消息、
工具执行和AI响应的完整日志。
为什么使用Markdown而不是数据库？ 三个原因：
- 人类可读：你可以grep、搜索和版本控制你的AI对话
- 可移植：通过复制文件夹即可移动整个对话历史
- AI友好：AI模型可以原生理解Markdown格式用于上下文检索
Gateway自动管理上下文窗口——当对话超过模型的token限制时，它会智能地 总结旧消息同时保留关键上下文。这使得跨越数周的对话而不会降级。
⚙️ 执行引擎：安全系统控制
这是clawbot与聊天机器人的区别所在：真正的任务执行。当AI决定需要shell 命令时，执行引擎通过多层保护安全地处理它：
- 沙箱化：命令在受限环境中运行，文件系统访问受限
- 权限门控：用户可配置的命令模式允许列表/拒绝列表
- 确认提示：破坏性操作需要明确的用户批准
- 审计日志：每个执行的命令都会记录时间戳、用户和结果
- 超时保护：命令在可配置的持续时间后自动终止
🔌 技能系统：可扩展功能
技能是clawbot的插件系统——包含SKILL.md文件的文件夹，用于教AI新功能。
Markdown文件如何扩展功能？ AI读取技能定义并学习：
- 技能的作用及何时使用
- 它接受哪些参数
- 触发它的示例命令
- 预期行为和边缘情况
技能可以包括shell脚本、Node.js模块或API集成代码。AI通过结构化 函数调用这些工具，接收结果，并将它们整合到响应中。这就是clawbot如何控制智能家居、 管理云基础设施或与专有内部系统集成——任何人都可以编写技能。
技术栈：驱动clawbot的技术
运行时：Node.js 22+
现代JavaScript运行时，具有出色的异步I/O性能用于实时通信。对 WebSocket、HTTP/2和worker线程的原生支持实现并行任务执行。
语言：TypeScript
类型安全的开发防止整类错误。对WebSocket消息、AI响应和 配置的强类型确保健壮的错误处理。
通信：WebSocket协议
Gateway和所有客户端之间的双向持久连接。实现实时消息流、即时 通知和AI响应的亚秒级延迟。
存储：基于文件的状态
对话存储为Markdown，配置为JSON，技能为结构化文件夹。无数据库依赖——更简单的 部署、更容易的备份、grep友好的调试。
WhatsApp：Baileys库
逆向工程的WhatsApp Web协议实现。使用浏览器使用的相同协议维护持久连接 ——无非官方API或电话号码共享。
Telegram：grammY框架
官方Telegram Bot API包装器，支持TypeScript。长轮询和webhook支持灵活部署、 文件上传、内联键盘和完整的机器人功能。
AI集成：提供商抽象
统一接口支持Anthropic Claude、OpenAI GPT-4、Ollama本地模型和Google Gemini。自动 在不同API格式之间转换以实现无缝提供商切换。
安全性：沙箱化执行
Shell命令在具有可配置权限的受限环境中运行。用户定义的信任边界防止 意外的系统损坏或未经授权的操作。
消息流：跟踪请求通过系统的过程
让我们追踪当你通过WhatsApp发送"2小时后提醒我给妈妈打电话"时会发生什么。
{"from": "user", "text": "Remind...", "channel": "whatsapp"}schedule_reminder(time="+2h", message="Call Mom")这19步编排在不到2秒内完成。分布式架构使每个组件都能独立工作 ——WhatsApp通道不知道Claude，Claude不知道WhatsApp，但它们通过Gateway的编排 无缝协调。
为什么这种架构很重要
大多数AI助手是单体的——所有逻辑在一个应用程序中，与特定平台紧密耦合。clawbot的 分布式设计实现了传统架构中不可能实现的功能：
- 热插拔组件：升级AI模型而无需重启通道。用Telegram替换WhatsApp而无需触及Gateway。
- 水平扩展：在不同机器上运行多个通道实例，全部连接到一个Gateway。
- 容错性：如果一个通道崩溃，其他通道继续运行。如果Gateway重启，通道会自动重新连接。
- 多租户：一个Gateway可以为多个用户提供服务，具有隔离的对话空间——非常适合家庭部署。
- 可扩展性：社区成员可以构建新的通道、技能或工具，而无需访问核心代码。
🔐 通过架构实现安全性
分布式设计不仅仅是为了灵活性——它是一个安全边界。通道在具有 有限权限的独立进程中运行。如果通道被攻破，攻击者只能访问该消息平台，而不是你的 整个系统。Gateway强制执行身份验证，执行引擎在运行任何系统命令之前应用额外的沙箱化。
技术决策和权衡
为什么使用WebSocket而不是HTTP REST？
HTTP是请求-响应：客户端问，服务器答。AI响应通常需要5-15秒。没有WebSocket，你需要 轮询（浪费）或长轮询（复杂）。WebSocket实现流式响应——AI在生成单词的瞬间 就开始发送，创造即时响应的感知。
为什么使用文件存储而不是数据库？
数据库增加了部署复杂性——安装、配置、备份策略。对于个人AI（1-10个用户），文件 提供足够的性能，同时保持可移植、可检查和可版本控制。你可以 grep你的对话历史，用Dropbox备份，或用Git跟踪更改。
为什么使用Node.js而不是Python/Go/Rust？
Node.js在I/O密集型任务（实时通信、API调用）中表现出色。JavaScript的async/await模型自然映射到 AI工作流（发送请求、等待响应、处理结果）。npm生态系统为每个 消息平台提供成熟的库。TypeScript在不牺牲开发速度的情况下增加安全性。