🦞 OpenClaw

Multi-channel AI Gateway — 你正在使用的 Agent 框架

Event-Driven Gateway Plugin Architecture TypeScript 68 Source Modules 8129 TypeScript Files 150+ Extensions 14 Chat Platforms

📦 8,129 TS files 🔌 150+ extensions 💬 14 channels 🧩 68 source modules 🛡️ Policy-based security

一、核心架构

OpenClaw 整体架构 — Event-Driven Gateway + Plugin System ┌──────────────────────────────────────────────────────────────────────────┐ │ Gateway (核心守护进程) │ │ ┌────────────────────────────────────────────────────────────────────┐ │ │ │ Session Manager (会话管理) │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ │ │ Telegram │ │ Discord │ │ WhatsApp │ │ Slack │ ...×14 │ │ │ │ └─────┬────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ │ └──────────────┴──────────────┴──────────────┘ │ │ │ │ ↓ inbound │ │ │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ │ │ Channel Plugin Layer (消息路由) │ │ │ │ │ │ allowlists → auth → routing → session binding │ │ │ │ │ └──────────────────────────┬───────────────────────────────────┘ │ │ │ │ ↓ │ │ │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ │ │ System Prompt Composer (提示词组装) │ │ │ │ │ │ stable prefix ←cache boundary→ volatile suffix │ │ │ │ │ │ [identity][tools][skills][context files][memory][runtime] │ │ │ │ │ └──────────────────────────┬───────────────────────────────────┘ │ │ │ │ ↓ │ │ │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ │ │ Provider Runtime (LLM 调用层) │ │ │ │ │ │ Anthropic / OpenAI / Google / DeepSeek / ... 40+ providers │ │ │ │ │ │ failover → retry → model fallback → credential rotation │ │ │ │ │ └──────────────────────────┬───────────────────────────────────┘ │ │ │ │ ↓ │ │ │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ │ │ Tool Execution Pipeline (工具执行) │ │ │ │ │ │ policy check → approval → exec → result → redaction │ │ │ │ │ └──────────────────────────┬───────────────────────────────────┘ │ │ │ │ ↓ outbound │ │ │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ │ │ Reply Delivery (回复投递) │ │ │ │ │ │ text / media / reactions / buttons / voice │ │ │ │ │ └──────────────────────────────────────────────────────────────┘ │ │ │ └────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │ │ │ Sub-Agent │ │ Cron Jobs │ │ Context │ │ Compaction │ │ │ │ Registry │ │ Scheduler │ │ Engine │ │ Service │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ └────────────┘ │ │ │ │ ┌────────────────────────────────────────────────────────────────────┐ │ │ │ Extension System (150+ plugins) │ │ │ │ providers × 40+ | channels × 14 | tools × 30+ | skills × 20+ │ │ │ └────────────────────────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────────────────────┘

二、系统提示词架构 (深度分析)

🧱 提示词三层结构 + Cache Boundary

System Prompt 组装流程 (~36,206 字符 + ~32,694 字符工具定义) ┌─────────────────────────────────────────────┐ │ STABLE PREFIX (缓存热区，跨 turn 不变) │ │ │ │ 1. Identity (SOUL.md / IDENTITY.md) │ │ 2. Tooling (可用工具描述) │ │ 3. Safety Rules │ │ 4. Skills (匹配的 SKILL.md) │ │ 5. Memory Recall 指令 │ │ 6. Workspace Files 注入顺序: │ │ AGENTS.md(10) → SOUL.md(20) → │ │ IDENTITY.md(30) → USER.md(40) → │ │ TOOLS.md(50) → BOOTSTRAP.md(60) → │ │ MEMORY.md(70) │ │ 7. Sub-Agent Delegation 偏好 │ │ 8. Provider Overlay (GPT-5 等) │ ├─────────────────────────────────────────────┤ │ ← CACHE BOUNDARY → │ │ (system-prompt-cache-boundary.ts) │ │ SHA256 hash 验证 prefix 稳定性 │ ├─────────────────────────────────────────────┤ │ VOLATILE SUFFIX (每 turn 重建) │ │ │ │ 9. Memory State (MEMORY.md 内容) │ │ 10. User Profile (USER.md) │ │ 11. Inbound Context (channel/chat/user) │ │ 12. Compaction Summary │ │ 13. Timestamp / Session / Model info │ │ 14. Heartbeat Context (HEARTBEAT.md) │ └─────────────────────────────────────────────┘ 关键设计决策: • Stable prefix 使用 LRU 缓存 (上限 64 条)，避免每次 turn 重新构建 • Cache boundary 确保上游 LLM provider 的 prefix cache 命中 • Workspace files 有明确的优先级排序 (CONTEXT_FILE_ORDER Map) • HEARTBEAT.md 是唯一标记为 dynamic 的上下文文件

三、七大注入层

