OpenClaw 源码与社区反馈研究

研究日期: 2026-05-01
仓库: openclaw/openclaw
版本: v2026.4.29-beta.2（截至研究日）
规模: 366,700+ stars / 75,300+ forks / 6,820 open issues / TypeScript / MIT
定位: 个人 AI 助手，自托管，多平台 IM 原生集成
研究目的: 提取对 Vyane / Yi / 自研 App 有用的架构设计和社区教训

---

一、架构总览

OpenClaw 是一个 TypeScript monorepo（src/ 下约 7,636 个源文件，119 个 extension 包），围绕 Gateway-centric、plugin-extensible、multi-channel agent system 构建。

核心数据流

用户消息 (Discord/Telegram/CLI/Web/...)
    |
    v
Channel Plugin (inbound) ──> Turn Kernel (准入检查)
    |
    v
Routing Engine (resolveAgentRoute) ──> Agent ID + Session Key
    |
    v
Command Queue (lane 并发控制) ──> runEmbeddedPiAgent()
    |
    v
Harness Selection (内置 PI / 插件 harness / auto)
    |
    v
Run Attempt Loop:
    ├── 构建 System Prompt (context files + memory + skills + provider)
    ├── 解析 Model + Auth Profile
    ├── 注册 Tools (bash, edit, read, MCP, channel, plugin)
    ├── Stream to LLM (Anthropic/OpenAI/Google/...)
    │     └── Tool calls 在循环中执行
    ├── 失败处理: auth 轮换 / model failover / compaction / 重试
    └── 提取 reply payloads
    |
    v
Channel Plugin (outbound) ──> 回复投递给用户
    |
    v
Session Store (持久化对话、更新元数据)

---

二、关键模块深度分析

2.1 Gateway（控制平面）

路径: src/gateway/ (~370 个非测试文件)

Gateway 是一个持久化 WebSocket 服务器（默认端口 18789），作为整个系统的控制平面：

• server.impl.ts (startGatewayServer) — 主服务器，启动时引导：认证系统、Channel 管理器、Cron 调度器、Plugin 运行时、Model Catalog、Control UI（Web 仪表板）、MCP HTTP 服务器、Node 注册表、Session 管理、健康监控
• server-methods/ — RPC 方法按领域组织：agent.ts, chat.ts, sessions.ts, channels.ts, config.ts, cron.ts, nodes.ts, secrets.ts, skills.ts, wizard.ts
• protocol/ — WebSocket 协议 schema（TypeBox），定义 agent events、channels、commands、config、cron、devices 等 frame

架构模式: Gateway 是长期运行的 daemon。客户端（Web UI、CLI、ACP agent、移动节点）通过 WebSocket 连接。所有 agent run、channel dispatch、cron job 都流经 Gateway 的事件循环。

对 Vyane 的启示:

• Vyane daemon 已经走了类似的 Gateway 架构路线（Phase 0+1，端口 8080）
• OpenClaw 的 WebSocket protocol schema 设计（TypeBox）值得参考——强类型的帧定义比松散的 JSON 更可靠
• 但 OpenClaw 的单进程 Gateway 是其资源瓶颈（空闲 400-800MB RAM），Vyane 应考虑更轻量的进程模型

2.2 Agent Loop（Agent 执行引擎）

路径: src/agents/ (~820 个非测试文件，最大模块)

Harness 系统（模型后端抽象）

type AgentHarness = {
  id: string;
  supports(ctx: AgentHarnessSupportContext): AgentHarnessSupport;
  runAttempt(params: EmbeddedRunAttemptParams): Promise<EmbeddedRunAttemptResult>;
  compact?(params): Promise<EmbeddedPiCompactResult>;
  reset?(params): Promise<void>;
};

选择逻辑按优先级：Pinned → Forced PI → Forced Plugin → Auto（扫描注册的插件 harness）

V2 生命周期: prepare -> start -> send -> resolveOutcome -> cleanup

核心 Run Loop

文件: src/agents/pi-embedded-runner/run.ts (runEmbeddedPiAgent)

