OpenClaw 自托管 Agent 网关

1. OpenClaw 是什么

OpenClaw 是一个自托管、开源的个人 AI 助手网关——把各种 IM 渠道（飞书/钉钉/企微/Discord/Slack/Telegram/WhatsApp/iMessage…）接到一个能执行任务的 LLM Agent 上，在你自己的机器/服务器上跑单个 Gateway 进程做桥梁，Web 控制台统一管会话/路由/技能/定时任务/权限。一句话：把聊天软件变成 Agent 的入口。

💡 深入理解 · 和 Claude Code 的定位差异：Claude Code 是"开发者在终端里用的编程 Agent"；OpenClaw 是"接 IM 的常驻个人助手网关"。但掀开看内部 harness 组件（循环/工具/记忆/权限）惊人相似——都收敛到 13-Harness 六层。

2. 三层架构：Channel / Brain / Body

OpenClaw 按"关注点分离"分三层：

💡 深入理解 · 为什么 Gateway 从不碰模型：职责分离。Gateway 只管"消息从哪来、该给哪个 Agent、回哪去"（连接/路由/控制面），推理交给 Brain 层。这样渠道接入（WhatsApp 用 Baileys、Telegram 用 grammY、Discord 用 discord.js）和模型逻辑解耦，加渠道不动大脑，换模型不动路由。CLI、Web UI、手机 App 都作为 WebSocket 客户端接入（默认绑 ws://127.0.0.1:18789）。

3. 七阶段 Agentic 循环（讲"消息进来怎么处理"）

一条消息进来走七个阶段：归一化 → 路由 → 组装上下文 → 推理 → ReAct → 加载技能 → 持久化记忆。
1. Normalize：渠道适配器把各平台输入转成统一 message 对象（发送者/正文/附件/渠道元数据），语音先转文字再进模型。
2. Route：Gateway 把消息路由到对的 Agent + session，一个 session 里的消息经 Command Queue 串行处理（一次一条）。
3~7. 组装上下文 → LLM 推理 → ReAct 循环调工具 → 按需加载 Skills → 把记忆持久化到文件。

💡 深入理解 · 确定性路由 + 多智能体路由：确定性路由 = 消息从哪个渠道来就回哪个渠道（可追溯）；多智能体路由 = 按渠道/群/发送者分给不同 Agent（隔离）。Command Queue 串行是刻意的——避免同会话并发改记忆导致状态错乱。

4. 记忆 = 文件优先

OpenClaw 的记忆哲学：文件优先，检索其次（memory as files first, retrieval second）——不迷信向量库，把对话/长期记忆/技能都存成纯 Markdown + YAML 文件（放 workspace 和 ~/.openclaw），典型 MEMORY.md 存长期精选记忆。好处：能用文本编辑器直接看、能 git 备份、能 grep、能手动删——透明可审计。

💡 深入理解 · 为什么不纯靠向量库：向量库是黑盒，你没法"打开看看 Agent 到底记住了啥"。文件即记忆让记忆可人工检视、可推理。但它不是把所有记忆文件每轮全塞进 Prompt——用分层控制 + 检索式访问（memory_search 语义检索 / memory_get 定点读取），只查相关片段，防上下文窗口爆炸。这就是 13 说的"状态外化到文件 + just-in-time 加载"的另一种典型实现。

❓ 常见追问 · 记忆黑盒/不稳定怎么办？（真实踩坑）→ 现象是"选择性遗忘"：普通事实没被写入 MEMORY.md，但模型判断更重要的内容记住了——问题出在写入决策这一步（模型自己判断"值不值得写"的推理不稳定），不是文件读写故障。对策：关键规则直接写进 MEMORY.md 固定段落不依赖模型主动决定，并要求执行前"引用复述规则"用输出可观测性反向校验。这是绕过不是根治，治本要网关侧提供"关键信息显式写入"的 API/hook。

5. Cron / Heartbeat / Webhook 三种自动化（讲"定时/事件驱动"）

三种触发方式：

💡 深入理解 · 主会话任务 vs 隔离任务：主会话任务直接在你的对话里跑，会污染主上下文；隔离任务开独立会话跑完再 announce 回渠道，不污染主线——和 17 Claude Code 的子代理只回摘要 是同一思路（隔离脏上下文）。隔离 cron 执行被当作后台任务追踪。

