第1课 OpenClaw 的内部结构#
为什么需要了解这个#
你已经学会了使用 OpenClaw——发送消息、连接通道、配置助手。但要解决非常规问题并理解为什么某些功能不正常，了解系统"底层"的工作原理会很有帮助。就像了解汽车的组成——不是为了成为机械师，而是为了理解发生了什么。
主要组件#
OpenClaw 由几个协同工作的部分组成：
1. Gateway（网关）#
Gateway 是系统的"大脑"。它是一个在你的电脑或服务器上持续运行的程序。
Gateway 的职责：
- 与所有聊天工具（Telegram、WhatsApp、Discord 等）保持连接
- 接收你的消息并发送给 AI 模型
- 管理会话（对话历史）
- 给辅助设备（节点）分配任务
Gateway 是唯一需要启动的进程。其他一切都连接到它。
启动 Gateway：
openclaw gateway默认监听端口 18789——就像所有人进入的门牌号。
2. WebSocket —— 通信方式#
WebSocket (WS) 是一种持续双向通信的技术。想象一个电话通话：你不需要每句话后挂断电话，而是持续交谈。
OpenClaw 的所有部分都通过 WebSocket 与 Gateway 通信：
- Mac 应用
- 命令行 (CLI)
- 网页界面 (WebChat)
- 设备（节点）
通信使用 JSON 格式——一种类似"键值对"列表的文本数据传输格式。
3. 客户端 (Clients)#
客户端是任何连接到 Gateway 的程序：
- macOS 应用 —— 菜单栏中的图形界面
- CLI（命令行界面）—— 终端中的文字命令
- WebChat —— 浏览器中的聊天
- Control UI —— 浏览器中的控制面板
每个客户端与 Gateway 建立一个 WebSocket 连接。
4. 节点 (Nodes)#
节点是辅助设备：手机、平板、树莓派。它们也通过 WebSocket 连接到 Gateway，但标记为"我是节点"。
节点可以：
- 拍照（摄像头）
- 录屏
- 获取位置
- 显示通知
5. Canvas（画布）#
Canvas 是助手可以在工作过程中创建和编辑的网页。它显示在 Gateway 的同一端口 18789 上。
它们如何协同工作#
当你发送消息时，发生了这些事：
你（Telegram）→ Gateway → AI 模型 → Gateway → Telegram 中的回复详细过程：
- 你在 Telegram 中写消息
- Gateway 通过 Telegram 机器人接收消息
- Gateway 将文本发送给 AI 模型（例如 Claude）
- 模型决定做什么——可能调用工具（读文件、搜索互联网）
- 如果需要设备——Gateway 通过 WebSocket 联系节点
- 准备好的回复由 Gateway 发送回 Telegram
连接生命周期#
当客户端连接到 Gateway 时，会进行"握手"：
- 客户端发送
connect请求（第一条消息必须是这个） - Gateway 验证授权令牌（如果已配置）
- Gateway 回复"ok"并发送当前状态
- 之后客户端可以发送请求，Gateway 会推送事件
如果第一条消息不是 connect，Gateway 会断开连接。
授权和信任#
- 每个客户端和节点都有设备标识（device identity）
- 新设备需要批准（pairing approval）
- 来自同一台电脑（localhost）的连接可以自动批准
- 远程连接需要明确确认
健康检查#
确认 Gateway 是否正常运行：
openclaw health
openclaw status --deep本课总结#
- Gateway 是管理一切的中心程序
- 系统的所有部分通过 WebSocket（持久连接）通信
- 客户端（应用、CLI、网页）连接到 Gateway 进行管理
- 节点（设备）作为带摄像头、屏幕等功能的辅助设备连接
- 连接时的第一条消息必须是带授权的
connect - 一个 Gateway = 一个主机。这是管理所有通道的统一入口