1. Resolve model — 查找 provider + model，解析 auth profiles
2. Build runtime plan — Auth plan + tool plan
3. Enter lane — 通过 command queue 实现并发控制
4. Attempt loop — 调用 runEmbeddedAttemptWithBackend()，失败时：
   • Auth failover — 401/rate-limit 时轮换 auth profiles
   • Model failover — 回退到配置的 fallback models
   • Overload backoff — 529/overloaded 指数退避
   • Compaction — context overflow 触发压缩后重试
   • Live model switch — 支持运行中热切换模型

单次 Attempt（attempt.ts，3,524 行）

1. Session setup（创建/恢复 SessionManager，获取写锁）
2. System prompt 构建（多源拼接）
3. Bootstrap（workspace 文件注入上下文）
4. Tool 注册（bash, edit, read, glob, grep, web-fetch, MCP, channel, plugin, skills）
5. Stream resolution（构建目标 provider 的流式函数 + middleware 包装）
6. Subscribe（流式 model 交互，循环中处理 tool calls，管理 compaction 触发）
7. 结果提取（assistant 文本、tool metas、usage、prompt cache stats）

对 Vyane 的启示:

• Harness 抽象是核心设计亮点 — Vyane 的多模型调度可以直接借鉴这个模式，将 Claude/GPT/Gemini 统一在一个 Harness 接口后面
• Auth profile 轮换 + model failover — Vyane 已经有多 key 轮询的需求（Tavily 6 key），可以泛化为通用的 auth profile rotation 机制
• attempt.ts 3,524 行是反面教材 — 单文件过大是工程质量问题的信号，Vyane 应该更严格地拆分

2.3 System Prompt 构建

文件: src/agents/system-prompt.ts

System prompt 按有序 section 构建：

1. Identity line（agent 名称）
2. Context files（AGENTS.md, SOUL.md, IDENTITY.md, USER.md, TOOLS.md, BOOTSTRAP.md, MEMORY.md）— 按优先级排序
3. Heartbeat section（cron/polling 用）
4. Skills section（可用的 slash commands）
5. Memory section（向量搜索结果）
6. Exec approval guidance（channel 特有）
7. Provider-specific contributions

Context files 分为 static（缓存）和 dynamic（如 heartbeat.md），为 prompt cache 效率做优化。

对 Vyane/Yi 的启示:

• 分层配置文件体系（SOUL.md / USER.md / TOOLS.md / BOOTSTRAP.md） 是 OpenClaw 最有影响力的设计之一
• Maple 的 OpenClaw 本地部署已经用了这套体系（Iris 的 workspace-iris/ 下有完整实例）
• Yi 的人格设计可以沿用 SOUL.md 范式，但建议：
  • 将 SOUL.md 拆为 identity（不变的核心身份）和 personality（可调的行为模式）
  • USER.md 对应 Maple 当前的 user memory，但 OpenClaw 的版本更结构化

2.4 Routing 系统

路径: src/routing/ (8 个文件)

路由将入站消息映射到 agent session：

type ResolvedAgentRoute = {
  agentId: string;
  sessionKey: string;
  mainSessionKey: string;
  matchedBy: "binding.peer" | "binding.guild+roles" | ... | "default";
};

分层绑定系统（严格优先级）：

1. 精确 peer 匹配
2. Parent peer（thread 继承）
3. Wildcard peer kind
4. Guild + roles
5. Guild only
6. Team
7. Account-scoped
8. Channel-scoped wildcard
9. Default agent

Session key 模式: {agentId}:{mainKey} 或 {agentId}:{channel}:{accountId}:{peerKind}:{peerId}

对 Vyane 的启示:

• 分层路由是多 agent 系统的刚需 — 当 Yi 需要根据不同的 channel/peer 路由到不同的 agent 人格时，这套绑定系统可以直接参考
• Session key 的命名约定 值得借鉴，但 Vyane 应该用更可读的格式而非纯拼接

2.5 Channel 抽象（多平台 IM 统一）

