01 - 需求拆解与背景分析

研究背景与目标

为什么分析 OpenClaw?

OpenClaw 是 2026 年初最具 viral 效应的开源 AI 项目之一，在不到一周内从约 7,800 Stars 飙升至超过 113,000 Stars，创下 GitHub 历史上最快增长记录。这个项目之所以引发广泛关注，是因为它代表了一种全新的 AI 助手范式：从对话式 AI 转变为行动式 AI (Agentic AI)。

传统 AI 助手 (如 ChatGPT、Claude Web 界面) 主要提供信息查询和对话能力，而 OpenClaw 则能够真正执行操作——运行终端命令、控制浏览器、管理文件系统、操作智能家居设备等。这种转变标志着 AI 从”能说”到”能做”的质变。

核心技术问题

本研究需要解答以下关键问题：

1. 架构设计：OpenClaw 如何通过 Gateway 架构实现统一的控制平面？
2. 工具集成：它是如何集成和管理数百种不同工具的？
3. 通信机制：与 Telegram、WhatsApp 等消息平台的通信是如何实现的？
4. 安全与隔离：如何在提供强大功能的同时保证安全性？

用户场景分析

场景一：个人自动化助手

用户希望在 Telegram 上给 AI 助手发送消息，让其自动完成日常任务，如：

• “帮我预订明天上午去上海的机票”
• “检查我的邮箱并总结未读邮件”
• “运行数据分析脚本并发送结果”

场景二：团队协作机器人

在 Slack 或 Discord 群组中，AI 助手需要：

• 响应@提及的消息
• 执行团队约定的自动化流程
• 在多个平台间同步信息

场景三：开发者生产力工具

开发者期望通过对话界面直接：

• 执行 shell 命令和脚本
• 控制浏览器进行网页自动化
• 管理项目文件和代码

技术栈概览

核心技术选型

OpenClaw 的技术栈设计体现了现代、高效、跨平台的理念：

架构角色定义

OpenClaw 架构中涉及三种核心角色：

1. Gateway (网关)

• 作为单一控制平面运行
• 维护所有消息平台连接
• 提供 WebSocket API 供客户端连接
• 默认绑定 127.0.0.1:18789

2. Clients (客户端)

• macOS App、CLI、Web UI 等控制界面
• 通过 WebSocket 连接到 Gateway
• 发送命令并接收事件推送

3. Nodes (节点)

• iOS/Android 设备或 headless 实例
• 以 role: node 身份连接 Gateway
• 提供设备本地能力 (相机、屏幕录制、定位等)

关键路径识别

消息流关键路径

用户消息 → 消息平台 → Gateway → 路由决策 → AI Agent → 工具执行 → 响应回传

关键节点分析：

1. 消息接入层：Gateway 必须同时维护多个消息平台的 WebSocket/HTTP 连接
2. 路由决策：根据消息来源 (DM/群组)、用户身份、会话状态决定处理方式
3. Agent 执行：Pi agent 运行时的工具调用和流式响应
4. 响应回传：将 Agent 输出格式化并通过原通道返回

工具集成关键路径

Agent 决策 → 工具选择 → 参数生成 → 权限检查 → 沙盒执行 → 结果返回

核心挑战：

1. 动态工具发现：如何在不重启系统的情况下添加新工具
2. 权限隔离：防止非授权操作，特别是群组环境中的安全边界
3. 跨平台一致性：确保同一工具在不同平台上行为一致

安全关键路径

设备配对 → 身份验证 → 权限检查 → 操作授权 → 审计日志

风险点：

• 暴露的 Gateway 实例可能导致 API 密钥泄露
• 群组消息可能包含 prompt injection 攻击
• 工具执行需要细粒度的沙盒控制

技术约束与边界

运行环境要求

• Node.js 版本: 必须 ≥22，使用现代 JavaScript 特性
• 操作系统: 支持 macOS、Linux、Windows (WSL2)
• 网络: 本地绑定优先，远程访问需通过 Tailscale/SSH 隧道
• 资源: CPU 密集型应用，推荐 2+ vCPU、2+ GB 内存

协议约束

• WebSocket 协议: 所有通信基于 JSON 格式的 WebSocket 帧
• 首次握手: 连接后第一帧必须是 connect 请求
• 幂等性: 副作用操作 (send, agent) 需要幂等键支持重试
• 事件不回放: 客户端断线后需主动刷新获取缺失事件

扩展边界

• Skills 系统: 通过文件系统约定 (SKILL.md) 实现工具扩展
• MCP 支持: 可接入外部 MCP 服务器扩展能力
• 平台限制: 部分功能 (如 iMessage) 仅限特定操作系统

竞品对比

OpenClaw 的核心差异化在于将对话式交互与代码执行无缝结合，而非传统的触发器-动作工作流模式。

结论与研究方向

基于以上分析，本研究将深入探讨以下四个核心主题：

1. Gateway 架构的协议设计与实现机制
2. Skills 系统与 MCP 协议的工具集成方案
3. Telegram 通道的具体实现细节
4. 安全模型与生产环境部署建议

每个主题将在后续章节中展开详细技术分析，包含架构图、代码示例和最佳实践建议。