10 · 设计复盘：OpenClaw 为什么这样设计

前 9 篇讲的是零件。这一篇讲整机。

OpenClaw 的核心不是“更会聊天”，而是把一个 AI Agent 放进可运行、可审计、可限制、可恢复的本地系统里。它用 Gateway 管入口，用 Session 管当前上下文，用 Workspace 管长期工作环境，用 Memory 管跨会话事实，用 Tool policy 和 Sandbox 管能力边界，用 Heartbeat / Cron / Webhooks 把时间和外部事件接进来。

这套设计的底层目标很朴素：

1. 一张图看完整系统

flowchart LR
  U[User / external system] --> C[Channel / Webhook / CLI]
  C --> G[Gateway]
  G --> R[Routing]
  R --> S[Session key]
  S --> L[Agent Loop]
  W[Workspace files] --> X[Context assembly]
  M[Memory files + search] --> X
  X --> L
  L --> P[Model]
  P --> T[Tools]
  TP[Tool policy] --> T
  SB[Sandbox / elevated] --> T
  T --> L
  L --> O[Reply / persistence]
  O --> C
  HB[Heartbeat] --> G
  CR[Cron] --> G
  BK[Background tasks ledger] --> G

按官方文档拆开：

2. 系统不变量

理解 OpenClaw，先记这几条不变量：

• Gateway 是控制面：Messaging channels、Control UI、CLI、Nodes、WebChat 都围绕 Gateway；clients 和 nodes 通过 WebSocket 接入。不要把某个聊天渠道当成系统核心。
• Agent Loop 按 session 串行：一次 run 是 intake -> context assembly -> model inference -> tool execution -> streaming replies -> persistence。同一 session 要避免互踩。
• Workspace 是工作环境：工具相对路径以 workspace 为默认 cwd。Workspace 不是安全边界。
• Memory 没有隐藏层：模型只“记得”写入磁盘的内容，memory search 只是帮它检索材料。不要以为模型自动保留所有历史。
• Context 不是 Memory：Context 是本次 run 发给模型的全部输入，受窗口限制。不是存了 memory 就等于本轮一定看见。
• Security 默认是个人 operator boundary：shared Gateway 不等于敌对多租户安全边界。陌生用户或客户要拆 Gateway、credentials、OS user 或 host。

3. 取舍一：长驻 Gateway，而不是每个平台各跑一套

OpenClaw 选择单个长期运行的 Gateway 来管理平台连接。

得到的是：

• WhatsApp、Telegram、Slack、Discord、Signal、iMessage、WebChat 等入口统一接入。
• CLI、macOS app、web UI、automations 走同一套 Gateway API。
• 健康状态、presence、heartbeat、cron、agent run 都能在一个控制面观察。

付出的代价是：

• Gateway 是关键进程，挂了就影响所有 channel。
• 配置和日志集中在 ~/.openclaw，权限管理必须严谨。
• 非 loopback 暴露会扩大攻击面。

适用边界很简单：个人助理、小团队、单 operator boundary 适合共享一个 Gateway；敌对多租户或客户共享 runtime 时应该拆 Gateway。

4. 取舍二：嵌入式 Agent Loop，而不是黑盒外包

OpenClaw 不是简单把消息转给一个外部聊天 API。它有自己的 embedded agent runtime 和 agent loop。

这让 OpenClaw 能控制：

• session resolution；
• model 和 auth profile 选择；
• skills snapshot；
• prompt assembly；
• tool execution；
• streaming；
• compaction retry；
• transcript persistence；
• hooks；
• timeout 和 cancellation。

得到的是可观察、可插拔、可约束。代价是系统概念变多：Agent Loop、Session、Context、Tool policy、Hooks 都需要理解。

这个取舍的实际意义：

5. 取舍三：Workspace 文件，而不是隐藏配置面板

Workspace 里放的是 Agent 可读、可修改、可迁移的工作材料：

得到的是透明和可迁移：

• 读文件就能看到 Agent 的规则和记忆。
• 私有 git repo 就能做备份和回滚。
• 迁移 workspace 比迁移数据库更直观。

代价是：

• Workspace 必须当作私密记忆处理。
• 不该把 secrets、raw chat dumps、~/.openclaw 里的配置和 credentials 提交进去。
• Workspace 不是 sandbox，安全隔离要另配。

6. 取舍四：磁盘 Memory，而不是模型隐藏状态

OpenClaw 的长期记忆不是“模型自己会记住”，而是写入 workspace 文件。

官方 Memory 体系的关键件包括：

• MEMORY.md：durable facts、preferences、decisions。
• memory/YYYY-MM-DD.md：daily notes。
• DREAMS.md：optional review diary and dreaming summaries。
• memory_search：semantic + keyword retrieval。
• memory_get：exact file / line range read。
• memory flush：compaction 前的 silent turn。

