OpenClaw 的心智模型：Gateway / Channel / Skill / Workspace
📖 上一章你已经把 OpenClaw 跑起来了，这章我们先不急着改配置，先把”地图”看明白。
想象一下：你走进一家大公司，前台在哪、谁管人事、谁管技术、资料室在哪——这些都不知道的话，肯定会跑错办公室。
这章就是帮你搞清楚：一条消息从进来到出去，都经过谁的手。
本章你将学会什么
Section titled “本章你将学会什么”- 用一句话记住五个核心概念，并知道它们之间的关系
- 看懂 OpenClaw 的核心结构图，分清”管事的”和”干活的”
- 走通”一条消息”从接入到回复的完整流程
- 理解为什么 Skill + Tools 才是”会聊天”到”能干活”的关键
- 搞明白 Workspace 什么时候该拆、什么时候不该拆
- ✅ 你已完成第 2 章，能在本地打开 Control UI（
127.0.0.1:18789） - ✅ 你知道”终端/命令行”和”配置文件”这两个基本概念
3.1 五个核心概念，一句话讲清
Section titled “3.1 五个核心概念，一句话讲清”先抛结论，后面再展开。记住这五句话，你就有了最基本的”导航能力”：
| 概念 | 一句话解释 |
|---|---|
| Gateway | 总调度室——所有消息必经的管理中枢 |
| Channel | 门口迎宾——把外部聊天软件接进来的连接器 |
| Tools | 手和脚——能帮你干活的各种能力（读文件、执行命令、搜网页…） |
| Skill | 说明书——告诉 AI “这类事该先用哪些工具、怎么一步步做” |
| Workspace | 工位——这个 AI 干活时的”工作文件夹”，读写文件都在这 |
💡 小贴士：很多人会把 Skill 和 Tools 搞混。记住一个简单区分：
- Tools = 你有哪些能力（能做什么）
- Skill = 你知道怎么使用这些能力的步骤（怎么做）
就像你有一把螺丝刀（Tools），但怎么组装宜家家具，得看说明书（Skill）。
3.1.1 Gateway：系统总控台
Section titled “3.1.1 Gateway：系统总控台”官方定义：Gateway 是 OpenClaw 的”单一控制平面”（single control plane），负责统一管理会话、渠道、工具调用与状态事件。客户端与节点通过 WebSocket 接入，默认地址 127.0.0.1:18789。
人话版：
Gateway 就是总调度室。想象一家餐厅：
- 顾客在门口点菜（消息进来）
- 调度室决定这道菜交给哪个厨师、要用什么食材
- 厨师做好了，调度室再把菜端给顾客
你在 Control UI（127.0.0.1:18789）上看到的大部分状态——在线不在线、有没有报错——根都在 Gateway，不是前端页面”现场编的”。
🔧 记住一点：如果你的 UI 显示有问题，先去看 Gateway 的日志，通常能发现真正的原因。
3.1.2 Channel：消息入口连接器
Section titled “3.1.2 Channel：消息入口连接器”官方定义：Channel 是把 OpenClaw 接到外部聊天软件的连接器。Telegram、Slack、Discord、飞书/WebChat 都属于 Channel。
人话版：
Channel 就是门口迎宾。每个聊天软件就是一个 Channel，它们各有各的接入方式：
- Telegram 要 Bot Token
- 飞书要 Webhook 或扫码登录
- Slack 可能用 WebSocket
但进了门之后，Gateway 就把它们统一对待了——不管从哪个渠道进来，在 OpenClaw 内部都是同一套”消息格式”。
一个关键点：回复是原路返回的，不是让 AI 自由选择”从哪回复”。这意味着：
- 从 Telegram 发的消息 → 回复回到 Telegram
- 从飞书发的消息 → 回复回到飞书
这叫确定性路由，目的是可控、可追溯。
3.1.3 Skill / Workspace：能力封装与工作边界
Section titled “3.1.3 Skill / Workspace：能力封装与工作边界”官方定义：
- Skill 是能力封装（通常以
SKILL.md为入口），告诉系统”这类任务怎么调用工具去完成” - Workspace 是 Agent 的工作目录与上下文根（默认
~/.openclaw/workspace），用于承载文件、记忆与本地上下文
人话版：
- Skill = 你给 AI 写的操作手册。比如”遇到代码审查任务时，先用
read工具读文件，再用exec跑测试，最后总结问题” - Workspace = 这个 AI 的工位。它只能在这个工位里读写文件，默认路径是
~/.openclaw/workspace
⚠️ 容易踩的坑：Workspace 是”默认工作目录”，但不是硬沙箱。如果你需要严格隔离（比如防止 AI 读到不该读的文件），需要额外配置 sandbox 策略。
3.1.4 Tools：Agent 的”手和脚”
Section titled “3.1.4 Tools：Agent 的”手和脚””官方定义：Tools 是 Agent 真正”动手干活”的能力集合，包括读写文件、执行命令、网页检索、浏览器自动化等。
人话版：
Tools 就是 AI 的工具箱。常见工具有：
| 工具 | 能做什么 | 举例 |
|---|---|---|
read / write / edit | 读写文件 | 读取配置文件、写个日志 |
exec / process | 执行命令 | 跑个 Python 脚本、编译代码 |
web_search / web_fetch | 搜网页 | 查资料、抓取页面 |
browser | 浏览器自动化 | 帮你点按钮、填表单 |
再次强调：
- Tools 决定”能做什么”
- Skill 决定”怎么做”
有 Skill 但没开对应 Tools = 有说明书但没工具，活还是干不了。 反过来，Tools 全开但没 Skill = 工具乱扔，很可能帮倒忙。
📋 术语速记卡（零基础版）
Section titled “📋 术语速记卡（零基础版）”| 术语 | 接地气说法 | 官方语义 |
|---|---|---|
| Gateway | ”总调度室” | 单一控制平面，统一会话/路由/事件，默认监听 127.0.0.1:18789 |
| Agent | ”一个独立大脑” | 每个 Agent 有独立 workspace、会话存储和认证配置 |
| Workspace | ”这个 Agent 的工位” | 默认 ~/.openclaw/workspace；是默认 cwd，不是硬沙箱 |
| Agent Directory（agentDir） | “放技术状态的目录” | 会话、认证、运行状态等技术数据目录（与 workspace 分离） |
| Channel | ”消息入口” | Telegram/Slack/Discord/飞书等连接器 |
| 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 / … 发消息） │ ▼Channel Connector（渠道连接器） │ 统一入站事件 ▼Gateway（总调度室 / 控制平面） ├─ 会话管理：这条消息该归哪个会话？ ├─ 路由决策：该交给哪个 Agent 处理？ ├─ Agent Loop：跑模型 + 调工具 ├─ 状态/事件流：告诉前端"正在干活"还是"干完了" └─ Web 控制台（Control UI / WebChat） │ ▼ Skill（能力说明书） ↔ Workspace（工位/文件） │ ▼ 结果回传到原渠道（Ta 来 Ta 回）记住一句线头：
Channel 负责接消息，Gateway 负责调度，Tools 负责动手，Skill 负责步骤，Workspace 负责上下文。
3.2.2 关键边界：控制面 vs 执行面
Section titled “3.2.2 关键边界：控制面 vs 执行面”OpenClaw 可以粗分成两层：
| 层面 | 负责什么 | 出问题会怎样 |
|---|---|---|
| 控制面（Gateway） | 连接、会话、路由、权限、事件广播 | 消息进不来、找不到 Agent、UI 显示异常 |
| 执行面（Agent Loop + Tools） | 模型推理、调用工具、产出结果 | 模型没回复、工具调用失败、结果不对 |
排障小技巧：
- 页面能打开但不出回复？先判断是控制面问题（连接/路由）还是执行面问题（模型密钥/工具超时）
- 怎么判断？看 Gateway 日志里有没有
accepted（收到消息）→running（正在处理）→end（处理完）
3.2.3 数据流向：消息、状态、结果
Section titled “3.2.3 数据流向：消息、状态、结果”一次对话过程中，其实有三条”流水线”在同时跑：
- 消息流：用户输入 → 模型输出 → 渠道回传
- 状态流：
connect、presence、health、lifecycle等事件（告诉前端”我还活着”） - 结果流：工具调用结果、会话落盘、日志
这三条流最后都会在 Gateway 汇总，统一的暴露给 UI/CLI/API。
💡 为什么看日志很重要：只盯着聊天软件里那一条消息通常不够，你得回到 Gateway 看上下文和事件，才能知道”为什么 AI 这次没回”。
⚠️ 容易被说错的三个点（社区常见误区）
Section titled “⚠️ 容易被说错的三个点（社区常见误区）”-
Canvas 不是独立端口
- ❌ 有人说”Canvas 在 18790 端口”
- ✅ 真相：Canvas 挂在 Gateway 同端口（默认
18789）下的固定路径，如/__openclaw__/canvas/
-
Heartbeat 不是 2 小时
- ❌ 有人说”默认 2 小时心跳一次”
- ✅ 真相：默认是
30m（30分钟），只有特定 OAuth 场景才是1h
-
OpenClaw 不是”原样直连 pi-coding runtime”
- ❌ 有人说”就是 pi-mono 直接套个壳”
- ✅ 真相：OpenClaw 嵌入了运行时并自管 session/discovery/tool wiring，是派生自
pi-mono但做了封装
3.3 一次请求的生命周期
Section titled “3.3 一次请求的生命周期”📌 这节是全章最核心的部分。建议先通读一遍理解流程，后面遇到问题时再回来对照。
3.3.1 消息接入与路由决策
Section titled “3.3.1 消息接入与路由决策”一条消息进来后，系统不是立刻回答，而是先确定**“这条消息归谁管”**。
路由顺序（官方文档定义）：
- 精确匹配 peer（用户 ID）
- 组合匹配 channel + peer
- 按 team / workspace 维度
- 匹配 account
- 匹配 channel
- 以上都不行 → 用默认 Agent
同时，会话键（session key） 也会区分：
- 直聊（DM）→ 可以折叠到主会话
- 群聊/频道 → 通常独立会话键，避免串台
🔍 排查提示：如果”我在 Slack 发消息，却跑到了另一个 Agent”，先检查 bindings 命中顺序和 channel/account/peer 条件是否写对了。
3.3.2 工具调用与中间状态
Section titled “3.3.2 工具调用与中间状态”路由确定后，进入 Agent Loop（智能体循环）：
1. 参数校验 → 返回 accepted（拿到 runId）2. 装配上下文：会话历史 + skills 快照 + bootstrap 内容3. 模型推理 ↔ 工具调用交替执行4. 持续发出流式事件：assistant / tool / lifecycle5. 结束：end 或 error一个重要特性：每个会话串行执行（serialized run）。这意味着：
- 同一会话不会同时跑两个任务
- 避免了”上一轮还没写完、下一轮又覆盖状态”的混乱
💡 如果你发现”AI 回复顺序乱了”，很可能是并发问题，检查一下是否在同一个 sessionKey 下发了多个请求。
3.3.3 输出回传与日志留痕
Section titled “3.3.3 输出回传与日志留痕”当生命周期进入 end 或 error，系统会：
- 对用户：发送最终回复到原渠道
- 对系统：更新会话存储、记录工具结果、写日志
这也是为什么我们说 “Gateway 是事实源（source of truth）”：
- 会话状态在 Gateway 所在主机上
- 不是散落在各客户端本地缓存里
🔧 排查提示：如果 UI 和渠道表现不一致，以 Gateway 侧的会话/日志为准。
3.4 Skills 为什么是生产力
Section titled “3.4 Skills 为什么是生产力”3.4.1 技能的输入/输出边界
Section titled “3.4.1 技能的输入/输出边界”很多人以为 Skill 就是”长提示词”，其实不完全对。
更准确的理解：Skill 是”带边界的能力单元”。
| 维度 | Skill 包含的内容 |
|---|---|
| 触发条件 | 什么情况下用这个技能？ |
| 依赖环境 | 需要哪些工具可用？需要什么环境变量？ |
| 执行步骤 | 第一步做什么、第二步做什么… |
| 输出格式 | 最终结果长什么样？ |
好处：
- 输入更结构化（不会随便一段话就把 AI 搞懵）
- 输出更稳定（知道期望是什么）
- 失败更可定位（卡在参数、依赖还是权限，一目了然）
3.4.2 技能执行的可追踪与可复用
Section titled “3.4.2 技能执行的可追踪与可复用”官方文档说：Skills 在会话启动时会生成可用快照（skills snapshot），并且可以热刷新。
两个实在的收益：
- 可追踪：这次对话用了哪批技能，可以回溯
- 可复用：同名技能的生效顺序是固定的：
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 原则（Keep It Simple, Stupid），更适合零基础读者稳步升级。
常见错误与排查
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 = 门口迎宾，把外部聊天软件接进来
-
Tools = 工具箱，决定 AI “能做什么”
-
Skill = 说明书，告诉 AI “怎么做”
-
Workspace = 工位，AI 干活时的文件读写边界
-
一次请求的生命周期：路由 → 会话 → Agent Loop → 工具执行 → 回传 + 留痕
-
Skill + Tools = 从”会聊天”到”能干活”的关键组合
-
Workspace 拆分原则：先稳后拆、按职责拆，不要在系统未稳定前引入过多复杂度
🎯 下一章预告：了解了整体架构，下一章我们将动手配置第一个 Channel（比如 Telegram 或飞书），让你的 AI 真正能接收和回复消息。