close
OpenClaw Internals
  • 中文

      • OpenClaw 架构总览

      这是顶层地图。所有其他架构文档都从这里分支出去。

      基于 OpenClaw 版本 2026.2.23（commit aceb17a）。

      高层架构

      消息流（入站 → 出站）

      一条从 Telegram 发出的消息到回复的完整链路：

      1. Telegram webhook 投递消息
        ↓
2. extensions/telegram/ 将消息标准化为通用格式
        ↓
3. src/channels/plugins/ — Channel 插件管理器接收消息
        ↓
4. src/routing/resolve-route.ts — 匹配 bindings 找到 agentId + sessionKey
   （匹配优先级：peer → guild+roles → guild → team → account → channel → default）
        ↓
5. src/auto-reply/ — 命令解析（/help, /new, /model）、指令处理
        ↓
6. src/agents/pi-embedded-runner/run.ts — runEmbeddedPiAgent()
   a. 从 JSONL 转录文件加载会话历史
   b. 构建 system prompt（身份 + skills + 工具 + 记忆上下文）
   c. 从配置/覆盖中选择模型 + 提供商
   d. 执行 Pi Agent 循环：LLM → 工具调用 → 执行 → LLM → ...
   e. 通过块回复流水线流式返回文本片段
   f. 将本轮对话追加到会话转录文件
   g. 上下文超限时自动压缩
        ↓
