zclaw_openfang/docs/archive/openclaw-legacy/openclaw-deep-dive.md

OpenClaw 深度理解与 ZCLAW 设计映射

日期: 2026-03-12
目的: 先彻底理解 OpenClaw 的产品哲学、运行机制、配置模型与扩展边界，再据此反推 ZCLAW 每一个功能页和设置项为什么存在、应该达成什么效果。

---

一、结论先行

OpenClaw 不是一个“聊天 UI + 模型接入器”，而是一个围绕本地执行、持续上下文、设备身份、消息路由、技能生态与主动服务组织起来的 本地优先 Agent 操作系统。

如果只把它理解成：

• WebSocket Gateway
• 模型调用
• 聊天窗口

那会错过它真正的核心：

• Agent 是一个有独立工作空间、人格、约束和记忆边界的长期运行实体
• Gateway 是执行中枢，不只是转发层
• 配置文件不是“偏好设置”，而是系统行为定义
• AGENTS.md / SOUL.md / USER.md / IDENTITY.md 不是装饰文件，而是 Agent 的可审计大脑
• Heartbeat / Channels / Skills / MCP / Tools / Sandbox / Bindings 是一套完整的运行时系统

对 ZCLAW 来说，这意味着：

• 我们的“设置页”本质上不应该只是 UI 偏好页
• 很多设置项的真实目标是 配置 OpenClaw Runtime，不是更新前端本地 state
• “快速配置”不应被理解为普通表单，而应被理解为 创建/配置一个新的 Agent 实例
• 右侧 Agent 区域不应只是展示文案，而应反映当前选中 Agent 的真实身份、边界、工作目录、用户上下文与运行约束

---

二、OpenClaw 的本质：它到底是什么

1. 它是 Agent Runtime，而不是聊天前端

从官方文档与协议设计看，OpenClaw 的核心不是 UI，而是下面这些长期存在的运行对象：

• Gateway
• Agent workspace
• Sessions
• Channels
• Bindings
• Heartbeat
• Device identity / pairing
• Skills / Tools / MCP / Plugins

聊天只是这些能力暴露给人的一个入口。

2. 它的核心价值是“执行 + 持续性 + 可控性”

OpenClaw 的设计哲学非常稳定，几乎所有模块都服务于下面三件事：

• 执行
  • 能真正读写文件、跑命令、控浏览器、发消息
• 持续性
  • 不只是一次性问答，而是可长期运转的 Agent
• 可控性
  • 用户能看到配置、文本指令、工作区与约束，而不是黑盒

这决定了 OpenClaw 与很多“AI 工作台”产品的根本不同：

• 它强调的是 Agent 作为系统角色
• 不是把模型套上聊天框就结束

---

三、OpenClaw 的系统骨架

1. Gateway：系统中枢

Gateway 是 OpenClaw 的真正控制面板。它负责：

• WebSocket 协议握手与会话维持
• Agent 运行时管理
• Session/stream 事件分发
• Channels 消息收发
• 配置热加载与配置 RPC
• Skills / Tools / Plugins / Heartbeat 协调
• Device auth / pairing / scopes

所以对 ZCLAW 而言：

• 前端不是系统中心
• 前端只是 OpenClaw Runtime 的一个控制界面

2. Workspace：每个 Agent 的“根目录”

官方文档明确说明：Agent 有自己的 workspace，里面放 bootstrap 文件和长期上下文，例如：

• AGENTS.md
• SOUL.md
• USER.md
• IDENTITY.md
• TOOLS.md
• HEARTBEAT.md
• memory.md
• memory/YYYY-MM-DD.md

这说明 OpenClaw 的“Agent 配置”不仅是 JSON，还是 文件系统上的可读可改上下文。

3. 多 Agent：多个独立人格 / 工作空间 / 路由单元

官方 Multi-Agent Routing 文档给出的不是“多 Agent 协作流水线”，而是：

• 多个 agentId
• 多个 workspace
• 多个 bindings
• 多个渠道账号/电话号码/机器人身份
• 多套独立人格、记忆、沙箱与工具权限

这意味着 OpenClaw 的多 Agent，本质上更像：

• 多个长期助手
• 多个角色实例
• 多个路由终点

