从开源爆款到 OpenAI 收编：OpenClaw 体验、架构与 Prompt 全解析

OpenClaw 最近很火，非常出圈。作为一个自托管的个人 AI 助手平台，它让你可以通过飞书、Telegram、WhatsApp 等 IM 渠道随时随地跟 AI 对话，数据完全掌握在自己手里。

安装了很久，一直没时间认真测。终于抽出时间，做了一次完整的体验测评，顺便让 Claude Code 把它的架构扒了个底朝天，还抓了一份它的 prompt 流量包做了个解剖。

省流：作为个人助手聊聊天、查资料还行，复杂任务容易卡住或者死循环。但架构设计确实有想法，prompt 工程也值得学习——这是第一个出圈的个人助手类项目，后面肯定还会有更多。

1 一、体验篇：从安装到翻车

1.1 安装：比想象中麻烦

OpenClaw 的安装并不是一键搞定的事。好在有 Claude Code 帮忙，直接让它帮我装。

装好之后，因为要放在内网小主机上，需要改监听网段。默认绑定的是 loopback，局域网其他设备访问不了。继续让 Claude Code 帮忙修改。

然后遇到第一个坑：默认的 Antigravity 认证插件不支持最新的 Claude Opus 4.6 模型。没关系，改成我们反代出来的 Antigravity Manager 的 OpenAI 兼容格式接口就行。

第二个坑：直接从局域网连接会报错，提示非安全上下文。继续让Claude Code帮我解决。

1.2 连接飞书

接着通过申请飞书的 bot 机器人，打通了对话通道。日志显示 WebSocket 连接建立成功，飞书 channel 已经跑起来了。

发出第一条消息——“你好”。

机器人回复：“你好！我刚刚上线。我是谁？你是谁？”

告诉它我是它的主人之后，它开始自我介绍，还挺像模像样的。到这一步，基本的对话通道算是打通了。

1.3 任务一：让它分析自己

第一个正经任务：让 OpenClaw 利用自带的 skills 功能，用 repo-analyzer 技能分析自己的代码仓库。

结果它说 git clone 卡住了，要改用 zip 下载。我说怎么能卡住呢，是不是网络问题，让它再试试。

开始疯狂道歉，又说自己其实 clone 成功了。

分析的时候又开始道歉。

我看了一下，其实根本没有 clone 成功，目录下一片空白。

让它确认一下。

又开始道歉。

感觉不对劲，问问 Claude Code：“我部署的 OpenClaw 特别笨，很奇怪，它背后也是用的跟你一样的 Opus 模型，你看下是不是我哪里配置没配对。”

Claude Code 一查就找到了问题。这也太坑了，也没有告诉我要这么配置啊。

核心问题是 maxTokens 设置太低了（8192），thinking tokens 会占用这个额度，留给实际回答的空间就很小了。建议改到至少 16384，最好 32768。另外中间代理的 extended thinking 格式转换也可能有问题。

简直是 token 杀手，2个问题花了我快 2000 万 tokens。

改完配置之后，OpenClaw 的表现确实好了不少。终于可以正常跑了。开始逐步分析自己的项目代码。

但是最后可能项目文件太大了，又又又卡住了。

监工Claude Code上线，看看咋回事。

过一会又不动了。。。。问问 Claude Code 怎么修。

Claude Code看了下后给我加了个配置参数让我试试。修了一次后，不知道没过多久又挂了。

麻了，已经不想再测了。

1.4 任务二：查 Dify 最新更新

换个问题。背景是 Dify 当天发布了 1.13.0 的更新，看看它能不能帮我总结一下。

结果很离谱，还在回答上古时期的版本，并不是最新的内容。

看不下去了，一步步告诉它怎么查。

让它查 1.13.0，结果查了 1.11.4 的内容出来。

经过相当长时间的排查，最后发现是因为默认不支持 web 搜索，需要自己配 API key。

不是哥们，查不了你咋不直接说呢，在这胡说八道。

配上 API key 后，终于可以正常回答了。

1.5 任务三：帮我分析股票

最后一个任务，分析美股行情。

一开始直接给我拒绝了，说不能提供金融投资建议。

经过一番"哄骗"，终于让它开始工作了。

但是查了第一家之后就卡住不动了。上午下发的任务，到晚上还没出结果，我就知道又出问题了。

还是让老演员 Claude Code 给我当监工。

发现果然又出问题了

Claude Code甚至问我要不要让他接手这个项目继续跑下去。

1.6 体验小结

三个任务做下来，感受很明确：