得到的是：

• 人能检查、编辑、删除。
• Git 能追踪记忆变化。
• Memory 和 Context 分离，降低“当前窗口塞爆”的风险。

代价是：

• Agent 必须真的把重要信息写入文件。
• Memory 质量取决于写入和整理。
• 需要检索时要用 memory_search 或结构化 wiki 插件，而不是假设所有历史自动可见。

正确心智模型：

7. 取舍五：确定性路由，而不是 AI 自己分发

Channel Routing 文档强调：模型不选择 channel，host config 决定路由。

多 Agent 路由也类似：Exact peer、thread parent、guild roles、guild、team、account、channel、default agent，按固定顺序匹配。

得到的是：

• 消息不会因为模型判断失误发给错误 Agent。
• 审计时可以从配置倒推消息流向。
• 安全规则能和路由规则绑定。

代价是：

• 需要配置 bindings。
• 用户要知道在哪个 channel 或 thread 找哪个 Agent。
• 配错路由时，系统会稳定地错，需要人修配置。

这就是 OpenClaw 的一个核心立场：

8. 取舍六：Session 生命周期，而不是无限聊天

Session 管的是当前对话桶。它有 sessionKey 和当前 sessionId，transcript 以 JSONL 存在磁盘。

生命周期规则包括：

• Daily reset 默认在 Gateway host 本地时间凌晨 4 点后换新 session。
• Idle reset 可选。
• /new 和 /reset 手动换新 session。
• Daily 和 idle 同时配置时，先到期的生效。
• 旧 transcript 不等于删除，memory 不等于 reset。

得到的是：

• 上下文不会无限增长。
• transcript 和当前运行状态分开。
• compaction、pruning、session cleanup 有明确对象。

代价是：

• 新手会误以为 reset 等于失忆。
• 重要事实必须进入 memory 或 workspace 文件，不能只停留在旧 session 里。

9. 取舍七：Context 有预算，而不是全量塞进去

Context 受模型窗口限制，OpenClaw 要构建 system prompt、注入 workspace files、带 conversation history、工具结果和附件。

为了不让 prompt 失控，OpenClaw 提供：

• /status 看窗口占用；
• /context list 看注入内容；
• /context detail 看更细的大小贡献；
• compaction 总结长对话；
• pruning 从本次模型输入里移除旧工具结果，但不改 transcript；
• context engine 插件接口。

得到的是可控成本和可解释的上下文组成。

代价是你不能说“Agent 应该看到所有东西”。它只能看到这次 run 被装进 context 的东西。

10. 取舍八：Heartbeat、Cron、Webhook 分开

OpenClaw 没把所有自动化都塞进一个“任务系统”。

三者边界：

Tasks 只负责记录后台工作：Cron executions、subagents、ACP runs、CLI operations 会创建 Task；Heartbeat、普通聊天、直接 slash command 不会因为“发生了”就自动变成 Task。

得到的是概念清晰。代价是新手一开始要分清“触发机制”和“台账”。

11. 取舍九：Sandbox、Tool policy、Elevated 分开

这三个词必须分清：

• Sandbox 控制工具在哪里运行。
• Tool policy 控制哪些工具能被调用。
• Elevated 控制 sandboxed exec 是否能出沙箱到 host。

官方规则里，deny 永远优先，allow 非空时其他工具都 blocked。/exec 不能覆盖被 deny 的 exec。Elevated 不授予额外工具，也不覆盖 tool allow/deny。

得到的是精准控制：

• 私人 Agent 可以 full access。
• 家庭/团队 Agent 可以 sandbox + read-only。
• 公共 Agent 可以 no filesystem/shell。

代价是配置复杂。但安全领域里，复杂度比“所有人都拿 root 权限”更可接受。

12. 取舍十：多 Agent 是边界，不只是分工

多 Agent 不是把一个人拆成多个聊天窗口。官方多 Agent 模型里，一个 Agent 是 workspace、agentDir、session store、模型/工具/权限配置的 scope。

拆 Agent 的理由：

• persona 不同；
• workspace 不同；
• credentials 不同；
• sandbox/tool policy 不同；
• session store 不同；
• channel bindings 不同。

不该拆的理由：

• 只是同一个 Agent 的临时后台任务；
• 只是想并行分析一个问题；
• 只是想让主 Agent 派一个子任务。

后者更适合 sub-agent 或 Cron isolated run。

13. 取舍十一：Hooks 和 Plugins 开扩展口

OpenClaw 有两类 hook：Internal hooks 位于 Gateway 事件脚本层，典型例子是 /new、/reset、/stop、agent:bootstrap、gateway:startup；Plugin hooks 位于 Agent/tool/gateway pipeline 内部扩展点，典型例子是 before_tool_call、before_prompt_build。

