学到第 11 讲我们终于进入 OpenClaw 的核心组件拆解。第一个必须讲的是 Gateway。很多人第一次看到 Gateway会把它理解成“一个转发请求的服务”。这只说对了一小半。在 OpenClaw 里Gateway 更像整个系统的入口层、会话调度中心和事件总线。它负责接住外部世界的输入也负责把 Agent 的输出送回正确的地方。如果没有 GatewayOpenClaw 就会退化成一个本地 CLI Agent有了 GatewayOpenClaw 才能同时面对 CLI、Dashboard、消息平台、节点、浏览器、自动化任务和远程调用。先说结论Gateway 不是普通代理OpenClaw 官方文档把 Gateway 描述为一个长期运行的 WebSocket server。它拥有 messaging surfaces、nodes、sessions、hooks 等运行面。你可以这样理解它的位置CLI / Dashboard / API / 消息平台 / Node ↓ Gateway ↓ Session / Queue / Agent Runtime / Tools / Hooks ↓ 流式事件 / 最终回复 / 渠道发送 / 状态持久化所以 Gateway 不是简单的 HTTP proxy。它至少做这些事接收连接 做认证和 pairing 维护会话和路由 接收 agent 请求 返回 accepted / final / stream event 连接消息平台和设备节点 管理健康检查和状态 承载 hooks、cron、presence 等事件如果说 Agent Runtime 是大脑和执行循环Gateway 就是神经系统和交通枢纽。Gateway 的第一职责统一入口OpenClaw 的入口很多。用户可能来自CLI Web UI macOS app Telegram 企业微信 Slack / Discord WhatsApp Webhook 自动化任务 远程节点这些入口的协议、身份、消息格式和权限都不同。Gateway 的第一件事就是把它们收进同一个运行面。官方架构文档里提到控制面客户端通过 WebSocket 连接 Gateway默认绑定在127.0.0.1:18789节点也通过 WebSocket 连接但会声明 node 角色和能力。这带来一个很重要的结果入口可以很多 运行状态只有一个 Gateway 统一管理这样 CLI 发起的任务、Dashboard 看到的事件、消息平台收到的回复才有可能围绕同一条 session transcript 协作。Gateway 的第二职责协议和认证Gateway 使用 WebSocket JSON payload。官方文档总结的 wire protocol 大概是第一帧connect 之后 req/res客户端请求和响应 event服务端推送事件这意味着 Gateway 不是“随便发字符串”的通道。它有明确的帧结构、请求 id、method、params、payload、error。同时Gateway 还要处理认证。比如shared secret token / password 设备身份 pairing approval Tailscale 或 trusted proxy 身份 本地 loopback 的信任路径这解释了为什么 Gateway 比普通本地脚本复杂。它要在“方便连接”和“不能被陌生入口接管”之间做平衡。Gateway 的第三职责Session 路由前面几讲反复提到 Session。Gateway 是 Session 路由的关键拥有者。当一条消息进来时Gateway 要判断来自哪个 channel 哪个账号 哪个 peer / group / thread 是否显式指定 session-key 是否绑定到某个 agent 是否已有正在运行的 run然后把它映射到对应 session。如果这个路由错了就会出现很多奇怪问题群聊里的上下文串到私聊CLI 的任务和消息平台的任务互相看不见Agent 以为“继续上一个任务”但其实进入了另一个 session同一个 webhook 重复触发多个任务所以 Gateway 的路由不只是工程细节。它决定 Agent 的上下文边界。Gateway 的第四职责Queue 和并发控制真实用户不会等 Agent 完美结束后才说下一句话。他们会补充、打断、纠正别看全部区域只看华东。 这个任务先停一下。 做完以后再帮我发群里。Gateway 必须决定这些输入如何进入当前 session。常见模式包括steer进入当前 run 的下一次模型调用 followup等当前 run 完成后处理 collect先收集稍后一起处理 interrupt中断当前 run没有这层队列Agent 很容易在长任务里乱套。Gateway 的价值就在于它不只是接收请求还管理请求之间的关系。Gateway 的第五职责事件流和可观测性当 Agent run 开始后Gateway 不只是等最终答案。它会把事件推给订阅者agent accepted lifecycle start / end / error assistant stream tool event presence health heartbeat shutdownCLI 可以显示流式文本。Dashboard 可以展示工具过程。消息平台可以收到进度草稿或最终回复。自动化系统可以等待结构化终态。这就是为什么 Gateway 是事件总线。如果没有事件流OpenClaw 就只能“最后给你一句话”有了事件流OpenClaw 才能解释“正在做什么、做到哪一步、哪里失败了”。Gateway 与 Agent Runtime 的关系Gateway 不是模型。Gateway 也不是 Agent 的全部。更准确的关系是Gateway 负责连接、认证、路由、队列、事件、渠道 Agent Runtime 负责 prompt、context、model、tool loop、session transcript但它们不是两个完全分离的孤岛。Gateway 会把请求送入 Agent Runtime。Agent Runtime 会把流式事件、工具状态、最终回复交回 Gateway。Gateway 再把这些结果送回 CLI、Dashboard 或消息平台。这就是 OpenClaw 的核心闭环外部输入 → Gateway → Agent Runtime → Gateway → 外部输出一个真实场景假设你在企业微信群里说帮我检查昨天退款异常并发一份摘要。Gateway 做的事大概是1. 接收企业微信 webhook 2. 校验来源和消息 id避免重复投递 3. 根据群聊和账号映射到 session 4. 判断当前 session 是否已有 run 5. 按 queue mode 创建新 run 或 steering 6. 把请求送入 Agent Runtime 7. 推送 lifecycle 和 tool events 给 Dashboard 8. 把最终摘要按企业微信限制分块发送 9. 写入 transcript 和 session metadata用户只看到“开始处理”和“最终摘要”。但系统中间经过了入口、路由、队列、模型、工具、输出适配等多个步骤。常见误解误解一Gateway 只是端口 18789不是。端口只是入口。Gateway 真正管理的是连接、会话、事件、路由和运行面。误解二CLI 可以绕过 Gateway 做所有事部分本地模式可以嵌入运行但 Gateway-backed run 才能共享 Gateway 管理的 session、MCP loopback、消息渠道和事件订阅。误解三Gateway 只服务聊天不是。它还服务节点、Canvas、健康检查、hooks、cron、presence、远程调用和工具事件。误解四Gateway 是安全边界的全部也不是。Gateway 做认证、pairing、连接和协议边界工具权限、exec approvals、sandbox、workspace 还在更低层继续约束执行。最后总结Gateway 是 OpenClaw 的入口层和调度中心。它统一外部入口维护连接和认证解析 session管理队列承载事件流并把 Agent Runtime 的结果送回正确渠道。一句话总结Gateway 让 OpenClaw 从“本地 Agent”变成“多入口、多会话、多渠道、可观察的 Agent 系统”。本节作业画出你理解的 Gateway 输入输出图至少包含 CLI、Dashboard、消息平台、Agent Runtime。思考如果 Gateway 路由错 session会出现哪些用户可见问题用openclaw gateway health或openclaw gateway probe的概念解释 health 和 probe 解决什么问题。写出一次群聊消息进入 Gateway 后的 5 个内部步骤。区分 Gateway 安全边界和工具执行安全边界。下一节预告下一节讲CLI本地命令如何连接到 OpenClaw我们会从用户敲下openclaw agent、openclaw gateway、openclaw doctor开始看 CLI 如何成为 OpenClaw 的本地控制面。参考资料OpenClaw DocsGateway architectureOpenClaw DocsGateway CLIOpenClaw DocsAgent loopOpenClaw DocsCommand queueOpenClaw DocsStreaming and chunking原文链接GatewayOpenClaw 的入口层和调度中心 | Harries Blog™
Gateway：OpenClaw 的入口层和调度中心
学到第 11 讲我们终于进入 OpenClaw 的核心组件拆解。第一个必须讲的是 Gateway。很多人第一次看到 Gateway会把它理解成“一个转发请求的服务”。这只说对了一小半。在 OpenClaw 里Gateway 更像整个系统的入口层、会话调度中心和事件总线。它负责接住外部世界的输入也负责把 Agent 的输出送回正确的地方。如果没有 GatewayOpenClaw 就会退化成一个本地 CLI Agent有了 GatewayOpenClaw 才能同时面对 CLI、Dashboard、消息平台、节点、浏览器、自动化任务和远程调用。先说结论Gateway 不是普通代理OpenClaw 官方文档把 Gateway 描述为一个长期运行的 WebSocket server。它拥有 messaging surfaces、nodes、sessions、hooks 等运行面。你可以这样理解它的位置CLI / Dashboard / API / 消息平台 / Node ↓ Gateway ↓ Session / Queue / Agent Runtime / Tools / Hooks ↓ 流式事件 / 最终回复 / 渠道发送 / 状态持久化所以 Gateway 不是简单的 HTTP proxy。它至少做这些事接收连接 做认证和 pairing 维护会话和路由 接收 agent 请求 返回 accepted / final / stream event 连接消息平台和设备节点 管理健康检查和状态 承载 hooks、cron、presence 等事件如果说 Agent Runtime 是大脑和执行循环Gateway 就是神经系统和交通枢纽。Gateway 的第一职责统一入口OpenClaw 的入口很多。用户可能来自CLI Web UI macOS app Telegram 企业微信 Slack / Discord WhatsApp Webhook 自动化任务 远程节点这些入口的协议、身份、消息格式和权限都不同。Gateway 的第一件事就是把它们收进同一个运行面。官方架构文档里提到控制面客户端通过 WebSocket 连接 Gateway默认绑定在127.0.0.1:18789节点也通过 WebSocket 连接但会声明 node 角色和能力。这带来一个很重要的结果入口可以很多 运行状态只有一个 Gateway 统一管理这样 CLI 发起的任务、Dashboard 看到的事件、消息平台收到的回复才有可能围绕同一条 session transcript 协作。Gateway 的第二职责协议和认证Gateway 使用 WebSocket JSON payload。官方文档总结的 wire protocol 大概是第一帧connect 之后 req/res客户端请求和响应 event服务端推送事件这意味着 Gateway 不是“随便发字符串”的通道。它有明确的帧结构、请求 id、method、params、payload、error。同时Gateway 还要处理认证。比如shared secret token / password 设备身份 pairing approval Tailscale 或 trusted proxy 身份 本地 loopback 的信任路径这解释了为什么 Gateway 比普通本地脚本复杂。它要在“方便连接”和“不能被陌生入口接管”之间做平衡。Gateway 的第三职责Session 路由前面几讲反复提到 Session。Gateway 是 Session 路由的关键拥有者。当一条消息进来时Gateway 要判断来自哪个 channel 哪个账号 哪个 peer / group / thread 是否显式指定 session-key 是否绑定到某个 agent 是否已有正在运行的 run然后把它映射到对应 session。如果这个路由错了就会出现很多奇怪问题群聊里的上下文串到私聊CLI 的任务和消息平台的任务互相看不见Agent 以为“继续上一个任务”但其实进入了另一个 session同一个 webhook 重复触发多个任务所以 Gateway 的路由不只是工程细节。它决定 Agent 的上下文边界。Gateway 的第四职责Queue 和并发控制真实用户不会等 Agent 完美结束后才说下一句话。他们会补充、打断、纠正别看全部区域只看华东。 这个任务先停一下。 做完以后再帮我发群里。Gateway 必须决定这些输入如何进入当前 session。常见模式包括steer进入当前 run 的下一次模型调用 followup等当前 run 完成后处理 collect先收集稍后一起处理 interrupt中断当前 run没有这层队列Agent 很容易在长任务里乱套。Gateway 的价值就在于它不只是接收请求还管理请求之间的关系。Gateway 的第五职责事件流和可观测性当 Agent run 开始后Gateway 不只是等最终答案。它会把事件推给订阅者agent accepted lifecycle start / end / error assistant stream tool event presence health heartbeat shutdownCLI 可以显示流式文本。Dashboard 可以展示工具过程。消息平台可以收到进度草稿或最终回复。自动化系统可以等待结构化终态。这就是为什么 Gateway 是事件总线。如果没有事件流OpenClaw 就只能“最后给你一句话”有了事件流OpenClaw 才能解释“正在做什么、做到哪一步、哪里失败了”。Gateway 与 Agent Runtime 的关系Gateway 不是模型。Gateway 也不是 Agent 的全部。更准确的关系是Gateway 负责连接、认证、路由、队列、事件、渠道 Agent Runtime 负责 prompt、context、model、tool loop、session transcript但它们不是两个完全分离的孤岛。Gateway 会把请求送入 Agent Runtime。Agent Runtime 会把流式事件、工具状态、最终回复交回 Gateway。Gateway 再把这些结果送回 CLI、Dashboard 或消息平台。这就是 OpenClaw 的核心闭环外部输入 → Gateway → Agent Runtime → Gateway → 外部输出一个真实场景假设你在企业微信群里说帮我检查昨天退款异常并发一份摘要。Gateway 做的事大概是1. 接收企业微信 webhook 2. 校验来源和消息 id避免重复投递 3. 根据群聊和账号映射到 session 4. 判断当前 session 是否已有 run 5. 按 queue mode 创建新 run 或 steering 6. 把请求送入 Agent Runtime 7. 推送 lifecycle 和 tool events 给 Dashboard 8. 把最终摘要按企业微信限制分块发送 9. 写入 transcript 和 session metadata用户只看到“开始处理”和“最终摘要”。但系统中间经过了入口、路由、队列、模型、工具、输出适配等多个步骤。常见误解误解一Gateway 只是端口 18789不是。端口只是入口。Gateway 真正管理的是连接、会话、事件、路由和运行面。误解二CLI 可以绕过 Gateway 做所有事部分本地模式可以嵌入运行但 Gateway-backed run 才能共享 Gateway 管理的 session、MCP loopback、消息渠道和事件订阅。误解三Gateway 只服务聊天不是。它还服务节点、Canvas、健康检查、hooks、cron、presence、远程调用和工具事件。误解四Gateway 是安全边界的全部也不是。Gateway 做认证、pairing、连接和协议边界工具权限、exec approvals、sandbox、workspace 还在更低层继续约束执行。最后总结Gateway 是 OpenClaw 的入口层和调度中心。它统一外部入口维护连接和认证解析 session管理队列承载事件流并把 Agent Runtime 的结果送回正确渠道。一句话总结Gateway 让 OpenClaw 从“本地 Agent”变成“多入口、多会话、多渠道、可观察的 Agent 系统”。本节作业画出你理解的 Gateway 输入输出图至少包含 CLI、Dashboard、消息平台、Agent Runtime。思考如果 Gateway 路由错 session会出现哪些用户可见问题用openclaw gateway health或openclaw gateway probe的概念解释 health 和 probe 解决什么问题。写出一次群聊消息进入 Gateway 后的 5 个内部步骤。区分 Gateway 安全边界和工具执行安全边界。下一节预告下一节讲CLI本地命令如何连接到 OpenClaw我们会从用户敲下openclaw agent、openclaw gateway、openclaw doctor开始看 CLI 如何成为 OpenClaw 的本地控制面。参考资料OpenClaw DocsGateway architectureOpenClaw DocsGateway CLIOpenClaw DocsAgent loopOpenClaw DocsCommand queueOpenClaw DocsStreaming and chunking原文链接GatewayOpenClaw 的入口层和调度中心 | Harries Blog™
