OpenClaw 的心智模型：Gateway / Channel / Skill / Workspace
你已经完成第 2 章，接下来先别急着“把配置一顿猛改”。
先把地图看懂：消息从哪来、经过谁、谁来执行、结果回到哪。
本章会把最容易把人绕晕的五个词（Gateway / Channel / Tools / Skill / Workspace）翻成大白话。你不用先啃源码，也能知道“出问题该去哪里看”。
本章你将学会什么
Section titled “本章你将学会什么”- 用一句话记住五个核心概念，并知道它们之间的关系。
- 看懂 OpenClaw 的核心结构图，分清控制面和执行面。
- 走通“一条消息”从接入到回复的完整生命周期。
- 理解为什么 Tools + Skills 才是“会聊天”到“能干活”的分水岭。
- 明确 Workspace 什么时候该拆、什么时候不该拆，避免过度工程化。
- 你已完成第 2 章，能在本地打开 Control UI（
127.0.0.1:18789）。 - 你知道“终端/命令行（CLI，黑底白字那个窗口）”和“配置文件”这两个基本概念即可。
3.1 五个核心概念一句话（补上 Tools）
Section titled “3.1 五个核心概念一句话（补上 Tools）”3.1.1 Gateway：系统总控台（control plane）
Section titled “3.1.1 Gateway：系统总控台（control plane）”一句话：Gateway 是 OpenClaw 的控制平面（control plane），负责统一管理会话（sessions）、渠道（channels）、工具调用与状态事件。
官方文档把它定义为“single control plane（单一控制平面）”，并说明客户端与节点通过 WebSocket 接入 Gateway，默认地址常见为 127.0.0.1:18789。
这句话翻译一下就是：你在 UI 里看到的大多数状态，根在 Gateway，不是前端页面“现场编的”。
给零基础读者的类比：Gateway 就像“总调度室”。
谁发来消息、谁该处理、处理中发生了什么、最后如何回传，都由这个调度室统一安排。
3.1.2 Channel：消息入口连接器
Section titled “3.1.2 Channel：消息入口连接器”一句话：Channel 是把 OpenClaw 接到外部聊天软件的连接器。
例如：Telegram、Slack、Discord、Feishu/Lark、WebChat 都属于 Channel。
虽然每个渠道接入方式不一样（Bot Token、Webhook、WebSocket、扫码登录），但在 Gateway 眼里都会被翻译成同一套结构：“入站消息 + 路由条件 + 出站回复”。
关键点在于：
OpenClaw 的回复路由是确定性的，通常“从哪个渠道进来，就回到哪个渠道”，不是让模型自由决定“回哪儿”。这样才可控、可追溯。
3.1.3 Skill / Workspace：能力封装与运行边界
Section titled “3.1.3 Skill / Workspace：能力封装与运行边界”一句话：
- Skill 是能力封装（通常以
SKILL.md为入口），告诉系统“这类任务怎么调用工具去完成”； - Workspace 是该 Agent 的工作目录与上下文根（默认
~/.openclaw/workspace），用于承载文件、记忆与本地上下文。
两者关系可以这样记：
- Skill 决定“你会做什么”；
- Workspace 决定“你在什么边界里做、读写哪些本地内容”。
注意一个容易误解的点：文档明确写了 Workspace 是默认 cwd（当前工作目录），不是绝对沙箱边界。如果你要强隔离，需要结合 sandbox 策略配置。
3.1.4 Tools：Agent 的“手和脚”
Section titled “3.1.4 Tools：Agent 的“手和脚””一句话：Tools 是 Agent 真正“动手干活”的能力集合。
你可以把 Tools 理解成“可调用功能清单”，例如：
- 读写文件（
read/write/edit/apply_patch） - 执行命令（
exec/process） - 网页检索和抓取（
web_search/web_fetch） - 浏览器自动化（
browser）
最容易搞混的一点是：
- Tools 决定“能做哪些动作”
- Skill 决定“按什么步骤使用这些动作”
所以有 Skill 但没开对应 Tools，任务依然跑不起来；
反过来，Tools 全开但没 Skill，也容易乱调用，翻车概率更高。
术语速记卡（社区高频问法，官方核验版）
| 术语 | 给零基础读者的说法 | 官方语义（v2026.2） |
|---|---|---|
| Gateway | “总调度室” | 单一控制平面，统一会话/路由/事件，默认监听 127.0.0.1:18789（WS） |
| Agent | “一个独立大脑” | 每个 Agent 有独立 workspace、会话存储和认证配置 |
| Workspace | “这个 Agent 的工作文件夹” | 默认 ~/.openclaw/workspace；是默认 cwd，不是硬沙箱 |
| Agent Directory（agentDir） | “放技术状态的目录” | 会话、认证、运行状态等技术数据目录（与 workspace 分离） |
| Channel | “消息入口” | Telegram/Slack/Discord/Feishu 等连接器，接入后统一进 Gateway |
| accountId | “同一渠道下的账号区分符” | 在多账号渠道里区分不同登录实例 |
| sessionKey | “会话归档键” | 决定消息落到哪个会话桶（并发控制也依赖它） |
| sessionId | “具体这段聊天记录文件” | 指向实际 transcript（如 JSONL） |
| binding | “分流规则” | 按 channel/account/peer/team 等字段把入站消息路由到指定 Agent |
| dmScope | “私聊上下文隔离级别” | main / per-peer / per-channel-peer / per-account-channel-peer |
3.2 一张图讲清结构
Section titled “3.2 一张图讲清结构”3.2.1 系统组件关系图
Section titled “3.2.1 系统组件关系图”先看简化结构图（逻辑视图）：
用户（你） │ ├─ 在聊天软件中发消息（Telegram/Slack/Feishu/...） │ ▼Channel Connector（渠道连接器） │ 统一入站事件 ▼Gateway（控制平面 / control plane） ├─ 会话管理（sessions） ├─ 路由决策（bindings, agent selection） ├─ 运行 Agent loop（模型 + 工具） ├─ 状态/事件流（lifecycle, assistant, tool） └─ Web 控制台（Control UI / WebChat） │ ▼ Skill（能力封装） ↔ Workspace（文件与上下文） │ ▼ 输出结果回传到原渠道你先记住一句就够：Channel 负责接消息，Gateway 负责调度，Tools 负责执行动作，Skill 负责组织步骤，Workspace 负责承载上下文。
3.2.2 关键边界：控制面与执行面
Section titled “3.2.2 关键边界：控制面与执行面”OpenClaw 的“控制面 vs 执行面”可以粗分为两层：
- 控制面（Gateway）
管连接、会话、路由、状态、权限策略、事件广播。 - 执行面（Agent loop + tools）
真正跑模型推理、调用工具、产出结果。
这个分层在排障时非常有用。
比如你遇到“页面能打开但不出回复”，先判断是控制面问题（连接/会话/路由）还是执行面问题（模型密钥/工具失败/超时），排查会快很多。
3.2.3 数据流向：消息、状态、结果
Section titled “3.2.3 数据流向：消息、状态、结果”把一次对话拆开看，至少有三条“流水线”：
- 消息流：用户输入、模型输出、渠道回传；
- 状态流：
connect、presence、health、lifecycle等事件； - 结果流：工具调用结果、会话落盘、日志与检查信息。
这些流会在 Gateway 汇总，再统一暴露给 UI/CLI/API。
所以只盯着聊天软件里那一条消息通常不够，你还得回到 Gateway 看上下文和事件。
你可能在社区帖子里见过一些“术语解释文”。这类内容很有帮助，但要防止版本漂移。
以当前文档为准，至少有三条容易被说反：
- Canvas 不是固定独立端口。 当前官方说明为 Gateway 同端口（默认
18789）下的路由（如/__openclaw__/canvas/）。 - Heartbeat 默认不是 2 小时。 当前默认是
30m，在 Anthropic OAuth/setup-token 场景下通常是1h。 - OpenClaw 不是 “pi-coding runtime 原样直连”。 当前是 OpenClaw 嵌入运行时并自管 session/discovery/tool wiring，文档写的是 derived from
pi-mono。
3.3 一次请求的生命周期
Section titled “3.3 一次请求的生命周期”3.3.1 消息接入与路由决策
Section titled “3.3.1 消息接入与路由决策”一条消息进来后，系统先做的不是“立刻回答”，而是先确定这条消息属于哪个 Agent、哪个 Session。
官方文档给出的关键路由顺序是：
peer 精确匹配 → channel+peer 组合 → team/workspace 维度 → account 匹配 → channel 匹配 → 默认 agent。
同时，会话键（session key）也会按聊天类型区分：
直聊（DM）可折叠到主会话，群聊/频道通常隔离为独立会话键。
这一步决定了“后续使用哪份上下文与历史”。
3.3.2 工具调用与中间状态
Section titled “3.3.2 工具调用与中间状态”路由完成后，进入 Agent loop（智能体循环）：
- 参数校验并返回
accepted（拿到runId）； - 装配上下文（会话历史 + skills snapshot + bootstrap 内容）；
- 模型推理与工具调用交替执行；
- 持续发出流式事件（assistant/tool/lifecycle）。
文档强调“每个会话串行执行（serialized run）”以避免竞态：
同一会话不会并发乱写，这能减少“上一轮没结束、下一轮又覆盖状态”的混乱。
3.3.3 输出回传与日志留痕
Section titled “3.3.3 输出回传与日志留痕”当生命周期进入 end 或 error，系统会产出最终回复并回传到原渠道，同时更新会话存储与日志。
你可以把这一步理解成两个动作：
- 对用户可见：收到最终回复；
- 对系统可见：会话、工具结果、状态事件被记录，便于后续检查与排障。
这也是为什么我们总说“Gateway 是事实源（source of truth）”：
会话状态和关键记录都在 Gateway 所在主机上，而不是散落在各客户端本地缓存里。
3.4 Skills 为什么是生产力
Section titled “3.4 Skills 为什么是生产力”3.4.1 技能的输入/输出边界
Section titled “3.4.1 技能的输入/输出边界”很多人把 Skill 理解成“长提示词”，这只说对了一半。
更准确地说，Skill 是“带边界的能力单元”：不只写“做什么”，还会约束“怎么触发、依赖什么环境、输出长什么样”。
当你把任务拆成可复用技能后，系统更容易做到：
- 输入更结构化；
- 输出更稳定；
- 失败更可解释（知道卡在参数、依赖还是权限）。
3.4.2 技能执行的可追踪与可复用
Section titled “3.4.2 技能执行的可追踪与可复用”官方文档说明 Skills 会在会话启动时生成可用快照（skills snapshot），并可在 watcher 开启时热刷新。
这能带来两个很实在的收益：
- 可追踪：当前会话到底用的是哪批技能，可回溯；
- 可复用：同名技能有清晰生效顺序（workspace > managed/local > bundled）。
你可以把它理解成“能力版本管理”：
不是每轮对话都靠临场发挥，而是基于一套受控能力集合运行。
3.4.3 技能管理：启用、禁用、检查
Section titled “3.4.3 技能管理：启用、禁用、检查”对生产环境最重要的一句：第三方技能默认按不可信处理。
官方文档也明确建议安装前先审阅内容，再谨慎注入 env / apiKey。
最低管理动作建议：
- 先最小启用，不要一次开太多技能；
- 给高风险技能单独审批与回归用例；
- 变更后观察至少一轮真实流量，再扩大范围。
3.5 Workspaces 的边界
Section titled “3.5 Workspaces 的边界”3.5.1 什么时候不该拆
Section titled “3.5.1 什么时候不该拆”下面这些场景，通常不建议一上来就拆多个 Workspace：
- 你只有一个主要使用者；
- 主要目标是“先跑通，先稳定”；
- 还在频繁改配置、改模型、改流程。
原因很现实：一拆就会多出更多路径、更多配置、更多排障分叉。
系统还没稳定时，这些复杂度通常比收益来得更快。
3.5.2 什么时候必须拆
Section titled “3.5.2 什么时候必须拆”以下信号出现时，建议拆分 Workspace（或至少拆 Agent）：
- 不同业务线需要强隔离上下文（例如客服与研发）；
- 不同人群共用入口，且会话/权限边界明显不同；
- 你需要独立的技能集合、模型策略或检查策略。
官方路由文档也给出对应实践：多 Agent 可以绑定到不同 workspace 与 session store，再由 bindings 做入站分流。
3.5.3 一套可维护的拆分准则
Section titled “3.5.3 一套可维护的拆分准则”给你一套“先稳后拆”的最小准则：
- 第一阶段（单工作区）：先把一条主流程跑稳，完成可跟做的排障闭环；
- 第二阶段（按职责拆）：只按“职责/权限边界”拆，不按想象中的“人格”拆；
- 第三阶段（按流量管理）：当并发、成本、检查压力上来，再做更细粒度路由。
一句话总结：先解决真实冲突，再引入结构复杂度。这符合 KISS，也更适合零基础读者稳步升级。
常见错误与排查
Section titled “常见错误与排查”| 现象 | 高概率原因 | 第一处理动作 |
|---|---|---|
| “我在 Slack 发消息，却回到了另一个地方” | 路由规则理解错误或绑定命中生效顺序误判 | 先核对 bindings 命中顺序与 channel/account/peer 条件 |
| “同一用户的上下文串台” | DM 会话范围（dmScope）配置不当 | 在多用户场景改为 per-channel-peer 或 per-account-channel-peer |
| “技能刚改完没生效” | 会话还在使用旧 skills snapshot | 新开会话重试；确认 skills watcher 与目录生效顺序 |
| “以为 Workspace 是绝对隔离，结果读到了不该读的路径” | 把默认 cwd 误当硬沙箱 | 显式启用 sandbox 策略，并复核 workspaceAccess 与工具权限 |
| “页面上能看见会话，但和渠道表现不一致” | 客户端缓存与 Gateway 事实源不一致 | 以 Gateway 侧会话/日志为准进行核对 |
- Gateway 是控制平面，Channel 是入口连接器，Skill 是能力封装，Workspace 是运行边界与上下文根。
- 一次请求并非“收到就答”，而是“路由 → 会话 → Agent loop → 工具执行 → 回传 + 留痕”。
- Skills 让系统从“会聊天”走向“能执行”，而 Workspace 决定了上下文与边界管理的可维护性。
- 拆 Workspace 的原则是“先稳后拆、按职责拆”，不要在系统未稳定前引入过多结构复杂度。