而不是：

• Planner / Executor / Combiner 这种任务分解型多智能体架构

对 ZCLAW 的直接影响：

• 我们左侧“分身”更接近 OpenClaw 的 agents.list
• 不应把“分身”只做成前端标签或临时角色描述
• 每个分身都应该最终映射到一个真实的 Agent 配置单元

---

四、配置模型：OpenClaw 为什么“像操作系统”

1. ~/.openclaw/openclaw.json 是系统配置，不是普通偏好设置

官方配置文档说明，openclaw.json 用来描述整个系统行为，例如：

• agents.defaults.*
• agents.list[]
• channels.*
• bindings
• heartbeat
• env
• tools
• sandbox
• plugins
• skills

并且支持：

• openclaw configure
• openclaw config get/set/unset
• config.get
• config.apply
• config.patch
• 热更新与重启语义

这说明 ZCLAW 的很多设置页，理应围绕下面的目标设计：

• 让用户理解自己正在配置 哪个 OpenClaw 子系统
• 让前端变成一个对配置进行可视化编辑的控制台

2. 配置是有层级和优先级的

OpenClaw 的很多能力都采用“默认值 + 局部覆盖”模型：

• agents.defaults.* 作为全局默认
• agents.list[].* 作为每个 Agent 的覆盖
• channels.defaults.* 作为全渠道默认
• channels.<channel>.* 覆盖
• channels.<channel>.accounts.<id>.* 再覆盖

这意味着 ZCLAW 做设置页时，必须把下面三类东西区分开：

• 系统级设置
• Agent 级设置
• 渠道/账号级设置

否则用户会搞不清：

• 当前改的是所有 Agent 还是某一个 Agent
• 当前改的是显示行为还是路由行为
• 当前改的是默认值还是具体实例

---

五、Bootstrap 文件的职责：为什么 OpenClaw 不靠数据库隐藏一切

1. AGENTS.md：操作规范与行为准则

默认 AGENTS.md 强调：

• 首次启动要建立 workspace
• Session 开始要先读 SOUL.md、USER.md、memory.md
• 不要泄露隐私和秘密
• 不要在外部消息面上发送半成品结果
• 工具和技能是通过 SKILL.md/TOOLS.md 组织的

它的定位更接近：

• Agent 的操作协议
• 安全规范
• 会话启动 checklist

2. SOUL.md：身份、气质、边界

官方模板把 SOUL.md 定义成：

• Core Truths
• Boundaries
• Vibe
• Continuity

也就是说，SOUL.md 不是“角色介绍”，而是：

• Agent 的底层人格与底线
• 它如何说话、如何决策、哪里必须克制

3. USER.md：关于用户这个人

USER.md 的职责不是泛化的“设置”，而是：

• 记录这个 Agent 正在服务的那个人是谁
• TA 的习惯、上下文、沟通偏好、时区、关注点

4. IDENTITY.md：Agent 的外显身份

官方模板中 IDENTITY.md 明确包含：

• Name
• Creature
• Vibe
• Emoji
• Avatar

这非常重要，因为它解释了 AutoClaw/类似产品里右侧 Agent 面板为什么会有：

• 名字
• emoji
• 风格
• 形象

对 ZCLAW 的直接映射：

• 右侧 Agent 区域展示的不是随机卡片
• 它应该是 Agent 的外显身份与用户上下文的可视化投影

---

六、Agent 的真正含义：OpenClaw 里“一个 Agent”是什么

结合官方 Multi-Agent Routing 文档，可以把一个 Agent 理解成：

• 一个 agentId
• 一个独立 workspace / agentDir
• 一组 bootstrap 文件
• 一套工具与 sandbox 规则
• 一套 session 历史
• 一组可能的 channel bindings
• 一种人格 / 工作方式 / 角色定位

因此“创建一个新 Agent”至少意味着下面几件事之一：

• 在 agents.list[] 中新增条目
• 为它准备独立 workspace 或 agentDir
• 写入/复制对应的 AGENTS.md / SOUL.md / USER.md / IDENTITY.md
• 给它绑定渠道、peer、账号或默认路由规则
• 根据风险模型配置它的工具权限/沙箱/Heartbeat

这也是为什么“快速配置”绝不能被简化成：