路径: src/channels/ (~180 个非测试文件)

每个 channel 是一个 ChannelPlugin，实现综合适配器接口：

type ChannelPlugin = {
  id: ChannelId;
  meta: ChannelMeta;                    // 标签、文档、排序、别名
  capabilities: ChannelCapabilities;
  config: ChannelConfigAdapter;          // 读取/验证配置
  setup?: ChannelSetupAdapter;           // 引导向导
  pairing?: ChannelPairingAdapter;       // 设备配对
  security?: ChannelSecurityAdapter;     // 白名单、认证
  groups?: ChannelGroupAdapter;          // 群聊支持
  outbound?: ChannelOutboundAdapter;     // 发消息
  lifecycle?: ChannelLifecycleAdapter;   // 启动/停止/重连
  gateway?: ChannelGatewayAdapter;       // WS 方法处理
  auth?: ChannelAuthAdapter;             // 登入/登出
  commands?: ChannelCommandAdapter;      // slash commands
  streaming?: ChannelStreamingAdapter;   // draft/typing
  threading?: ChannelThreadingAdapter;   // 线程支持
  messaging?: ChannelMessagingAdapter;   // 富消息工具
  actions?: ChannelMessageActionAdapter; // 反应、编辑等
  heartbeat?: ChannelHeartbeatAdapter;
  agentTools?: ChannelAgentToolFactory;  // channel 专属工具
};

Turn Kernel（src/channels/turn/kernel.ts）是 channel 交互的原子单元：

1. Preflight — 准入检查（dispatch vs observe-only vs drop）
2. Record — 持久化入站消息
3. Dispatch — 运行 agent 并通过 outbound adapter 投递回复
4. History finalize — 清理群聊历史缓冲

对 Vyane/Yi 的启示:

• ChannelPlugin 接口设计是参考标杆 — 但 OpenClaw 的 119 个 extension 规模带来了巨大的维护负担。Yi 初期应该只支持 2-3 个 channel（自研 App + Discord/Telegram），等核心稳定后再扩展
• Turn Kernel 的准入检查 是重要的安全边界——在群聊场景中，agent 需要判断何时发言。OpenClaw 的 AGENTS.md 中已有明确的群聊发言规则，Maple 的本地 Iris 配置也沿用了这套规则
• optional adapter 模式（setup?, pairing?, security?）比 required + noop 更好——channel 只实现自己需要的能力

2.6 Memory 系统

路径: src/memory/, src/memory-host-sdk/ (~60 个文件), src/agents/memory-search.ts

存储

使用 SQLite + 可选的 sqlite-vec 向量搜索：

type ResolvedMemorySearchConfig = {
  store: {
    driver: "sqlite";
    path: string;              // per-agent SQLite 文件
    fts: { tokenizer: "unicode61" | "trigram" };
    vector: { enabled: boolean; extensionPath?: string };
  };
  sources: Array<"memory" | "sessions">;
  chunking: { tokens: 400; overlap: 80 };
  query: {
    maxResults: 6;
    minScore: 0.35;
    hybrid: {
      enabled: true;
      vectorWeight: 0.7;
      textWeight: 0.3;
      mmr: { enabled: boolean; lambda: 0.7 };
      temporalDecay: { halfLifeDays: 30 };
    };
  };
};

检索

• Hybrid search — 向量相似度（embedding）+ 全文搜索（FTS5）加权组合
• MMR（Maximal Marginal Relevance）— 多样性感知的重排序
• 时间衰减 — 近期记忆得分更高（半衰期 30 天）
• 候选过采样 — 先多取候选再重排

Embedding 管线

• 支持多 embedding provider（per-agent 配置）
• 批处理 + remote/local fallback
• 分块: 可配置 token 大小 + overlap
• 同步触发: session 启动时、搜索时、文件监控、定时

记忆来源

• MEMORY.md — 根 workspace 记忆文件（canonical: MEMORY.md，legacy: memory.md）
• Extra paths — 额外记忆文件
• Session memory — 实验性：索引历史 session 转录文本用于检索
• QMD（Query-Markdown）— 结构化查询解析

