# OpenClaw(龙虾 🦞)架构模板 > **代表产品 / 原型**:OpenClaw(龙虾 🦞,原名 Clawdbot→Moltbot,作者 Peter Steinberger) —— 同类:Hermes(爱马仕) > **一句话定位**:自托管、常驻在你自己机器上的个人 agent 网关——一个本地守护进程把能干活的编码型 agent 接到你已经在用的聊天软件(WhatsApp/Telegram/Slack/Discord…),7×24 随叫随到,数据与密钥都留在本地。 --- ## 1. 一句话定位 OpenClaw = **一个常驻在你自己机器上的本地守护进程(Gateway),把一个能调用工具、能干活的编码型 agent,接到你已经在用的聊天软件上。** 你不用再开一个新 App、不用把对话和密钥交给某个云端 SaaS:它寄生在 WhatsApp / Telegram / Slack / Discord 这些你本来就在刷的窗口里,你发条消息就等于给 agent 派活,它 7×24 在你的机器上待命。一句话——**它是「个人版、自托管、寄生在现有聊天 UI 上」的 agent 网关**,而不是又一个 agent SaaS。它和 [AI Agent 平台](../ai-agent-platform/README.md) 的根本差异在于:那类平台为「多租户、跑别人的任务」而生;OpenClaw 为「**单用户、跑你自己的活、数据本地自持**」而生。 ## 2. 业务本质:它在解决什么问题 它要消灭的是**「AI 散落各平台」的碎片化**:你的 agent 能力今天在这个网页、明天在那个 App,会话历史、能用的工具、记下来的事各处一份,谁也不认谁;密钥要么交给一堆云服务,要么自己散落各处。 OpenClaw 的答案是:**用一个单用户的控制平面,把会话、渠道、工具、记忆全部收敛到一处,而且这处就在你自己机器上。** 这个收敛点(Gateway)是你所有 agent 交互的唯一真相源——不管你从哪个聊天软件发消息,背后都是同一个常驻进程、同一份配置、同一份记忆。它卖的不是「更强的模型」,而是「**把零散的 AI 能力,统一成一个常驻在你身边、归你自己管的助理**」。 > 一个贯穿全篇的判断要先记住:OpenClaw 是**单用户、单信任边界**的产物。它的所有便利(常驻、热重载、本地优先)都建立在「**机器的主人 = agent 的主人 = 唯一可信的人**」这个前提上。一旦要给不可信的人用,这个前提崩塌,架构就得重做(见第 8、10 节)。 ## 3. 核心需求与约束 **功能性需求(系统要能做什么):** - [ ] 把一个能调用工具的编码型 agent 接到多个聊天渠道(WhatsApp/Telegram/Slack/Discord/飞书/iMessage…) - [ ] 跨渠道统一的会话路由与隔离(同一渠道不同对端、不同渠道不同账号互不串味) - [ ] 工具编排:让 agent 能执行命令、读写文件、调外部能力——并受审批与沙箱约束 - [ ] 持久化记忆:跨会话记得住事,且记忆**可读、可检索、可版本化** - [ ] 自主巡检(Heartbeat)+ 精确定时(Cron):不只被动应答,还能定时主动干活 - [ ] 配置热重载:改完配置不重启即生效 - [ ] 技能机制:把可复用的能力打包、共享、按需装载 **非功能性需求 / 质量属性(系统要做得多好):** | 质量属性 | 目标 | 为什么对这类系统重要 | |---|---|---| | **常驻可用** | 7×24 在线,随叫随到 | 个人助理的根本价值就是「永远在」,断了就废 | | **本地优先(local-first)** | 配置/会话/记忆/密钥全在本机 | 这是它相对云端 SaaS 的核心卖点——数据与密钥不出户 | | **配置热重载** | 改 `openclaw.json` 不重启即生效 | 常驻进程不能为改个开关就断线 | | **会话隔离** | 不同渠道/对端的上下文不串味 | 单进程服务多渠道,串味=隐私事故 | | **可审计** | 工具调用、定时任务、记忆全部留痕可查 | 自托管 = operator 自担责任,出事要能复盘 | **关键约束(不可逾越的边界):** - 🔴 **运行环境**:需要较新的运行时(Node 24,或 22.19+);Windows 上需经 WSL2 才能稳定跑(很多渠道依赖类 Unix 行为)。 - 🔴 **单信任边界 / 单用户,而非多租户**:整个系统假定只有一个可信主人。它**不是**给一群陌生人共享的 SaaS;把它当多租户用,就是把安全模型用反了。 - 🔴 **自带模型 provider key**:OpenClaw 自己不卖、不跑模型,你得自带某个模型供应商的密钥(它只负责编排,不负责推理)。 - 🔴 **行为依赖上游**:agent 内核与多数 harness 是外部项目,其能力与脾气随上游变化(见第 8 节决策 ③)。 ## 4. 架构全景图 中心是常驻的 **Gateway 守护进程**(hub),各聊天渠道是辐条(spoke);Gateway 内部包着 agent 运行时、会话路由、工具编排、调度器与记忆。 ``` 你已经在用的聊天软件(spoke,12+ 渠道) WhatsApp Telegram Slack Discord 飞书 iMessage Signal … │ │ │ │ │ │ │ └─────────┴────────┴───┬───┴───────┴───────┴────────┘ │ 入站消息(先过 DM 策略:pairing/allowlist/open/disabled) ▼ ┌──────────────────────────────────────────────────────────────────────┐ │ Gateway 守护进程(单进程 · 控制平面 · sessions/routing/channel 唯一真相源)│ │ 读 ~/.openclaw/openclaw.json(JSON5,严格 schema 校验 + 热重载) │ │ │ │ ① 渠道适配器 ──▶ ② 会话路由(dmScope: main/per-peer/per-channel-peer) │ │ │ 绑定/重置 thread(daily / idleMinutes) │ │ ▼ │ │ ┌──────────────── ③ agent 运行时(可插拔 harness)───────────────┐ │ │ │ 内置 Pi 内核:owns model loop · thread state · 动态工具 · │ │ │ │ context engine · compaction │ │ │ │ 插件: codex │ ACP: Claude Code / Gemini CLI / OpenCode … │ │ │ │ 行动循环:构建系统提示 → 模型规划 → 调工具 → 观察 → 再决策 │ │ │ │ hook: before_model_resolve / before_prompt_build / │ │ │ │ before_tool_call / after_tool_call │ │ │ └───────┬───────────────────┬────────────────────┬──────────────┘ │ │ │ 工具调用 │ 读/写记忆 │ 调度触发 │ │ ▼ ▼ ▼ │ │ ┌──────────────┐ ┌──────────────────┐ ┌────────────────────┐ │ │ │ ④ 工具编排 │ │ ⑥ 持久化记忆 │ │ ⑤ 调度器 │ │ │ │ 策略(deny默认)│ │ workspace 纯 MD: │ │ Heartbeat(~30m): │ │ │ │ + 审批 │ │ MEMORY.md │ │ 主会话巡检/省钱 │ │ │ │ + Docker 沙箱│ │ memory/日期.md │ │ Cron: 精确/隔离/ │ │ │ │ │ │ (可选 DREAMS.md) │ │ 留 task 记录 │ │ │ └──────────────┘ └──────────────────┘ └────────────────────┘ │ │ │ │ │ ⑦ 技能机制:SKILL.md(Markdown+YAML)→ 编成 XML 注入提示;多来源按 │ │ 优先级合并;ClawHub = 可共享的技能注册表 │ └────────────────────────────┬───────────────────────────────────────────┘ ▼ 流式回写「来时那条渠道/会话」,并落盘(transcript + 记忆) 你在聊天窗口里看到回复 ``` > 灵魂是中心那个 **单进程 Gateway 控制平面**:它既是 hub(收编所有渠道与会话),又内嵌 agent 运行时,还把工具、调度、记忆挂在自己身上。**所有便利(常驻、热重载、本地自持)和所有风险(单信任边界、单进程串行)都源于这个「一切收敛到一个本地进程」的选择。** ## 5. 组件职责 逐个说明上图里每个关键部件**做什么 + 为什么需要它**。 - **① Gateway 控制平面**:常驻进程,是 sessions / routing / channel 配置的**唯一真相源**(hub-and-spoke 的 hub);读 `~/.openclaw/openclaw.json`(JSON5),做严格 schema 校验并支持热重载;可前台 debug 跑,也可后台 launchd/systemd 常驻。*为什么需要*:个人助理要「永远在」,且多渠道必须有一个统一收敛点,否则会话/路由/配置就又散了。 - **② 渠道适配器(spoke)**:把各聊天平台(12+:WhatsApp/Telegram/Slack/Discord/飞书/iMessage/Signal/Teams/Matrix/LINE/WeChat/QQ/WebChat…)的协议差异抹平成统一的「入站消息 / 出站回复」。每渠道带 DM 策略:`pairing`(默认)/`allowlist`/`open`/`disabled`,群聊可要求 `@bot`。*为什么需要*:消息平台就是 UI,这层让「寄生现有聊天软件」成为可能,也承担第一道准入。 - **③ agent 行动循环 + 可插拔 harness**:内置极简编码内核 **Pi**(由 Gateway 包一层:`agentCommand` 解析用哪个模型、载哪些技能 → `runEmbeddedPiAgent` 执行),Pi 自己持有模型循环、线程状态、动态工具、上下文引擎与压缩(compaction);也可换 harness——插件 `codex`、或经 **ACP** 接 Claude Code / Gemini CLI / OpenCode / Cursor。提供 `before_model_resolve / before_prompt_build / before_tool_call / after_tool_call` 等 hook。*为什么需要*:agent 内核外包让 OpenClaw 保持轻、跟得上前沿(见决策 ③)。 - **④ 工具编排 + 审批 + 沙箱**:agent 要执行命令、读写文件、调外部能力时,先过策略(`exec`/`gateway`/`cron` 等默认 **deny**、allow/deny 名单),高危走审批,执行可放进 **Docker 沙箱**。*为什么需要*:工具能「改变世界」,自托管下这是 operator 唯一的安全阀。 - **⑤ 心跳调度器(Heartbeat)+ Cron**:Heartbeat 默认每 ~30m(Anthropic OAuth 模式 1h)在**主会话**跑一轮自主巡检;Cron 是内置调度器,持久化 job、精确/一次性触发、到点唤醒并投递到渠道或 webhook。*为什么需要*:让 agent 从「被动应答」升级为「会主动盯事 + 准点干活」。 - **⑥ 跨渠道会话管理**:`dmScope` 决定会话粒度(`main` / `per-peer` / `per-channel-peer`);thread 可按 `daily` 或 `idleMinutes` 重置;多 agent 路由把不同渠道/账号/对端**路由到隔离的 agent**(各自 workspace + sessions)。*为什么需要*:单进程服务多渠道,隔离是隐私与上下文不串味的保证。 - **⑦ 持久化记忆**:workspace 是**纯 Markdown**——`MEMORY.md`(每个 DM 会话开头加载)、`memory/YYYY-MM-DD.md`(今天+昨天自动加载)、可选 `DREAMS.md`;用 `memory_search`/`memory_get` 检索(memory-core 插件)。「模型只记得写进磁盘的东西,**没有隐藏状态**」。*为什么需要*:把记忆做成可读、可 grep、可版本化的纯文本,是这套系统最克制也最聪明的取舍(见决策 ⑤)。 - **⑧ 技能机制 + ClawHub**:技能 = `SKILL.md`(Markdown 正文 + YAML frontmatter 元数据),被编成 **XML 注入系统提示**;多来源按优先级合并;**ClawHub** 是可共享、可发现的技能注册表。`SOUL.md` / `AGENTS.md` 则是人格 / 流程注入文件。*为什么需要*:用最低门槛(写 Markdown)让能力可打包、可共享、可审计——代价是装第三方技能=信任其内容(见决策 ④)。 ## 6. 关键数据流 挑三个最能体现 OpenClaw 特点的场景。 **场景一:聊天软件来一条消息(被动应答主链路)** ``` ① 你在 Telegram 发:「把今天的会议纪要整理进备忘」 ② 渠道适配器收下 → 过 DM 策略鉴权(pairing/allowlist/open?不通过直接挡掉) ③ 会话路由:按 dmScope 找到对应 agent + session(隔离,不串味) ④ 构建系统提示:注入 MEMORY.md + 近两日 memory/日期.md + 相关技能(XML)+ SOUL/AGENTS ⑤ Pi 行动循环:模型规划 → 要调「写文件」工具 ⑥ 工具受约束:策略检查(默认 deny,需在 allow 名单)→ 必要时审批 → 在沙箱里执行 ⑦ 结果喂回模型 → 模型决定收尾 → 流式把回复写回「来时那条 Telegram 会话」 ⑧ 落盘:transcript 记录;若模型主动写盘,记忆才更新(否则下次不记得) ⟲ 全程由 per-session + global 队列串行执行(见第 9 节瓶颈) ``` **场景二:Heartbeat 自主巡检(模糊时间 / 共享主会话 / 省钱)** ``` 每 ~30m(OAuth 模式 1h)定时触发一次,在【主会话】里跑一轮: ① 读 HEARTBEAT.md(你写下的「该定期盯的事」清单) ② 只把【此刻到期】的任务塞进这一轮提示 —— 不到期的一律不进上下文(省 token) ③ Pi 跑一轮:有到期事就干(可调工具),干完流式回主会话 ④ 若这一轮无事可做 → 回一句 HEARTBEAT_OK 即收工 ⑤ 关键:Heartbeat【不创建 task 记录】—— 它是「轻巡检」,不是「留痕作业」 动机:常驻 + 周期性唤醒会【持续烧 token】,故默认设计极度克制 ``` **场景三:Cron 精确定时(精确时间 / 隔离执行 / 留痕)** ``` 你登记一个 cron job:「每天 09:00 拉一份昨日数据日报」 ① Gateway 内置调度器持久化该 job(进程重启后仍在) ② 到 09:00 精确唤醒 agent —— 隔离执行(不混进主会话上下文) ③ 跑完把结果投递到指定渠道,或打到 webhook ④ 每次执行都【产生一条 task 记录】—— 可审计、可回看 与 Heartbeat 的分工:Cron = 精确/隔离/留痕;Heartbeat = 模糊/共享/省钱 ``` ## 7. 数据模型与存储选择 核心思想:**一切都在本地 `~/.openclaw/` 下,且大量是人类可读的纯文本。** 概念实体:`配置`、`会话 transcript`、`记忆 workspace`、`技能`、`密钥凭证`、`task 记录`。 | 数据 | 存储形态 | 为什么 | |---|---|---| | 全局配置 | `~/.openclaw/openclaw.json`(**JSON5**) | 人可手写、带注释;严格 schema 校验 + 热重载 | | 会话 transcript | 本地会话记录(按 agent/session 隔离) | 可审计、可回放;隔离防串味 | | 记忆(长期) | `MEMORY.md`(每个 DM 开头加载) | 纯文本可读可 grep 可版本化;无隐藏状态 | | 记忆(每日) | `memory/YYYY-MM-DD.md`(今天+昨天自动加载) | 近期上下文低成本注入,旧的靠检索取 | | 记忆(可选) | `DREAMS.md` | 长期/反思性笔记的可选载体 | | 技能 | 多来源 `SKILL.md`,按优先级合并 | Markdown+YAML 低门槛;多来源(本地/ClawHub)可叠加 | | 密钥 / 凭证 | `~/.openclaw/` 下 | 本地自持,不出户 | | task 记录 | 由 Cron 产生(Heartbeat 不产) | 区分「留痕作业」与「轻巡检」 | > 一条要刻进脑子的安全前提:**「assume anything under `~/.openclaw/` may contain secrets」**——这个目录里既有明文配置、又有会话与记忆、还有密钥;明文即敏感数据,这直接决定了第 10 节「整盘加密 + 专用用户」的建议。 ## 8. 关键架构决策与权衡 ⭐ **(本模板最值钱的一节。)** 每个决策都写清:面临的选择、取向、放弃了什么。 **决策 ① 自托管单进程 daemon + 单信任边界 ⭐(全篇地基)** - 选项 A:云端多租户 SaaS。优点:省心、天然多用户;代价:数据与密钥交出去、不是 local-first。 - 选项 B:**自托管单进程守护进程 + 单信任边界**。优点:**local-first、常驻、热重载**,数据密钥不出户;代价:**它不是多租户**,要给不可信的人用,必须额外拆信任边界(独立 gateway / 凭证甚至独立 OS 用户、主机)。 - **取向**:B。OpenClaw 的全部卖点都建立在「一个可信主人 + 一个本地进程」上;**多租户不是没做,而是被刻意排除在信任模型之外**。 **决策 ② 消息平台即 UI,而非自建前端 ⭐** - 选项 A:自建 Web/桌面客户端。优点:UI 完全可控;代价:多一个要装、要维护的新客户端,用户得改习惯。 - 选项 B:**寄生在你已经在用的聊天软件里**。优点:**零新客户端、零学习成本**,随时随地;代价:把各平台的**账号、凭证、多用户语义**统统纳入攻击面(群里别人也能说话、平台账号可能被盗)。 - **取向**:B。降门槛的收益压倒一切,但要清醒:**你把信任边界外包给了聊天平台**(见第 10 节准入策略)。 **决策 ③ agent 内核外包 + 可插拔 harness ⭐** - 选项 A:自造 agent 内核。优点:行为完全自控、跨场景一致;代价:重,且追前沿追到累。 - 选项 B:**内核外包**——内置极简 **Pi**,插件接 `codex`,经 **ACP** 接 Claude Code / Gemini CLI / OpenCode / Cursor。优点:**轻、跟得上前沿**,用户能用上自己惯用的 harness;代价:**行为依赖上游**,且**跨 harness 一致性要 OpenClaw 自己抹平**(同一句话在 Pi 和 Claude Code 下表现可能不同)。 - **取向**:B。Gateway 只做「控制平面 + 编排」,把「怎么思考」这件高速演进的事让给专门的内核。 **决策 ④ 技能 = SKILL.md 编成 XML 注入 + ClawHub 注册表 ⭐** - 选项 A:技能写成代码插件。优点:能力强;代价:门槛高、不好共享、审计难。 - 选项 B:**技能 = `SKILL.md`(Markdown + YAML frontmatter),编成 XML 注入提示,经 ClawHub 共享**。优点:**低门槛、可共享、可审计**(就是一段你能读的文字);代价:**装第三方技能 = 信任其内容**——它会进系统提示,等于供应链/提示注入入口。 - **取向**:B,但把「装技能=授信」当红线(见第 10、11 节)。 **决策 ⑤ 记忆 = 磁盘纯文本,无隐藏状态 ⭐** - 选项 A:记忆放进数据库/向量库黑盒。优点:检索强;代价:不可读、难版本化、容易当成「它自动记得一切」的魔法。 - 选项 B:**记忆 = 磁盘纯 Markdown**(`MEMORY.md`/`memory/日期.md`),「模型只记得写进磁盘的东西」。优点:**可读、可 grep、可版本化**,行为透明;代价:**依赖模型主动写盘**(它不写就不记得),且**明文即敏感数据**。 - **取向**:B。透明与可审计压倒「黑盒记得更多」;检索另配 `memory_search`/`memory_get` 补足。 **决策 ⑥ Heartbeat 与 Cron 双轨调度 ⭐** - 单一机制做不到「既省钱又精确」:自主巡检要省 token、可模糊;定时作业要精确、要留痕。 - **取向**:**双轨**。**Heartbeat**=模糊时间 / 共享主会话 / 只注入到期项 / 无事回 OK / 不留 task(省钱);**Cron**=精确时间 / 隔离执行 / 每次产 task 记录(留痕)。动机直白:**常驻 + 周期性唤醒会持续烧 token,所以默认设计极度克制**。 ## 9. 规模化与瓶颈 先定调:**OpenClaw 是单用户单机常驻,不为高并发 / 多租户设计。** 这里的「规模化」不是「扛更多用户」,而是「一个人用得更重时,什么先撑不住」。 - **第一个瓶颈:单进程串行执行。** Pi 行动循环按 **per-session + global 队列**串行跑——多个渠道同时来消息会**排队**等待。→ 这是单进程控制平面的固有代价;破解方向不是「加机器」,而是接受它本就是个人助理(必要时拆多 agent / 多 gateway 实例,但那已偏离单信任边界初衷)。 - **第二个瓶颈:成本与上下文(烧 token)。** 常驻 + Heartbeat 周期性唤醒会**持续烧 token**(有报道作者团队跑 100 agent 一个月烧掉百万美元级别 token,这正是默认克制的动机)。→ 破解:Heartbeat **只注入到期项、无事回 `HEARTBEAT_OK`、不留 task**;近期记忆只自动注入「今天+昨天」,更早的靠检索按需取。 - **第三个瓶颈:渠道侧的平台约束。** 各聊天平台有自己的 **API 速率限制与账号政策**,你刷得太猛可能被限速甚至封号。→ 破解:把渠道当受约束的外部依赖,DM 策略收紧、控制主动外发频率。 ## 10. 安全与合规要点 一句话定调:**自托管 = operator 自担。** OpenClaw 的安全模型是**单 operator 信任边界**,默认就假定「机器主人即唯一可信者」。 - 🔴 **密钥即一切,目录即敏感**:`~/.openclaw/` 下有配置、会话、记忆、密钥(明文)。建议 **整盘加密 + 用专用 OS 用户跑 Gateway**,缩小泄露面。 - 🔴 **工具权限 policy-first**:`exec` / `gateway` / `cron` 等默认 **deny**;用 allow/deny 名单精确放行;高危走审批;执行放 **Docker 沙箱**。**绝不要给「带工具的 agent」配弱小模型**——弱模型更易被诱导越界。 - 🔴 **提示注入「未解决」**:这是公认未解的难题。OpenClaw 的防线是**纵深**: - **第一道也是最有效的一道——入站准入**:`pairing`(默认)/`allowlist`,别用 `open`;群聊要求 `@bot`。把陌生人挡在门外,胜过事后补救。 - **DM 隔离**:`per-channel-peer` 让不同对端上下文互不可见。 - **上下文可见性过滤**:控制哪些内容能进提示。 - ⚠️ **群聊放大风险**:群里**任何被策略允许的发送者**,都能在策略范围内诱发工具调用——准入名单要当回事。 - 🔴 **不可信场景必须拆边界**:一旦要给不可信的人用,**必须拆 gateway + 凭证,甚至独立 OS 用户 / 主机**——别在单信任边界里硬塞多用户。 ## 11. 常见误区 / 反模式 每条写「错误做法 → 为什么错 → 正确思路」。 - ❌ **把它当多租户 SaaS 来部署**(给一群陌生人共享一个 Gateway) → ✅ 它是**单信任边界**;多用户/不可信场景请拆独立 gateway + 凭证甚至独立主机。 - ❌ **默认全开,还给敏感渠道接上全权工具** → ✅ policy-first:工具默认 deny、按需 allow、敏感操作走审批与沙箱。 - ❌ **以为它有「魔法记忆黑盒」,自动记得一切** → ✅ **无隐藏状态**;模型不主动写盘就不记得,记忆是磁盘上你能读到的纯文本。 - ❌ **滥装第三方技能 / 盲目让 agent 执行入站内容** → ✅ **装技能=授信**;技能会进系统提示,入站内容当不可信输入,靠准入与审批兜底。 - ❌ **混淆 Heartbeat 与 Cron**(拿心跳当精确闹钟,或指望它留痕) → ✅ 精确 + 留痕用 **Cron**;模糊巡检 + 省钱用 **Heartbeat**(不产 task)。 - ❌ **用弱小模型驱动带工具的 agent** → ✅ 带工具 = 能改变世界,越要用够强、够稳、抗注入的模型。 - ❌ **把技能 frontmatter 写成多行** → ✅ 解析器**只认单行 key**,metadata 必须是**单行 JSON**;写成多行会解析失败。 ## 12. 演进路线:个人可信 → 收紧策略 → 拆信任边界 架构不变,但**策略随暴露面收紧**。别拿「个人单机的宽松默认」去套「对外暴露」的场景。 | 阶段 | 场景 | 策略怎么设(具体) | 此时该操心什么 | |---|---|---|---| | **个人单机可信** | 只有你自己用,本机常驻 | 默认 **permissive** 也无妨;`pairing` 准入,工具按需开 | 先把助理跑起来、用顺手 | | **接更多渠道 / 装技能** | 多渠道接入、引入第三方技能 | **收紧策略**:渠道用 `allowlist`、群聊要 `@bot`、第三方技能逐一审、敏感工具走审批+沙箱 | 准入面与供应链(技能即授信) | | **团队 / 对外暴露** | 给他人或不可信场景用 | **拆信任边界**:独立 gateway + 独立凭证,必要时独立 OS 用户 / 主机;工具配最小集 | 多用户语义、攻击面隔离、最小权限 | ## 13. 可复用要点 这套设计里能搬到别处的「带得走的智慧」: - 💡 **单一控制平面收敛协调**:把会话/渠道/工具/记忆收敛到一个真相源(Gateway),是治理碎片化的通用解——和网关、中间层「把横切关注点收编到一个入口」同源。 - 💡 **寄生现有 UI 降门槛**:与其逼用户装新客户端,不如寄生在他们已经在用的入口里;代价是把那个入口的信任边界一并继承过来,要清醒。 - 💡 **把记忆做成可审计的纯文本**:无隐藏状态、可读可 grep 可版本化——透明胜过「黑盒记得更多」,代价是依赖主动写盘。 - 💡 **准入是提示注入的第一道、也是最有效的防线**:与其指望事后过滤,不如先用 `pairing`/`allowlist` 把不可信来源挡在门外——**最便宜的安全往往在入口**。 - 💡 **用机制区分「省钱巡检」与「精确留痕」**:Heartbeat vs Cron 的双轨,本质是「模糊省成本」与「精确可审计」两类需求别用一个机制硬扛。 ## 🎯 随堂检验 --- ## 14. 参考原型与延伸阅读 > 本节只列**已核实**的官方仓库与文档。想动手,从仓库 README 入手,再按主题深读。 **🔧 开源原型(可直接读代码):** - [openclaw/openclaw](https://github.com/openclaw/openclaw) — 官方仓库 README,自托管个人 agent 网关的总入口,体现「单一控制平面 + 寄生聊天 UI」。 **📖 官方文档(按主题):** - [OpenClaw Docs 首页](https://docs.openclaw.ai/) — 文档总览。 - [Gateway 配置](https://docs.openclaw.ai/gateway/configuration) — `openclaw.json`(JSON5)、schema 校验与热重载,对应第 7 节。 - [安全模型](https://docs.openclaw.ai/gateway/security) — 单信任边界、policy-first 工具权限、准入与提示注入防线,对应第 10 节。 - [心跳调度](https://docs.openclaw.ai/gateway/heartbeat) — Heartbeat 的省钱设计,对应第 6 节场景二与决策 ⑥。 - [Agent 行动循环](https://docs.openclaw.ai/concepts/agent-loop) — plan→act→observe 与 hook,对应第 5 节组件 ③。 - [Agent 运行时 / harness](https://docs.openclaw.ai/concepts/agent-runtimes) — 内置 Pi、插件 codex、ACP 接 Claude Code/Gemini CLI/OpenCode,对应决策 ③。 - [记忆持久化](https://docs.openclaw.ai/concepts/memory) — 磁盘纯文本、无隐藏状态,对应决策 ⑤。 - [技能机制](https://docs.openclaw.ai/tools/skills) — `SKILL.md` + frontmatter + ClawHub,对应决策 ④。 **🔗 相关模板(本仓库):** - [Hermes(爱马仕)](../hermes/README.md) — **同类姊妹篇**:同为「把 agent 接到聊天软件」的个人网关,可对照其取舍差异。 - [Claude Code](../claude-code/README.md) — OpenClaw 可经 ACP 复用的编码型 harness 之一。 - [Codex](../codex/README.md) — 另一个可经插件/ACP 接入的 harness。 - [AI Agent / 工作流平台](../ai-agent-platform/README.md) — 对照「多租户、跑别人任务」的 agent 平台与「单用户、跑自己活」的本篇有何根本不同。 - [十大核心架构模式](../../tutorial/04-十大核心架构模式.md) — 「单一控制平面」「能不用就别用」等取舍的母体。 --- > 📌 一句话记住 OpenClaw:**它是一个常驻你自己机器、寄生在现有聊天软件里的个人 agent 网关——用一个单进程控制平面把会话/渠道/工具/记忆全收敛到本地,数据与密钥不出户;它不自造 agent 内核(内嵌 Pi、可经 ACP 复用 Claude Code 等),记忆是磁盘上无隐藏状态的纯文本;而它全部的便利都押在「单用户单信任边界」这个前提上——一旦要给不可信的人用,就必须先把信任边界拆开。**