• 只存几个前端字段
• 只改一个 Zustand store
• 只改显示文案

它的本质是：

• 创建一个新的 Agent 实体

---

七、Routing：为什么 OpenClaw 的多 Agent 不只是“列表切换”

官方路由顺序大致是：

• peer 精确匹配
• parentPeer 继承匹配
• guild/team/roles 等平台级规则
• accountId 规则
• channel fallback
• default agent / first agent / main

这说明 Agent 不是只在 UI 中被“选中”，而是在运行时通过消息来源自动路由。

对 ZCLAW 的启发：

• 左侧分身列表只是 人能看懂的入口
• 真正完成 OpenClaw 化，还需要绑定路由语义
• 后续应该把“分身”扩展为：
  • Agent 基本资料
  • 渠道路由绑定
  • 默认 Agent / fallback Agent
  • 每 Agent 的 workspace / tools / heartbeat

---

八、Heartbeat：为什么“定时任务页”不能只做 cron 列表

官方 Heartbeat 文档显示：

• Heartbeat 是 定期触发一个完整 Agent turn
• 默认会读 HEARTBEAT.md
• 如果没事做，返回 HEARTBEAT_OK
• 可以配置投递目标，如 none、last 或具体渠道
• 可以设置 active hours
• 支持 per-agent heartbeat 覆盖

这说明 Heartbeat 与普通 cron 的区别在于：

• cron 是“按时间执行动作”
• Heartbeat 是“按时间唤醒 Agent 去检查是否有事要做”

对 ZCLAW 的直接含义：

• “定时任务页”如果只展示 cron 表达式，会偏离 OpenClaw
• 应该更多展示：
  • 哪些 Agent 开启了 heartbeat
  • Heartbeat 多久触发一次
  • 触发时会看什么（HEARTBEAT.md）
  • 结果发到哪里
  • 活跃时段限制

---

九、Skills：为什么它不是“插件市场”，而是 Agent 的工作知识库

官方文档与命令表明：

• openclaw skills list
• openclaw skills info <name>
• openclaw skills check

以及仓库中多处强调：

• SKILL.md
• 渐进式披露
• 每个技能是任务说明 + 规则 + 可选脚本/工具的组合

因此 Skills 的真实价值不是“多装几个功能按钮”，而是：

• 把复杂任务封装成可复用工作流
• 控制模型只在需要时展开更多上下文
• 让 Agent 在执行具体任务时有稳定手册可读

对 ZCLAW 的影响：

• 技能页不应该只是展示一个目录列表
• 它的目标应该是让用户理解：
  • 当前 Agent 可用哪些技能
  • 每个技能解决什么问题
  • 技能是否可被当前 Agent 触发
  • 额外目录实际上影响的是 Agent 的能力面

---

十、Channels：为什么 IM 频道不是“集成列表”而是系统输入面

OpenClaw 的渠道模型并不是简单“接一个 webhook”这么轻。

它包含：

• channel 类型
• accounts（多账号/多 bot）
• accountId
• allow/deny / mention / thread 绑定
• peer/group/direct message 路由
• bindings 到 agent

这意味着渠道页的真正目标是：

• 管理消息从哪里进系统
• 管理不同输入源归属哪个 Agent
• 管理默认/显式路由规则

因此 ZCLAW 的 IM 频道页未来应围绕：

• 已接入哪些 channel
• 每个 channel 有哪些 account
• 每个 account 绑定了哪些 agent
• 每个 Agent 接哪些 peer/group
• 是否 require mention

而不是只做：

• “飞书开/关”
• “添加一个渠道按钮”

---

十一、MCP：在 OpenClaw 里意味着什么

从现有资料可以确认，OpenClaw 原生支持 MCP / RPC adapters / 外部工具扩展。

在 OpenClaw 语境下，MCP 的作用不是点缀，而是：

• 给 Agent 扩展新的上下文来源与工具面
• 让技能可以调用标准化外部能力
• 让模型在不写死工具的情况下复用第三方协议能力

因此 ZCLAW 的 MCP 服务页的目的应是：

• 不是本地 toggle 假状态
• 而是管理 Agent 当前可访问的工具能力集合

---