层级	来源	触发时机	内容
1. System Prompt	system-prompt.ts	每 session 构建	身份、工具、安全、技能、上下文文件
2. Tool Definitions	pi-tool-definition-adapter.ts	每 turn	~32,694 字符的 JSON Schema 工具定义
3. Provider Overlay	gpt5-prompt-overlay.ts	特定 provider	GPT-5 等模型的特殊指令覆盖
4. Context Engine	context-engine/*.ts	压缩触发时	上下文压缩策略
5. Memory Flush	plugins/memory-state.ts	每 turn volatile	MEMORY.md + 向量检索结果
6. Inbound Context	channels/plugins/	每条消息	channel, chat_type, sender 信息
7. Compaction Summary	compaction.ts	上下文溢出时	历史对话摘要

四、工具执行管线

Tool Execution Pipeline (策略驱动，多层安全) LLM tool_call ↓ ┌─────────────────┐ │ Tool Policy │ ← tool-policy-pipeline.ts │ (策略匹配) │ path-policy, fs-policy, sender-policy └────────┬────────┘ ↓ allowed ┌─────────────────┐ │ Approval Gate │ ← bash-tools.exec-approval-request.ts │ (审批检查) │ native approvals / chat approvals │ │ suggest / auto-edit / full-auto └────────┬────────┘ ↓ approved ┌─────────────────┐ │ Tool Dispatch │ ← tool-policy-match.ts │ (执行路由) │ sandbox / host / node / gateway │ │ exec-host-node.ts (远程执行) └────────┬────────┘ ↓ executed ┌─────────────────┐ │ Result Guard │ ← session-tool-result-guard.ts │ (结果过滤) │ redaction, sanitization └────────┬────────┘ ↓ 返回给 LLM 安全特性: • Exec 安全层级: deny → allowlist → full • 文件系统策略: workspace-only, path-pattern • 提升权限 (elevated): 需要用户显式 /approve • 沙箱模式: Docker container 隔离 • Node 执行: 远程设备上的受控执行

五、会话管理

Session 生命周期

Session Key: agent:{agentId}:{channel}:{chatType}:{chatId}
会话类型: main / isolated / current / session:{custom-id}
Sub-Agent: spawn → run → announce → cleanup，支持 fork context
Compaction: 分块摘要 + 合并摘要 + 标识符保留策略
Failover: 模型切换 + credential 轮换 + provider 降级

六、150+ 扩展生态系统

扩展分类

类别	数量	代表
Chat Channels	14	Telegram, Discord, WhatsApp, Signal, Slack, iMessage, Feishu, Matrix, IRC, QQ, LINE, Nostr, WeChat, Google Chat
LLM Providers	40+	OpenAI, Anthropic, Google, DeepSeek, Groq, Mistral, Ollama, LMStudio, OpenRouter, Together, Fireworks, Chutes, HuggingFace...
Tools	30+	Browser, File Transfer, Web Search, Voice Call, Image/Video/Music Gen, Document Extract, Canvas...
Skills (内置)	20+	diagram-maker 🧭, spike 🧪, node-inspect-debugger 🪲, browser-automation, github, weather, video-frames, taskflow, find-skills, clawhub...
Memory	4	Memory Core, LanceDB Vector, Wiki, Active Memory
Speech/TTS	5+	ElevenLabs, Deepgram, Azure Speech, SenseAudio, Local CLI

七、OpenClaw vs Hermes: 关键差异

架构对比

维度	OpenClaw	Hermes Agent
语言	TypeScript	Python
核心模式	Event-Driven Gateway	Conversation Loop (AIAgent)
插件系统	编译时扩展 (extensions/)	运行时插件 (plugins/)
提示词缓存	Cache Boundary + LRU	Anthropic prefix cache 继承
自我改进	无 (靠用户配置)	✅ Background Review Fork
Sub-Agent	sessions_spawn + registry	delegate_task + kanban
Compaction	分块摘要 + 标识符保留	ContextCompressor + 可插拔引擎
工具安全	Policy Pipeline + Approval	Guardrails + Approval Callback
Channels	14 (编译时绑定)	30+ (运行时发现)
记忆	MEMORY.md + LanceDB	MEMORY.md + 外部 Provider + Self-improvement

🎯 OpenClaw 对你构建 Agent 的启示：

Cache Boundary 是天才设计 — 把系统提示词拆成 stable/volatile，stable 跨 turn 复用，直接命中 LLM provider 的 prefix cache，节省大量 token 和延迟
Policy Pipeline 是安全最佳实践 — 不靠一个巨型 if-else，而是多个独立 policy 组合成管线，每个关注一个安全维度
Extension 系统 = 编译时插件 — 比运行时插件更安全（类型检查），但灵活性低（需要 rebuild）
缺少自我改进 — 这是 Hermes 的杀手特性，OpenClaw 没有 background review loop
Sub-Agent 架构值得学习 — spawn/steer/kill/yield 四个操作覆盖了子代理的完整生命周期

八、关键源文件

文件	作用	行数
`src/agents/system-prompt.ts`	系统提示词组装核心	~500
`src/agents/compaction.ts`	上下文压缩与摘要	~400
`src/agents/system-prompt-cache-boundary.ts`	Cache boundary 分割点	~50
`src/agents/pi-embedded-runner.ts`	嵌入式 LLM 调用 runner	~600
`src/agents/tool-policy-pipeline.ts`	工具策略管线	~200
`src/agents/subagent-registry.ts`	子代理注册与生命周期	~500
`src/agents/bash-tools.exec.ts`	Shell 执行安全控制	~300
`src/plugins/memory-state.ts`	记忆状态注入	~200
`src/gateway/agent-prompt.ts`	Agent 消息构建	~100