得到的是可扩展：

• reset 时写 memory；
• bootstrap 前注入文件；
• tool call 前做 policy；
• plugin install 前做扫描；
• message dispatch 前后做处理。

代价是 hook/plugin 代码也进入 trust boundary。安装 plugin 等于给 Gateway 增加代码能力，不能当普通配置看。

14. 什么时候应该重新设计

OpenClaw 当前设计很适合个人助理、工作室、小团队、自托管自动化。约束变了，取舍也要变。

需要拆更硬边界的场景：

• 陌生用户共享一个 Agent：shared authority 风险太高。
• 客户数据不能混在一个 Gateway：Gateway 不是敌对多租户边界。
• Agent 有写生产系统的能力：工具后果不可只靠 prompt 控制。
• 浏览器 profile 有真实后台登录态：cookie 和登录态就是权限。
• 合规要求每个部门单独审计 credentials：凭据和日志需要独立台账。

这些场景下优先：

• 分 Gateway；
• 分 credentials；
• 分 OS user；
• 分 host 或 VPS；
• 公共入口只给 sandboxed + messaging-only tools；
• 关闭 elevated；
• 关闭 host browser control；
• 打开 strict browser SSRF policy；
• 用 openclaw security audit --deep 做基线检查。

不要用一句“我们配置了 prompt 防御”来替代系统边界。

15. 一句话解释每个核心概念

你可以用这组句子自测：

• Gateway：所有 channel、client、node、automation 进入 OpenClaw 的控制面。
• Channel：把不同消息平台标准化，并把回复送回确定目标。
• Agent：带 workspace、session store、模型和工具边界的执行主体。
• Agent Loop：一次消息变成回复和动作的完整运行链路。
• Workspace：Agent 的工作目录和长期文件环境，不是安全沙箱。
• Memory：写在磁盘上的长期事实和检索索引，不是模型隐藏记忆。
• Context：本次 run 实际发给模型的全部输入。
• Session：当前对话桶，决定历史、并发和当前 transcript。
• Compaction：把长对话压成摘要，保留可继续运行的上下文。
• Heartbeat：周期性主会话检查。
• Cron：Gateway 精确调度器。
• Webhook：外部系统主动触发 OpenClaw 的入口。
• Task：后台工作的状态台账。
• Tool policy：哪些工具可被调用。
• Sandbox：工具运行位置和文件系统边界。
• Elevated：sandboxed exec 的出沙箱开关。
• Hook：在特定 Gateway 或 Agent 生命周期点插入逻辑。

如果你能不用看前文解释这些概念之间的关系，这个理解系列就完成了。

16. 给 Agent 的架构复盘任务

把这段发给 OpenClaw Agent，做一次只读架构审计：

请只读复盘当前 OpenClaw 部署架构，不要修改文件。

要求：
1. 运行 openclaw status、openclaw gateway status，说明 Gateway bind、port、remote/local mode。
2. 运行 openclaw sessions --json，总结当前 session 类型、活跃度、store path。
3. 运行 /context list 或 openclaw agent 侧可用命令，说明 workspace bootstrap 和主要 context 来源。
4. 检查 workspace 文件：AGENTS.md、SOUL.md、TOOLS.md、USER.md、IDENTITY.md、HEARTBEAT.md、MEMORY.md、memory/。
5. 检查 channels 配置，说明 DM policy、group policy、mention gating、context visibility。
6. 运行 openclaw sandbox explain --json，总结 sandbox、tool policy、elevated gates。
7. 检查 heartbeat、cron、webhook、tasks 配置和最近状态。
8. 输出一张文字版架构图：入口 -> Gateway -> route -> session -> agent loop -> tools -> persistence。
9. 标出三个最可能导致误用的边界，并给出最小修复建议。

17. 系列完成自检

到这里，你应该能回答：

1. 为什么 OpenClaw 要用 Gateway 做控制面？
2. 为什么 Agent Loop 需要按 session 串行？
3. Workspace 为什么不是 sandbox？
4. Memory 和 Context 的边界是什么？
5. 为什么 Channel routing 不能交给模型猜？
6. 为什么 reset 不等于失忆？
7. 为什么 Heartbeat、Cron、Webhook、Tasks 不能混成一个概念？
8. 为什么 tool policy 比 prompt 防御更硬？
9. 什么场景必须拆 Gateway 或 host？
10. 你自己的 OpenClaw 部署里，最危险的入口在哪里？

18. 接下来去哪

19. 官方资料

• Gateway architecture
• Agent Runtime
• Agent Loop
• Agent workspace
• Memory overview
• Context
• Session management
• Channel Routing
• Automation & Tasks
• Security