十二、Device Auth：为什么 Gateway 连接不是普通 WebSocket 连接

官方协议和 troubleshooting 文档表明：

• 握手不是简单 ws.connect
• Gateway 会先发 connect.challenge
• 客户端必须：
  • 等待 challenge
  • 使用 challenge 参与签名 payload
  • 发送 device.nonce
  • 携带 device.id / publicKey / signature / signedAt
• device.id 来源于公钥指纹
• device auth 与 token / deviceToken / pairing / scopes 共同决定是否给权限

这件事对 ZCLAW 很关键，因为它说明：

• “连接 Gateway”不是 UI 层小问题
• 它背后是 OpenClaw 的安全边界
• 前端任何“连接设置”都必须尊重设备身份与鉴权语义

我们这次调试里已经验证：

• 少字段会被拒绝
• 错误 device.id 会触发 device-id-mismatch
• 错误 payload 会触发 device signature invalid
• 错误 client.mode 也会直接握手失败

所以后续实现必须把 Gateway 连接视作 协议适配工程，而不是按钮状态问题。

---

十三、ZCLAW 的功能设置为什么存在：逐页重解释

下面用 OpenClaw 视角重写 ZCLAW 设置页目的。

1. 通用

目的不是“桌面偏好”。

真实目标：

• 控制连接状态
• 暴露一部分系统级行为开关
• 说明 Agent 的运行模式、安全边界与可见性

2. 模型与 API

真实目标：

• 管理 OpenClaw 的 provider / model defaults
• 决定 Agent 运行时使用的主模型与 fallback
• 调试 Gateway 连接与鉴权

3. MCP 服务

真实目标：

• 定义 Agent 可以接入哪些外部能力
• 把工具面显式暴露给用户管理

4. 技能

真实目标：

• 管理 Agent 可以调用的工作流知识库
• 让用户知道 Agent 的“会做什么”来自哪里

5. IM 频道

真实目标：

• 管理系统从哪里收消息
• 管理消息如何路由到 Agent

6. 工作区

真实目标：

• 确定 Agent 的执行边界
• 决定 bootstrap 文件、上下文、技能和文件访问根目录
• 影响 sandbox / file restriction / file watching 等运行时行为

7. 数据与隐私

真实目标：

• 让用户理解数据存储在哪里
• 让用户知道哪些行为在本地、哪些可能涉及外部服务
• 明确优化计划 / telemetry 是否参与

8. 分身 / 快速配置

真实目标：

• 创建一个新的 Agent 实例
• 配置其身份、角色、风格、工作目录、约束和用户上下文
• 最终应该映射到：
  • agents.list[]
  • agent workspace / agentDir
  • IDENTITY.md / SOUL.md / USER.md / AGENTS.md

9. 右侧 Agent 面板

真实目标：

• 展示当前 Agent 的外显身份
• 展示它如何理解用户
• 展示它的边界、工作目录、当前模型和关注领域

---

十四、对 ZCLAW 当前实现的启发

1. 已经接近正确方向的部分

• 三栏桌面结构
• 分身 / IM / 定时任务主界面骨架
• 对 OpenClaw Gateway 的接入方向
• 自定义插件模式
• 使用 bootstrap 文件与默认配置模板
• 将中文模型、飞书、UI RPC 作为 OpenClaw 上层定制

2. 当前最容易继续偏离的部分

• 把设置页做成前端本地假状态
• 把分身做成只影响 UI 的列表项
• 把快速配置当成“多几个表单字段”
• 把 Heartbeat 误做成 cron 列表
• 把技能页误做成目录浏览器
• 把 IM 页误做成渠道开关

3. 应当优先建立的统一原则

后续所有功能实现都建议遵循下面这个判断标准：

如果一个页面改动之后，没有改变 OpenClaw Runtime 的真实行为、真实配置、真实路由、真实工作区或真实 Agent 上下文，那它大概率还只是“演示 UI”，不是系统能力。

---

十五、对当前几个关键争议点的明确判断

1. “快速配置到底是什么？”

结论：

• 快速配置 = 创建 / 更新一个 Agent
• 不是普通设置
• 不是只改前端 state
• 不是只改 quickConfig JSON

2. “右侧 Agent 区域应该显示什么？”