❓ 常见追问 · Cron 为什么不稳定？（真实踩坑）→ 聊天里临时建定时任务常失败，需要"手动创建 + 时区正确 + 技能权限组合对"三者齐了才行。根因常是 Skill 依赖没写进镜像（见 §7）。

6. 三道权限闸

安全是一等公民，三道闸层层收：

入口闸（谁能连进来）→ 工具闸（能用哪些工具）→ 执行闸（在哪跑）
 pairing/allowlist 默认禁高风险白名单 Docker 沙箱

1. 入口闸：默认只绑 127.0.0.1:18789（loopback，只本机）；非 loopback 绑定强制 token/密码鉴权；DM 走 pairing 配对——新设备 ID 连进来要审批，Gateway 发设备 token 后续复用。
2. 工具闸：默认拒绝 + 白名单制。典型沙箱默认 allow bash/read/write/edit/sessions_*，deny browser/canvas/nodes/cron/discord/gateway。模型只看得到"过了 profile + allow/deny 策略 + provider 限制 + 沙箱状态 + 渠道权限 + 插件可用性"层层过滤后幸存的工具。
3. 执行闸：高风险动作在 Docker 沙箱里跑，权限只在容器内，动宿主机要显式挂载卷。

💡 深入理解 · 纵深防御 vs 单点信任：三道闸的价值在于"任何一层疏漏不至于直接击穿"。但要诚实：如果把策略从"默认禁+白名单"改成"默认允+黑名单"，或批量放开整类工具，一个疏漏就能让高危工具直接跑到沙箱里，那时沙箱成了唯一防线而非纵深一环。所以必须坚持"默认拒绝、逐个显式允许"，并对 allowlist 变更做审查。

💡 深入理解 · 多智能体隔离是结构性的：不是营销话术，而是烘焙进路由、会话存储、workspace、鉴权边界里——不同 Agent 的会话/记忆/权限物理隔离。但 OpenClaw 定位是"个人助手信任模型"，不是多租户强隔离系统，多人多群混用要谨慎（这是它的边界，讲选型结论时"负向结论也是价值"）。

7. 真实踩坑归因（体现"边界认知"，讲经历时用）

六个坑，每个有归因：
1. 记忆黑盒：选择性遗忘 → 问题在"写入决策"不稳定，非读写故障 → 关键规则写死 MEMORY.md + 复述校验。
2. Skills 与运行环境强耦合：Gateway 在 Docker 里，Skill 依赖的二进制必须容器内可用，手动装的没写进 Dockerfile → 换机器/重建就丢，Cron 一触发报"命令不存在" → 解耦：依赖显式写进镜像构建。
3. Docker 权限边界：权限只在容器内，操作宿主机要显式挂卷——"扩权限面 vs 隐私隔离"的权衡。
4. Cron 不稳定：手动建 + 时区对 + 技能权限组合对，缺一不行。
5. Token 成本敏感：多次确认 + 带大量文档，输入 token 大（实测问 13 次约 0.63 元）。
6. 信任模型：个人助手信任模型，非多租户强隔离，多人混用谨慎。

8. 高频追问速答

❓ 常见追问 · Agent 系统怎么设计？ → 拿 OpenClaw 做模板：三层架构（Gateway 路由/Brain 推理/Body 工具）+ 文件即记忆（MEMORY.md + 检索式访问）+ Cron/Heartbeat 调度（隔离任务不污染主线）+ 三道权限闸（入口 allowlist→工具白名单→Docker 沙箱）。核心三原则：状态外化到文件、权限分层、路由确定性。
❓ 常见追问 · 为什么记忆用文件不用向量库？ → 透明可审计（能看/grep/git 备份/手动删），向量库是黑盒。但不全塞进 Prompt，配 memory_search 检索式访问防上下文爆炸。文件优先、检索其次。
❓ 常见追问 · 和 Claude Code 什么关系？ → 两个不同 harness 实现：Claude Code 是终端编程 Agent，OpenClaw 是接 IM 的常驻助手网关；内部组件（循环/工具/记忆/权限）高度相似，都收敛到 Harness 六层。详见 17-ClaudeCode原理·13-Harness。
❓ 常见追问 · 沙箱怎么防逃逸？ → 最小挂载（只挂工作目录）、不开 --privileged、禁挂 Docker socket（防逃逸提权）、非 root 跑、资源限制防滥用、网络白名单出口。诚实承认没做完整逃逸渗透测试、seccomp/AppArmor 未上，别吹"绝对隔离"。