本地 OpenClaw 的记忆实践（Iris workspace）

Maple 本地的 Iris 配置使用了双层记忆系统：

• Daily notes: memory/YYYY-MM-DD.md — 当天原始日志
• Long-term: MEMORY.md — 策展后的长期记忆

关键安全规则：MEMORY.md 仅在 main session（与用户直接对话）中加载，群聊/共享上下文中不加载，防止私人信息泄露。

对 Vyane 的启示:

• Hybrid search 的参数配置 可以直接作为 Vyane memory 系统的起点（vectorWeight 0.7 / textWeight 0.3 / MMR lambda 0.7 / 半衰期 30 天）
• SQLite + sqlite-vec 是轻量级但功能完整的选择，适合单用户场景
• 社区反馈揭示了严重问题：三个用户同版本三种行为（chunking+embedding / 日期文件 / 什么都不记），QMD 后端 CPU-only 机器 10 秒超时后永久降级不恢复——这表明记忆系统的配置确定性和降级恢复是必须优先考虑的
• Maple 当前的 CC CLI memory 系统（markdown + frontmatter 索引） 反而比 OpenClaw 的更稳定，因为避免了 embedding/vector 的复杂度。Vyane 可以采用渐进策略：先用 markdown + FTS，确认稳定后再加向量搜索

2.7 Session 管理

路径: src/sessions/ (13 个文件) + src/agents/session-*.ts + src/gateway/session-*.ts

• Session ID — UUID
• Session Key — 编码 agent、channel、account、peer 作用域的派生字符串
• Session 生命周期 — pub/sub 模式的 create/destroy 事件
• Session 写锁 — 防止并发写入同一 session
• DM 作用域 — 可配置: main（所有 DM 共享一个 session）/ per-peer / per-channel-peer / per-account-channel-peer
• Compaction — context window 管理: successor transcripts、checkpoint-based、带 hook 通知
• Subagent sessions — 生成的子 agent 有独立的 session key

2.8 Plugin 系统

路径: src/plugins/ (~100+ 个文件), extensions/ (119 个包)

插件类型：

• Channel plugins — IM 平台集成
• Model provider plugins — LLM 后端
• Tool plugins — 搜索、文档提取、媒体生成
• Agent harness plugins — 替代 agent 执行后端（Codex、Kilocode 等）
• Hook plugins — 生命周期钩子
• Memory plugins — 替代记忆后端（LanceDB、Wiki）

Plugin Runtime 注入接口：

type PluginRuntime = PluginRuntimeCore & {
  subagent: {
    run(params): Promise<SubagentRunResult>;
    waitForRun(params): Promise<SubagentWaitResult>;
    getSessionMessages(params): Promise<...>;
    deleteSession(params): Promise<void>;
  };
  nodes: {
    list(params?): Promise<RuntimeNodeListResult>;
    invoke(params): Promise<unknown>;
  };
  channel: PluginRuntimeChannel;
};

2.9 ACP（Agent Client Protocol）

路径: src/acp/ (~60 个非测试文件)

OpenClaw 实现了 Agent Client Protocol 用于外部 agent 集成：

• server.ts — ACP stdio server，通过 WebSocket 连接 Gateway
• translator.ts — ACP 协议与 OpenClaw Gateway 事件的双向翻译
• control-plane/manager.ts — 运行时管理: session 生成、身份协调、turn 流式传输

---

三、社区反馈综合

3.1 用户喜欢的

主动式行为（Proactive）

• 与 ChatGPT 等被动工具不同，OpenClaw 会主动联系用户（晨报、价格变动提醒等）
• 据 TryOpenClaw 统计，平台 60% 的消息是自动外发的

消息平台原生集成

• 在 WhatsApp/Telegram/Discord 里直接用，不需要单独 App
• 用例：家族史 Telegram bot（50+ 家庭成员）、园艺排班、SOC2 合规评估

开源与数据自主

“memory being locked away with a specific vendor, it’s stored in version control that I can read and edit.”