结论：

• 当前选中 Agent 的真实身份与用户上下文
• 不是硬编码卡片
• 不是随机占位数据

3. “Clone / 分身 应该如何理解？”

结论：

• 在 ZCLAW 语境里，它应该逐步收敛为 OpenClaw 的 Agent 实例
• 不是任务拆解型多智能体
• 不是单纯聊天角色标签

4. “连接 Gateway 为什么难？”

结论：

• 因为它不是普通 ws 连接，而是设备身份 + token/scopes + challenge 签名协议

---

十六、建议的 ZCLAW 后续实现顺序

P0：先把 Gateway 协议适配做对

包括：

• 正确 client.id / client.mode
• 正确 device.id
• 正确 v2/v3 签名 payload
• 正确 token/deviceToken 处理
• 正确错误展示

P1：把“分身”升级为真实 Agent 模型

包括：

• agents.list 映射
• 选中 Agent 的真实状态
• 右侧 Agent 面板绑定真实字段

P2：把快速配置升级为 Agent 创建向导

包括：

• 基本身份
• 用户上下文
• 工作目录
• 工具/文件限制
• heartbeat / skills / channels 初始策略

P3：把设置页升级为 OpenClaw Runtime 配置面板

包括：

• config.get / config.patch / config.apply
• agent defaults vs per-agent overrides
• channels/accounts/bindings
• skills / mcp / workspace / privacy

P4：做真正的产品化封装

包括：

• Tauri sidecar 管理 Gateway
• 首次安装/配置向导
• 错误诊断与修复建议
• AutoClaw 风格的上层体验

---

十七、给后续开发的操作性原则

后续写代码时，建议每次先问自己：

• 这个功能对应的是 OpenClaw 的哪个子系统？
• 它改的是系统级、Agent 级，还是渠道/账号级？
• 它落地到哪里：JSON 配置、workspace 文件、bindings、channel account，还是 runtime state？
• 它改变的是 UI 表象，还是 Agent 的真实行为？
• 它是否应该反映在右侧 Agent 面板 / 左侧分身列表 / 渠道路由 / heartbeat 行为中？

如果这些问题答不清，通常说明实现路径还没对齐 OpenClaw。

---

十八、参考资料

官方公开资料

1. OpenClaw Gateway Protocol
   https://docs.openclaw.ai/gateway/protocol
2. OpenClaw Gateway Troubleshooting
   https://docs.openclaw.ai/gateway/troubleshooting
3. OpenClaw Configuration
   https://docs.openclaw.ai/gateway/configuration
4. OpenClaw Multi-Agent Routing
   https://docs.openclaw.ai/concepts/multi-agent
5. OpenClaw Heartbeat
   https://docs.openclaw.ai/gateway/heartbeat
6. OpenClaw Skills CLI
   https://docs.openclaw.ai/cli/skills
7. OpenClaw Default AGENTS.md
   https://docs.openclaw.ai/reference/AGENTS.default
8. OpenClaw SOUL.md Template
   https://docs.openclaw.ai/reference/templates/SOUL
9. OpenClaw USER Template
   https://docs.openclaw.ai/reference/templates/USER
10. OpenClaw IDENTITY Template
    https://docs.openclaw.ai/reference/templates/IDENTITY
11. Third-party client authentication guide issue
    https://github.com/openclaw/openclaw/issues/17571
12. Device signature mismatch issue
    https://github.com/openclaw/openclaw/issues/39667

仓库内现有文档

1. docs/deviation-analysis.md
2. docs/architecture-v2.md
3. README.md
4. config/openclaw.default.json
5. config/AGENTS.md
6. config/SOUL.md
7. config/USER.md
8. config/IDENTITY.md

---

十九、这份文档对 ZCLAW 当前工作的直接作用

它可以作为后续所有实现的判断依据，尤其是：

• Gateway 连接修复
• 分身/快速配置重构
• 右侧 Agent 面板设计
• 工作区设置页语义校正
• IM/Skills/MCP/Heartbeat 页面重构

一句话总结：

ZCLAW 不是要“做一个像 AutoClaw 的前端”，而是要“在真正理解 OpenClaw 运行模型之后，做一个面向中文场景的 Tauri 封装层”。