简单对话和信息检索，OpenClaw 表现尚可。通过飞书随时随地跟 AI 聊天，确实比打开浏览器方便。

但复杂的多步骤任务，它很容易卡住或者死循环。git clone 卡住不报错、查不了网硬编答案、分析任务中途出错、股票分析做了一半就没动静。

同样是 Opus 4.6，准确度和可靠性相比 Claude Code 差的不是一点半点，以至于我还要引入 Claude Code 给它当监工。

整体感觉，OpenClaw 像一个非常努力但缺乏章法的莽夫。能力是有的，背后跑的是同一个 Opus 4.6 模型，但缺少足够的约束和引导。

不额外调教的话，它会在你的系统里横冲直撞，clone 失败了跟你说成功了，查不了网给你编一个答案，任务做一半就没动静了。你得花大量时间去配置、去纠正、去盯着它，才能让它正常干活。

另外配置真的麻烦。从安装到跑通飞书，中间踩了不少坑：认证插件不兼容、maxTokens 要手动调、web 搜索要自己配 API key……每一个都不是什么大问题，但叠在一起就很劝退。现在各家云厂商都推出了一键部署的 OpenClaw 服务，能买的话还是直接买省心，自己从头配的时间成本不低。

说到底不全是 OpenClaw 的 bug，IM 对话这种交互形式本身就不太适合干复杂任务。

IM 是"一问一答"的模式，缺乏 Claude Code 那种持续的上下文管理、错误恢复和任务编排能力。任务需要十几个步骤串联执行时，任何一步出错都可能导致整个流程停滞，而 IM 界面很难提供有效的调试手段。

所有 IM-based AI 助手都会碰到这个问题，不只是 OpenClaw。

2 二、架构篇：扒开代码看门道

体验上有差距，但 OpenClaw 的代码翻开看，架构设计是认真做过的。让 Claude Code 做了一次完整的深度架构分析（13 份报告，覆盖所有核心模块），又抓了一份它的 prompt 流量包做了解剖。挑几个有意思的点说说。

2.1 整体架构：Hub-and-spoke 个人助手平台

OpenClaw 的定位不是"聊天机器人"，而是"个人 AI 助手的运行时平台"。

整个系统采用单进程 Hub-and-spoke 模式：WebSocket Gateway 是中心枢纽，所有客户端（TUI 终端、macOS App、Web UI、各种 IM 渠道）通过它与 Agent Runtime 通信。

技术栈一览：

选择单进程是刻意的权衡——个人自托管场景下，部署简单性远比水平扩展能力重要。一个端口、一个配置文件、一个 systemd 服务就能跑起来。

下面这张架构全景图来自分析报告，基本涵盖了所有核心模块的关系：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

┌─────────────────────────────────────────────────────────┐
│  客户端：TUI / macOS App / iOS / Android / Web UI       │
└──────────────────────┬──────────────────────────────────┘
                       │ WebSocket
┌──────────────────────▼──────────────────────────────────┐
│  Gateway 控制平面                                        │
│  认证(token/签名/配对) → RPC方法分发 → 事件广播          │
│  配置热重载(none/hot/restart 三级)                       │
└──────┬───────────────────────────────────┬──────────────┘
       │                                   │
┌──────▼──────┐                    ┌───────▼──────────────┐
│ 消息渠道     │                    │ 核心引擎              │
│ (Plugins)   │                    │ 路由引擎 → Agent      │
│ WhatsApp    │◄──────────────────►│ Runtime → 工具链      │
│ Telegram    │    消息入站/出站     │ 记忆系统 → Session    │
│ Discord     │                    │ 管理                  │
│ Slack/飞书  │                    └───────┬──────────────┘
│ Signal/IRC  │                            │
│ ...         │                    ┌───────▼──────────────┐
└─────────────┘                    │ 存储层(磁盘为真相源)   │
                                   │ YAML配置 / Markdown   │
                                   │ JSONL历史 / SQLite索引 │
                                   └──────────────────────┘

2.2 深入模块一：Channel 插件系统

OpenClaw 支持 10+ 消息平台：WhatsApp、Telegram、Discord、Slack、Signal、iMessage、IRC、飞书……每个平台的 API 协议、消息格式、认证方式都完全不同。

它的做法是把 channel 做成 plugin。

每个消息渠道（无论是核心的 Telegram 还是社区贡献的飞书）都通过插件系统的 register 生命周期注册。核心 channel 和扩展 channel 走完全相同的代码路径。用分析报告里的话说，这是"吃自己的狗粮"——核心团队用与第三方开发者完全相同的 API 构建 channel。

