# ZCLAW 深度理解与 ZCLAW 设计映射 **日期**: 2026-03-12 **目的**: 先彻底理解 ZCLAW 的产品哲学、运行机制、配置模型与扩展边界，再据此反推 ZCLAW 每一个功能页和设置项为什么存在、应该达成什么效果。 --- ## 一、结论先行 ZCLAW **不是一个“聊天 UI + 模型接入器”**，而是一个围绕本地执行、持续上下文、设备身份、消息路由、技能生态与主动服务组织起来的 **本地优先 Agent 操作系统**。 如果只把它理解成： - WebSocket Gateway - 模型调用 - 聊天窗口 那会错过它真正的核心： - **Agent 是一个有独立工作空间、人格、约束和记忆边界的长期运行实体** - **Gateway 是执行中枢，不只是转发层** - **配置文件不是“偏好设置”，而是系统行为定义** - **AGENTS.md / SOUL.md / USER.md / IDENTITY.md 不是装饰文件，而是 Agent 的可审计大脑** - **Heartbeat / Channels / Skills / MCP / Tools / Sandbox / Bindings 是一套完整的运行时系统** 对 ZCLAW 来说，这意味着： - 我们的“设置页”本质上不应该只是 UI 偏好页 - 很多设置项的真实目标是 **配置 ZCLAW Runtime**，不是更新前端本地 state - “快速配置”不应被理解为普通表单，而应被理解为 **创建/配置一个新的 Agent 实例** - 右侧 `Agent` 区域不应只是展示文案，而应反映当前选中 Agent 的真实身份、边界、工作目录、用户上下文与运行约束 --- ## 二、ZCLAW 的本质：它到底是什么 ### 1. 它是 Agent Runtime，而不是聊天前端 从官方文档与协议设计看，ZCLAW 的核心不是 UI，而是下面这些长期存在的运行对象： - **Gateway** - **Agent workspace** - **Sessions** - **Channels** - **Bindings** - **Heartbeat** - **Device identity / pairing** - **Skills / Tools / MCP / Plugins** 聊天只是这些能力暴露给人的一个入口。 ### 2. 它的核心价值是“执行 + 持续性 + 可控性” ZCLAW 的设计哲学非常稳定，几乎所有模块都服务于下面三件事： - **执行** - 能真正读写文件、跑命令、控浏览器、发消息 - **持续性** - 不只是一次性问答，而是可长期运转的 Agent - **可控性** - 用户能看到配置、文本指令、工作区与约束，而不是黑盒 这决定了 ZCLAW 与很多“AI 工作台”产品的根本不同： - 它强调的是 **Agent 作为系统角色** - 不是把模型套上聊天框就结束 --- ## 三、ZCLAW 的系统骨架 ### 1. Gateway：系统中枢 Gateway 是 ZCLAW 的真正控制面板。它负责： - WebSocket 协议握手与会话维持 - Agent 运行时管理 - Session/stream 事件分发 - Channels 消息收发 - 配置热加载与配置 RPC - Skills / Tools / Plugins / Heartbeat 协调 - Device auth / pairing / scopes 所以对 ZCLAW 而言： - 前端不是系统中心 - 前端只是 **ZCLAW 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` 这说明 ZCLAW 的“Agent 配置”不仅是 JSON，还是 **文件系统上的可读可改上下文**。 ### 3. 多 Agent：多个独立人格 / 工作空间 / 路由单元 官方 `Multi-Agent Routing` 文档给出的不是“多 Agent 协作流水线”，而是： - 多个 `agentId` - 多个 `workspace` - 多个 `bindings` - 多个渠道账号/电话号码/机器人身份 - 多套独立人格、记忆、沙箱与工具权限 这意味着 ZCLAW 的多 Agent，本质上更像： - 多个长期助手 - 多个角色实例 - 多个路由终点 而不是： - Planner / Executor / Combiner 这种任务分解型多智能体架构 对 ZCLAW 的直接影响： - 我们左侧“分身”更接近 ZCLAW 的 `agents.list` - 不应把“分身”只做成前端标签或临时角色描述 - 每个分身都应该最终映射到一个真实的 Agent 配置单元 --- ## 四、配置模型：ZCLAW 为什么“像操作系统” ### 1. `~/.zclaw/zclaw.json` 是系统配置，不是普通偏好设置 官方配置文档说明，`zclaw.json` 用来描述整个系统行为，例如： - `agents.defaults.*` - `agents.list[]` - `channels.*` - `bindings` - `heartbeat` - `env` - `tools` - `sandbox` - `plugins` - `skills` 并且支持： - `zclaw configure` - `zclaw config get/set/unset` - `config.get` - `config.apply` - `config.patch` - 热更新与重启语义 这说明 ZCLAW 的很多设置页，理应围绕下面的目标设计： - 让用户理解自己正在配置 **哪个 ZCLAW 子系统** - 让前端变成一个对配置进行可视化编辑的控制台 ### 2. 配置是有层级和优先级的 ZCLAW 的很多能力都采用“默认值 + 局部覆盖”模型： - `agents.defaults.*` 作为全局默认 - `agents.list[].*` 作为每个 Agent 的覆盖 - `channels.defaults.*` 作为全渠道默认 - `channels..*` 覆盖 - `channels..accounts..*` 再覆盖 这意味着 ZCLAW 做设置页时，必须把下面三类东西区分开： - **系统级设置** - **Agent 级设置** - **渠道/账号级设置** 否则用户会搞不清： - 当前改的是所有 Agent 还是某一个 Agent - 当前改的是显示行为还是路由行为 - 当前改的是默认值还是具体实例 --- ## 五、Bootstrap 文件的职责：为什么 ZCLAW 不靠数据库隐藏一切 ### 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 的真正含义：ZCLAW 里“一个 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：为什么 ZCLAW 的多 Agent 不只是“列表切换” 官方路由顺序大致是： - peer 精确匹配 - parentPeer 继承匹配 - guild/team/roles 等平台级规则 - accountId 规则 - channel fallback - default agent / first agent / main 这说明 Agent 不是只在 UI 中被“选中”，而是在运行时通过消息来源自动路由。 对 ZCLAW 的启发： - 左侧分身列表只是 **人能看懂的入口** - 真正完成 ZCLAW 化，还需要绑定路由语义 - 后续应该把“分身”扩展为： - 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 表达式，会偏离 ZCLAW - 应该更多展示： - 哪些 Agent 开启了 heartbeat - Heartbeat 多久触发一次 - 触发时会看什么（HEARTBEAT.md） - 结果发到哪里 - 活跃时段限制 --- ## 九、Skills：为什么它不是“插件市场”，而是 Agent 的工作知识库 官方文档与命令表明： - `zclaw skills list` - `zclaw skills info ` - `zclaw skills check` 以及仓库中多处强调： - `SKILL.md` - 渐进式披露 - 每个技能是任务说明 + 规则 + 可选脚本/工具的组合 因此 Skills 的真实价值不是“多装几个功能按钮”，而是： - 把复杂任务封装成可复用工作流 - 控制模型只在需要时展开更多上下文 - 让 Agent 在执行具体任务时有稳定手册可读 对 ZCLAW 的影响： - 技能页不应该只是展示一个目录列表 - 它的目标应该是让用户理解： - 当前 Agent 可用哪些技能 - 每个技能解决什么问题 - 技能是否可被当前 Agent 触发 - 额外目录实际上影响的是 Agent 的能力面 --- ## 十、Channels：为什么 IM 频道不是“集成列表”而是系统输入面 ZCLAW 的渠道模型并不是简单“接一个 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：在 ZCLAW 里意味着什么 从现有资料可以确认，ZCLAW 原生支持 MCP / RPC adapters / 外部工具扩展。 在 ZCLAW 语境下，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 层小问题 - 它背后是 ZCLAW 的安全边界 - 前端任何“连接设置”都必须尊重设备身份与鉴权语义 我们这次调试里已经验证： - 少字段会被拒绝 - 错误 `device.id` 会触发 `device-id-mismatch` - 错误 payload 会触发 `device signature invalid` - 错误 `client.mode` 也会直接握手失败 所以后续实现必须把 Gateway 连接视作 **协议适配工程**，而不是按钮状态问题。 --- ## 十三、ZCLAW 的功能设置为什么存在：逐页重解释 下面用 ZCLAW 视角重写 ZCLAW 设置页目的。 ### 1. 通用 目的不是“桌面偏好”。 真实目标： - 控制连接状态 - 暴露一部分系统级行为开关 - 说明 Agent 的运行模式、安全边界与可见性 ### 2. 模型与 API 真实目标： - 管理 ZCLAW 的 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 / 定时任务主界面骨架 - 对 ZCLAW Gateway 的接入方向 - 自定义插件模式 - 使用 bootstrap 文件与默认配置模板 - 将中文模型、飞书、UI RPC 作为 ZCLAW 上层定制 ### 2. 当前最容易继续偏离的部分 - 把设置页做成前端本地假状态 - 把分身做成只影响 UI 的列表项 - 把快速配置当成“多几个表单字段” - 把 Heartbeat 误做成 cron 列表 - 把技能页误做成目录浏览器 - 把 IM 页误做成渠道开关 ### 3. 应当优先建立的统一原则 后续所有功能实现都建议遵循下面这个判断标准： > 如果一个页面改动之后，没有改变 ZCLAW Runtime 的真实行为、真实配置、真实路由、真实工作区或真实 Agent 上下文，那它大概率还只是“演示 UI”，不是系统能力。 --- ## 十五、对当前几个关键争议点的明确判断 ### 1. “快速配置到底是什么？” 结论： - **快速配置 = 创建 / 更新一个 Agent** - 不是普通设置 - 不是只改前端 state - 不是只改 `quickConfig` JSON ### 2. “右侧 Agent 区域应该显示什么？” 结论： - 当前选中 Agent 的真实身份与用户上下文 - 不是硬编码卡片 - 不是随机占位数据 ### 3. “Clone / 分身 应该如何理解？” 结论： - 在 ZCLAW 语境里，它应该逐步收敛为 ZCLAW 的 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：把设置页升级为 ZCLAW 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 风格的上层体验 --- ## 十七、给后续开发的操作性原则 后续写代码时，建议每次先问自己： - 这个功能对应的是 ZCLAW 的哪个子系统？ - 它改的是系统级、Agent 级，还是渠道/账号级？ - 它落地到哪里：JSON 配置、workspace 文件、bindings、channel account，还是 runtime state？ - 它改变的是 UI 表象，还是 Agent 的真实行为？ - 它是否应该反映在右侧 Agent 面板 / 左侧分身列表 / 渠道路由 / heartbeat 行为中？ 如果这些问题答不清，通常说明实现路径还没对齐 ZCLAW。 --- ## 十八、参考资料 ### 官方公开资料 1. ZCLAW Gateway Protocol https://docs.zclaw.ai/gateway/protocol 2. ZCLAW Gateway Troubleshooting https://docs.zclaw.ai/gateway/troubleshooting 3. ZCLAW Configuration https://docs.zclaw.ai/gateway/configuration 4. ZCLAW Multi-Agent Routing https://docs.zclaw.ai/concepts/multi-agent 5. ZCLAW Heartbeat https://docs.zclaw.ai/gateway/heartbeat 6. ZCLAW Skills CLI https://docs.zclaw.ai/cli/skills 7. ZCLAW Default AGENTS.md https://docs.zclaw.ai/reference/AGENTS.default 8. ZCLAW SOUL.md Template https://docs.zclaw.ai/reference/templates/SOUL 9. ZCLAW USER Template https://docs.zclaw.ai/reference/templates/USER 10. ZCLAW IDENTITY Template https://docs.zclaw.ai/reference/templates/IDENTITY 11. Third-party client authentication guide issue https://github.com/zclaw/zclaw/issues/17571 12. Device signature mismatch issue https://github.com/zclaw/zclaw/issues/39667 ### 仓库内现有文档 1. `docs/deviation-analysis.md` 2. `docs/architecture-v2.md` 3. `README.md` 4. `config/zclaw.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 的前端”，而是要“在真正理解 ZCLAW 运行模型之后，做一个面向中文场景的 Tauri 封装层”。