I. 核心架构 - 1. Gateway 架构 课程位置阶段I. 核心架构课序第 1 课前置知识无后续课程Agent Loop 本课核心问题如果你问我“OpenClaw 是怎么管理这么多消息平台的为什么一个东西能同时接收 WhatsApp、Telegram、Discord 的消息”我会这样回答通过一个叫Gateway的中央枢纽它就像一个邮局所有消息都先送到这里然后分配给对应的 Agent 处理。 你需要理解的三个关键点1. Gateway 是什么简单说Gateway 就是 OpenClaw 的中心大脑。类比想象你开了一家万能答题机构这个机构可以通过QQ、微信、电话、邮件接收提问但是你只有一个 Agent老板Gateway 就是前台小姐负责接收来自各种渠道的问题整理成统一格式交给后面的 Agent 处理把答案送回去技术上Gateway 是一个长期运行的服务用 WebSocket 协议它监听18789 端口默认所有客户端CLI、Web UI、macOS app、手机都通过 WebSocket 连接到它所有消息平台WhatsApp、Telegram 等也连接到它2. Gateway 管理两种角色角色 1Operator操作者你、CLI、Web UI用来控制和监管系统权限读、写、管理、批准等角色 2Node节点是指远程设备手机、树莓派提供能力相机、屏幕、位置等权限受限的特定能力打个比喻Operator 是老板可以做任何决策Node 是设备工人只能做特定工作比如拍照3. Gateway 如何管理消息完整流程消息进来 WhatsApp 消息 ──┐ Telegram 消息 ──┤ Discord 消息 ───┼─→ Gateway 中央枢纽 ──→ Agent 处理 ──→ 回复 Slack 消息 ─────┤ 其他平台 ────────┘ Gateway 的工作 1. 接收从各平台 2. 标准化统一格式 3. 路由送给正确的 Agent 4. 传回把答案送回去 Gateway 的三大核心机制机制 1WebSocket 握手与认证为什么用 WebSocket长连接不需要反复建立连接双向通信服务器可以主动推送低延迟握手过程你需要知道的1. 客户端连接到 ws://localhost:18789 2. Gateway 发送 challenge验证码 3. 客户端用私钥签署这个验证码 4. 发回签署后的信息 device ID 5. Gateway 验证签名 6. 成功现在连接已建立类比像银行的取款流程银行问“你是谁”challenge你出示身份证并签名签署银行验证签名允许你操作机制 2设备配对为什么需要配对第一次连接的设备是陌生的不能直接信任需要人工批准或本地自动批准配对的两种方式方式 1本地自动批准你在本地localhost 或同一网络 → Gateway 自动批准 → 不需要手动确认方式 2远程手动批准你在远程不同网络 → Gateway 生成配对码 → 用户看到新设备想连接 → 用户点击批准 → 然后才能使用真实例子你在办公室 Wi-Fi 用 CLI → 自动批准本地你在咖啡馆用手机 → 需要批准远程机制 3Device Token 管理Token 是什么一个证书证明我就是这个设备第一次配对成功后Gateway 给你颁发下次连接你直接拿 Token不用再走握手流程工作流程第一次 握手 → 验证 → 配对批准 → 颁发 Token → 保存到本地 第二次及以后 直接用 Token → Gateway 验证 → 连接成功 快速不需要重复握手类比第一次去酒店出示身份证办理入住拿房卡以后每次直接刷房卡进房间 为什么这样设计很重要1. 安全性陌生设备不能直接访问需要人工或本地批准防止未授权的访问2. 可扩展性一个 Gateway 可以管理无数设备新增平台只需要对接 Gateway不需要改动 Agent 的代码3. 隔离性每个设备独立的连接一个设备的问题不影响其他设备可以单独管理和控制 实战看看 Gateway 在你的系统中做什么查看 Gateway 状态# 查看 Gateway 是否运行openclaw status# 查看已连接的设备openclaw presence# 查看 Gateway 日志openclaw logs--follow查看配置# Gateway 配置在哪cat~/.openclaw/openclaw.json|grepgateway# 主要配置项{gateway:{port:18789,# 监听端口bind:auto,# 绑定地址mode:local,# 本地模式还是远程auth:{mode:token,# 认证方式token:xxx...# 认证令牌}}}常见场景场景 1本地开发你的 MacBook 运行 OpenClaw Gateway 同一网络的其他设备连接 → 自动批准都是本地场景 2远程部署服务器上运行 Gateway 你在家通过 SSH 隧道连接 → 需要手动批准第一次场景 3多设备iPhone 连接 → 需要批准 iPad 连接 → 又需要批准 Mac 连接 → 又需要批准 每个设备都是独立的⚠️ 常见陷阱陷阱表现原因解决连接失败“无法连接到 Gateway”Gateway 没有运行openclaw status检查配对被拒“需要批准新设备”第一次连接需要人工确认用户界面中点击批准Token 过期“认证失败”Token 有效期过了重新配对端口被占用“端口 18789 已被使用”其他程序占用了端口改端口或关闭其他程序 学习心得我学这一课时的体会当我第一次接触 Gateway 的时候我以为它是某个魔法能自动从各种平台收消息。但学完后我明白了Gateway 就是一个智能的前台。最让我印象深刻的是设备配对机制。之前我以为本地自动批准是一个 Bug后来才意识到这是优秀的设计——本地环境下我们假设是安全的所以自动批准远程环境下我们谨慎所以需要人工确认这样既方便又安全与其他课程的关联后续课程Agent Loop 会说Agent 怎么处理来自 Gateway 的消息之后还会学Session 管理会说Gateway 怎么区分不同用户配合使用Multi-Agent 会说一个 Gateway 怎么管理多个 Agent✅ 你现在应该理解的学完这一课你应该能够用一句话解释Gateway 是什么画出消息怎么从 WhatsApp 到 Agent的流程图解释本地自动批准和远程手动批准的区别知道Token是用来做什么的能查看自己系统中的 Gateway 状态如果你都能做到说明真的理解了 快速参考表概念简单说GatewayOpenClaw 的中央枢纽像邮局WebSocket长连接协议用来通信Operator操作者有完整权限Node设备有受限权限Challenge安全验证时的挑战码Device Pairing第一次设备连接时的批准过程Device Token设备的身份证证明你就是你本地连接localhost 或同网络自动批准远程连接不同网络需要手动批准 相关资源官方文档Gateway 架构https://docs.openclaw.ai/gateway/architectureProtocol 细节https://docs.openclaw.ai/gateway/protocol配置参考https://docs.openclaw.ai/gateway/configuration相关课程下一课I-2. Agent Loop之后I-3. Context 管理 本课总结最关键的 3 点Gateway 是中心所有消息都经过它所有平台都连接到它一个 Gateway 管理整个系统安全第一第一次连接需要配对本地自动远程需确认Token 用来快速认证为后续课程打基础理解 Gateway 才能理解 Agent Loop理解消息流才能理解 Session这是整个系统的地基你现在应该理解了 OpenClaw 是怎么听的。下一课会讲怎么想Agent Loop。
OpenClaw学习总结_I_核心架构系列_Gateway架构详解
I. 核心架构 - 1. Gateway 架构 课程位置阶段I. 核心架构课序第 1 课前置知识无后续课程Agent Loop 本课核心问题如果你问我“OpenClaw 是怎么管理这么多消息平台的为什么一个东西能同时接收 WhatsApp、Telegram、Discord 的消息”我会这样回答通过一个叫Gateway的中央枢纽它就像一个邮局所有消息都先送到这里然后分配给对应的 Agent 处理。 你需要理解的三个关键点1. Gateway 是什么简单说Gateway 就是 OpenClaw 的中心大脑。类比想象你开了一家万能答题机构这个机构可以通过QQ、微信、电话、邮件接收提问但是你只有一个 Agent老板Gateway 就是前台小姐负责接收来自各种渠道的问题整理成统一格式交给后面的 Agent 处理把答案送回去技术上Gateway 是一个长期运行的服务用 WebSocket 协议它监听18789 端口默认所有客户端CLI、Web UI、macOS app、手机都通过 WebSocket 连接到它所有消息平台WhatsApp、Telegram 等也连接到它2. Gateway 管理两种角色角色 1Operator操作者你、CLI、Web UI用来控制和监管系统权限读、写、管理、批准等角色 2Node节点是指远程设备手机、树莓派提供能力相机、屏幕、位置等权限受限的特定能力打个比喻Operator 是老板可以做任何决策Node 是设备工人只能做特定工作比如拍照3. Gateway 如何管理消息完整流程消息进来 WhatsApp 消息 ──┐ Telegram 消息 ──┤ Discord 消息 ───┼─→ Gateway 中央枢纽 ──→ Agent 处理 ──→ 回复 Slack 消息 ─────┤ 其他平台 ────────┘ Gateway 的工作 1. 接收从各平台 2. 标准化统一格式 3. 路由送给正确的 Agent 4. 传回把答案送回去 Gateway 的三大核心机制机制 1WebSocket 握手与认证为什么用 WebSocket长连接不需要反复建立连接双向通信服务器可以主动推送低延迟握手过程你需要知道的1. 客户端连接到 ws://localhost:18789 2. Gateway 发送 challenge验证码 3. 客户端用私钥签署这个验证码 4. 发回签署后的信息 device ID 5. Gateway 验证签名 6. 成功现在连接已建立类比像银行的取款流程银行问“你是谁”challenge你出示身份证并签名签署银行验证签名允许你操作机制 2设备配对为什么需要配对第一次连接的设备是陌生的不能直接信任需要人工批准或本地自动批准配对的两种方式方式 1本地自动批准你在本地localhost 或同一网络 → Gateway 自动批准 → 不需要手动确认方式 2远程手动批准你在远程不同网络 → Gateway 生成配对码 → 用户看到新设备想连接 → 用户点击批准 → 然后才能使用真实例子你在办公室 Wi-Fi 用 CLI → 自动批准本地你在咖啡馆用手机 → 需要批准远程机制 3Device Token 管理Token 是什么一个证书证明我就是这个设备第一次配对成功后Gateway 给你颁发下次连接你直接拿 Token不用再走握手流程工作流程第一次 握手 → 验证 → 配对批准 → 颁发 Token → 保存到本地 第二次及以后 直接用 Token → Gateway 验证 → 连接成功 快速不需要重复握手类比第一次去酒店出示身份证办理入住拿房卡以后每次直接刷房卡进房间 为什么这样设计很重要1. 安全性陌生设备不能直接访问需要人工或本地批准防止未授权的访问2. 可扩展性一个 Gateway 可以管理无数设备新增平台只需要对接 Gateway不需要改动 Agent 的代码3. 隔离性每个设备独立的连接一个设备的问题不影响其他设备可以单独管理和控制 实战看看 Gateway 在你的系统中做什么查看 Gateway 状态# 查看 Gateway 是否运行openclaw status# 查看已连接的设备openclaw presence# 查看 Gateway 日志openclaw logs--follow查看配置# Gateway 配置在哪cat~/.openclaw/openclaw.json|grepgateway# 主要配置项{gateway:{port:18789,# 监听端口bind:auto,# 绑定地址mode:local,# 本地模式还是远程auth:{mode:token,# 认证方式token:xxx...# 认证令牌}}}常见场景场景 1本地开发你的 MacBook 运行 OpenClaw Gateway 同一网络的其他设备连接 → 自动批准都是本地场景 2远程部署服务器上运行 Gateway 你在家通过 SSH 隧道连接 → 需要手动批准第一次场景 3多设备iPhone 连接 → 需要批准 iPad 连接 → 又需要批准 Mac 连接 → 又需要批准 每个设备都是独立的⚠️ 常见陷阱陷阱表现原因解决连接失败“无法连接到 Gateway”Gateway 没有运行openclaw status检查配对被拒“需要批准新设备”第一次连接需要人工确认用户界面中点击批准Token 过期“认证失败”Token 有效期过了重新配对端口被占用“端口 18789 已被使用”其他程序占用了端口改端口或关闭其他程序 学习心得我学这一课时的体会当我第一次接触 Gateway 的时候我以为它是某个魔法能自动从各种平台收消息。但学完后我明白了Gateway 就是一个智能的前台。最让我印象深刻的是设备配对机制。之前我以为本地自动批准是一个 Bug后来才意识到这是优秀的设计——本地环境下我们假设是安全的所以自动批准远程环境下我们谨慎所以需要人工确认这样既方便又安全与其他课程的关联后续课程Agent Loop 会说Agent 怎么处理来自 Gateway 的消息之后还会学Session 管理会说Gateway 怎么区分不同用户配合使用Multi-Agent 会说一个 Gateway 怎么管理多个 Agent✅ 你现在应该理解的学完这一课你应该能够用一句话解释Gateway 是什么画出消息怎么从 WhatsApp 到 Agent的流程图解释本地自动批准和远程手动批准的区别知道Token是用来做什么的能查看自己系统中的 Gateway 状态如果你都能做到说明真的理解了 快速参考表概念简单说GatewayOpenClaw 的中央枢纽像邮局WebSocket长连接协议用来通信Operator操作者有完整权限Node设备有受限权限Challenge安全验证时的挑战码Device Pairing第一次设备连接时的批准过程Device Token设备的身份证证明你就是你本地连接localhost 或同网络自动批准远程连接不同网络需要手动批准 相关资源官方文档Gateway 架构https://docs.openclaw.ai/gateway/architectureProtocol 细节https://docs.openclaw.ai/gateway/protocol配置参考https://docs.openclaw.ai/gateway/configuration相关课程下一课I-2. Agent Loop之后I-3. Context 管理 本课总结最关键的 3 点Gateway 是中心所有消息都经过它所有平台都连接到它一个 Gateway 管理整个系统安全第一第一次连接需要配对本地自动远程需确认Token 用来快速认证为后续课程打基础理解 Gateway 才能理解 Agent Loop理解消息流才能理解 Session这是整个系统的地基你现在应该理解了 OpenClaw 是怎么听的。下一课会讲怎么想Agent Loop。