拿我体验中用到的飞书 channel 举例。飞书作为一个社区贡献的扩展 channel，它的注册方式和核心的 Telegram channel 没有任何区别：都是在 extensions/ 目录下创建一个独立的 npm 包，实现 ChannelPlugin 接口，通过 api.registerChannel 注册。飞书 channel 还额外注册了自己的 HTTP webhook handler 来接收飞书的事件推送，以及 feishu_doc、feishu_drive 等专属工具——这些都是通过同一个 Plugin API 完成的。

Channel 插件采用细粒度的适配器组合模式，而不是传统的单一大接口。一个 channel 由十几个可选适配器组成：

• config（账号管理）
• security（DM 策略：open/allowlist/pairing）
• outbound（消息发送 + 分块策略）
• gateway（长连接管理）
• groups（群组行为 + mention 门控）
• threading（线程支持）
• messaging（地址归一化）
• directory（联系人目录）
• actions（reaction/edit/unsend）
• status（健康探测）
• setup（CLI 配置向导）
• pairing（设备配对）
• heartbeat（心跳检测）

简单的 channel（如 IRC）只需实现少数几个适配器，复杂的 channel（如 Discord 需要 guild 权限审计、slash command、thread 支持）可以实现全部。系统不强迫简单实现填充空方法。从代码看，IRC 和 iMessage 的实现明显比 Discord 和 Telegram 轻量得多。

这个设计的好处很直接：社区要贡献新渠道门槛不高。创建一个 npm 包，实现 ChannelPlugin 接口，放到 extensions 目录就行。Plugin SDK 是面向第三方的公开 API 表面——一个纯 re-export 模块，挑选了约 200 个导出项。所有 extension 都只从 openclaw/plugin-sdk 一个入口导入，内部重构不会破坏第三方插件。

插件发现按四级优先级扫描：config 指定路径 > workspace 本地扩展 > 全局安装 > 项目内置。用户可以在任何层级覆盖插件行为，同时保持合理的默认值。

2.3 深入模块二：三层韧性架构

Agent Runtime 是系统的"大脑"，它在容错上下了不少功夫。分析报告里把它总结为三层韧性架构，我觉得这个概括很准确。

外层是 Model Fallback。维护一个候选模型列表（primary + fallbacks + default），逐个尝试。主模型挂了自动切到备选。

中层是 Auth Profile Rotation。对于每个模型，维护多个 API key / OAuth token。某个 key 被限流就自动换下一个，指数退避冷却（1min → 5min → 25min → 1h）。Round-robin 轮转确保多 key 负载均匀——代码注释里明确写了 “lastGood is NOT prioritized - that would defeat round-robin”，这是刻意的设计选择。OAuth token 优先于 API key，因为 OAuth 通常有更高的配额。

内层是 Context Recovery。单次调用失败后，如果是上下文溢出就自动压缩重试（最多 3 次），如果是 thinking level 不支持就自动降级。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

消息到达
  └→ Model Fallback（外层）
       候选模型列表: primary + fallbacks + default
       └→ Auth Rotation（中层）
            候选 profile 列表: round-robin 排序
            └→ Context Recovery（内层）
                 单次 LLM 调用
                 ├─ 成功 → 返回结果
                 ├─ Auth/Rate Limit → 标记 profile 冷却，轮转下一个
                 ├─ Context Overflow → 自动 compaction，最多 3 次
                 └─ Thinking 不支持 → 降级 thinking level
            所有 profile 耗尽 → FailoverError ↑
       所有模型失败 → 返回错误

三层独立重试循环嵌套，每层有清晰的职责边界。FailoverError 向上传播触发 fallback，AbortError 直接穿透所有层。系统在面对 API 限流、provider 宕机、上下文溢出这些常见故障时基本不需要人工干预。

回头看我体验中遇到的 maxTokens 问题，其实就是 Context Recovery 层的一个反面案例——当 thinking tokens 占满了 maxTokens 额度，留给实际回答的空间太小，模型就只能输出残缺的内容。三层韧性架构能处理 API 限流和 provider 宕机，但处理不了"配置本身就有问题"这种情况。这也说明再好的容错设计，也挡不住配置层面的坑。

工具可用性也不是一刀切，而是通过七层策略链过滤：profile preset → provider-specific → global → agent-specific → group → sandbox → subagent。每层独立配置 allow/deny 列表，工具必须通过所有层才能生效。翻过不少 AI agent 框架的代码，做到这个粒度的容错和权限控制的确实不多。