真实生产力

• 团队用它跑每日 standup，监控 GitHub/Linear 汇总
• 一位用户的 agent 成功诊断硬盘故障并恢复了 1.5TB 数据

“Having an AI teammate is actually fun. Our entire team said they’d be sad if they had to stop using it.”

3.2 主要痛点

Memory 系统混乱（最高频投诉）

GitHub Issue #43747：同一版本下三个同事的记忆行为完全不同：

• 用户 A: chunking + embedding 存 SQLite
• 用户 B: 按日期存 markdown 文件
• 用户 C: 什么都不记

QMD Memory Backend（#11308）20+ 相关 issue：

• CPU-only 机器 10 秒超时，fallback 后永久降级，不恢复
• memory_search 在 QMD 模式下不调 QMD 搜索
• 每次查询启动子进程而非持久 MCP server，冷启动开销严重

自托管稳定性差

Field Report #41372（4 周生产环境 25 个问题）：

• 配置文件加了不认识的 key → crash-loop（377+ 次重启，无 backoff）
• CLI 文档与实际语法 9 处不一致
• Discord bot 能发不能收（静默丢弃消息）
• 2GB VPS 上 CRM 同步 cron 导致 OOM

Channel 集成脆弱

• 2026.4.26 版本更新后大面积 Discord/Gateway crash
• Telegram “silent reply” bug：agent 收到消息有日志，但回复永远不到达用户，无错误输出
• 部分用户因此转向 Hermes Agent

安全漏洞严重

• 原生防御率仅 17%（论文 “Don’t Let the Claw Grip Your Hand”）
• CVE-2026-25253（ClawJacked）：零点击 WebSocket 劫持远程代码执行
• 40,214 个暴露实例，35.4% 被标记为可利用
• ClawHub 上确认 1,184 个恶意 skills（最大的 AI agent 供应链攻击）
• 135,000+ 实例绑定 0.0.0.0 而非 localhost

资源消耗

• Gateway 空闲 400-800MB RAM
• 每个活跃 channel ~100MB，浏览器自动化 2-4GB
• 2GB 机器不可用；4GB 仅无浏览器场景
• 孤立 Chromium 实例不自动清理 → 长期内存泄漏

成本

• Opus 重度使用日花费 $110
• 多位用户月均 $100-400 API 费用
• 自托管总成本（含维护时间）$250-300/月 > 托管服务 $45-55/月

3.3 与竞品对比

维度	OpenClaw	Claude Code	Manus AI
定位	24/7 多平台自主 agent	终端原生编码 agent	云托管通用 agent
部署	自托管（Docker/VPS）	本地 CLI	云端零安装
多 channel	50+ 平台原生支持	无	自有 Web UI
安全	17% 防御率，6 CVE	Anthropic 官方维护	数据经海外服务器
记忆	markdown + QMD（不稳定）	手动 markdown	托管
适用人群	自动化玩家、非工程师	开发者	非技术业务团队

Harrison Chase（LangChain）指出 OpenClaw、Claude Code、Manus 底层架构本质相同：model + runtime + harness。

---

四、对 Vyane / Yi / 自研 App 的设计提取

4.1 直接可借鉴的设计

设计	OpenClaw 实现	Vyane 应用建议
Harness 抽象	AgentHarness 接口统一多模型后端	Vyane 多模型调度的核心抽象，直接采用 supports() + runAttempt() + compact() 接口模式
Auth profile rotation	401/rate-limit 时自动轮换 auth profiles	泛化为通用 key rotation（已有 Tavily 6 key 需求）
Model failover chain	配置 fallback models，overload 时自动切换	Vyane 已有"Codex Pro 挂时 fallback haxi"的需求，可以标准化
分层 system prompt	SOUL.md / USER.md / TOOLS.md / BOOTSTRAP.md / MEMORY.md 分离	Yi 人格设计直接沿用，但拆 identity（不变）和 personality（可调）
Hybrid memory search	vector 0.7 + FTS 0.3 + MMR + 时间衰减	作为 Vyane memory 的参数起点
Turn Kernel 准入检查	preflight → record → dispatch → finalize	Yi 在群聊场景的发言控制
Session key 编码	{agentId}:{channel}:{accountId}:{peerKind}:{peerId}	多 channel session 隔离的命名约定
Context file 分 static/dynamic	为 prompt cache 优化	Vyane system prompt 构建时区分不变量和动态部分