7. src/channels/plugins/outbound/ — 将回复发送到 Telegram API

      模块索引

      每个模块有独立的详细文档。Status 列标识写作进度。

      模块文件关键源码路径状态
      GatewayGatewaysrc/gateway/server.impl.ts, server.ts, server-http.ts完成
      Pi Agent 运行时Pi Agent Runtimesrc/agents/pi-embedded-runner/, pi-embedded.ts完成
      Channel 插件Channel Pluginssrc/channels/plugins/types.plugin.ts, extensions/*/完成
      路由Routingsrc/routing/resolve-route.ts, bindings.ts, session-key.ts完成
      自动回复流水线Auto-Reply Pipelinesrc/auto-reply/reply/agent-runner-execution.ts完成
      工具策略Tool Policysrc/agents/tool-policy-pipeline.ts, tool-policy.ts完成
      Skills 系统Skills Systemsrc/agents/skills/workspace.ts, skills.ts完成
      记忆（RAG）Memory (RAG)src/memory/manager.ts, hybrid.ts, embeddings.ts完成
      会话Sessionssrc/sessions/, src/gateway/session-utils.ts完成
      Cron 与心跳Cron & Heartbeatsrc/cron/service.ts, service/timer.ts, service/jobs.ts完成
      配置系统Config Systemsrc/config/io.ts, types.openclaw.ts, zod-schema.ts完成
      Plugin SDKPlugin SDKsrc/plugin-sdk/index.ts（543 行，18+ 种 adapter 类型）完成
      Control UI（Canvas）Control UI (Canvas)ui/src/ui/app.ts, gateway.ts完成
      原生客户端Native Appsapps/macos/, apps/ios/, apps/android/完成

      跨模块设计模式

      横跨多个模块的复用设计模式。完整列表见 patterns 索引。

      模式文件涉及模块
      Markdown 即配置Markdown-as-ConfigSkills、Memory、Config
      仅追加 JSONLAppend-Only JSONLSessions、Cron
      Ed25519 设备认证Ed25519 Device AuthGateway、Control UI、Native Apps、Pairing
      级联配置解析Cascading ConfigConfig、Tool Policy
      Context Overflow 恢复Context Overflow RecoveryPi Agent Runtime、Compaction

      深入分析

      高影响子系统的代码级 walkthrough。完整列表见 deep-dives 索引。

      主题文件核心源码
      Compaction 内部机制Compaction Internalssrc/agents/compaction.ts（406 行）
      Heartbeat 成本分析Heartbeat Cost Analysissrc/cron/service/timer.ts（877 行）
      Context Budget 分配Context Budget Allocationsrc/agents/pi-embedded-runner/run.ts、defaults.ts

      关键架构决策（源码验证）

      1. 单进程：Gateway（src/gateway/server.impl.ts）在一个 Node.js 进程中运行所有内容 — WebSocket 服务器、HTTP API、Channel 插件、Agent 运行时、Cron。默认端口 18789，Canvas Host 在 端口+1，Browser Control 在 端口+2。

      2. 本地优先持久化：会话以只追加 JSONL 文件存储（~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl）。记忆使用带向量扩展的 SQLite（memory.db）。配置使用支持环境变量替换的 JSON5（openclaw.json）。不依赖云服务。

      3. BYOM（自带模型）：Pi Agent SDK（@mariozechner/pi-agent-core）抽象了 LLM 提供商。支持 Anthropic、OpenAI、Google Gemini、xAI Grok、DeepSeek、Mistral、Ollama 等。可按 agent、按会话或按轮次选择模型。

      4. Markdown 即配置：Skills 是带 YAML frontmatter 的 SKILL.md 文件。记忆笔记是 Markdown。Agent 工作空间文件是 Markdown。全部人类可读、Git 友好、LLM 原生可解析。

      5. 通道无关的插件架构：每个消息平台是一个扩展包（extensions/*/），实现 src/channels/plugins/types.plugin.ts 中的 ChannelPlugin 接口。目前 38 个扩展，每个包含约 15 种 adapter 类型（config、security、outbound、status、gateway、threading 等）。

      6. pnpm workspaces monorepo：根包 + ui/ + extensions/* 作为工作空间成员。通过 tsdown 构建。TypeScript 5.9，Node.js 22+，严格模式。

      源码目录结构

      openclaw/
├── src/                          # 核心源码（48 个子目录）
│   ├── gateway/                  # Gateway 服务器、WebSocket、HTTP、Control UI
│   ├── agents/                   # Pi Agent 运行时、skills、tools、会话、模型
│   ├── channels/                 # Channel 插件基础设施 + 类型
│   ├── routing/                  # 消息路由（bindings → agent + session）
│   ├── auto-reply/               # 入站消息 → agent 轮次流水线
│   ├── config/                   # openclaw.json 加载、验证、schema
│   ├── memory/                   # RAG：SQLite 向量 + FTS5、嵌入、混合搜索
│   ├── sessions/                 # Session key 工具、持久化
│   ├── cron/                     # Cron 服务、心跳、定时任务
│   ├── security/                 # 审计、工具策略、危险工具列表
│   ├── plugins/                  # Plugin SDK 类型、运行时、加载
│   ├── plugin-sdk/               # 面向扩展作者的公开 SDK（544 行 index.ts）
│   ├── hooks/                    # 生命周期钩子系统
│   ├── cli/                      # CLI 接线
│   ├── commands/                 # CLI 命令（gateway、setup、doctor 等）
│   ├── browser/                  # Playwright 浏览器自动化
│   ├── media/                    # 媒体处理流水线
│   ├── media-understanding/      # 图像/视频分析
│   ├── tts/                      # 文本转语音
│   ├── markdown/                 # Markdown 工具
│   ├── infra/                    # 基础设施辅助
│   ├── logging/                  # 日志系统
│   ├── pairing/                  # 设备配对协议
│   ├── process/                  # 进程管理
│   ├── providers/                # LLM 提供商配置
│   ├── shared/                   # 共享工具
│   ├── types/                    # 通用类型定义
│   ├── utils/                    # 通用工具
│   ├── web/                      # Web 服务器辅助
│   ├── wizard/                   # 设置向导
│   ├── telegram/                 # Telegram 特定源码（与扩展共享）
│   ├── discord/                  # Discord 特定源码
│   ├── whatsapp/                 # WhatsApp 特定源码
│   ├── slack/                    # Slack 特定源码
│   ├── signal/                   # Signal 特定源码
│   ├── imessage/                 # iMessage 特定源码
│   ├── line/                     # LINE 特定源码
│   └── ...
│
├── extensions/                   # 38 个扩展包
│   ├── telegram/                 # @openclaw/telegram
│   ├── discord/                  # @openclaw/discord
│   ├── whatsapp/                 # @openclaw/whatsapp
│   ├── slack/                    # @openclaw/slack
│   ├── signal/                   # @openclaw/signal
│   ├── imessage/                 # @openclaw/imessage（通过 BlueBubbles）
│   ├── matrix/                   # @openclaw/matrix
│   ├── msteams/                  # @openclaw/msteams
│   ├── feishu/                   # @openclaw/feishu（飞书）
│   ├── irc/                      # @openclaw/irc
│   ├── nostr/                    # @openclaw/nostr
│   ├── twitch/                   # @openclaw/twitch
│   ├── memory-core/              # 核心记忆扩展
│   ├── memory-lancedb/           # LanceDB 记忆后端
│   ├── voice-call/               # 语音通话支持
│   ├── phone-control/            # 手机自动化
│   ├── llm-task/                 # LLM 任务委托
│   ├── diagnostics-otel/         # OpenTelemetry 诊断
│   └── ...
│
├── skills/                       # 52 个内置 skills（SKILL.md 格式）
│   ├── github/                   # 通过 gh CLI 的 GitHub 操作
│   ├── slack/                    # Slack 通道工具
│   ├── canvas/                   # Canvas 显示操作
│   ├── coding-agent/             # 委托给 Codex/Claude Code
│   ├── obsidian/                 # Obsidian 集成
│   ├── notion/                   # Notion 集成
│   └── ...
│
├── ui/                           # Control UI（Lit + Vite）
│   ├── src/ui/app.ts             # 主 <openclaw-app> 组件
│   ├── src/ui/gateway.ts         # WebSocket 客户端（Ed25519 设备认证）
│   └── vite.config.ts            # 构建输出到 dist/control-ui/
│
├── apps/                         # 原生客户端
│   ├── macos/                    # Swift 6 / SwiftUI，菜单栏应用（macOS 15+）
│   ├── ios/                      # Swift 6 / SwiftUI，XcodeGen（iOS 18+）
│   ├── android/                  # Kotlin / Jetpack Compose（API 31+）
│   └── shared/OpenClawKit/       # 共享 Swift 包
│
├── package.json                  # name: openclaw, version: 2026.2.23
├── pnpm-workspace.yaml           # Monorepo：根 + ui + extensions/*
├── tsconfig.json                 # strict, NodeNext, es2023
└── tsdown.config.ts              # 构建入口点

      配置结构（openclaw.json）

      从 src/config/types.openclaw.ts 和 Zod schema 验证：

      {
  "agents": {
    "defaults": {
      "provider": "anthropic",
      "model": "claude-opus-4-6",
      "thinking": "auto",
      "compaction": { "enabled": true },
      "sandbox": { "tools": { "allow": ["*"], "deny": [] } },
      "skills": { "allowlist": ["*"] }
    },
    "list": [
      { "id": "default", "name": "OpenClaw", "avatar": "🦞" }
    ]
  },
  "channels": {
    "telegram": [{ "accountId": "bot1", "botToken": "${TELEGRAM_BOT_TOKEN}", "dmPolicy": "open" }],
    "discord": [{ "accountId": "bot1", "botToken": "${DISCORD_BOT_TOKEN}", "dmPolicy": "open" }]
  },
  "bindings": [
    { "match": { "channel": "telegram" }, "agentId": "default" }
  ],
  "gateway": { "enabled": true, "port": 18789, "bind": "loopback" },
  "cron": { "enabled": true, "heartbeat": { "enabled": true, "intervalSeconds": 600 } },
  "memory": { "provider": "openai", "model": "text-embedding-3-small", "enabled": true }
}

      我的认知盲区

      诚实记录我尚未理解的部分。随着认知增长持续更新。

      • 工具策略流水线如何组合过滤层？——已解答：7 步级联白名单管道，每步渐进式过滤工具。无显式 deny，不在白名单中的工具即被排除。详见 Tool Policy。
      • 压缩流程如何决定总结/保留？——已解答：BASE_CHUNK_RATIO=0.4 自适应分块，splitMessagesByTokenShare() 按 token 均分消息到 N 个块，最旧的块优先丢弃，repairToolUseResultPairing() 修复裁剪后孤立的 tool_results。详见 Pi Agent Runtime 和 Compaction Internals。
      • 记忆混合搜索权重——已解答：score = vectorWeight * vectorScore + textWeight * textScore，可选 MMR 重排（lambda=0.7：70% 相关性，30% 多样性惩罚，基于 Jaccard 相似度）。详见 Memory (RAG)。
      • 设备配对协议——已解答：Ed25519 挑战-响应，8 位字母数字配对码（排除易混淆的 0O1I），60 分钟 TTL，最多 3 个待处理，设备 ID 由公钥 SHA-256 哈希派生。详见 Native Apps 和 Ed25519 Device Auth。
      • 扩展热重载——已解答：扩展不支持热重载（需要重启 Gateway）。仅配置级的 hooks 和 cron 支持热重载，通过 chokidar 文件监听器实现，300ms 防抖。详见 src/gateway/config-reload.ts。
      • 子 Agent 注册表——已解答：无显式深度限制。通过 rootSessionKey 在 listDescendantRunsForRequester() 中递归查询追踪所有层级。孤儿检测 via resolveSubagentRunOrphanReason()，announce 最多重试 3 次，5 分钟超时。详见 src/agents/subagent-registry.ts（1,081 行）。
      • WebSocket 重连策略——已解答：服务端不主动重连（无状态接受连接）。Web UI（ui/src/ui/gateway.ts）使用指数退避：初始 800ms，倍率 1.7x，上限 15s。iOS 应用仅在切到前台时重试（attemptAutoReconnectIfNeeded()）。详见 WebSocket Disconnects。
      • Config 热重载失败处理——已解答：重载失败时，系统记录错误并跳过更新，旧配置继续驻留内存。无回滚机制。文件缺失时重试 2 次（150ms 间隔）后跳过。无效配置记录校验错误后跳过。详见 src/gateway/config-reload.ts:370-388。
      • JSONL 转录损坏恢复——已解答：双层恢复。文件级：repairSessionFileIfNeeded()（src/agents/session-file-repair.ts）丢弃无法解析的 JSON 行并创建 .bak-{pid}-{timestamp} 备份。转录级：repairToolUseResultPairing() + repairToolCallInputs() + sanitizeToolCallInputs() 修复孤立/重复的 tool results。详见 Session Transcript Corruption。
      • Memory 索引缓存淘汰——maxEntries 配置存在于 src/memory/manager.ts，但未实现任何淘汰/驱逐逻辑。INDEX_CACHE 是无界的 Map，无 LRU、大小检查或 TTL。疑似未实现的功能。
      • 多 Agent 会话键碰撞——会话键是确定性的（agent:{agentId}:{mainKey}，见 src/routing/session-key.ts）。无 UUID 生成、碰撞检测或锁机制。系统依赖外部唯一性（不同的 agent ID + 每 channel 不同的 peer ID）而非内建安全保障。