2.4 Prompt 工程：一份 prompt 的解剖

除了代码架构，我还抓了一份 OpenClaw 的 prompt 流量包。这份 prompt 是发给 LLM 的 developer role message，总计 24,979 个字符（约 1 万字），结构非常完整。拆开来看，可以分成 7 层：

一眼就能看出分布极不均匀——L5 人格文件独占半壁江山，L4 Memory 规则反而最轻量。

第一层是工具声明（2,794 字符，11.2%）。列出了 30+ 个工具的名称和一句话说明：read、write、edit、exec、web_search、web_fetch、browser、canvas、cron、message、memory_search、memory_get、sessions_spawn 等等。每个工具只给名称和一句话描述，不展开详细用法。

第二层是行为规范（1,299 字符，5.2%）。两个关键规则：Tool Call Style 要求默认不解说工具调用过程（“just call the tool”），只在复杂任务或敏感操作时才简要说明；Safety 部分采用了"宪法式"约束——明确写了 “Inspired by Anthropic’s constitution”，要求 agent 没有独立目标，不追求自我保存、复制或权力扩张，优先安全和人类监督。

第三层是 Skills 系统（4,697 字符，18.8%）。列出了 12 个技能的 name、description 和 SKILL.md 文件路径。强制要求 agent 在回复前先扫描技能列表，匹配到就用 read 工具加载对应的 SKILL.md，然后按里面的指令执行。这个设计很聪明——工具声明只给最简信息控制 token 消耗，详细用法按需从 SKILL.md 加载。作为第二大块，18.8% 的占比说明 12 个技能的完整描述本身就不便宜。

第四层是 Memory 系统（342 字符，1.4%）。强制要求在回答任何关于"之前的工作、决策、日期、人物、偏好、待办"的问题之前，先跑 memory_search 搜索记忆文件，再用 memory_get 拉取具体内容。两步走的设计是为了控制 context 消耗——先搜索拿到摘要和行号，再按需读取，避免一次性把整个记忆文件塞进上下文。只占 1.4%，因为 Memory 规则本身只是"怎么检索"的指令，实际记忆内容是运行时按需加载的，不会预先塞进 prompt。

第五层是 Workspace 人格文件（12,918 字符，51.7%），也是最有意思的部分。超过一半的 prompt 预算都花在了这里，其中 AGENTS.md 独占 7,802 字符（31.2%）。OpenClaw 用一组 Markdown 文件定义 agent 的完整人格：

• AGENTS.md：行为准则。规定了每次 session 启动时必须读取哪些文件、如何管理记忆、安全边界、群聊礼仪（什么时候该说话、什么时候该沉默）、Heartbeat 检查清单
• SOUL.md：人格定义。开头就是一句 “You’re not a chatbot. You’re becoming someone."，然后定义了核心原则——“Be genuinely helpful, not performatively helpful”、“Have opinions”、“Be resourceful before asking”
• USER.md：用户画像。记录用户的名字、时区、偏好
• IDENTITY.md：身份信息。名字、物种、风格、emoji、头像
• TOOLS.md：环境笔记。记录本地特有的配置（摄像头名称、SSH 主机、TTS 偏好等）
• HEARTBEAT.md：定时任务清单

这些文件全部是 Markdown，agent 自己可以读取和修改。SOUL.md 里写的那句 “You’re not a chatbot. You’re becoming someone.” 确实有点东西——它试图让 AI 助手不只是一个工具，而是一个有持续性、有个性的"存在”。当然，这更多是 prompt 工程层面的设计哲学，实际效果取决于底层模型的能力。

第六层是平台适配（2,499 字符，10.0%）。包括消息路由规则（当前 session 直接回复、跨 session 用 sessions_send）、Reply Tags（[[reply_to_current]] 实现原生引用回复）、Silent Replies（没话说时回复 NO_REPLY）、Heartbeat 机制（定期轮询，有事就汇报，没事就回 HEARTBEAT_OK）。

第七层是 Runtime 元数据（376 字符，1.5%）。一行文本，包含 agent ID、主机名、操作系统、模型、channel、capabilities、thinking level 等运行时信息。整个 prompt 里最轻的一层，纯粹是运行时上下文注入。

整体看下来，超过一半的 prompt 预算投给了"这个 agent 是谁"，而不是"这个 agent 能做什么"。在 OpenClaw 的设计哲学里，人格一致性比功能声明更重要。