4.2 应该避免的陷阱

陷阱	OpenClaw 表现	Vyane 的规避策略
Memory 配置不确定性	同版本三种行为	memory 行为必须有单一明确的配置路径，不依赖隐式 fallback
降级不恢复	QMD 超时后永久降级	任何降级必须有恢复机制（定时重试 / 手动重置）
单文件过大	attempt.ts 3,524 行	硬性拆分，单文件 < 500 行
119 个 extension	维护负担巨大	Yi 初期只做 2-3 个 channel，等核心稳定后扩展
0.0.0.0 默认绑定	135,000+ 暴露实例	默认 localhost，外部访问需要显式配置
Gateway 单进程	空闲 400-800MB	考虑更轻量的进程模型
CLI 文档与实际不一致	9 处 CLI 语法差异	CLI 自描述（--help 从代码生成），不依赖手写文档
配置不容错	未知 key → crash-loop	配置 JSON schema 发布 + unknown key 警告而非 crash
供应链攻击	1,184 个恶意 skills	skill/plugin 签名验证 + 沙箱隔离

4.3 Maple 本地 OpenClaw 遗产的迁移价值

已有的 Iris workspace 配置（runtime/openclaw/.openclaw/workspace-iris/）包含：

• AGENTS.md（378 行）— 完整工作手册：协作模式、执行标准、5 级失败升级策略、多模型讨论规则、Linear 规范、Discord 管理 SOP
• TOOLS.md（302 行）— 工具配置详表
• MEMORY.md — 9 条详细经验教训
• 38 个 diary 文件（2026-03-16 至 2026-04-05）

这些内容中的协作模式和失败升级策略已经部分迁移到了当前的 CLAUDE.md / AGENTS.md 体系。工具配置和 SOP 在 Vyane 设计阶段可以作为需求参考。

---

五、不确定性与局限

项目	说明
源码深度	通过 GitHub API 和 raw file fetch 分析，未 clone 完整仓库。部分模块（如 context-engine、trajectory）仅了解目录级结构
社区反馈采样偏差	主要来源是 GitHub Issues、HN、X、Reddit。不满意的用户发帖概率更高
版本快速迭代	OpenClaw 几乎每日发版（研究日版本 v2026.4.29-beta.2），具体实现细节可能快速变化
本地 OpenClaw vs 上游	Maple 本地的 .openclaw/ 是定制化部署（Iris agent），与上游版本有配置差异。AGENTS.md 模板一致但具体 workspace 内容不同
安全数据来源	"17% 防御率"来自学术论文，"1,184 个恶意 skills"来自 Antiy CERT 报告，均为二手引用

---

六、建议的后续工作

1. 深度阅读 OpenClaw 的 Harness 接口定义（src/agents/harness/types.ts）— 如果 Vyane 要实现多模型调度的 provider abstraction，这是最直接的参考
2. 对比 Hermes Agent 的 Memory/Skill/Compression 设计 — 社区中被反复提到的替代品，且已有本地参考资料（references/hermes-agent/）
3. 评估 SQLite + sqlite-vec 方案 — OpenClaw 的 hybrid search 参数可以直接实验，但需要先验证 sqlite-vec 在 macOS ARM 上的稳定性
4. Iris 遗留数据的选择性迁移 — 38 个 diary 文件中筛选有价值的经验教训，整合到当前 memory 体系
5. Channel Plugin 接口设计 — 为 Yi 的自研 App + Discord 设计统一的 channel 抽象时，参考 OpenClaw 的 optional adapter 模式但大幅简化

---

研究完成于 2026-05-01，基于 openclaw/openclaw main 分支（v2026.4.29-beta.2）