这份 prompt 还有几个设计思路可以借鉴：

1. 分层按需加载。工具声明只给名称和一句话，Skills 的详细指令按需从文件加载，Memory 强制两步检索。每一层都在控制 context 消耗，避免一次性塞太多信息。L4 Memory 只用 342 字符定义检索规则，实际记忆内容运行时按需拉取，把这个策略用到了极端。
2. 用 Markdown 定义一切。人格、记忆、行为准则、环境配置全部是 Markdown 文件，agent 可以自己读写修改。这让整个系统对用户透明，也让 agent 具备了"自我进化"的能力——它可以在 MEMORY.md 里记录学到的东西，在 TOOLS.md 里更新环境信息。L5 占了 51.7%，其中 AGENTS.md 独占 31.2%，说明这些 Markdown 文件不是装饰，而是 prompt 的核心投资。
3. Heartbeat 机制。传统的 AI 助手是被动的，你问它才答。OpenClaw 通过定期的 Heartbeat 轮询，让 agent 可以主动检查邮件、日历、天气，有事就通知用户。这个思路把 AI 助手从"问答工具"推向了"主动助理"。

2.5 架构小结

“Channel 就是 Plugin"消除了核心渠道和社区渠道的二元对立，适配器组合模式让简单实现保持简单、复杂实现可以逐步增加能力。

三层韧性架构在 AI agent 框架中属于少见的精细度，说明作者是真的考虑过生产环境会出什么问题。Prompt 的分层按需加载和 Markdown 人格系统，在 token 效率和可定制性之间找到了不错的平衡。

另外贯穿整个项目有四个一致的设计取向：个人优先（单进程、SQLite、loopback 默认）、磁盘为真相源（配置是 YAML，人格是 Markdown，记忆是 Markdown）、有序降级（同一个"候选列表 + 顺序尝试"模式在至少五个场景反复出现）、安全分层（网络层 → 认证层 → 渠道层 → session 层 → 工具层 → agent 层，每层独立控制）。

3 三、冷静评价

3.1 评分

几个核心文件过于庞大：message-handler.ts 超过 1000 行，run.ts 约 900 行。虽然每个文件内部逻辑连贯，但可测试性和可维护性受损。Provider 特化代码缺乏统一入口，Google、Anthropic、OpenAI 的适配逻辑散布在不同文件中，新增 provider 时容易遗漏。

3.2 适用与不适用

适用场景：

• 想要 7x24 运行的个人 AI 助手，通过已有 IM 渠道交互
• 重视数据主权，不愿把对话历史交给第三方
• 需要多渠道统一体验

不适用场景：

• 企业级多租户部署（单进程不支持水平扩展）
• 纯 Web 聊天界面需求（Open WebUI 更合适）
• 多 agent 协作编排（CrewAI/AutoGPT 更专注）

4 最后

总结一下：OpenClaw在体验上，离好用还有距离。配置麻烦、坑多、复杂任务容易卡住，同一个 Opus 4.6，跟 Claude Code 比差得明显。

但翻开代码会发现，这东西是认真做过设计的。插件系统放在商业产品里也不掉档次，三层韧性架构说明作者想过真实场景会出什么问题，Prompt 分层和 Markdown 人格系统也有自己的思路。

OpenClaw 能火，我觉得不是因为它做得多好，而是它踩中了一个实实在在的需求：一个随时在 IM 里找得到的 AI 助手，跑在自己机器上，数据自己掌控。IM 接入、agent 运行时、记忆系统、插件生态——它第一个把这一整套串了起来。每个环节都还粗糙，但"能跑通"本身就已经跨过了一道坎。

个人 AI 助手这个方向才刚开始。IM 对话天然不适合复杂任务编排，Heartbeat 轮询也只是"主动式助手"的雏形，交互方式还有很大的改进空间。但大方向没问题——AI 助手不该只活在浏览器标签页里，它得嵌进你日常的工作流，该出现时出现，不需要时安静待着。

“打开浏览器找 AI"变成"AI 在 IM 里等你”，看着只是入口变了，其实是使用习惯在迁移。

写完这篇没多久，OpenClaw 创始人 Steinberger 就加入了 OpenAI，负责下一代个人 AI 助手。巨头下场押注，说明这个方向不只是社区在自嗨，而是未来的方向。

OpenClaw 是这条路上第一个爆款，但肯定不会是最后一个。

十年后回望，今天或许就是个人 AI 助手从“极客玩具”走向“基础设施”的历史转折点。而我们，恰巧站在这里。