分析目标版本: OpenClaw 2026.3.14
仓库地址: https://github.com/openclaw/openclaw
官方文档: https://docs.openclaw.ai/zh-CN

---

目录

• 第一部分：项目概述与总体架构
  • 1.1 项目简介
  • 1.2 核心设计理念
  • 1.3 技术栈总览
  • 1.4 项目目录结构
  • 1.5 核心架构图
• 第二部分：启动流程与引导机制
  • 2.1 入口文件 openclaw.mjs
  • 2.2 主入口 src/entry.ts
  • 2.3 公共 API 导出
  • 2.4 运行时环境
  • 2.5 全局状态管理
  • 2.6 版本管理
• 第三部分：CLI 命令行系统
• 第四部分：Gateway 网关服务器
• 第五部分：Agent 智能体系统
• 第六部分：插件系统
• 第七部分：渠道系统
• 第八部分：AI 模型提供商系统
• 第九部分：配置系统
• 第十部分：会话管理
• 第十一部分：自动回复引擎
• 第十二部分：Hook 系统
• 第十三部分：记忆系统
• 第十四部分：ACP 协议
• 第十五部分：定时任务系统
• 第十六部分：浏览器自动化
• 第十七部分：语音系统
• 第十八部分：安全体系
• 第十九部分：Skills 技能系统
• 第二十部分：原生应用
• 第二十一部分：构建与部署
• 第二十二部分：测试体系
• 第二十三部分：Webhook 与自动化
• 第二十四部分：Clawnet 重构规划
• 第二十五部分：全部扩展清单与分析
• 第二十六部分：关键依赖与第三方库

---

第一部分：项目概述与总体架构

1.1 项目简介

OpenClaw 是一个开源的多渠道 AI 网关系统，其核心目标是将大语言模型 (LLM) 的能力无缝接入各种即时通讯平台。该项目采用 TypeScript 编写，运行于 Node.js 22+ 环境，以 MIT 许可证发布。

1.1.1 项目定位

OpenClaw 定位为一个AI Agent Gateway（AI 智能体网关），而非简单的聊天机器人框架。它的核心价值在于：

1. 多渠道统一接入：同时连接 WhatsApp、Telegram、Discord、Slack、Signal、iMessage、飞书、Google Chat、Matrix、Mattermost、IRC、LINE、Nostr、Twitch 等 20+ 即时通讯平台，所有渠道共享同一个 AI 后端
2. 多模型灵活切换：支持 Anthropic (Claude)、OpenAI (GPT)、Google (Gemini)、Mistral、Moonshot、Perplexity、Ollama (本地模型) 等 15+ AI 模型提供商，支持模型故障自动转移
3. 网关化远程控制：通过 WebSocket RPC 协议实现远程管理，支持从 iOS/macOS/Android 原生应用、命令行工具、Web 界面等多种客户端控制网关
4. 插件化高度可扩展：73 个官方扩展 + 52 个内置技能，开发者可通过标准化 Plugin SDK 开发自定义渠道、模型提供商、工具、服务等

1.1.2 项目规模

指标	数量
TypeScript 源文件总数	6,452+
核心源码文件 (src/)	4,752
扩展文件 (extensions/)	1,700
官方扩展数量	73
内置技能数量	52
Plugin SDK 导出入口	250+
原生应用	3 (iOS, macOS, Android)
CLI 命令	50+
源码子目录	52
npm 构建脚本	77

1.1.3 核心数据流

用户消息 (WhatsApp/Telegram/Discord/...)
    │
    ▼
渠道插件 (Channel Plugin)
    │ ── 消息标准化、安全过滤、会话路由
    ▼
Gateway 网关
    │ ── 认证、速率限制、请求分发
    ▼
自动回复引擎 (Auto-Reply Engine)
    │ ── 媒体理解、链接理解、Hook 执行
    ▼
Agent 系统
    │ ── 模型选择、会话管理、工具执行
    ▼
LLM 提供商 (Anthropic/OpenAI/Ollama/...)
    │ ── 推理、流式输出
    ▼
响应处理
    │ ── TTS 转换、消息分块、格式适配
    ▼
渠道插件 (Channel Plugin)
    │ ── 平台特定格式化、发送
    ▼
用户收到回复

1.2 核心设计理念

OpenClaw 的架构设计遵循以下核心原则：

1.2.1 网关中心化 (Gateway-Centric)

整个系统围绕一个中央 Gateway 进程运行。Gateway 是所有功能的汇聚点：

• WebSocket RPC 服务器：提供标准化的远程控制接口
• 渠道管理器：启动/停止各消息平台的连接
• 插件运行时：动态加载/卸载扩展
• 定时任务服务：Cron 调度与心跳检查
• 健康监控：系统状态检查与诊断
• 会话管理：多用户多渠道的会话隔离

这种设计的优势在于：所有渠道共享同一个进程空间，可以高效地共享配置、会话状态、认证凭据等资源，同时通过单一端口对外提供控制面。

1.2.2 插件化架构 (Plugin-First)

OpenClaw 采用彻底的插件化设计，几乎所有功能都以插件形式存在：

• 渠道插件：每个通讯平台是一个独立插件
• 提供商插件：每个 AI 模型提供商是一个独立插件
• 工具插件：Agent 使用的工具以插件注册
• 服务插件：后台服务（如 ACP 运行时、语音通话）以插件注册
• Hook 插件：生命周期事件处理以插件注册

插件通过三种工厂函数注册：definePluginEntry（通用）、defineChannelPluginEntry（渠道）、defineSetupPluginEntry（设置向导），每种工厂函数提供不同层次的抽象。

1.2.3 懒加载与快速启动 (Lazy Loading)

CLI 启动采用两级路由机制：

1. 快速路由 (Fast-path)：高频命令（如 health、status）绕过 Commander 框架直接执行
2. 按需加载：仅加载当前命令需要的模块，避免启动时加载全部 4,752 个文件

这种设计确保 CLI 响应速度在毫秒级别，即使项目代码量庞大。

1.2.4 多层安全模型 (Defense in Depth)

安全设计贯穿所有层次：

• 渠道层：DM 配对/白名单、群组策略、@提及门控
• 网关层：认证令牌、角色授权、速率限制
• Agent 层：工具策略（允许/拒绝）、提权控制
• 执行层：Docker 沙箱隔离、安全正则检查、SSRF 防护
• 配置层：危险配置标志检测、凭据安全存储

1.2.5 协议标准化

系统内部使用多种标准协议：

• JSON-RPC over WebSocket：Gateway 控制面协议
• MCP (Model Context Protocol)：模型上下文协议，用于 Agent 工具交互
• ACP (Agent Control Protocol)：Agent 控制协议，用于沙箱化 Agent 执行
• 各平台原生协议：Discord Gateway、Telegram Bot API、Slack Bolt、Signal Protocol 等

1.3 技术栈总览

类别	技术选型	说明
运行时	Node.js 22+	主运行时，要求 ESM 支持
开发运行时	Bun	用于开发环境加速
编程语言	TypeScript 5.x	严格模式，ES2023 目标
模块系统	ESM (ECMAScript Modules)	全项目统一使用 ESM
包管理器	pnpm	工作区 (workspace) 模式
构建工具	tsdown	TypeScript 专用打包器
测试框架	Vitest	V8 覆盖率，70% 阈值
Web UI 框架	Lit + TailwindCSS	轻量级 Web 组件
iOS/macOS	Swift / SwiftUI	原生应用开发
Android	Kotlin	Gradle 构建系统
WebSocket	ws	高性能 WebSocket 库
HTTP 框架	内置/自定义	轻量级 HTTP 路由
数据库	SQLite	本地持久化存储
向量数据库	LanceDB	记忆系统向量检索
消息广播	Redis (可选)	多实例消息同步
容器化	Docker / docker-compose	部署与沙箱隔离
配置格式	JSON5	支持注释的 JSON 超集
Schema 验证	Zod	运行时类型校验
图像处理	Sharp	高性能图像转换
PDF 解析	pdfjs-dist	PDF 文本提取
浏览器自动化	Playwright	Chromium 控制
Cron 表达式	Croner	时区感知的定时调度
MCP 协议	@modelcontextprotocol/sdk	Agent 工具协议

关键技术决策说明

为什么选择 TypeScript + ESM？
TypeScript 提供了静态类型检查，在 6,452+ 文件的大型代码库中保证了代码质量和重构安全性。ESM 模块系统支持 tree-shaking 和更好的代码分割，配合懒加载策略减少启动时间。

为什么选择 JSON5 而非 YAML/TOML？
JSON5 保持了 JSON 的简洁性，同时支持注释和尾随逗号，降低了用户编辑配置时的错误率。相比 YAML 的缩进敏感性和 TOML 的嵌套表达限制，JSON5 在可读性和灵活性之间取得了平衡。

为什么选择 SQLite 而非 PostgreSQL？
OpenClaw 的定位是单机运行的个人 AI 网关，SQLite 零配置、零依赖的特性完美契合这一场景。对于需要多实例部署的场景，通过可选的 Redis 消息广播来实现协调。

为什么选择 LanceDB？
LanceDB 是嵌入式向量数据库，无需独立进程，与 SQLite 理念一致。它支持 L2 距离计算和高效的 ANN (近似最近邻) 检索，满足记忆系统的向量搜索需求。

1.4 项目目录结构

openclaw/                           # 项目根目录
├── package.json                    # 主 package，版本 2026.3.14
├── pnpm-workspace.yaml             # pnpm 工作区配置
├── tsconfig.json                   # TypeScript 配置（严格模式，ES2023）
├── tsdown.config.ts                # 构建配置
├── vitest.config.ts                # 默认测试配置
├── vitest.e2e.config.ts            # E2E 测试配置
├── vitest.extensions.config.ts     # 扩展测试配置
├── vitest.gateway.config.ts        # 网关测试配置
├── openclaw.mjs                    # CLI 二进制入口（Node 版本检查 + ESM 加载）
├── Dockerfile                      # 主容器镜像
├── Dockerfile.sandbox              # Agent 沙箱镜像
├── Dockerfile.sandbox-browser      # 浏览器沙箱镜像
├── Dockerfile.sandbox-common       # 公共沙箱基础镜像
├── docker-compose.yml              # 服务编排
├── render.yaml                     # Render 平台部署配置
├── .env.example                    # 环境变量示例
├── .oxlintrc.json                  # Oxlint 代码检查
├── .oxfmtrc.jsonc                  # Oxfmt 格式化
├── .pre-commit-config.yaml         # Git 预提交钩子
│
├── src/                            # ===== 核心源码 (4,752 文件) =====
│   ├── entry.ts                    # CLI 主入口
│   ├── index.ts                    # 包根导出
│   ├── library.ts                  # 公共 API 桶文件
│   ├── runtime.ts                  # 运行时环境类型
│   ├── globals.ts                  # 全局状态 (verbose/yes)
│   ├── version.ts                  # 版本解析
│   ├── channel-web.ts              # Web 渠道桥接
│   ├── logging.ts                  # 日志配置
│   ├── logger.ts                   # 日志实例
│   ├── utils.ts                    # 通用工具函数
│   │
│   ├── agents/                     # [923 文件] Agent 智能体运行时
│   │   ├── agent-command.ts        #   核心编排器 (~1300 行)
│   │   ├── agent-scope.ts          #   Agent 身份与作用域
│   │   ├── acp-spawn.ts            #   ACP 会话生成
│   │   ├── cli-runner.ts           #   CLI 后端运行器
│   │   ├── auth-profiles.ts        #   API 密钥轮换与故障转移
│   │   ├── model-selection.ts      #   模型选择逻辑
│   │   ├── model-fallback.ts       #   模型故障转移
│   │   ├── pi-embedded.ts          #   嵌入式 Pi Agent
│   │   ├── subagent-registry.ts    #   子 Agent 注册表
│   │   ├── workspace.ts            #   工作区解析
│   │   ├── skills.ts               #   技能快照
│   │   ├── tools/                  #   Agent 工具定义
│   │   └── sandbox/                #   Docker 沙箱
│   │
│   ├── acp/                        # [55 文件] Agent 控制协议
│   │   ├── policy.ts               #   策略执行
│   │   ├── server.ts               #   ACP 网关服务
│   │   └── translator.ts           #   协议翻译器
│   │
│   ├── auto-reply/                 # [300 文件] 自动回复引擎
│   │   └── reply/
│   │       └── get-reply.ts        #   回复编排主逻辑
│   │
│   ├── browser/                    # [158 文件] 浏览器自动化
│   │   ├── chrome.ts               #   Chrome 管理
│   │   └── cdp.ts                  #   CDP 协议操作
│   │
│   ├── channels/                   # [193 文件] 渠道插件系统
│   │   └── plugins/
│   │       ├── index.ts            #   渠道插件注册表
│   │       ├── registry.ts         #   渠道解析缓存
│   │       └── types.plugin.ts     #   ChannelPlugin 接口定义
│   │
│   ├── cli/                        # [309 文件] CLI 路由与命令
│   │   ├── run-main.ts             #   CLI 主运行器
│   │   ├── route.ts                #   快速路由
│   │   └── program/                #   Commander 程序构建 (~45 文件)
│   │       ├── build-program.ts    #     程序构建
│   │       ├── command-registry.ts #     命令注册表
│   │       ├── routes.ts           #     快速路由定义
│   │       └── register.*.ts       #     各域命令注册器
│   │
│   ├── commands/                   # [366 文件] 命令实现
│   │
│   ├── config/                     # [245 文件] 配置加载与验证
│   │   ├── config.ts               #   配置桶模块
│   │   ├── io.ts                   #   配置 I/O 引擎
│   │   ├── types.ts                #   配置类型 (~37 类型模块)
│   │   ├── validation.ts           #   配置验证
│   │   ├── runtime-overrides.ts    #   运行时覆盖
│   │   ├── paths.ts                #   路径解析
│   │   └── legacy-migrate.ts       #   旧版配置迁移
│   │
│   ├── cron/                       # [110 文件] 定时任务
│   │   ├── schedule.ts             #   调度计算 (croner)
│   │   └── service.ts              #   CronService 类
│   │
│   ├── daemon/                     # [54 文件] 守护进程管理
│   │
│   ├── gateway/                    # [370 文件] WebSocket 网关
│   │   ├── server.ts               #   服务器导出
│   │   ├── server.impl.ts          #   服务器实现 (~120 导入)
│   │   ├── server-methods.ts       #   RPC 方法分发
│   │   ├── client.ts               #   网关客户端
│   │   ├── state.ts                #   网关状态管理
│   │   └── server-methods/         #   RPC 方法处理器 (65+ 文件)
│   │
│   ├── hooks/                      # [45 文件] Hook 事件系统
│   │   ├── types.ts                #   Hook 数据模型
│   │   └── internal-hooks.ts       #   内部 Hook 事件
│   │
│   ├── infra/                      # [494 文件] 基础设施
│   │   ├── ports/                  #   端口管理
│   │   ├── paths/                  #   路径工具
│   │   ├── env/                    #   环境变量
│   │   └── exec/                   #   进程执行
│   │
│   ├── memory/                     # [103 文件] 记忆/知识管理
│   │   └── search-manager.ts       #   记忆搜索 (QMD + 降级)
│   │
│   ├── media/                      # [41 文件] 媒体处理
│   ├── media-understanding/        # [56 文件] 媒体分析
│   │
│   ├── plugin-sdk/                 # [166 文件] 公共 Plugin SDK
│   │   ├── index.ts                #   SDK 主导出
│   │   └── core.ts                 #   插件工厂函数
│   │
│   ├── plugins/                    # [186 文件] 插件注册与运行时
│   │   └── registry.ts             #   PluginRegistry
│   │
│   ├── security/                   # [35 文件] 安全功能
│   │   ├── audit.ts                #   安全审计
│   │   ├── safe-regex.ts           #   安全正则
│   │   ├── skill-scanner.ts        #   技能安全扫描
│   │   └── dangerous-tools.ts      #   危险工具检测
│   │
│   ├── secrets/                    # [51 文件] 凭据管理
│   ├── sessions/                   # [13 文件] 会话管理
│   ├── tts/                        # [12 文件] 文字转语音
│   ├── tui/                        # [47 文件] 终端 UI
│   ├── wizard/                     # [16 文件] 设置向导
│   ├── shared/                     # [74 文件] 共享工具
│   ├── routing/                    # [11 文件] 消息路由
│   ├── process/                    # [28 文件] 进程管理
│   ├── providers/                  # [9 文件] 提供商接口
│   ├── image-generation/           # [11 文件] 图像生成
│   ├── web-search/                 # [2 文件] Web 搜索
│   ├── link-understanding/         # [6 文件] 链接理解
│   ├── context-engine/             # [6 文件] 上下文引擎
│   ├── markdown/                   # [14 文件] Markdown 工具
│   ├── logging/                    # [30 文件] 日志系统
│   ├── terminal/                   # [19 文件] 终端操作
│   ├── pairing/                    # [9 文件] 设备配对
│   ├── node-host/                  # [16 文件] 节点运行时
│   ├── canvas-host/                # [5 文件] Canvas/A2UI
│   ├── types/                      # [8 文件] 共享类型
│   ├── interactive/                # [2 文件] 交互模式
│   ├── scripts/                    # [2 文件] 构建脚本
│   ├── bindings/                   # [1 文件] 原生绑定
│   ├── compat/                     # [1 文件] 兼容层
│   ├── docs/                       # [1 文件] 嵌入文档
│   ├── i18n/                       # [1 文件] 国际化
│   └── test-utils/                 # [34 文件] 测试工具
│
├── extensions/                     # ===== 插件扩展 (73 个, 1,700 文件) =====
│   ├── discord/                    # [201 文件] Discord
│   ├── telegram/                   # [166 文件] Telegram
│   ├── slack/                      # [144 文件] Slack
│   ├── feishu/                     # [113 文件] 飞书
│   ├── whatsapp/                   # [100 文件] WhatsApp
│   ├── matrix/                     # [98 文件] Matrix
│   ├── msteams/                    # [85 文件] Microsoft Teams
│   ├── voice-call/                 # [65 文件] 语音通话
│   ├── mattermost/                 # [57 文件] Mattermost
│   ├── bluebubbles/                # [51 文件] BlueBubbles
│   ├── signal/                     # [48 文件] Signal
│   ├── imessage/                   # [47 文件] iMessage
│   ├── zalouser/                   # [44 文件] Zalo (用户)
│   ├── tlon/                       # [41 文件] Tlon
│   ├── nextcloud-talk/             # [36 文件] Nextcloud Talk
│   ├── zalo/                       # [34 文件] Zalo
│   ├── twitch/                     # [33 文件] Twitch
│   ├── irc/                        # [31 文件] IRC
│   ├── googlechat/                 # [29 文件] Google Chat
│   ├── nostr/                      # [29 文件] Nostr
│   ├── diffs/                      # [25 文件] Diff 处理
│   ├── acpx/                       # [22 文件] ACP 运行时
│   ├── synology-chat/              # [20 文件] Synology Chat
│   ├── line/                       # [13 文件] LINE
│   ├── google/                     # [12 文件] Google AI
│   ├── openshell/                  # [12 文件] OpenShell
│   ├── openai/                     # [7 文件] OpenAI
│   ├── firecrawl/                  # [7 文件] Firecrawl
│   ├── lobster/                    # [6 文件] Lobster 工作流
│   ├── minimax/                    # [6 文件] MiniMax
│   ├── github-copilot/             # [5 文件] GitHub Copilot
│   ├── zai/                        # [5 文件] Z.AI
│   ├── memory-lancedb/             # [4 文件] LanceDB 记忆
│   ├── mistral/                    # [4 文件] Mistral
│   ├── moonshot/                   # [4 文件] Moonshot
│   ├── modelstudio/                # [4 文件] ModelStudio
│   ├── llm-task/                   # [4 文件] LLM Task
│   ├── diagnostics-otel/           # [4 文件] OpenTelemetry
│   ├── anthropic/                  # [2 文件] Anthropic
│   ├── shared/                     # [8 文件] 共享扩展工具
│   └── [33 更多扩展...]            # 其他扩展
│
├── skills/                         # ===== 技能 (52 个) =====
│   ├── coding-agent/               # 编码 Agent
│   ├── github/                     # GitHub 操作
│   ├── slack/                      # Slack 操作
│   ├── weather/                    # 天气查询
│   ├── 1password/                  # 密码管理
│   ├── apple-notes/                # Apple 备忘录
│   ├── notion/                     # Notion
│   ├── obsidian/                   # Obsidian
│   ├── spotify-player/             # Spotify 播放器
│   ├── tmux/                       # Tmux 管理
│   └── [42 更多技能...]            # 其他技能
│
├── apps/                           # ===== 原生应用 =====
│   ├── ios/                        # iOS 应用 (Swift/SwiftUI)
│   │   ├── Sources/                #   源代码
│   │   ├── ActivityWidget/         #   桌面小组件
│   │   ├── ShareExtension/         #   分享扩展
│   │   ├── WatchApp/               #   Apple Watch 应用
│   │   └── fastlane/               #   TestFlight 自动化
│   ├── macos/                      # macOS 应用 (Swift/SwiftUI)
│   │   └── Sources/                #   源代码
│   ├── android/                    # Android 应用 (Kotlin)
│   │   ├── app/                    #   主模块
│   │   ├── benchmark/              #   性能基准测试
│   │   └── gradle/                 #   构建配置
│   └── shared/                     # 共享框架
│       └── OpenClawKit/            #   iOS/macOS 共享 Swift 框架
│
├── Swabble/                        # ===== Swift CLI 框架 =====
│   ├── Sources/
│   │   ├── SwabbleCore/            #   核心功能
│   │   ├── SwabbleKit/             #   公共 API
│   │   └── swabble/                #   CLI 工具
│   └── Tests/                      #   测试
│
├── ui/                             # Web UI 组件 (Lit + TailwindCSS)
├── docs/                           # 文档 (Mintlify)
│   ├── zh-CN/                      #   中文文档
│   ├── ja-JP/                      #   日文文档
│   └── .generated/                 #   自动生成文档
├── test/                           # 测试夹具
├── vendor/                         # 第三方依赖
├── changelog/                      # 变更日志
└── assets/                         # 静态资源

1.5 核心架构图

┌─────────────────────────────────────────────────────────────────────┐
│                        OpenClaw 系统架构                            │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                │
│  │  iOS App    │  │  macOS App  │  │  Android    │  原生客户端     │
│  │  (SwiftUI)  │  │  (SwiftUI)  │  │  (Kotlin)   │                │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘                │
│         │                │                 │                        │
│         └───────────┬────┴────────────────┘                        │
│                     │ WebSocket JSON-RPC                            │
│  ┌──────────────────▼──────────────────────────────────────────┐   │
│  │                    Gateway 网关服务器                         │   │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │   │
│  │  │ WS RPC   │ │ 认证授权  │ │ 速率限制 │ │ 健康监控  │       │   │
│  │  │ Server   │ │ Auth     │ │ Rate     │ │ Health   │       │   │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │   │
│  │  ┌──────────────────────────────────────────────────┐       │   │
│  │  │              Plugin Runtime 插件运行时             │       │   │
│  │  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐    │       │   │
│  │  │  │Channels│ │Provider│ │ Tools  │ │Services│    │       │   │
│  │  │  │渠道插件 │ │模型提供 │ │工具插件 │ │服务插件 │    │       │   │
│  │  │  └────────┘ └────────┘ └────────┘ └────────┘    │       │   │
│  │  └──────────────────────────────────────────────────┘       │   │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │   │
│  │  │ Sessions │ │  Cron    │ │  Hooks   │ │ Secrets  │       │   │
│  │  │ 会话管理  │ │ 定时任务 │ │ 事件钩子 │ │ 凭据管理 │       │   │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │   │
│  └─────────────────────────────────────────────────────────────┘   │
│         │                                      │                    │
│    ┌────▼────────────────────┐    ┌────────────▼──────────┐        │
│    │   Auto-Reply Engine     │    │   Agent System        │        │
│    │   自动回复引擎           │    │   智能体系统           │        │
│    │  ┌────────────────┐     │    │  ┌─────────────────┐  │        │
│    │  │ 媒体理解        │     │    │  │ 模型选择/故障转移│  │        │
│    │  │ 链接理解        │     │    │  │ 会话管理        │  │        │
│    │  │ Hook 执行       │     │    │  │ 工具执行        │  │        │
│    │  │ 指令解析        │     │    │  │ 沙箱隔离        │  │        │
│    │  └────────────────┘     │    │  │ 记忆系统        │  │        │
│    └─────────────────────────┘    │  └─────────────────┘  │        │
│                                    └──────────┬───────────┘        │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                   渠道层 (Channel Layer)                      │   │
│  │  ┌────┐┌────┐┌────┐┌────┐┌────┐┌────┐┌────┐┌────┐         │   │
│  │  │ WA ││ TG ││ DC ││ SK ││ SG ││ iM ││ FS ││ GC │  ...    │   │
│  │  └────┘└────┘└────┘└────┘└────┘└────┘└────┘└────┘         │   │
│  └─────────────────────────────────────────────────────────────┘   │
│         │                                      │                    │
│    ┌────▼────────────────────┐    ┌────────────▼──────────┐        │
│    │   LLM Provider Layer    │    │   Memory System       │        │
│    │   模型提供商层           │    │   记忆系统             │        │
│    │  ┌─────┐ ┌─────┐       │    │  ┌─────────────────┐  │        │
│    │  │Anthr│ │OpenAI│      │    │  │ LanceDB 向量DB   │  │        │
│    │  │opic │ │     │       │    │  │ QMD 量子记忆DB   │  │        │
│    │  └─────┘ └─────┘       │    │  │ SQLite 持久化    │  │        │
│    │  ┌─────┐ ┌─────┐       │    │  └─────────────────┘  │        │
│    │  │Ollam│ │Googl│       │    └───────────────────────┘        │
│    │  │a    │ │e    │       │                                      │
│    │  └─────┘ └─────┘       │                                      │
│    └─────────────────────────┘                                     │
│                                                                     │
│  WA=WhatsApp TG=Telegram DC=Discord SK=Slack SG=Signal             │
│  iM=iMessage FS=飞书 GC=Google Chat                                │
└─────────────────────────────────────────────────────────────────────┘

架构层次说明

第一层：客户端层

• iOS/macOS/Android 原生应用通过 WebSocket 连接到 Gateway
• CLI 工具通过同一协议连接
• WebChat 组件提供 Web 端接入

第二层：Gateway 网关层

• 所有控制面操作的统一入口
• 管理所有子系统的生命周期
• 提供 65+ RPC 方法

第三层：引擎层

• 自动回复引擎：消息预处理和 Agent 调度
• Agent 系统：LLM 交互的核心运行时

第四层：渠道层

• 20+ 通讯平台的适配器
• 每个渠道独立的消息监听、发送、健康检查

第五层：基础服务层

• LLM 提供商抽象
• 向量记忆存储
• 凭据安全管理

---

第二部分：启动流程与引导机制

2.1 入口文件 openclaw.mjs

openclaw.mjs 是整个项目的 CLI 二进制入口文件，也是 package.json 中 bin 字段指定的可执行文件。该文件在安装时被链接到全局 PATH，用户通过 openclaw 命令启动。

核心职责

1. Node.js 版本检查：确保运行环境为 Node.js 22+，这是 ESM 原生支持和其他现代特性（如 --disable-warning 标志）的最低要求
2. ESM 模块加载：作为 .mjs 文件，直接以 ESM 模式运行，无需 --experimental-modules 标志
3. 委托执行：加载编译后的 dist/entry.js 并执行

设计原理

选择 .mjs 扩展名而非 package.json 中的 "type": "module" 是因为：

• .mjs 文件无论 package.json 如何配置都以 ESM 模式运行
• 避免了与某些工具链的兼容性问题
• 作为二进制入口，需要明确的模块类型声明

#!/usr/bin/env node

// 版本检查
const [major] = process.versions.node.split('.').map(Number);
if (major < 22) {
  console.error(`OpenClaw requires Node.js 22 or later. Current: ${process.version}`);
  process.exit(1);
}

// 加载编译后的入口
await import('./dist/entry.js');

2.2 主入口 src/entry.ts

src/entry.ts 是实际的应用入口（约 150 行），编译后输出为 dist/entry.js。它执行一系列初始化步骤：

2.2.1 重复执行防护

import { isMainModule } from './infra/is-main-module.js';

// 当 OpenClaw 作为共享依赖被 bundle 时，防止重复执行
if (!isMainModule()) {
  // 不是主模块，静默退出
  process.exit(0);
}

isMainModule() 检查当前文件是否为进程的主入口模块。在某些打包场景下（如被其他 CLI 工具间接引用），可能会意外执行此文件，此防护确保只有直接运行时才继续。

2.2.2 全局初始化

// 1. 安装 Gaxios fetch 兼容层
//    Gaxios 是 Google API 客户端使用的 HTTP 库
//    需要确保 global fetch 存在（Node.js 22 原生支持）
installGaxiosFetchCompat();

// 2. 设置进程标题
//    在 ps、top 等工具中显示为 "openclaw" 而非 "node"
process.title = 'openclaw';

// 3. 安装警告过滤器
//    抑制 Node.js 实验性功能警告
installWarningFilters();

// 4. 规范化环境变量
//    处理 Windows/macOS/Linux 差异
normalizeEnvVars();

2.2.3 实验性警告处理

Node.js 对某些 API（如 fetch、WebSocket）会输出实验性警告。OpenClaw 通过检测和重生进程来彻底消除这些警告：

// 如果当前进程没有 --disable-warning 标志
if (!process.execArgv.includes('--disable-warning=ExperimentalWarning')) {
  // 用新标志重新启动进程
  const args = [...process.execArgv, '--disable-warning=ExperimentalWarning', ...process.argv.slice(1)];
  const child = spawn(process.execPath, args, {
    stdio: 'inherit',
    env: process.env,
  });
  child.on('exit', (code) => process.exit(code ?? 1));
  return; // 当前进程不再继续
}

这种"重生"策略虽然会增加几毫秒的启动开销，但确保了用户不会被无关警告干扰。

2.2.4 快速路径优化

对于最常用的简单查询命令，直接处理而不加载完整 CLI 框架：

// --version 快速路径
if (argv.includes('--version') || argv.includes('-v')) {
  const version = resolveVersion();
  console.log(version);
  process.exit(0);
}

// --help 快速路径
if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
  await printRootHelp();
  process.exit(0);
}

2.2.5 CLI Profile 支持

// --profile <name> 支持多配置文件运行
const profileIndex = argv.indexOf('--profile');
if (profileIndex !== -1 && argv[profileIndex + 1]) {
  const profileName = argv[profileIndex + 1];
  // 设置环境变量，后续配置加载会使用此 profile
  process.env.OPENCLAW_PROFILE = profileName;
  // 从 argv 中移除 --profile 参数
  argv.splice(profileIndex, 2);
}

Profile 机制允许同一台机器上运行多个 OpenClaw 实例，每个使用不同的配置文件。

2.2.6 委托到 CLI 主运行器

// 所有初始化完成后，委托到 CLI 系统
import { runCli } from './cli/run-main.js';
await runCli(argv);

2.3 公共 API 导出 src/library.ts

src/library.ts 是 OpenClaw 作为 npm 包被其他项目引用时的公共 API 表面（约 48 行）。它从各个内部模块中精选并重新导出稳定的 API：

// 配置管理
export { loadConfig } from './config/io.js';
export { parseConfigJson5 } from './config/io.js';

// 依赖注入
export { createDefaultDeps } from './infra/deps.js';

// 会话管理
export { loadSessionStore, saveSessionStore } from './sessions/store.js';

// 回复引擎
export { getReplyFromConfig } from './auto-reply/reply/get-reply.js';

// 基础设施
export { ensurePortAvailable } from './infra/ports/ensure.js';
export { runExec } from './infra/exec/run.js';
export { ensureBinary } from './infra/exec/ensure-binary.js';

// Web 渠道
export { monitorWebChannel } from './channel-web.js';

// 交互工具
export { promptYesNo } from './interactive/prompt.js';

// 进程管理
export { waitForever } from './infra/wait.js';

// ... 30+ 更多导出

设计原则

• 稳定性：只导出不太可能发生破坏性变更的 API
• 最小表面：不导出内部实现细节
• 隔离性：消费者不需要了解内部模块结构
• 向后兼容：通过 src/index.ts 的 runLegacyCliEntry() 保持旧版 API 兼容

2.4 运行时环境 src/runtime.ts

src/runtime.ts 定义了运行时环境抽象，这是 OpenClaw 依赖注入模式的基石：

/**
 * RuntimeEnv 抽象了进程级别的 I/O 操作
 * 使核心逻辑可以在不同上下文中运行（CLI、嵌入、测试）
 */
export type RuntimeEnv = {
  /** 标准输出 */
  log: (msg: string) => void;
  /** 错误输出 */
  error: (msg: string) => void;
  /** 进程退出 */
  exit: (code: number) => never;
};

默认运行时

export const defaultRuntime: RuntimeEnv = {
  log: (msg: string) => {
    // 清除当前进度行（如果有的话），然后输出
    clearProgressLine();
    console.log(msg);
  },
  error: (msg: string) => {
    clearProgressLine();
    console.error(msg);
  },
  exit: (code: number) => {
    // 退出前恢复终端状态
    restoreTerminalState();
    process.exit(code);
  },
};

非退出运行时（测试/嵌入用）

export function createNonExitingRuntime(): RuntimeEnv {
  return {
    log: defaultRuntime.log,
    error: defaultRuntime.error,
    exit: (code: number) => {
      // 抛出异常而非退出进程
      throw new ExitError(code);
    },
  };
}

这个运行时抽象在测试中非常重要：测试不希望调用 process.exit() 终止 Vitest 进程。在嵌入式场景中（如 OpenClaw 作为库被其他应用引用），也不应该直接退出宿主进程。

Vitest 集成

// 在 Vitest 运行期间抑制日志输出，除非显式启用
if (isVitestRun() && !process.env.OPENCLAW_TEST_LOG) {
  defaultRuntime.log = () => {};
  defaultRuntime.error = () => {};
}

2.5 全局状态管理 src/globals.ts

src/globals.ts 管理模块级别的全局状态，主要是 CLI 标志：

// 全局 verbose 标志
let _verbose = false;

export function setGlobalVerbose(value: boolean): void {
  _verbose = value;
}

export function getGlobalVerbose(): boolean {
  return _verbose;
}

// 全局 --yes 标志（跳过所有确认提示）
let _yes = false;

export function setGlobalYes(value: boolean): void {
  _yes = value;
}

export function getGlobalYes(): boolean {
  return _yes;
}

日志工具

/**
 * 同时写入结构化日志（debug 级别）和控制台
 * 仅在 verbose 模式下生效
 */
export function logVerbose(msg: string): void {
  if (_verbose) {
    logger.debug(msg);
    console.log(msg);
  }
}

/**
 * 判断是否应该输出 verbose 日志
 * 条件：verbose 标志开启 OR 文件日志级别设为 debug
 */
export function shouldLogVerbose(): boolean {
  return _verbose || getFileLogLevel() === 'debug';
}

主题化格式器

import chalk from 'chalk';

export const success = chalk.green;
export const warn = chalk.yellow;
export const info = chalk.blue;
export const danger = chalk.red;

这些格式器在整个 CLI 输出中保持一致的颜色主题。

2.6 版本管理 src/version.ts

src/version.ts 实现了多级回退的版本解析链（129 行）：

/**
 * 版本解析优先级（从高到低）：
 * 1. 构建时注入的 __OPENCLAW_VERSION__ 常量
 * 2. package.json 的 version 字段
 * 3. build-info.json 文件
 * 4. OPENCLAW_BUNDLED_VERSION 环境变量
 * 5. 回退值 "0.0.0"
 */
export function resolveVersion(): string {
  // 1. 构建时定义（tsdown 注入）
  if (typeof __OPENCLAW_VERSION__ !== 'undefined') {
    return __OPENCLAW_VERSION__;
  }

  // 2. 从 package.json 读取
  try {
    const pkg = findClosestPackageJson('openclaw');
    if (pkg?.version) return pkg.version;
  } catch {}

  // 3. 从 build-info.json 读取
  try {
    const info = readBuildInfo();
    if (info?.version) return info.version;
  } catch {}

  // 4. 环境变量
  if (process.env.OPENCLAW_BUNDLED_VERSION) {
    return process.env.OPENCLAW_BUNDLED_VERSION;
  }

  // 5. 回退
  return '0.0.0';
}

服务版本解析

用于 Gateway 运行时报告版本：

/**
 * 解析运行时服务版本
 * 优先级：OPENCLAW_VERSION env > resolveVersion() > OPENCLAW_SERVICE_VERSION > npm_package_version
 */
export function resolveRuntimeServiceVersion(): string {
  return (
    process.env.OPENCLAW_VERSION ??
    resolveVersion() ??
    process.env.OPENCLAW_SERVICE_VERSION ??
    process.env.npm_package_version ??
    '0.0.0'
  );
}

这种多级回退设计确保了在各种部署场景（npm 全局安装、Docker 容器、源码运行、嵌入式使用）下都能正确获取版本号。

---

第三部分：CLI 命令行系统

3.1 CLI 架构概述

OpenClaw 的 CLI 系统采用双层路由架构，在保持功能完整性的同时优化了启动性能：

用户输入 `openclaw <command> [args]`
    │
    ▼
src/entry.ts (快速路径: --version, --help)
    │
    ▼
src/cli/run-main.ts::runCli()
    │
    ├─── 快速路由 (tryRouteCli)
    │    └── 直接执行高频命令
    │
    └─── Commander 路由 (buildProgram)
         └── 完整命令体系

快速路由 vs Commander

特性	快速路由	Commander
启动开销	极低（仅加载必需模块）	较高（需构建完整命令树）
覆盖命令	~10 个高频命令	全部 50+ 命令
参数解析	手动 argv 解析	Commander 内置解析
适用场景	health、status 等简单查询	agent run、gateway 等复杂命令

3.2 主运行器 src/cli/run-main.ts

runCli(argv) 是 CLI 系统的核心函数，执行完整的启动流程：

export async function runCli(argv: string[]): Promise<void> {
  // 1. Windows argv 规范化
  //    Windows 下 process.argv 可能包含不同的路径格式
  argv = normalizeWindowsArgv(argv);

  // 2. 解析 CLI Profile
  //    支持 --profile <name> 多实例配置
  const profile = extractProfile(argv);

  // 3. 加载环境变量
  //    按优先级: process env > CWD .env > global .env > config env 块
  await loadDotEnv(profile);

  // 4. 规范化环境变量
  //    统一 Windows/macOS/Linux 差异
  normalizeEnv();

  // 5. 确保 openclaw 在 PATH 上
  //    某些操作需要 openclaw 命令可被子进程找到
  ensureOnPath();

  // 6. 断言最低运行时版本
  assertMinimumRuntimeVersion();

  // 7. 尝试快速路由（跳过 Commander）
  const routed = await tryRouteCli(argv, profile);
  if (routed) return; // 快速路由已处理

  // 8. 构建完整 Commander 程序
  const program = buildProgram();

  // 9. 识别主命令名称
  const primaryCommand = identifyPrimaryCommand(argv);

  // 10. 懒加载：仅注册当前命令
  await registerCoreCliByName(program, primaryCommand);
  await registerSubCliByName(program, primaryCommand);

  // 11. 注册插件 CLI 命令
  //     如果主命令不是内置的，尝试从插件中查找
  if (!isBuiltinCommand(primaryCommand)) {
    await registerPluginCli(program, primaryCommand);
  }

  // 12. 执行命令
  await program.parseAsync(argv, { from: 'user' });

  // 13. 清理
  await cleanupMemoryManagers();
}

关键设计点

懒加载策略：不会在启动时注册所有 50+ 命令。identifyPrimaryCommand 从 argv 中提取命令名称，然后 registerCoreCliByName 仅注册该命令及其子命令。这避免了加载不需要的模块。

插件 CLI 扩展：插件可以注册自己的 CLI 子命令。如果用户输入的命令不是内置命令，系统会查找已注册的插件命令。

内存管理：退出前调用 cleanupMemoryManagers() 确保向量数据库连接、会话存储等资源被正确释放。

3.3 快速路由 src/cli/route.ts

src/cli/route.ts 实现了快速路由机制，用于绕过 Commander 框架直接执行高频命令：

export async function tryRouteCli(argv: string[], profile?: string): Promise<boolean> {
  // 可通过环境变量禁用快速路由（调试用）
  if (process.env.OPENCLAW_DISABLE_ROUTE_FIRST === '1') {
    return false;
  }

  // 查找匹配的路由
  const match = findRoutedCommand(argv);
  if (!match) return false;

  // 准备配置
  const config = await prepareConfigForRoute(profile);

  // 显示 banner（如果适用）
  emitBanner(match);

  // 可选加载插件
  if (match.route.needsPlugins) {
    await loadPluginsForRoute(config);
  }

  // 直接执行路由处理器
  await match.route.handler(match.parsedArgs, config);

  return true;
}

路由定义

src/cli/program/routes.ts 定义了快速路由表：

export interface RouteSpec {
  /** 命令路径，如 ['health'] 或 ['gateway', 'status'] */
  path: string[];
  /** 是否需要加载插件 */
  needsPlugins?: boolean;
  /** 处理器函数 */
  handler: (args: ParsedArgs, config: Config) => Promise<void>;
  /** 参数定义 */
  flags?: FlagDef[];
}

export const routes: RouteSpec[] = [
  {
    path: ['health'],
    handler: async (args, config) => {
      const { healthCommand } = await import('../../commands/health.js');
      await healthCommand(config, args);
    },
  },
  {
    path: ['status'],
    handler: async (args, config) => {
      const { statusCommand } = await import('../../commands/status.js');
      await statusCommand(config, args);
    },
  },
  {
    path: ['gateway', 'status'],
    handler: async (args, config) => {
      const { gatewayStatusCommand } = await import('../../commands/gateway-status.js');
      await gatewayStatusCommand(config, args);
    },
  },
  {
    path: ['sessions'],
    handler: async (args, config) => {
      const { sessionsCommand } = await import('../../commands/sessions.js');
      await sessionsCommand(config, args);
    },
  },
  {
    path: ['agents', 'list'],
    handler: async (args, config) => {
      const { agentsListCommand } = await import('../../commands/agents-list.js');
      await agentsListCommand(config, args);
    },
  },
  // ... 更多快速路由
];

匹配算法：findRoutedCommand 将 argv 与路由的 path 进行前缀匹配，支持多级命令（如 gateway status）。

3.4 Commander 程序构建

src/cli/program/build-program.ts 构建完整的 Commander 程序：

import { Command } from 'commander';

export function buildProgram(): Command {
  const program = new Command('openclaw');
  program
    .description('Multi-channel AI gateway')
    .option('-v, --verbose', 'Enable verbose output')
    .option('-y, --yes', 'Skip confirmation prompts')
    .option('--profile <name>', 'Use named config profile')
    .allowUnknownOption(true) // 允许插件命令的未知选项
    .helpOption('-h, --help', 'Show help');

  // 设置全局选项处理
  program.hook('preAction', (thisCommand) => {
    const opts = thisCommand.opts();
    if (opts.verbose) setGlobalVerbose(true);
    if (opts.yes) setGlobalYes(true);
  });

  return program;
}

3.5 命令注册机制

src/cli/program/command-registry.ts 实现了按需加载的命令注册：

/**
 * 命令注册器映射
 * key: 命令名称
 * value: 异步注册函数（懒加载对应模块）
 */
const coreRegistrars: Record<string, (program: Command) => Promise<void>> = {
  agent: async (p) => {
    const { registerAgentCli } = await import('./register.agent.js');
    registerAgentCli(p);
  },
  gateway: async (p) => {
    const { registerGatewayCli } = await import('./register.gateway.js');
    registerGatewayCli(p);
  },
  setup: async (p) => {
    const { registerSetupCli } = await import('./register.setup.js');
    registerSetupCli(p);
  },
  configure: async (p) => {
    const { registerConfigureCli } = await import('./register.configure.js');
    registerConfigureCli(p);
  },
  onboard: async (p) => {
    const { registerOnboardCli } = await import('./register.onboard.js');
    registerOnboardCli(p);
  },
  // ... 更多注册器
};

export async function registerCoreCliByName(
  program: Command,
  name: string
): Promise<boolean> {
  const registrar = coreRegistrars[name];
  if (!registrar) return false;
  await registrar(program);
  return true;
}

各域命令注册器文件

文件	注册的命令
register.agent.ts	agent run, agent list, agent config, agent cancel
register.gateway.ts	gateway start, gateway stop, gateway status, gateway restart
register.setup.ts	setup, setup wizard, setup model
register.configure.ts	configure, configure get, configure set
register.onboard.ts	onboard, onboard channel, onboard provider
register.message.ts	message send, message history
register.status-health-sessions.ts	status, health, sessions
register.maintenance.ts	doctor, audit, update, backup
register.subclis.ts	browser, cron, devices, hooks, skills, tts

配置守卫

config-guard.ts 确保需要配置的命令在配置就绪后才执行：

export function withConfigGuard(
  handler: (config: Config, ...args: any[]) => Promise<void>
): (...args: any[]) => Promise<void> {
  return async (...args) => {
    const config = await ensureConfigReady();
    if (!config) {
      console.error('Configuration not initialized. Run: openclaw setup');
      process.exit(1);
    }
    await handler(config, ...args);
  };
}

3.6 核心命令详解

以下是核心 CLI 命令的功能说明：

网关管理

• openclaw gateway start — 启动 Gateway 网关服务器（主命令）
• openclaw gateway stop — 停止运行中的网关
• openclaw gateway status — 查看网关状态（端口、连接数、渠道状态）
• openclaw gateway restart — 重启网关

Agent 操作

• openclaw agent run <prompt> — 运行一次性 Agent 任务
• openclaw agent list — 列出已配置的 Agent
• openclaw agent config <id> — 查看/修改 Agent 配置
• openclaw agent cancel <runId> — 取消运行中的 Agent 任务

配置管理

• openclaw configure — 交互式配置编辑
• openclaw configure get <path> — 获取配置值
• openclaw configure set <path> <value> — 设置配置值

初始化设置

• openclaw setup — 初始化 OpenClaw（创建配置文件）
• openclaw setup wizard — 交互式设置向导
• openclaw onboard <channel> — 配置渠道连接
• openclaw onboard <provider> — 配置模型提供商

系统运维

• openclaw health — 健康检查
• openclaw status — 系统概况
• openclaw sessions — 会话列表
• openclaw doctor — 诊断问题
• openclaw audit — 安全审计
• openclaw update — 检查/执行更新
• openclaw backup — 配置备份

子系统管理

• openclaw browser launch — 启动托管浏览器
• openclaw cron list/add/remove — 定时任务管理
• openclaw devices list/pair — 设备管理
• openclaw hooks list/install — Hook 管理
• openclaw skills list/install/uninstall — 技能管理
• openclaw tts speak <text> — 文字转语音
• openclaw dns — DNS 诊断

---

第四部分：Gateway 网关服务器

4.1 网关架构概述

Gateway 是 OpenClaw 的核心进程，所有功能围绕它运行。它是一个长期运行的 WebSocket RPC 服务器，同时管理所有渠道连接、插件运行时、定时任务和安全策略。

              ┌─────────────────────────────────────────┐
              │          Gateway 进程                     │
              │                                          │
              │  ┌──────────────────────────────────┐    │
              │  │     WebSocket RPC Server          │    │
              │  │     (端口 3000, 可配置)            │    │
              │  └──────────┬───────────────────────┘    │
              │             │                            │
              │  ┌──────────▼───────────────────────┐    │
              │  │  Request Dispatcher               │    │
              │  │  25+ 处理器模块, 65+ RPC 方法      │    │
              │  └──────────┬───────────────────────┘    │
              │             │                            │
              │  ┌──────────▼───────────────────────┐    │
              │  │  子系统管理器                       │    │
              │  │  ┌────────┐ ┌────────┐ ┌────────┐ │    │
              │  │  │Channels│ │Plugins │ │Sessions│ │    │
              │  │  ├────────┤ ├────────┤ ├────────┤ │    │
              │  │  │  Cron  │ │ Hooks  │ │Secrets │ │    │
              │  │  ├────────┤ ├────────┤ ├────────┤ │    │
              │  │  │Browser │ │ Health │ │  TTS   │ │    │
              │  │  ├────────┤ ├────────┤ ├────────┤ │    │
              │  │  │Discov. │ │ Nodes  │ │ Canvas │ │    │
              │  │  └────────┘ └────────┘ └────────┘ │    │
              │  └──────────────────────────────────┘    │
              └─────────────────────────────────────────┘

Gateway 的设计理念是单进程多功能：一个 Gateway 进程即可满足个人用户的全部需求，同时通过 WebSocket 接口支持远程管理。

4.2 服务器实现 src/gateway/server.impl.ts

src/gateway/server.impl.ts 是整个系统最复杂的文件之一，包含约 120+ 个 import 语句，从几乎所有子系统中引入依赖。

4.2.1 服务器选项

export interface GatewayServerOptions {
  /** 绑定模式 */
  bind: 'loopback' | 'lan' | 'tailnet' | 'auto';
  /** 监听端口 (默认 3000) */
  port?: number;
  /** TLS 证书路径 */
  tls?: { cert: string; key: string };
  /** 配置对象 */
  config: OpenClawConfig;
  /** 运行时环境 */
  runtime: RuntimeEnv;
}

export interface GatewayServer {
  /** 关闭网关 */
  close: (reason?: string) => Promise<void>;
  /** 服务器地址信息 */
  address: { host: string; port: number };
  /** 是否正在运行 */
  running: boolean;
}

4.2.2 启动流程

startGatewayServer() 的启动流程按顺序执行以下步骤：

export async function startGatewayServer(
  options: GatewayServerOptions
): Promise<GatewayServer> {
  const { config, runtime, bind, port } = options;

  // ===== 阶段 1: 基础设施初始化 =====

  // 1.1 创建子系统日志器
  const loggers = {
    gateway: createLogger('gateway'),
    canvas: createLogger('canvas'),
    discovery: createLogger('discovery'),
    tailscale: createLogger('tailscale'),
    channels: createLogger('channels'),
    browser: createLogger('browser'),
    health: createLogger('health'),
    cron: createLogger('cron'),
    reload: createLogger('reload'),
    hooks: createLogger('hooks'),
    plugins: createLogger('plugins'),
    ws: createLogger('ws'),
    secrets: createLogger('secrets'),
  };

  // 1.2 验证配置
  const validationResult = validateConfig(config);
  if (validationResult.errors.length > 0) {
    for (const error of validationResult.errors) {
      loggers.gateway.error(`Config error: ${error}`);
    }
  }

  // 1.3 初始化认证系统
  const auth = await bootstrapAuth(config);

  // ===== 阶段 2: 凭据与插件 =====

  // 2.1 激活凭据管理
  const secretsManager = await activateSecrets(config, loggers.secrets);

  // 2.2 加载插件
  const pluginRegistry = await loadPlugins(config, {
    logger: loggers.plugins,
    secretsManager,
    registrationMode: 'full', // 完整模式：注册所有功能
  });

  // ===== 阶段 3: 渠道管理 =====

  // 3.1 初始化渠道管理器
  const channelManager = await createChannelManager(config, pluginRegistry, {
    logger: loggers.channels,
  });

  // 3.2 启动已配置的渠道账户
  await channelManager.startConfiguredAccounts();

  // ===== 阶段 4: 服务层 =====

  // 4.1 初始化 Cron 服务
  const cronService = new CronService(config, loggers.cron);
  await cronService.start();

  // 4.2 启动健康监控
  const healthMonitor = startHealthMonitor(config, {
    channelManager,
    cronService,
    logger: loggers.health,
  });

  // 4.3 启动插件服务
  await startPluginServices(pluginRegistry, { logger: loggers.plugins });

  // ===== 阶段 5: WebSocket 服务器 =====

  // 5.1 创建 HTTP/WS 服务器
  const server = createServer(bind, port, options.tls);

  // 5.2 设置 WebSocket 处理
  const wss = new WebSocketServer({ server });
  setupWebSocketHandlers(wss, {
    auth,
    pluginRegistry,
    channelManager,
    cronService,
    config,
    loggers,
  });

  // ===== 阶段 6: 网络与发现 =====

  // 6.1 节点注册表
  const nodeRegistry = createNodeRegistry();

  // 6.2 Exec 审批路由
  setupExecApprovalRouting(config, nodeRegistry);

  // 6.3 服务发现 (Bonjour/mDNS)
  if (config.gateway?.discovery?.enabled !== false) {
    await startDiscovery(server, loggers.discovery);
  }

  // 6.4 Tailscale 暴露
  if (bind === 'tailnet' || config.gateway?.tailscale?.enabled) {
    await exposeTailscale(server, loggers.tailscale);
  }

  // ===== 阶段 7: 就绪 =====
  loggers.gateway.info(`Gateway running on ${bind}:${port}`);

  return {
    close: async (reason) => { /* 优雅关闭所有子系统 */ },
    address: { host: server.address().address, port },
    running: true,
  };
}

4.2.3 绑定模式说明

模式	监听地址	使用场景
loopback	127.0.0.1	本机访问，最安全
lan	0.0.0.0	局域网访问，用于同网络设备连接
tailnet	Tailscale 接口	通过 Tailscale VPN 远程访问
auto	自动选择	根据环境自动决定绑定方式

4.3 WebSocket 协议与消息格式

Gateway 使用基于 WebSocket 的 JSON-RPC 协议进行通信。

4.3.1 消息帧格式

请求帧（客户端 → 服务器）：

{
  "id": "req-001",
  "method": "chat.send",
  "params": {
    "channel": "telegram",
    "target": "user123",
    "text": "Hello!"
  }
}

响应帧（服务器 → 客户端）：

{
  "id": "req-001",
  "result": {
    "success": true,
    "messageId": "msg-456"
  }
}

错误帧：

{
  "id": "req-001",
  "error": {
    "code": -32600,
    "message": "Invalid Request",
    "data": { "detail": "Missing required parameter: target" }
  }
}

事件帧（服务器推送，无 id）：

{
  "event": "message.received",
  "data": {
    "channel": "telegram",
    "sender": "user123",
    "text": "Hi there!",
    "timestamp": "2026-03-17T10:30:00Z"
  }
}

4.3.2 认证握手

连接建立后的第一步是认证：

Client                                    Server
  │                                          │
  │──── WebSocket Connect ──────────────────▶│
  │                                          │
  │◀──── Hello (server capabilities) ────────│
  │                                          │
  │──── Authenticate ──────────────────────▶│
  │     { mode: "token",                     │
  │       token: "xxx",                      │
  │       clientType: "cli",                 │
  │       clientVersion: "2026.3.14" }       │
  │                                          │
  │◀──── HelloOk ───────────────────────────│
  │     { role: "operator",                  │
  │       scopes: ["read","write","admin"],  │
  │       sessionId: "sess-789" }            │
  │                                          │
  │──── RPC Requests... ───────────────────▶│

支持的认证模式：

• token: 静态认证令牌（配置在 gateway.auth.token）
• password: 密码认证（用于简单部署）
• device-token: 设备绑定令牌（由配对流程生成）
• bootstrap-token: 初始配对令牌（一次性使用）

4.3.3 角色与权限

角色	权限	说明
operator	全部	完整管理权限
node	受限	移动/桌面节点，受限操作集
acp	受限	ACP 客户端，仅 Agent 操作
readonly	只读	监控用，无写入权限

4.4 RPC 方法分发

src/gateway/server-methods.ts 负责将 RPC 请求分发到对应的处理器：

/**
 * 核心网关处理器映射
 * 每个模块导出一组方法处理器
 */
const coreGatewayHandlers = mergeHandlers(
  connectHandlers,        // 连接管理
  logsHandlers,          // 日志查询
  voicewakeHandlers,     // 语音唤醒
  healthHandlers,        // 健康检查
  channelsHandlers,      // 渠道操作
  chatHandlers,          // 聊天消息
  cronHandlers,          // 定时任务
  devicesHandlers,       // 设备管理
  doctorHandlers,        // 诊断
  execApprovalsHandlers, // 执行审批
  webHandlers,           // Web 操作
  modelsHandlers,        // 模型管理
  configHandlers,        // 配置操作
  wizardHandlers,        // 设置向导
  talkHandlers,          // 对话管理
  toolsCatalogHandlers,  // 工具目录
  ttsHandlers,           // TTS 操作
  skillsHandlers,        // 技能管理
  sessionsHandlers,      // 会话操作
  systemHandlers,        // 系统信息
  updateHandlers,        // 更新管理
  nodesHandlers,         // 节点管理
  pushHandlers,          // 推送通知
  sendHandlers,          // 消息发送
  usageHandlers,         // 用量统计
  agentHandlers,         // Agent 操作
  agentsHandlers,        // Agent 列表
  browserHandlers,       // 浏览器操作
);

/**
 * 请求分发主函数
 */
export async function handleGatewayRequest(
  method: string,
  params: unknown,
  context: RequestContext
): Promise<unknown> {
  // 1. 查找处理器
  const handler = coreGatewayHandlers[method]
    ?? pluginGatewayHandlers[method];

  if (!handler) {
    throw new RpcError(-32601, `Method not found: ${method}`);
  }

  // 2. 角色授权检查
  if (handler.requiredRole && !hasRole(context.role, handler.requiredRole)) {
    throw new RpcError(-32603, `Insufficient permissions for ${method}`);
  }

  // 3. 操作范围检查
  if (handler.requiredScope && !hasScope(context.scopes, handler.requiredScope)) {
    throw new RpcError(-32603, `Missing scope: ${handler.requiredScope}`);
  }

  // 4. 速率限制
  if (!checkRateLimit(method, context.clientId)) {
    throw new RpcError(-32000, 'Rate limit exceeded');
  }

  // 5. 执行处理器
  return handler.handle(params, context);
}

4.4.1 RPC 方法分类（65+ 方法）

Agent 操作

方法	说明	所需角色
agent.run	执行 Agent 任务	operator
agent.status	查询运行状态	operator, node
agent.list	列出 Agent	operator, node
agent.cancel	取消任务	operator
agent.config	Agent 配置	operator

聊天操作

方法	说明
chat.send	发送消息到渠道
chat.history	获取聊天历史
chat.inject	注入系统消息
chat.stream	流式输出

渠道管理

方法	说明
channels.start	启动渠道账户
channels.stop	停止渠道账户
channels.status	渠道状态
channels.config	渠道配置

系统管理

方法	说明
system.info	系统信息
system.shutdown	关闭网关
system.restart	重启网关
config.get	获取配置
config.set	设置配置
config.reload	重新加载配置

会话管理

方法	说明
sessions.list	会话列表
sessions.reset	重置会话
sessions.export	导出会话

其他

方法	说明
health.check	健康检查
health.audit	安全审计
models.list	模型列表
models.default	默认模型
cron.list/add/update/remove/run	定时任务 CRUD
devices.list/pair/approve	设备管理
skills.list/install/uninstall	技能管理
tts.speak/voices/config	TTS 操作
browser.launch/navigate/screenshot/close	浏览器操作

4.5 认证与授权机制

Gateway 的认证系统支持多种认证方式，并通过角色和操作范围控制访问权限。

认证流程

// 认证配置（在 openclaw.json 中）
{
  "gateway": {
    "auth": {
      "token": "your-secret-token",           // 静态令牌
      "password": "your-password",             // 密码
      "allowedOrigins": ["https://your-app"],  // CORS 允许源
      "deviceTokens": {                        // 设备绑定令牌
        "iphone-1": "device-token-xxx"
      }
    },
    "port": 3000,
    "bind": "loopback"
  }
}

安全策略

1. DM 配对机制：移动设备通过配对流程获取设备令牌，配对需要在 Gateway 端确认
2. 速率限制：控制面 RPC 请求有速率限制，防止滥用
3. TLS 支持：可配置 TLS 证书实现加密通信
4. Tailscale 集成：通过 Tailscale VPN 安全暴露 Gateway

4.6 网关客户端 src/gateway/client.ts

src/gateway/client.ts 实现了 Gateway 的 WebSocket 客户端，被 CLI、ACP 服务器和移动节点使用：

export class GatewayClient {
  private ws: WebSocket;
  private pendingRequests: Map<string, PendingRequest>;
  private reconnectTimer: NodeJS.Timeout | null;
  private requestId: number = 0;

  constructor(private options: GatewayClientOptions) {
    this.pendingRequests = new Map();
  }

  /**
   * 连接到 Gateway
   */
  async connect(): Promise<void> {
    const url = this.buildWsUrl();
    this.ws = new WebSocket(url);

    this.ws.on('open', () => this.handleOpen());
    this.ws.on('message', (data) => this.handleMessage(data));
    this.ws.on('close', (code, reason) => this.handleClose(code, reason));
    this.ws.on('error', (err) => this.handleError(err));

    // 等待连接和认证完成
    await this.waitForHelloOk();
  }

  /**
   * 发送 RPC 请求
   */
  async request<T>(method: string, params?: unknown): Promise<T> {
    const id = `req-${++this.requestId}`;
    const frame = JSON.stringify({ id, method, params });

    return new Promise((resolve, reject) => {
      // 设置超时
      const timeout = setTimeout(() => {
        this.pendingRequests.delete(id);
        reject(new Error(`Request timeout: ${method}`));
      }, this.options.timeout ?? 30000);

      this.pendingRequests.set(id, { resolve, reject, timeout });
      this.ws.send(frame);
    });
  }

  /**
   * 监听事件
   */
  on(event: string, handler: (data: unknown) => void): void {
    this.eventHandlers.set(event, handler);
  }

  /**
   * 处理收到的消息
   */
  private handleMessage(raw: Buffer): void {
    const msg = JSON.parse(raw.toString());

    if (msg.id && this.pendingRequests.has(msg.id)) {
      // 这是一个响应帧
      const pending = this.pendingRequests.get(msg.id)!;
      this.pendingRequests.delete(msg.id);
      clearTimeout(pending.timeout);

      if (msg.error) {
        pending.reject(new RpcError(msg.error.code, msg.error.message));
      } else {
        pending.resolve(msg.result);
      }
    } else if (msg.event) {
      // 这是一个事件帧
      const handler = this.eventHandlers.get(msg.event);
      if (handler) handler(msg.data);
    }
  }

  /**
   * 自动重连
   */
  private handleClose(code: number, reason: string): void {
    if (this.options.autoReconnect && code !== 1000) {
      this.reconnectTimer = setTimeout(() => {
        this.connect().catch(() => {});
      }, this.options.reconnectDelay ?? 5000);
    }
  }
}

客户端模式

interface GatewayClientOptions {
  /** Gateway 地址 */
  host: string;
  port: number;

  /** 认证方式 */
  auth:
    | { mode: 'token'; token: string }
    | { mode: 'password'; password: string }
    | { mode: 'device-token'; token: string; deviceId: string }
    | { mode: 'bootstrap-token'; token: string };

  /** 客户端类型 */
  clientType: 'cli' | 'acp' | 'node';

  /** 自动重连 */
  autoReconnect?: boolean;
  reconnectDelay?: number;

  /** 请求超时 */
  timeout?: number;

  /** 设备身份签名（用于设备绑定认证） */
  deviceIdentity?: DeviceIdentity;
}

4.7 健康检查与监控

Gateway 内置健康检查机制，用于监控所有子系统的运行状态：

// 健康检查响应格式
interface HealthCheckResult {
  status: 'healthy' | 'degraded' | 'unhealthy';
  uptime: number;
  version: string;
  channels: {
    [id: string]: {
      status: 'connected' | 'disconnected' | 'error';
      lastActivity: string;
    };
  };
  cron: { activeJobs: number; nextRun: string };
  memory: { heapUsed: number; heapTotal: number; rss: number };
  sessions: { active: number; total: number };
}

健康检查可通过 openclaw health CLI 命令或 health.check RPC 方法访问。

4.8 远程网关部署

Gateway 支持远程部署，通过以下方式实现安全的远程访问：

1. SSH 隧道：ssh -L 3000:localhost:3000 remote-host 将远程 Gateway 映射到本地
2. Tailscale VPN：通过 bind: "tailnet" 直接在 Tailscale 网络上暴露
3. TLS 加密：配置 TLS 证书对通信加密
4. 反向代理：通过 Nginx/Caddy 反向代理添加 HTTPS 和域名

远程 Gateway 配置示例：

{
  "gateway": {
    "bind": "tailnet",       // 仅通过 Tailscale 可达
    "port": 3000,
    "auth": {
      "token": "strong-random-token"
    },
    "tailscale": {
      "enabled": true,
      "hostname": "openclaw-gateway"
    }
  }
}

---

第五部分：Agent 智能体系统

5.1 Agent 系统架构

Agent 系统是 OpenClaw 最大的子系统（923 个文件），负责与大语言模型 (LLM) 进行交互，管理对话会话，执行工具调用，并处理多轮对话。

消息到达
    │
    ▼
agentCommandFromIngress()  ← 从自动回复引擎调用
    │
    ├── 解析 Agent 身份 (agent-scope.ts)
    │   └── 从配置中查找匹配的 Agent
    │
    ├── 选择模型 (model-selection.ts)
    │   └── 考虑故障转移策略
    │
    ├── 加载会话 (sessions/)
    │   └── 恢复上下文、历史消息
    │
    ├── 准备工具 (tools/)
    │   └── 根据工具策略过滤可用工具
    │
    ├── 加载技能 (skills.ts)
    │   └── 注入技能指令到系统提示
    │
    ├── 选择运行时
    │   ├── 嵌入式 Pi Agent (pi-embedded.ts)
    │   └── CLI 后端运行器 (cli-runner.ts)
    │
    ├── 执行 LLM 推理
    │   └── 流式输出、工具调用循环
    │
    ├── 处理结果
    │   ├── 更新会话记录
    │   ├── 触发 Hook 事件
    │   └── 投递响应到渠道
    │
    └── 清理资源

5.2 Agent 命令编排器

src/agents/agent-command.ts 是整个 Agent 系统的核心编排器，约 1300 行代码。它协调所有 Agent 子系统完成一次完整的 Agent 轮次。

/**
 * 从外部入口（渠道消息、CLI 命令）触发 Agent 运行
 */
export async function agentCommandFromIngress(
  params: AgentIngressParams
): Promise<AgentResult> {
  const {
    message,           // 用户消息
    sessionKey,        // 会话标识
    config,            // 配置对象
    channelId,         // 渠道 ID
    senderId,          // 发送者 ID
    pluginRegistry,    // 插件注册表
    deliverResult,     // 结果投递函数
  } = params;

  // 1. 解析 Agent 身份
  const agentId = resolveAgentIdForSession(sessionKey, config);
  const agentConfig = resolveAgentConfig(agentId, config);

  // 2. 选择模型（支持故障转移）
  const model = await selectModel(agentConfig, config, {
    channelId,
    sessionKey,
    fallbackChain: agentConfig.models?.fallback,
  });

  // 3. 解析认证凭据
  const authProfile = resolveAuthProfile(model.provider, config);

  // 4. 加载/创建会话
  const session = await loadOrCreateSession(sessionKey, {
    agentId,
    resetPolicy: agentConfig.sessions?.resetPolicy,
  });

  // 5. 解析工作区目录
  const workspaceDir = resolveAgentWorkspaceDir(agentId, config);

  // 6. 加载技能快照
  const skills = await loadSkillSnapshot(agentConfig, config, pluginRegistry);

  // 7. 构建系统提示
  //    注入: Agent 身份 + 工作区引导 (AGENTS.md/SOUL.md/TOOLS.md) + 技能指令
  const systemPrompt = buildSystemPrompt({
    agentConfig,
    skills,
    workspaceDir,
    channelId,
    session,
  });

  // 8. 选择 Agent 运行时
  let result: AgentResult;
  if (agentConfig.runtime === 'acp') {
    // ACP 沙箱模式
    result = await spawnAcpAgent({
      task: message,
      agentId,
      model,
      authProfile,
      session,
      systemPrompt,
      sandbox: agentConfig.sandbox,
    });
  } else if (agentConfig.runtime === 'cli-backend') {
    // CLI 后端模式
    result = await runCliAgent({
      message,
      model,
      authProfile,
      session,
      systemPrompt,
      workspaceDir,
    });
  } else {
    // 默认: 嵌入式 Pi Agent
    result = await runEmbeddedPiAgent({
      message,
      model,
      authProfile,
      session,
      systemPrompt,
      tools: resolveAvailableTools(agentConfig, pluginRegistry),
      timeout: agentConfig.timeout,
    });
  }

  // 9. 更新会话记录
  await updateSessionTranscript(session, message, result);

  // 10. 触发 agent_end Hook
  await emitHook('agent_end', {
    agentId,
    sessionKey,
    result,
  });

  // 11. 投递结果
  if (deliverResult) {
    await deliverResult(result);
  }

  return result;
}

关键特性

超时处理：Agent 运行有可配置的超时时间，超时后优雅取消并返回部分结果。

流式输出：LLM 的流式响应实时传递给渠道，用户可以看到"正在输入"指示器。

工具调用循环：Agent 可以多次调用工具，每次工具结果返回后继续对话，直到 LLM 生成最终回复。

5.3 Agent 作用域与多 Agent 配置

src/agents/agent-scope.ts 管理多 Agent 配置，允许一个 OpenClaw 实例运行多个具有不同个性、模型和工具集的 Agent。

// 配置示例
{
  "agents": {
    "default": "assistant",    // 默认 Agent ID
    "list": {
      "assistant": {
        "model": "anthropic/claude-opus-4-6",
        "identity": {
          "name": "助手",
          "personality": "友好、专业"
        },
        "skills": ["coding-agent", "github", "weather"],
        "tools": {
          "policy": "allow-all",
          "deny": ["dangerous_exec"]
        },
        "memory": { "enabled": true },
        "workspace": "~/openclaw-workspace/assistant"
      },
      "coder": {
        "model": "openai/gpt-5.4",
        "identity": {
          "name": "编码助手",
          "personality": "专注于代码生成和审查"
        },
        "skills": ["coding-agent"],
        "sandbox": { "enabled": true, "mode": "docker" },
        "workspace": "~/openclaw-workspace/coder"
      }
    }
  }
}

核心函数

/**
 * 列出所有配置的 Agent ID
 */
export function listAgentIds(config: OpenClawConfig): string[] {
  return Object.keys(config.agents?.list ?? {});
}

/**
 * 解析默认 Agent ID
 */
export function resolveDefaultAgentId(config: OpenClawConfig): string {
  return config.agents?.default ?? listAgentIds(config)[0] ?? 'default';
}

/**
 * 解析 Agent 配置（合并默认配置和 Agent 特定配置）
 */
export function resolveAgentConfig(
  agentId: string,
  config: OpenClawConfig
): ResolvedAgentConfig {
  const defaultConfig = config.agents?.defaults ?? {};
  const agentConfig = config.agents?.list?.[agentId] ?? {};

  // 深度合并：Agent 特定配置覆盖默认配置
  return deepMerge(defaultConfig, agentConfig);
}

/**
 * 解析 Agent 工作区目录
 */
export function resolveAgentWorkspaceDir(
  agentId: string,
  config: OpenClawConfig
): string {
  const agentConfig = resolveAgentConfig(agentId, config);
  return (
    agentConfig.workspace ??
    path.join(getOpenClawDataDir(), 'workspaces', agentId)
  );
}

工作区引导 (Workspace Bootstrap)

每个 Agent 的工作区目录可以包含以下引导文件，它们会被自动注入到系统提示中：

文件	用途
AGENTS.md	Agent 身份和行为指令
SOUL.md	Agent 个性和世界观
TOOLS.md	环境特定的工具提示（设备名称、SSH 主机等）

5.4 模型选择与故障转移

src/agents/model-selection.ts 和 model-fallback.ts 实现了智能模型选择和故障转移：

/**
 * 模型选择流程：
 * 1. 会话级模型覆盖（用户通过命令切换）
 * 2. 渠道级模型覆盖（特定渠道使用不同模型）
 * 3. 心跳模型覆盖（定时任务使用经济型模型）
 * 4. Agent 配置的模型
 * 5. 全局默认模型
 */
export async function selectModel(
  agentConfig: ResolvedAgentConfig,
  config: OpenClawConfig,
  context: ModelSelectionContext
): Promise<ResolvedModel> {
  // 优先级从高到低
  const modelRef =
    context.sessionModelOverride ??
    context.channelModelOverride ??
    context.heartbeatModelOverride ??
    agentConfig.model ??
    config.models?.default;

  if (!modelRef) {
    throw new Error('No model configured. Run: openclaw setup wizard');
  }

  // 解析模型引用 (格式: "provider/model-name")
  const resolved = resolveModelRef(modelRef, config);

  return resolved;
}

故障转移机制

/**
 * 模型故障转移链
 * 当主模型不可用时（API 错误、速率限制、凭据过期），
 * 自动切换到备选模型
 */
export async function executeWithFallback<T>(
  models: string[],     // [主模型, 备选1, 备选2, ...]
  executor: (model: ResolvedModel) => Promise<T>,
  config: OpenClawConfig
): Promise<T> {
  let lastError: Error | null = null;

  for (const modelRef of models) {
    try {
      const model = resolveModelRef(modelRef, config);
      return await executor(model);
    } catch (error) {
      lastError = error;
      if (isRetryableError(error)) {
        // 速率限制、临时错误 → 尝试下一个模型
        continue;
      }
      // 非重试错误（如参数错误）→ 直接抛出
      throw error;
    }
  }

  throw lastError ?? new Error('All models failed');
}

/**
 * 判断错误是否可重试
 */
function isRetryableError(error: unknown): boolean {
  if (error instanceof ApiError) {
    return [429, 500, 502, 503, 504].includes(error.statusCode);
  }
  return false;
}

认证轮换

auth-profiles.ts 管理多个 API 密钥的轮换：

// 配置示例：同一提供商的多个密钥
{
  "models": {
    "providers": {
      "anthropic": {
        "apiKeys": [
          "sk-key-1",  // 主密钥
          "sk-key-2",  // 备选密钥（主密钥达到速率限制时使用）
        ],
        "cooldownProfiles": {
          // 当某个密钥被速率限制后，冷却一段时间
          "sk-key-1": { "cooldownMs": 60000 }
        }
      }
    }
  }
}

5.5 Agent 工具系统

Agent 在对话中可以使用工具来执行操作。工具通过插件系统注册，并根据策略控制哪些工具可用。

内置工具

工具	功能	说明
web_search	网络搜索	使用 Brave/Perplexity/Firecrawl
web_fetch	网页获取	Readability 提取 + Firecrawl 降级
memory_recall	记忆召回	向量搜索长期记忆
memory_store	记忆存储	嵌入并存储信息
memory_forget	记忆删除	删除指定记忆
send_message	发送消息	主动发送消息到渠道
voice_call	语音通话	发起/管理语音通话
browser_navigate	浏览器导航	打开网页
browser_screenshot	浏览器截图	捕获页面截图
exec	命令执行	执行 shell 命令（需审批）
firecrawl_search	Firecrawl 搜索	高级网络搜索
firecrawl_scrape	Firecrawl 抓取	网页内容抓取

工具策略

{
  "agents": {
    "list": {
      "assistant": {
        "tools": {
          // 策略模式
          "policy": "allow-all",  // 或 "deny-all"

          // 显式允许列表
          "allow": ["web_search", "web_fetch", "memory_recall"],

          // 显式拒绝列表
          "deny": ["exec", "voice_call"],

          // 提权工具（需要用户确认）
          "elevated": ["exec", "browser_navigate"]
        }
      }
    }
  }
}

工具调用流程

Agent (LLM) 生成工具调用请求
    │
    ▼
工具策略检查 → 被拒绝 → 返回错误给 LLM
    │ (通过)
    ▼
工具是否需要提权？ → 是 → 等待用户/操作者确认
    │ (否/已确认)
    ▼
执行工具
    │
    ▼
返回结果给 LLM
    │
    ▼
LLM 继续对话（可能再次调用工具或生成最终回复）

5.6 子智能体 (Sub-agents)

子智能体 (Sub-agents) 允许主 Agent 在后台启动独立的 Agent 会话来处理特定任务：

// 子智能体配置
{
  "agents": {
    "list": {
      "assistant": {
        "subagents": {
          "enabled": true,
          "maxConcurrent": 3,       // 最大并发子 Agent 数
          "isolatedSessions": true, // 子 Agent 使用独立会话
          "announceSteps": true,    // 向用户通告进度
          "toolPolicy": "inherit"   // 继承父 Agent 的工具策略
        }
      }
    }
  }
}

子智能体的典型用途：

• 在处理用户请求的同时，后台搜索相关信息
• 并行执行多个独立的工具调用
• 长时间运行的任务（如代码生成、文件处理）不阻塞主对话

5.7 沙箱隔离

Agent 可以在 Docker 沙箱中运行，提供进程级别的隔离：

// 沙箱配置
{
  "agents": {
    "list": {
      "coder": {
        "sandbox": {
          "enabled": true,
          "mode": "docker",
          "image": "openclaw-sandbox:latest",  // 使用 Dockerfile.sandbox
          "network": "none",                    // 无网络访问
          "memoryLimit": "512m",
          "cpuLimit": "1.0",
          "timeout": 300000,                    // 5 分钟超时
          "mounts": [
            // 只读挂载工作区
            { "source": "/workspace", "target": "/workspace", "readonly": true }
          ]
        }
      }
    }
  }
}

沙箱镜像由 Dockerfile.sandbox 和 Dockerfile.sandbox-browser 构建：

• sandbox: 基础沙箱，包含 Node.js 运行时和基本工具
• sandbox-browser: 扩展沙箱，额外包含 Chromium 浏览器用于自动化

5.8 CLI 后端运行器

src/agents/cli-runner.ts 实现了通过外部 CLI 工具运行 Agent 的后端：

/**
 * 使用 CLI 后端运行 Agent
 * 支持的后端: Claude Code CLI, Codex CLI, Pi CLI, OpenCode CLI
 */
export async function runCliAgent(params: CliAgentParams): Promise<AgentResult> {
  const { message, model, authProfile, session, systemPrompt, workspaceDir } = params;

  // 1. 构建系统提示
  const fullPrompt = buildCliSystemPrompt(systemPrompt, session.history);

  // 2. 解析引导上下文
  const bootstrapContext = resolveBootstrapContext(workspaceDir);

  // 3. 启动 CLI 进程
  const proc = spawn(resolveCliBackendPath(model.provider), [
    '--model', model.modelId,
    '--system-prompt', fullPrompt,
    '--message', message,
    ...(authProfile.apiKey ? ['--api-key', authProfile.apiKey] : []),
  ], {
    cwd: workspaceDir,
    env: { ...process.env, ...authProfile.env },
  });

  // 4. 收集输出（支持流式）
  const output = await collectStreamOutput(proc);

  // 5. 处理模型故障转移
  if (output.error && isRetryableError(output.error)) {
    // 使用备选模型重试
    return runCliAgent({ ...params, model: getNextFallbackModel(model) });
  }

  return { text: output.text, toolCalls: output.toolCalls };
}

5.9 嵌入式 Pi Agent

src/agents/pi-embedded.ts 集成了 Pi Agent 框架（来自 @mariozechner/pi-* 依赖），这是默认的 Agent 运行时：

/**
 * 嵌入式 Pi Agent 运行 Agent 轮次
 * Pi 框架提供：
 * - 流式 LLM 对话
 * - 工具调用编排
 * - 上下文窗口管理
 * - 多提供商适配
 */
export async function runEmbeddedPiAgent(
  params: EmbeddedAgentParams
): Promise<AgentResult> {
  const { message, model, authProfile, session, systemPrompt, tools, timeout } = params;

  // 创建 Pi Agent 实例
  const agent = createPiAgent({
    model: {
      provider: model.provider,
      modelId: model.modelId,
      apiKey: authProfile.apiKey,
      baseUrl: authProfile.baseUrl,
    },
    systemPrompt,
    tools: tools.map(toPiTool), // 转换为 Pi 工具格式
    history: session.messages,
    options: {
      streaming: true,
      maxTurns: 20,            // 最大工具调用轮次
      timeout,
      thinkingLevel: model.thinkingLevel ?? 'adaptive',
    },
  });

  // 执行 Agent 轮次
  const result = await agent.run(message);

  return {
    text: result.response,
    toolCalls: result.toolCalls,
    usage: result.tokenUsage,
    thinking: result.thinking,
  };
}

嵌入式 Pi Agent 是最常用的运行时，因为它直接在 Gateway 进程中运行，无需额外的子进程开销。

---

第六部分：插件系统

6.1 插件架构总览

OpenClaw 的插件系统是整个架构的基石。它提供了一套标准化的注册 API，使得渠道、模型提供商、工具、服务等功能都以统一方式扩展。

插件加载流程:
    │
    ▼
扫描 extensions/ 目录
    │
    ▼
读取每个扩展的 openclaw.plugin.json 清单
    │
    ▼
检查依赖（环境变量、配置项、二进制文件）
    │
    ▼
加载 index.ts 入口模块
    │
    ▼
调用 register(api) 注册回调
    │
    ├── api.registerChannel(...)       → 注册渠道
    ├── api.registerProvider(...)      → 注册模型提供商
    ├── api.registerTool(...)          → 注册工具
    ├── api.registerService(...)       → 注册后台服务
    ├── api.registerGatewayMethod(...) → 注册 RPC 方法
    ├── api.registerHook(...)          → 注册事件钩子
    ├── api.registerCli(...)           → 注册 CLI 命令
    └── api.register*(...)             → 注册其他能力
    │
    ▼
PluginRegistry 收集所有注册项
    │
    ▼
Gateway 启动时使用注册表初始化各子系统

6.2 插件注册工厂

src/plugin-sdk/core.ts 提供三种插件注册工厂函数：

6.2.1 definePluginEntry — 通用插件

最灵活的工厂函数，适用于任何类型的插件：

import { definePluginEntry } from 'openclaw/plugin-sdk/core';

export default definePluginEntry({
  id: 'my-custom-plugin',
  name: 'My Custom Plugin',
  description: 'A custom plugin example',
  kind: 'tool',  // 可选: 'channel', 'provider', 'memory', 'tool', 'service'

  // 可选: Zod 配置 schema
  configSchema: z.object({
    apiKey: z.string().optional(),
    maxRetries: z.number().default(3),
  }),

  // 注册回调
  register(api) {
    // 注册工具
    api.registerTool({
      name: 'my_tool',
      description: 'Does something useful',
      parameters: z.object({ query: z.string() }),
      execute: async (params, ctx) => {
        return { result: `Processed: ${params.query}` };
      },
    });

    // 注册生命周期钩子
    api.on('agent_end', async (event) => {
      // Agent 轮次结束后的处理
    });

    // 注册 CLI 子命令
    api.registerCli((program) => {
      program
        .command('my-plugin status')
        .action(async () => { /* ... */ });
    });
  },
});

6.2.2 defineChannelPluginEntry — 渠道插件

专为通讯渠道设计的工厂函数，内置渠道注册和运行时注入逻辑：

import { defineChannelPluginEntry } from 'openclaw/plugin-sdk/core';
import { telegramPlugin } from './src/channel.js';
import { setTelegramRuntime } from './src/runtime.js';

export default defineChannelPluginEntry({
  id: 'telegram',
  name: 'Telegram',
  description: 'Telegram Bot API integration',

  // ChannelPlugin 实现对象
  plugin: telegramPlugin,

  // 运行时注入函数
  setRuntime: setTelegramRuntime,

  // 可选: 完整模式下的额外注册
  registerFull: (api) => {
    // 注册子 Agent 钩子、额外工具等
    api.on('agent_end', handleTelegramAgentEnd);
  },
});

内部实现逻辑：

export function defineChannelPluginEntry(options) {
  return definePluginEntry({
    id: options.id,
    name: options.name,
    description: options.description,
    register(api) {
      // 1. 注入运行时
      if (options.setRuntime) {
        options.setRuntime(api.runtime);
      }

      // 2. 注册渠道
      api.registerChannel({ plugin: options.plugin });

      // 3. 完整模式下的额外注册
      if (api.registrationMode === 'full' && options.registerFull) {
        options.registerFull(api);
      }
    },
  });
}

6.2.3 defineSetupPluginEntry — 设置向导插件

用于独立的设置/配置入口，不加载完整运行时依赖：

import { defineSetupPluginEntry } from 'openclaw/plugin-sdk/core';
import { telegramSetupPlugin } from './src/channel.setup.js';

export default defineSetupPluginEntry(telegramSetupPlugin);

这种分离确保设置向导只加载最小的依赖，加速 openclaw onboard telegram 等命令的响应。

6.3 插件注册表 PluginRegistry

src/plugins/registry.ts 定义了 PluginRegistry，它是所有插件注册项的中央存储：

export interface PluginRegistry {
  /** 已注册的插件列表 */
  plugins: PluginRecord[];

  /** Agent 工具 */
  tools: RegisteredTool[];

  /** 生命周期钩子 */
  hooks: RegisteredHook[];
  typedHooks: TypedHookRegistry;

  /** 渠道插件 */
  channels: RegisteredChannel[];
  channelSetups: RegisteredChannelSetup[];

  /** 各类提供商 */
  providers: {
    llm: RegisteredLLMProvider[];
    speech: RegisteredSpeechProvider[];
    mediaUnderstanding: RegisteredMediaProvider[];
    imageGeneration: RegisteredImageGenProvider[];
    webSearch: RegisteredWebSearchProvider[];
  };

  /** Gateway 扩展 */
  gatewayHandlers: RegisteredGatewayHandler[];
  httpRoutes: RegisteredHttpRoute[];

  /** CLI 扩展 */
  cliRegistrars: RegisteredCliRegistrar[];

  /** 后台服务 */
  services: RegisteredService[];

  /** 自定义命令 */
  commands: RegisteredCommand[];

  /** 对话绑定处理器 */
  conversationBindingResolvedHandlers: RegisteredBindingHandler[];

  /** 诊断信息 */
  diagnostics: RegisteredDiagnostic[];
}

/**
 * 单个插件的记录
 */
export interface PluginRecord {
  id: string;
  name: string;
  version: string;
  format: 'esm' | 'cjs';
  kind: string;
  origin: string;       // 文件路径或 npm 包名
  enabled: boolean;
  counts: {
    tools: number;
    hooks: number;
    channels: number;
    providers: number;
    services: number;
    gatewayHandlers: number;
    httpRoutes: number;
    commands: number;
  };
}

createPluginRegistry()

export function createPluginRegistry(): {
  registry: PluginRegistry;
  api: (pluginId: string) => OpenClawPluginApi;
} {
  const registry: PluginRegistry = {
    plugins: [],
    tools: [],
    hooks: [],
    // ... 初始化所有空数组
  };

  // 为每个插件创建独立的 API 实例
  function createApiForPlugin(pluginId: string): OpenClawPluginApi {
    return {
      registerChannel: (opts) => {
        registry.channels.push({ pluginId, ...opts });
      },
      registerProvider: (opts) => {
        registry.providers.llm.push({ pluginId, ...opts });
      },
      registerTool: (opts) => {
        registry.tools.push({ pluginId, ...opts });
      },
      // ... 所有注册方法
      runtime: createPluginRuntime(pluginId),
      registrationMode: 'full',
    };
  }

  return {
    registry,
    api: createApiForPlugin,
  };
}

6.4 Plugin API 注册方法

OpenClawPluginApi 提供以下注册方法：

方法	注册目标	说明
registerChannel(opts)	渠道插件	注册消息平台适配器
registerProvider(opts)	LLM 提供商	注册 AI 模型提供商
registerTool(opts)	Agent 工具	注册 Agent 可调用的工具
registerService(opts)	后台服务	注册有 start/stop 生命周期的服务
registerGatewayMethod(opts)	Gateway RPC	注册自定义 RPC 方法
registerCli(opts)	CLI 子命令	注册 Commander 命令
registerSpeechProvider(opts)	TTS 提供商	注册语音合成提供商
registerMediaUnderstandingProvider(opts)	媒体理解	注册图像/媒体分析能力
registerImageGenerationProvider(opts)	图像生成	注册图像生成能力
registerWebSearchProvider(opts)	网络搜索	注册 Web 搜索提供商
registerHook(event, handler)	事件钩子	注册特定事件的处理器
on(event, handler)	事件钩子	registerHook 的别名
registerHttpRoute(opts)	HTTP 路由	注册自定义 HTTP 端点
registerCommand(opts)	直接命令	注册绕过 LLM 的快捷命令
registerContextEngine(opts)	上下文引擎	注册上下文管理实现
registerInteractiveHandler(opts)	交互处理器	注册交互式 UI 处理器

每个注册方法都接受一个配置对象，包含该类型所需的特定字段。例如工具注册：

api.registerTool({
  name: 'weather',
  description: 'Get current weather for a location',
  parameters: z.object({
    location: z.string().describe('City name'),
    units: z.enum(['celsius', 'fahrenheit']).default('celsius'),
  }),
  // 是否可选（缺失依赖不阻塞加载）
  optional: true,
  execute: async (params, ctx) => {
    const weather = await fetchWeather(params.location, params.units);
    return { temperature: weather.temp, condition: weather.condition };
  },
});

6.5 插件清单 openclaw.plugin.json

每个扩展目录下的 openclaw.plugin.json 文件声明了插件的元数据和配置 schema：

{
  // 唯一标识符
  "id": "discord",

  // 提供的渠道 ID（渠道插件必需）
  "channels": ["discord"],

  // 提供的提供商 ID（提供商插件必需）
  // "providers": ["anthropic"],

  // 认证环境变量自动检测
  "providerAuthEnvVars": {
    "discord": ["DISCORD_BOT_TOKEN"]
  },

  // 引导向导中的认证选项
  "providerAuthChoices": [
    {
      "id": "bot-token",
      "label": "Discord Bot Token",
      "description": "From Discord Developer Portal"
    }
  ],

  // 配置 schema（JSON Schema 格式）
  "configSchema": {
    "type": "object",
    "properties": {
      "token": { "type": "string", "description": "Bot token" },
      "guildId": { "type": "string", "description": "Guild ID" },
      "dmPolicy": {
        "type": "string",
        "enum": ["open", "paired", "closed"],
        "default": "paired"
      }
    },
    "required": ["token"]
  },

  // UI 提示（配置编辑器使用）
  "uiHints": {
    "token": {
      "label": "Bot Token",
      "placeholder": "Enter your Discord bot token",
      "sensitive": true     // 敏感字段，UI 中隐藏
    },
    "guildId": {
      "label": "Guild ID",
      "advanced": true      // 高级设置，默认折叠
    }
  },

  // 内置技能目录
  "skills": ["./skills"],

  // 插件类型
  "kind": "channel"  // 或 "provider", "memory", "tool", "service"
}

这个清单文件使得：

1. 静态分析：无需加载插件即可了解其能力
2. UI 生成：配置编辑器根据 schema 和 uiHints 自动生成表单
3. 依赖检查：根据 providerAuthEnvVars 检测用户是否已配置凭据

6.6 Plugin SDK 导出体系

Plugin SDK 通过 package.json 的 exports 字段提供了 250+ 个模块入口，覆盖不同的运行时上下文：

{
  "exports": {
    // 核心 SDK
    "./plugin-sdk": "./dist/plugin-sdk/index.js",
    "./plugin-sdk/core": "./dist/plugin-sdk/core.js",
    "./plugin-sdk/compat": "./dist/plugin-sdk/compat.js",

    // 运行时上下文
    "./plugin-sdk/runtime": "./dist/plugin-sdk/runtime.js",
    "./plugin-sdk/setup": "./dist/plugin-sdk/setup.js",

    // 渠道运行时
    "./plugin-sdk/channel-runtime": "./dist/plugin-sdk/channel-runtime.js",
    "./plugin-sdk/agent-runtime": "./dist/plugin-sdk/agent-runtime.js",
    "./plugin-sdk/reply-runtime": "./dist/plugin-sdk/reply-runtime.js",

    // 提供商运行时
    "./plugin-sdk/provider-runtime": "./dist/plugin-sdk/provider-runtime.js",
    "./plugin-sdk/provider-openai-compat": "./dist/plugin-sdk/provider-openai-compat.js",

    // 渠道特定 SDK
    "./plugin-sdk/discord": "./dist/plugin-sdk/discord.js",
    "./plugin-sdk/telegram": "./dist/plugin-sdk/telegram.js",
    "./plugin-sdk/slack": "./dist/plugin-sdk/slack.js",
    // ... 20+ 渠道
    // ... 200+ 更多入口
  }
}

这种细粒度的导出设计使插件开发者可以精确导入所需的类型和工具，避免加载不必要的模块。

6.7 插件生命周期管理

插件的生命周期经历以下阶段：

1. 发现 (Discovery)
   └── 扫描 extensions/ 目录，读取 openclaw.plugin.json

2. 加载 (Loading)
   └── 动态 import() 入口模块 (index.ts)

3. 注册 (Registration)
   └── 调用 register(api) 回调，收集所有注册项

4. 激活 (Activation)
   └── 启动已注册的服务 (service.start())
   └── 初始化渠道连接 (channel.startAccount())

5. 运行 (Running)
   └── 处理请求、事件、工具调用

6. 停止 (Shutdown)
   └── 停止服务 (service.stop())
   └── 断开渠道连接
   └── 清理资源

7. 热重载 (Hot Reload) [可选]
   └── 配置变更触发部分插件重新加载

服务插件的 start/stop 接口：

api.registerService({
  name: 'my-background-service',
  start: async (context) => {
    // 启动后台任务
    const interval = setInterval(() => { /* ... */ }, 60000);
    return { stop: async () => clearInterval(interval) };
  },
});

---

第七部分：渠道 (Channel) 系统

7.1 渠道系统架构

渠道系统是 OpenClaw 连接外部通讯平台的核心抽象层。每个通讯平台（Discord、Telegram、Slack 等）都通过实现 ChannelPlugin 接口来接入系统。

渠道系统的核心职责：

1. 消息监听：实时接收各平台的消息
2. 消息标准化：将平台特定的消息格式转换为统一格式
3. 安全过滤：基于白名单、配对状态、群组策略过滤消息
4. 消息发送：将 Agent 响应转换为平台特定格式并发送
5. 状态管理：连接健康检查、重连、账户管理

7.2 ChannelPlugin 接口规范

ChannelPlugin 是所有渠道必须实现的核心接口，定义在 src/channels/plugins/types.plugin.ts：

export interface ChannelPlugin {
  /** 渠道唯一标识 */
  id: string;

  /** 显示名称 */
  label: string;

  /** ==== 适配器集合 ==== */

  /** 配置适配器: 账户解析、配置读取 */
  config: {
    resolveAccounts(config: OpenClawConfig): ChannelAccount[];
    getConfigPath(): string;
  };

  /** 设置适配器: 交互式配置向导 */
  setup: {
    run(prompter: WizardPrompter): Promise<SetupResult>;
  };

  /** 配对适配器: 用户配对/审批流程 */
  pairing?: {
    requestPairing(userId: string): Promise<PairingRequest>;
    approvePairing(requestId: string): Promise<void>;
  };

  /** 安全适配器: DM 策略、白名单 */
  security: {
    getDmPolicy(): 'open' | 'paired' | 'closed';
    isAllowed(senderId: string, chatType: 'dm' | 'group'): boolean;
    getAllowlistWarnings(): string[];
  };

  /** 群组适配器: 群组策略、提及检测 */
  groups?: {
    getMentionPolicy(): 'required' | 'optional' | 'none';
    getToolPolicy(groupId: string): ToolPolicy;
  };

  /** 提及适配器: 清除机器人提及文本 */
  mentions?: {
    stripPatterns: RegExp[];
  };

  /** 出站适配器: 消息发送 */
  outbound: {
    sendText(target: string, text: string, opts?: SendOptions): Promise<void>;
    sendMedia(target: string, media: MediaPayload): Promise<void>;
    sendPoll?(target: string, poll: PollPayload): Promise<void>;
    resolveTarget(input: string): Promise<ResolvedTarget>;
    getMaxChunkSize(): number;  // 如 Discord 2000, Telegram 4096
  };

  /** 状态适配器: 运行时状态 */
  status: {
    getStatus(): ChannelStatus;
    probe(): Promise<ProbeResult>;
    buildAuditSnapshot(): AuditSnapshot;
  };

  /** 网关适配器: 启动消息监听 */
  gateway: {
    startAccount(account: ChannelAccount, context: GatewayContext): Promise<void>;
    stopAccount?(account: ChannelAccount): Promise<void>;
  };

  /** 消息适配器: 目标标准化、会话路由 */
  messaging: {
    normalizeTarget(raw: string): string;
    resolveSessionKey(msg: IncomingMessage): string;
  };

  /** 执行审批适配器 */
  execApprovals?: {
    getApprovers(channelId: string): string[];
    requestApproval(request: ApprovalRequest): Promise<ApprovalResult>;
  };

  /** 目录适配器: 联系人/群组目录 */
  directory?: {
    listPeers(): DirectoryEntry[];
    listGroups(): DirectoryEntry[];
  };

  /** 名称解析适配器 */
  resolver?: {
    resolveUserName(userId: string): Promise<string>;
    resolveChannelName(channelId: string): Promise<string>;
  };

  /** 操作适配器: 表情回应、踢人、禁言 */
  actions?: {
    react?(target: string, emoji: string): Promise<void>;
    timeout?(userId: string, duration: number): Promise<void>;
    kick?(userId: string): Promise<void>;
    ban?(userId: string): Promise<void>;
  };

  /** ACP 绑定适配器 */
  bindings?: {
    matchConversation(binding: ConversationBinding): boolean;
  };

  /** 线程适配器 */
  threading?: {
    getReplyToMode(): 'thread' | 'reply' | 'none';
  };

  /** Agent 提示适配器 */
  agentPrompt?: {
    getToolHints(): string;  // 注入到 Agent 系统提示中
  };
}

这个接口看似庞大，但大多数适配器是可选的。一个最小的渠道实现只需要提供 config、security、outbound、gateway 和 messaging 适配器。

7.3 渠道扩展开发模式

每个渠道扩展遵循标准的文件结构模式：

extensions/<channel>/
├── index.ts                  # 主入口 (defineChannelPluginEntry)
├── setup-entry.ts            # 设置入口 (defineSetupPluginEntry)
├── api.ts                    # 公共类型导出（非运行时依赖）
├── runtime-api.ts            # 运行时类型导出
├── openclaw.plugin.json      # 插件清单
├── package.json              # 依赖声明
└── src/
    ├── channel.ts            # ChannelPlugin 对象实现
    ├── channel.setup.ts      # 设置向导实现
    ├── runtime.ts            # 运行时存储 (createPluginRuntimeStore)
    ├── config-schema.ts      # 配置 schema 验证
    ├── monitor.ts            # 实时消息监听器
    ├── send.ts               # 出站消息发送
    ├── probe.ts              # 健康探测
    ├── accounts.ts           # 多账户解析
    ├── normalize.ts          # 目标标准化
    ├── targets.ts            # 目标解析
    ├── types.ts              # 内部类型定义
    ├── actions.ts            # 消息操作（回应、踢人等）
    ├── history.ts            # 聊天历史获取
    ├── attachments.ts        # 附件处理
    └── [platform-specific]   # 平台特定模块

运行时存储模式

渠道使用 createPluginRuntimeStore 管理全局运行时实例：

// src/runtime.ts
import { createPluginRuntimeStore } from 'openclaw/plugin-sdk/runtime';

const store = createPluginRuntimeStore<PluginRuntime>(
  'Telegram runtime not initialized'
);

export const setTelegramRuntime = store.set;
export const getTelegramRuntime = store.get;

这是一个简单的全局 get/set 单例，在插件注册时通过 setRuntime 注入运行时实例，随后在任何需要运行时的地方通过 get() 获取。

7.4 Discord 渠道实现

Discord 是功能最丰富的渠道实现（201 个文件），充分利用了 Discord API 的高级特性。

注册方式：

export default defineChannelPluginEntry({
  id: 'discord',
  plugin: discordPlugin,
  setRuntime: setDiscordRuntime,
  registerFull: registerDiscordSubagentHooks,
});

核心特性：

• Gateway WebSocket 监听：通过 Discord.js 库连接 Discord Gateway，实时接收消息事件
• Message Content Intent：启动时检查机器人是否有 Message Content Intent 权限，这是读取消息内容的必要条件
• Guild 级安全：每个 Discord 服务器 (Guild) 可以有独立的白名单和策略
• 消息分块：Discord 有 2000 字符的消息长度限制，长消息自动分块发送
• 丰富消息格式：支持 Embeds（嵌入卡片）、Components（按钮/下拉菜单）、Polls（投票）
• PluralKit 集成：检测和处理 PluralKit 代理消息
• 语音消息：支持发送和接收 Discord 语音消息
• 执行审批：支持通过 Discord 消息确认执行审批请求
• ACP 对话绑定：支持 ACP 协议的对话上下文绑定

消息流：

Discord Gateway WebSocket
    │
    ▼
monitorDiscordProvider()
    │ ── 过滤: 白名单/提及检查/机器人消息排除
    ▼
消息标准化
    │ ── 提取文本/附件/引用/线程上下文
    ▼
路由到 Agent 系统
    │
    ▼
Agent 响应
    │
    ▼
sendMessageDiscord(target, text, opts)
    │ ── 分块 (≤2000 字符)
    │ ── 格式化 (Markdown → Discord 格式)
    ▼
Discord API 发送

7.5 Telegram 渠道实现

Telegram 渠道通过 Bot API HTTP 接口与 Telegram 通信（166 个文件）。

核心特性：

• 长轮询 (Long Polling)：使用 getUpdates API 的长轮询模式获取新消息，通过 update_offset 追踪已处理的更新
• HTTP Fetch API：直接使用 fetch 调用 Telegram Bot API（src/api-fetch.ts），不依赖大型 SDK
• 消息限制：4096 字符消息长度限制
• 内联按钮：支持 InlineKeyboard 按钮交互
• 贴纸缓存：缓存贴纸元数据以优化性能
• 反应级别：支持消息反应层级控制
• Markdown 格式：支持 MarkdownV2 格式化
• Opus 语音：TTS 输出默认使用 Opus 格式以优化 Telegram 语音消息大小

配置示例：

{
  "channels": {
    "telegram": {
      "token": "BOT_TOKEN",        // Bot Token from @BotFather
      "dmPolicy": "paired",        // 需要配对才能 DM
      "allowFrom": ["user_id_1"],  // 白名单
      "replyTo": "thread"          // 使用线程回复
    }
  }
}

7.6 Slack 渠道实现

Slack 渠道使用 @slack/bolt 框架实现（144 个文件）。

核心特性：

• Bolt 框架：基于 Slack 官方 Bolt for JavaScript 框架
• 线程对话：默认在线程中回复，保持频道整洁
• 交互式消息：支持按钮、下拉菜单、Modal 对话框
• Slack 事件订阅：通过 Events API 接收实时消息
• 工作区安装：支持 OAuth 安装流程

设置入口：独立的 slackSetupPlugin 处理 OAuth 安装配置。

7.7 飞书 (Feishu) 渠道实现

飞书是功能最强大的渠道实现之一（113 个文件），除了基础消息功能外还提供了丰富的办公工具集成。

核心特性：

• 基础消息收发（文本、图片、文件）
• 飞书专属工具集：通过 registerFull 注册额外工具
  • Bitable 工具：多维表格操作（创建、查询、更新记录）
  • Chat 工具：群组管理操作
  • Doc 工具：文档创建与编辑
  • Drive 工具：云空间文件管理
  • Perm 工具：权限管理
  • Wiki 工具：知识库操作
• 内置技能：携带自己的 skills/ 目录

// 飞书的 registerFull 注册额外工具
registerFull: (api) => {
  api.registerTool(createBitableTool(getFeishuRuntime));
  api.registerTool(createChatTool(getFeishuRuntime));
  api.registerTool(createDocTool(getFeishuRuntime));
  api.registerTool(createDriveTool(getFeishuRuntime));
  api.registerTool(createPermTool(getFeishuRuntime));
  api.registerTool(createWikiTool(getFeishuRuntime));
  registerSubagentHooks(api);
}

7.8 WhatsApp 渠道实现

WhatsApp 渠道（100 个文件）通过 WhatsApp Web 协议连接：

• QR 码登录：提供 login-qr-api.ts 实现扫码登录
• 多设备支持：兼容 WhatsApp 多设备协议
• 媒体处理：图片、视频、语音消息、文档收发
• 群组支持：群消息监听与回复

7.9 Signal 渠道实现

Signal 渠道（48 个文件）通过 Signal Protocol 实现端到端加密的消息通信：

• Signal Protocol：使用 Signal 的加密协议确保消息安全
• 标准渠道模式：遵循标准 ChannelPlugin 接口
• DM 和群组：同时支持私聊和群组消息

7.10 其他渠道概述

除上述主要渠道外，OpenClaw 还支持以下平台：

渠道	文件数	说明
Matrix	98	开源去中心化通讯协议
Microsoft Teams	85	企业通讯
Mattermost	57	开源企业通讯
BlueBubbles	51	iMessage 桥接 (macOS)
iMessage	47	Apple iMessage 直接集成
Zalo User	44	越南社交平台 (用户模式)
Tlon	41	Urbit 社交网络
Nextcloud Talk	36	自托管通讯
Zalo	34	越南社交平台 (官方 API)
Twitch	33	直播平台聊天
IRC	31	Internet Relay Chat
Google Chat	29	Google 工作区通讯
Nostr	29	去中心化社交协议
Synology Chat	20	Synology NAS 通讯
LINE	13	日韩社交平台
Xiaomi	3	小米生态

所有渠道都遵循相同的 ChannelPlugin 接口模式，确保与核心系统的一致性。

---

第八部分：AI 模型提供商系统

8.1 Provider 系统架构

Provider 系统通过统一接口抽象不同的 AI 模型提供商，每个提供商实现 ProviderPlugin 接口：

export interface ProviderPlugin {
  id: string;              // 如 "anthropic", "openai", "ollama"
  label: string;           // 显示名称
  docsPath: string;        // 文档路径
  envVars: string[];       // 相关环境变量

  /** 认证方式列表 */
  auth: AuthMethod[];

  /** 动态模型解析（前向兼容新模型） */
  resolveDynamicModel: (modelId: string) => ModelEntry | null;

  /** 提供商能力声明 */
  capabilities: {
    streaming: boolean;
    toolCalling: boolean;
    vision: boolean;
    thinking: boolean;    // 推理/思考模式
    caching: boolean;     // 提示缓存
  };

  /** 判断是否为现代模型引用格式 */
  isModernModelRef: (ref: string) => boolean;

  /** 解析默认思考级别 */
  resolveDefaultThinkingLevel: () => string;

  /** 获取用量认证信息 */
  resolveUsageAuth: () => AuthConfig;

  /** 获取用量快照 */
  fetchUsageSnapshot: () => Promise<UsageSnapshot>;

  /** 是否支持缓存 TTL */
  isCacheTtlEligible: () => boolean;

  /** 构建认证诊断提示 */
  buildAuthDoctorHint: () => string;
}

模型引用格式统一为 provider/model-name，如 anthropic/claude-opus-4-6、openai/gpt-5.4。

8.2 Anthropic (Claude) 提供商

Anthropic (Claude) 提供商通过 definePluginEntry 注册，同时提供 LLM 和媒体理解两种能力：

export default definePluginEntry({
  id: 'anthropic',
  register(api) {
    api.registerProvider(anthropicProvider);
    api.registerMediaUnderstandingProvider(anthropicMediaProvider);
  },
});

认证方式：

• setup-token：粘贴 Claude 设置令牌
• api-key：直接输入 API 密钥

动态模型解析：支持前向兼容新模型（如自动从 claude-opus-4-5 模板克隆 claude-opus-4-6）

特性：

• 思考模式 (Thinking)：Claude 4.6 默认使用 adaptive 思考级别
• 提示缓存：支持 cacheRetention（none/short/long）控制缓存策略
• 1M 上下文窗口 Beta 支持
• 每个 Agent 可单独覆盖缓存设置

环境变量：ANTHROPIC_OAUTH_TOKEN、ANTHROPIC_API_KEY

8.3 OpenAI 提供商

OpenAI 提供商注册了五种能力，是功能最全面的提供商之一：

export default definePluginEntry({
  id: 'openai',
  register(api) {
    // 1. 标准 OpenAI 提供商（API Key）
    api.registerProvider(buildOpenAIProvider());

    // 2. Codex 提供商（ChatGPT OAuth）
    api.registerProvider(buildOpenAICodexProviderPlugin());

    // 3. 语音合成
    api.registerSpeechProvider(openaiSpeechProvider);

    // 4. 媒体理解
    api.registerMediaUnderstandingProvider(openaiMediaProvider);

    // 5. 图像生成
    api.registerImageGenerationProvider(openaiImageGenProvider);
  },
});

两个独立的 LLM 提供商：

• openai：通过 API Key 认证，访问 GPT-5.4 系列
• openai-codex：通过 ChatGPT OAuth 认证，访问 Codex 系列

传输协议自动升级：连接 api.openai.com 时自动将 openai-completions API 升级为 openai-responses API

模型目录：自动注入 GPT-5.4、GPT-5.4-pro、GPT-5.4-mini、GPT-5.4-nano 等模型

8.4 Ollama 本地模型

Ollama 提供商支持本地运行的开源模型：

核心特性：

• 自动发现：探测本地/远程 Ollama 实例，通过 /api/tags 列出可用模型
• 原生 API：使用 Ollama 原生 /api/chat 接口（非 OpenAI 兼容模式），支持流式输出和工具调用
• 模型拉取：通过 ensureOllamaModelPulled 自动拉取所需模型
• 云模型：支持 kimi-k2.5:cloud、minimax-m2.5:cloud、glm-5:cloud 等云端模型
• 上下文窗口处理：自动管理模型的上下文窗口限制

引导向导：

• Cloud 模式：使用远程 Ollama 服务
• Local 模式：使用本地 Ollama 实例

配置：

{
  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://localhost:11434",
        "command": "ollama",  // Ollama 命令路径
        "apiKey": "ollama-local"  // 默认本地密钥
      }
    }
  }
}

8.5 其他提供商概述

OpenClaw 支持 30+ 个 AI 模型提供商：

提供商	ID	说明
Google AI	google	Gemini 系列
Mistral	mistral	Mistral 系列
Moonshot	moonshot	Kimi 系列
Perplexity	perplexity	搜索增强
OpenRouter	openrouter	多模型路由
xAI	xai	Grok 系列
Together AI	together	开源模型托管
Hugging Face	huggingface	开源模型
vLLM	vllm	本地推理服务
BytePlus	byteplus	字节跳动
Qianfan	qianfan	百度千帆
Volcengine	volcengine	火山引擎
MiniMax	minimax	MiniMax
ModelStudio	modelstudio	阿里模型工坊
Amazon Bedrock	amazon-bedrock	AWS 托管模型
NVIDIA	nvidia	NVIDIA NIM
Kimi Coding	kimi-coding	Kimi 编程
Chutes	chutes	Chutes AI
Venice	venice	Venice AI
SGLang	sglang	本地推理框架
Synthetic	synthetic	合成/模拟提供商
Z.AI	zai	Z.AI
Qwen Portal	qwen-portal-auth	通义千问
Cloudflare AI Gateway	cloudflare-ai-gateway	CF 代理
Vercel AI Gateway	vercel-ai-gateway	Vercel 代理
Copilot Proxy	copilot-proxy	GitHub Copilot
GitHub Copilot	github-copilot	GitHub Copilot

所有提供商遵循相同的 ProviderPlugin 接口，通过统一的 provider/model 引用格式使用。

---

第九部分：配置系统

9.1 配置系统架构

配置系统是 OpenClaw 运行的基础，基于 JSON5 格式的配置文件驱动所有行为。

核心组件：

• src/config/io.ts：配置读写引擎
• src/config/types.ts：37 个配置域的类型定义
• src/config/validation.ts：配置校验
• src/config/runtime-overrides.ts：运行时覆盖
• src/config/paths.ts：路径解析
• src/config/legacy-migrate.ts：旧版迁移

9.2 配置文件格式与加载

配置文件位于 ~/.openclaw/openclaw.json（JSON5 格式），支持注释和环境变量替换：

{
  // 全局模型配置
  "models": {
    "default": "anthropic/claude-opus-4-6",
    "providers": {
      "anthropic": {
        "apiKey": "${ANTHROPIC_API_KEY}"  // 环境变量替换
      }
    }
  },

  // 渠道配置
  "channels": {
    "telegram": {
      "token": "${TELEGRAM_BOT_TOKEN}",
      "dmPolicy": "paired",
      "allowFrom": ["*"]
    },
    "discord": {
      "token": "${DISCORD_BOT_TOKEN}"
    }
  },

  // Agent 配置
  "agents": {
    "default": "assistant",
    "list": {
      "assistant": {
        "model": "anthropic/claude-opus-4-6",
        "skills": ["coding-agent", "github"],
        "memory": { "enabled": true }
      }
    }
  },

  // 网关配置
  "gateway": {
    "port": 3000,
    "bind": "loopback",
    "auth": {
      "token": "${GATEWAY_TOKEN}"
    }
  },

  // 环境变量块
  "env": {
    "ANTHROPIC_API_KEY": "sk-xxx"
  }
}

配置 I/O 引擎 (src/config/io.ts)

/**
 * 加载配置文件
 * 1. 读取 JSON5 文件
 * 2. 执行环境变量替换 (${VAR} 语法)
 * 3. 处理配置包含 (includes)
 * 4. 应用默认值
 * 5. 执行 Shell 环境变量回退
 * 6. 缓存结果
 */
export async function loadConfig(profile?: string): Promise<OpenClawConfig> {
  const configPath = resolveConfigPath(profile);
  const raw = await readFile(configPath, 'utf-8');

  // 解析 JSON5
  let config = parseConfigJson5(raw);

  // 环境变量替换
  config = substituteEnvVars(config);

  // 处理 includes
  if (config.includes) {
    for (const includePath of config.includes) {
      const included = await loadConfig(includePath);
      config = deepMerge(config, included);
    }
  }

  // 应用默认值
  config = applyDefaults(config);

  // 验证
  const errors = validateConfig(config);
  if (errors.length > 0) {
    // 记录验证警告，但不阻止启动
    for (const err of errors) {
      logger.warn(`Config warning: ${err}`);
    }
  }

  // 缓存
  configCache.set(profile ?? 'default', config);

  return config;
}

配置备份与审计

配置修改时自动创建备份文件（openclaw.json.bak.N），支持配置审计日志记录所有变更。

9.3 环境变量体系

环境变量按以下优先级解析（从高到低）：

1. 进程环境变量 (process.env)：命令行直接设置的变量
2. 当前目录 .env (CWD/.env)：项目级环境文件
3. 全局 .env (~/.openclaw/.env)：用户级环境文件
4. 配置 env 块 (openclaw.json 中的 "env": {})：配置文件内嵌变量
5. Shell 环境导入 (shellEnv.enabled)：从 Shell profile 导入变量

${VAR} 替换语法

配置文件中的所有字符串值都支持 ${VAR_NAME} 替换：

{
  "models": {
    "providers": {
      "anthropic": {
        "apiKey": "${ANTHROPIC_API_KEY}"  // 运行时替换为实际值
      }
    }
  },
  "gateway": {
    "port": "${GATEWAY_PORT:-3000}"  // 支持默认值语法
  }
}

Shell 环境导入

当 shellEnv.enabled 为 true 时，OpenClaw 会从用户的 Shell profile（_/.bashrc、/.zshrc 等）中导入环境变量，这对于不使用 .env 文件的用户非常方便。

9.4 配置域详解

配置系统覆盖 37 个域，每个域有独立的类型定义：

域	配置路径	说明
agents	agents.*	Agent 列表、默认 Agent、Agent 特定配置
acp	acp.*	ACP 协议启用、调度、白名单
approvals	approvals.*	执行审批策略
auth	auth.*	认证配置
browser	browser.*	浏览器自动化配置
channels	channels.*	各渠道配置
cli	cli.*	CLI 行为配置
cron	cron.*	定时任务列表
gateway	gateway.*	网关端口、绑定、认证
hooks	hooks.*	Hook 启用、配置
messages	messages.*	消息处理策略
models	models.*	模型提供商、默认模型
plugins	plugins.*	插件启用/禁用
sandbox	sandbox.*	沙箱隔离配置
secrets	secrets.*	凭据管理
skills	skills.*	技能启用、路径
tts	tts.*	语音合成配置
tools	tools.*	工具策略
memory	memory.*	记忆系统配置
sessions	sessions.*	会话策略
logging	logging.*	日志级别、输出
mcp	mcp.*	MCP 服务器配置
search	search.*	搜索引擎配置

9.5 配置热重载

Gateway 支持配置热重载，通过 config.reload RPC 方法或文件变更监听触发：

1. 重新读取配置文件
2. 验证新配置
3. 差异比较确定变更项
4. 按需重新初始化受影响的子系统
5. 无需重启 Gateway 进程

---

第十部分：会话管理

10.1 会话模型

会话是 OpenClaw 管理对话上下文的核心机制。每个对话维护独立的消息历史和状态。

会话作用域

作用域	Key 格式	说明
Per-Sender (DM)	agent:<agentId>:dm:<channelId>:<senderId>	每个用户的私聊独立会话
Per-Channel-Peer (群组)	agent:<agentId>:group:<channelId>:<groupId>	每个群组独立会话
Main	agent:<agentId>:main	系统级主会话

会话重置策略

{
  "sessions": {
    "resetPolicy": {
      "mode": "daily",       // 每日重置
      // 或
      "mode": "idle",        // 空闲后重置
      "idleTimeout": 3600000 // 1 小时无活动后重置
    }
  }
}

10.2 会话存储

会话以 JSONL（JSON Lines）格式存储为文件，每行一条消息记录：

{"role":"system","content":"You are a helpful assistant...","timestamp":"2026-03-17T10:00:00Z"}
{"role":"user","content":"Hello!","timestamp":"2026-03-17T10:00:01Z","sender":"user123","channel":"telegram"}
{"role":"assistant","content":"Hi there!","timestamp":"2026-03-17T10:00:02Z","usage":{"promptTokens":100,"completionTokens":50}}

存储路径：~/.openclaw/sessions/<session-key>.jsonl

10.3 会话策略

src/sessions/ 模块提供以下策略控制：

• send-policy.ts：每会话发送策略（允许/拒绝特定渠道、聊天类型）
• model-overrides.ts：每会话模型覆盖（用户切换模型时记录）
• level-overrides.ts：每会话 verbose 级别
• input-provenance.ts：追踪消息来源元数据
• transcript-events.ts：会话更新事件发射，通知其他子系统

---

第十一部分：自动回复引擎

11.1 回复引擎架构

自动回复引擎 (src/auto-reply/) 是连接渠道消息和 Agent 系统的桥梁（300 个文件），负责消息的预处理和 Agent 调度。

11.2 消息处理流水线

getReplyFromConfig() 是自动回复引擎的核心函数，定义了完整的消息处理流水线：

export async function getReplyFromConfig(params: ReplyParams): Promise<ReplyResult> {
  // 阶段 1: 解析 Agent 身份
  const agentId = resolveAgentId(params);
  const agentConfig = resolveAgentConfig(agentId, params.config);

  // 阶段 2: 解析模型和工作区
  const model = selectModel(agentConfig, params);
  const workspace = resolveWorkspace(agentConfig);
  const skills = filterSkills(agentConfig, params.config);

  // 阶段 3: 媒体理解
  //   如果消息包含图片，调用视觉模型提取描述
  if (params.message.images?.length > 0) {
    const descriptions = await understandMedia(params.message.images, params.config);
    params.message.mediaContext = descriptions;
  }

  // 阶段 4: 音频理解
  //   如果消息是语音消息，调用 STT 转录
  if (params.message.audio) {
    const transcript = await transcribeAudio(params.message.audio, params.config);
    params.message.text = transcript;
    params.message.audioTranscript = transcript;
  }

  // 阶段 5: 链接理解
  //   提取消息中的 URL，获取网页内容摘要
  if (containsUrls(params.message.text)) {
    const linkContext = await understandLinks(params.message.text, params.config);
    params.message.linkContext = linkContext;
  }

  // 阶段 6: 执行 pre-agent Hook
  await emitHook('before_agent_start', {
    message: params.message,
    agentId,
    sessionKey: params.sessionKey,
  });

  // 阶段 7: 管理输入指示器
  const typingIndicator = startTypingIndicator(params.channel, params.target);

  // 阶段 8: 命令授权检查
  if (isCommand(params.message.text)) {
    const authorized = checkCommandAuth(params);
    if (!authorized) return { text: 'Unauthorized', blocked: true };
  }

  // 阶段 9: 初始化会话状态
  const session = await initSession(params.sessionKey, agentId);

  // 阶段 10: 模型覆盖应用
  const finalModel = applyModelOverrides(model, params);

  // 阶段 11: 委托给 Agent 系统
  const result = await runPreparedReply({
    message: params.message,
    model: finalModel,
    agentConfig,
    session,
    workspace,
    skills,
    pluginRegistry: params.pluginRegistry,
  });

  // 阶段 12: 停止输入指示器
  typingIndicator.stop();

  return result;
}

11.3 指令系统

自动回复引擎支持以下指令前缀：

指令	功能	示例
think	启用推理/思考模式	消息前加入思考标记
reasoning	设置推理级别	low/medium/high
verbose	启用详细输出	显示工具调用细节
elevated	提升权限	允许执行高权限工具
exec	命令执行	直接执行系统命令
queue	队列处理	将消息加入处理队列

---

第十二部分：Hook 系统

12.1 Hook 系统架构

Hook 系统提供了事件驱动的扩展机制，允许在系统生命周期的关键节点执行自定义逻辑。

Hook 数据模型：

interface Hook {
  name: string;
  description: string;
  source: 'bundled' | 'managed' | 'workspace' | 'plugin';
  filePath: string;
  handlerPath: string;
}

interface HookEntry extends Hook {
  frontmatter: Record<string, unknown>;
  metadata: OpenClawHookMetadata;
  invocationPolicy: 'always' | 'once' | 'conditional';
}

interface OpenClawHookMetadata {
  events: string[];           // 触发事件列表
  os?: string[];              // OS 要求
  bins?: string[];            // 二进制依赖
  envVars?: string[];         // 环境变量依赖
  configPaths?: string[];     // 配置依赖
  install?: InstallSpec[];    // 安装方式
}

12.2 事件类型

事件类别	事件名称	触发时机
command	command.before	CLI 命令执行前
	command.after	CLI 命令执行后
session	session.created	会话创建时
	session.reset	会话重置时
agent	before_agent_start	Agent 轮次开始前
	agent_end	Agent 轮次结束后
gateway	gateway.started	Gateway 启动完成
	gateway.stopping	Gateway 即将停止
message	message.received	消息收到时
	message.sent	消息发送后
	message.transcribed	语音转文字完成
	message.preprocessed	消息预处理完成

每个事件携带丰富的上下文信息（发送者、渠道、对话、元数据等）。

12.3 Hook 来源与管理

Hook 可以来自多个来源：

1. 内置 (bundled)：OpenClaw 自带的 Hook
2. npm 包 (managed)：通过 openclaw hooks install 安装的 npm 包
3. Git 仓库：从 Git 仓库安装
4. 工作区 (workspace)：Agent 工作区目录下的 Hook 文件
5. 插件注册 (plugin)：通过 api.registerHook() 注册

Hook 管理命令：

openclaw hooks list            # 列出所有 Hook
openclaw hooks install <pkg>   # 安装 Hook
openclaw hooks remove <name>   # 移除 Hook

---

第十三部分：记忆系统

13.1 记忆系统架构

记忆系统使 Agent 具有长期记忆能力，跨会话保留重要信息。

src/memory/search-manager.ts 实现了带降级的记忆搜索：

/**
 * FallbackMemoryManager
 * 主要后端: QMD (Quantum Memory Database)
 * 降级后端: 内置 MemoryIndexManager
 *
 * 当 QMD 不可用或出错时，自动降级到内置引擎
 */
export class FallbackMemoryManager {
  private qmd: QmdMemoryManager | null;
  private builtin: MemoryIndexManager;
  private cache: Map<string, MemoryManager>; // 按 agentId + config 缓存

  async search(query: string, opts: SearchOptions): Promise<MemoryResult[]> {
    try {
      if (this.qmd) {
        return await this.qmd.search(query, opts);
      }
    } catch (error) {
      logger.warn('QMD search failed, falling back to builtin');
    }
    return this.builtin.search(query, opts);
  }

  async readFile(params: ReadParams): Promise<string> {
    // 同样的降级逻辑
  }

  close(): void {
    this.qmd?.close();
    this.builtin.close();
    this.cache.clear();
  }
}

13.2 LanceDB 向量存储

extensions/memory-lancedb/ 提供基于 LanceDB 向量数据库的记忆存储：

三个工具：

• memory_recall：向量搜索，将查询嵌入为向量后在 LanceDB 中执行 ANN 搜索
• memory_store：嵌入文本并存储，带去重检测（避免重复存储相同信息）
• memory_forget：按 ID 或搜索条件删除记忆

向量搜索实现：

// L2 距离 → 相似度分数转换
function l2ToSimilarity(l2Distance: number): number {
  return 1 / (1 + l2Distance);
}

async function searchMemories(query: string, topK: number = 10): Promise<Memory[]> {
  const embedding = await embedText(query); // 使用配置的嵌入模型
  const results = await lanceTable.search(embedding)
    .limit(topK)
    .execute();

  return results.map(r => ({
    id: r.id,
    text: r.text,
    similarity: l2ToSimilarity(r._distance),
    timestamp: r.timestamp,
  }));
}

安全措施：

• 提示注入检测 (looksLikePromptInjection)
• HTML 实体转义
• 记忆内容用 <relevant-memories> XML 标签包裹，标注为"不可信数据"

13.3 自动记忆与召回

Memory LanceDB 扩展通过两个 Hook 实现自动记忆管理：

自动召回 (before_agent_start Hook)：

1. 将用户消息嵌入为向量
2. 在 LanceDB 中搜索相关记忆
3. 将匹配的记忆作为 <relevant-memories> XML 注入到 Agent 的上下文中

自动捕获 (agent_end Hook)：

1. 扫描用户消息，检测触发模式（偏好、联系人、决策等）
2. 将识别到的信息嵌入并存储
3. 去重检查防止重复存储

配置：

{
  "memory": {
    "embedding": {
      "apiKey": "${OPENAI_API_KEY}",
      "model": "text-embedding-3-small",
      "dimensions": 1536
    },
    "dbPath": "~/.openclaw/memory.lancedb",
    "autoCapture": true,      // 自动捕获
    "autoRecall": true,       // 自动召回
    "captureMaxChars": 5000   // 最大捕获长度
  }
}

---

第十四部分：ACP 协议

14.1 ACP 概述

ACP (Agent Control Protocol) 是一个标准化的 Agent 通信协议，用于在沙箱环境中安全地执行 Agent 任务。OpenClaw 同时实现了 ACP 服务端和客户端。

核心模块：

• src/acp/policy.ts：策略执行（启用/禁用、调度、Agent 白名单）
• src/acp/server.ts：ACP 网关服务器
• src/acp/translator.ts：ACP ↔ OpenClaw Gateway RPC 协议翻译器

14.2 ACP 服务端

src/acp/server.ts 启动 ACP 网关服务器，作为 WebSocket 客户端连接到 OpenClaw Gateway：

export async function serveAcpGateway(config: OpenClawConfig): Promise<void> {
  const gatewayClient = new GatewayClient({
    host: config.gateway.host,
    port: config.gateway.port,
    auth: { mode: 'token', token: config.gateway.auth.token },
    clientType: 'acp',
  });

  await gatewayClient.connect();

  // 创建 ACP 协议翻译器
  const translator = new AcpGatewayAgent(gatewayClient, config);

  // 监听 ACP 客户端连接
  // translator 实现了 @agentclientprotocol/sdk 的 Agent 接口
  // 将 ACP 请求翻译为 Gateway RPC 调用
}

src/acp/translator.ts 翻译器支持：

• initialize/authenticate：ACP 握手 → Gateway 认证
• prompt：ACP 任务 → Gateway agent.run
• cancel：取消任务
• sessions：会话管理
• 配置选项：thought_level、fast_mode、verbose_level、reasoning_level
• 安全限制：提示大小 2MB 上限、速率限制

14.3 ACPX 运行时

extensions/acpx/ 提供 ACP 运行时后端，作为 Gateway 插件服务运行：

// 注册为后台服务
api.registerService(createAcpxRuntimeService(config));

配置项：

{
  "acp": {
    "enabled": true,
    "dispatch": { "enabled": true },
    "runtime": {
      "command": "acpx",
      "expectedVersion": "1.x",
      "cwd": "~/.openclaw/acp",
      "permissionMode": "approve-all",  // 或 "approve-reads", "deny-all"
      "nonInteractivePermissions": ["read"],
      "timeoutSeconds": 300,
      "queueOwnerTtlSeconds": 600,
      "mcpServers": {
        // MCP 服务器注入到 ACP 环境
        "filesystem": { "command": "mcp-filesystem", "args": ["/workspace"] }
      }
    }
  }
}

---

第十五部分：定时任务系统

15.1 Cron 服务

src/cron/service.ts 实现了 CronService 类，管理定时任务：

export class CronService {
  private jobs: Map<string, CronJob>;
  private store: PersistentStore;

  constructor(config: OpenClawConfig, logger: Logger) {
    this.jobs = new Map();
    this.store = new PersistentStore(config);
  }

  async start(): Promise<void> {
    // 从持久化存储恢复任务
    const savedJobs = await this.store.loadAll();
    for (const job of savedJobs) {
      this.scheduleJob(job);
    }
  }

  // CRUD 操作
  async add(job: CronJobDef): Promise<string>;
  async update(id: string, updates: Partial<CronJobDef>): Promise<void>;
  async remove(id: string): Promise<void>;
  async run(id: string): Promise<void>;        // 立即执行
  async enqueueRun(id: string): Promise<void>; // 加入执行队列
  list(): CronJobStatus[];
  status(id: string): CronJobStatus;
  stop(): void;
}

src/cron/schedule.ts 使用 croner 库处理三种调度类型：

类型	配置	示例
at	一次性执行	{ kind: "at", time: "2026-03-17T15:00:00Z" }
every	间隔执行	{ kind: "every", interval: "30m" }
cron	Cron 表达式	{ kind: "cron", expression: "0 9 * * 1-5" }

所有调度都是时区感知的，使用用户配置的时区。

15.2 心跳机制

心跳机制与 Cron 不同，它是在主会话上下文中进行周期性检查：

• Cron：精确调度，在隔离会话中运行，适合定时任务
• 心跳 (Heartbeat)：在主会话中周期性检查，适合批量状态更新

{
  "heartbeat": {
    "enabled": true,
    "interval": "5m",           // 每 5 分钟
    "model": "openai/gpt-4o-mini", // 使用经济型模型
    "prompt": "Check for new emails and summarize any unread ones."
  }
}

---

第十六部分：浏览器自动化

16.1 浏览器管理

src/browser/chrome.ts 管理 Chrome 浏览器实例：

interface RunningChrome {
  pid: number;
  executable: string;
  userDataDir: string;
  cdpPort: number;           // Chrome DevTools Protocol 端口
  process: ChildProcess;
}

• 以 CDP 调试模式启动 Chrome
• 跨平台可执行文件解析（macOS/Linux/Windows）
• Profile 装饰：标记为 OpenClaw 管理的浏览器实例
• 支持容器化运行（浏览器在 Docker 容器中）

16.2 CDP 协议操作

src/browser/cdp.ts 实现 Chrome DevTools Protocol 操作：

// URL 处理
function normalizeCdpWsUrl(url: string): string {
  // 容器环境中 0.0.0.0 → 外部主机
  return url.replace('0.0.0.0', resolveExternalHost());
}

// 截图捕获
async function captureScreenshot(cdpClient: CdpClient): Promise<Buffer> {
  const metrics = await cdpClient.send('Page.getLayoutMetrics');
  const screenshot = await cdpClient.send('Page.captureScreenshot', {
    format: 'png',
    clip: {
      x: 0, y: 0,
      width: metrics.cssContentSize.width,
      height: metrics.cssContentSize.height,
      scale: 1,
    },
  });
  return Buffer.from(screenshot.data, 'base64');
}

安全措施：

• 导航守卫：防止访问内部网络地址
• SSRF 防护：检查目标 URL，阻止服务端请求伪造攻击

---

第十七部分：语音系统

17.1 语音转文字 (STT)

语音转文字 (STT) 支持自动检测链：

sherpa-onnx (本地, 最快)
    ↓ 不可用
whisper-cli (本地 CLI)
    ↓ 不可用
whisper Python (本地 Python)
    ↓ 不可用
Gemini CLI (Google STT)
    ↓ 不可用
Provider API Keys (Deepgram/OpenAI/Groq/Google)

配置项：

• maxBytes：最大音频大小 20MB
• 作用域规则：按 chatType (DM/group) 控制 allow/deny
• 转录结果作为 {{Transcript}} 模板变量可用

17.2 文字转语音 (TTS)

src/tts/tts.ts 实现文字转语音引擎：

提供商：

提供商	说明	需要 API Key
Edge TTS	微软边缘 TTS（免费默认）	否
OpenAI TTS	OpenAI 语音合成	是
ElevenLabs	高质量 AI 语音	是
插件提供商	通过 registerSpeechProvider 注册	取决于插件

自动模式：

模式	行为
off	不生成语音
always	每次回复都生成语音
inbound	仅当收到语音消息时以语音回复
tagged	仅当 Agent 使用 [[tts:...]] 指令时

输出格式优化：

• Telegram：Opus 格式（语音消息体积小）
• 其他平台：MP3 格式

长文本处理：超过长度限制的回复自动生成摘要后再合成语音

17.3 语音通话

extensions/voice-call/ 提供完整的电话通话能力（65 个文件）：

支持的电话提供商：Telnyx、Twilio、Plivo、Mock（测试用）

工具: voice_call 支持多个动作：

• initiate_call：发起电话
• continue_call：继续通话
• speak_to_user：向用户说话
• end_call：结束通话
• get_status：获取通话状态

Gateway RPC 方法：voicecall.initiate、voicecall.continue、voicecall.speak、voicecall.end、voicecall.status、voicecall.start

配置涵盖：电话号码、入站策略、Webhook 服务、隧道（ngrok/Tailscale）、流式 STT (OpenAI Realtime)、TTS、通话参数（时长、静默超时、并发数）。

---

第十八部分：安全体系

18.1 安全模型

OpenClaw 采用多层安全模型：

渠道层安全：

• DM 策略：open（任何人可发送）、paired（需配对确认）、closed（仅白名单）
• 白名单：allowFrom 列表控制允许的发送者
• 群组策略：@提及门控（仅当被提及时回复）
• 群组工具策略：每个群组可限制可用工具

网关层安全：

• Token/密码认证
• 角色授权（operator/node/acp/readonly）
• 操作范围（read/write/admin）
• 速率限制

Agent 层安全：

• 工具策略（allow/deny 列表）
• 提权控制（elevated 工具需要确认）
• 执行审批（exec 命令需操作者确认）

执行层安全：

• Docker 沙箱（网络隔离、资源限制）
• SSRF 防护
• 安全正则检查
• 技能安全扫描

18.2 安全审计

src/security/audit.ts 实现全面的安全审计：

interface SecurityAuditReport {
  findings: SecurityFinding[];
  score: number; // 0-100 安全评分
}

interface SecurityFinding {
  severity: 'info' | 'warn' | 'critical';
  category: string;
  message: string;
  recommendation: string;
}

审计检查项：

检查项	说明
文件系统权限	配置文件、凭据文件权限检查
渠道安全	白名单配置、DM 策略检查
沙箱配置	Docker 沙箱是否启用
浏览器 CDP 暴露	CDP 端口是否对外开放
网络策略	网关绑定是否安全
Safe-bin 策略	可执行文件路径策略
Gateway 认证	是否配置了认证
Docker 标签	容器安全标签检查

可通过 openclaw audit CLI 命令或 health.audit RPC 方法执行。深度模式还会探测运行中的 Gateway。

18.3 沙箱隔离

Docker 沙箱提供进程级隔离。三个 Dockerfile：

• Dockerfile.sandbox-common：公共基础（Node.js 运行时、基本工具）
• Dockerfile.sandbox：标准沙箱（基于 common，无浏览器）
• Dockerfile.sandbox-browser：浏览器沙箱（包含 Chromium）

沙箱限制：

• 网络隔离（network: "none"）
• 内存限制
• CPU 限制
• 只读文件系统挂载
• 超时强制终止

---

第十九部分：Skills 技能系统

19.1 Skills 架构

Skills 是基于 Markdown 的指令文件，通过 SKILL.md 前置元数据声明能力和依赖，内容则是 Agent 的行为指令。

技能加载流程：

1. 扫描 skills/ 目录和扩展携带的技能
2. 解析 SKILL.md 前置元数据
3. 检查依赖（二进制文件、配置项、环境变量）
4. 满足条件的技能被加载到 Agent 的技能快照中
5. 技能内容注入到 Agent 系统提示

19.2 SKILL.md 规范

---
name: my-skill
description: "When to use this skill and when NOT to use it"
homepage: https://example.com
metadata:
  openclaw:
    emoji: "🔧"
    requires:
      bins:                    # 硬性要求的二进制文件
        - "gh"
      anyBins:                 # 至少需要其中一个
        - "curl"
        - "wget"
      config:                  # 必需的配置路径
        - "channels.slack"
    install:                   # 自动安装方式
      - id: brew
        kind: brew
        formula: gh
      - id: apt
        kind: apt
        package: gh
---

# My Skill

这里是技能的指令内容，会被注入到 Agent 的系统提示中。
Agent 将根据这些指令来执行相关操作。

## 使用方法
- 当用户请求 X 时，执行 Y 命令
- 格式化输出为 Z

## 注意事项
- 不要执行危险操作
- 确认前先说明计划

关键字段说明

字段	类型	说明
name	string	技能唯一名称
description	string	何时使用（及何时不使用）此技能
requires.bins	string[]	必须全部存在的二进制文件
requires.anyBins	string[]	至少一个存在的二进制文件
requires.config	string[]	必须存在的配置路径
install	InstallSpec[]	自动安装方式（brew/apt 等）

19.3 代表性技能详解

coding-agent 技能

编排外部编码 Agent（Codex、Claude Code、Pi、OpenCode），支持：

• 一次性编码任务
• 后台会话模式
• 并行 PR 审查
• Git worktree 工作流

github 技能

封装 gh CLI 操作：Issues、PR、CI、API 查询。要求 gh 二进制文件，提供 brew/apt 安装方式。

slack 技能

Slack 消息操作：回应、固定、发送、编辑、删除、阅读、成员信息、表情列表。要求 channels.slack 配置。

weather 技能

通过 curl 查询 wttr.in 获取天气信息，无需 API 密钥。

完整技能清单（52 个）

生产力: 1password, apple-notes, apple-reminders, bear-notes, notion, obsidian, things-mac, trello
通讯: discord, github, slack, imsg (iMessage), gh-issues
媒体: camsnap, gifgrep, openai-image-gen, openai-whisper, video-frames, sherpa-onnx-tts
工具: tmux, node-connect, goplaces, weather, spotify-player, sonoscli, wacli, eightctl
开发: coding-agent, skill-creator, clawhub, oracle, peekaboo, session-logs
系统: healthcheck, himalaya (email), openhue, ordercli, sag, summarize, xurl
数据: bluebubbles (blucli), gog, mcporter, nano-banana-pro, nano-pdf, blogwatcher

---

第二十部分：原生应用

20.1 iOS 应用

Swift/SwiftUI 原生应用，通过 WebSocket 连接到 Gateway：

• Sources/: SwiftUI 视图和逻辑
• ActivityWidget/: 桌面小组件，显示 Agent 状态
• ShareExtension/: 分享扩展，从其他应用发送内容到 OpenClaw
• WatchApp/: Apple Watch 应用，快速查看和回复
• fastlane/: TestFlight 自动化部署
• Config/: 构建配置

通过 WebSocket 使用 chat.history、chat.send、chat.inject 等 RPC 方法与 Gateway 交互。

20.2 macOS 应用

Swift/SwiftUI 桌面应用：

• 菜单栏常驻快速访问
• 远程控制功能（SSH/Tailscale 隧道）
• 完整的聊天 UI（WebChat 组件）
• 与 iOS 共享 OpenClawKit 框架

20.3 Android 应用

Kotlin 原生应用：

• Gradle 构建系统
• Material Design UI
• 内含性能基准测试 (benchmark/)
• WebSocket Gateway 连接

20.4 共享框架 OpenClawKit

apps/shared/OpenClawKit/ 是 iOS 和 macOS 共享的 Swift 框架：

• Gateway 客户端封装（WebSocket 连接、认证、RPC 调用）
• 聊天 UI 组件
• 工具集成（Canvas A2UI）
• 设备配对逻辑

Swabble/ 是独立的 Swift CLI 框架：

• SwabbleCore/：核心功能
• SwabbleKit/：公共 API
• swabble/：CLI 工具
• 用于构建 Swift 命令行工具

---

第二十一部分：构建与部署

21.1 构建系统

项目使用 pnpm workspace 单仓库模式管理：

核心构建工具：

• tsdown：TypeScript 打包器，配置在 tsdown.config.ts
• TypeScript 5.x：严格模式，ES2023 目标
• pnpm：包管理与工作区管理

关键 npm 脚本（77 个）：

# 构建
pnpm build              # 完整构建（包含 A2UI 打包、Plugin SDK）
pnpm build:docker       # Docker 构建（不含 A2UI）

# 测试
pnpm test               # 完整测试套件
pnpm test:force         # 强制运行全部测试
pnpm test:coverage      # 覆盖率测试（70% 阈值）
pnpm test:e2e           # Gateway E2E 测试
pnpm test:live          # 提供商实时测试
pnpm test:docker:*      # Docker 集成测试

# 代码质量
pnpm lint               # Oxlint 代码检查
pnpm format             # Oxfmt 格式化

# 文档
pnpm docs:dev           # 启动文档开发服务器

TypeScript 配置（tsconfig.json）：

{
  "compilerOptions": {
    "target": "es2023",
    "module": "node16",
    "moduleResolution": "node16",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "dist",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  }
}

21.2 Docker 容器化

四个 Dockerfile 满足不同场景：

Dockerfile — 主服务容器：

FROM node:22-slim
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN npm install -g pnpm && pnpm install --frozen-lockfile --prod
COPY dist/ dist/
COPY openclaw.mjs ./
EXPOSE 3000
CMD ["node", "openclaw.mjs", "gateway", "start"]

Dockerfile.sandbox-common — 沙箱公共基础：

• Node.js 22 运行时
• 基本系统工具
• 非 root 用户

Dockerfile.sandbox — 标准沙箱：

• 基于 sandbox-common
• 无网络访问
• 资源限制

Dockerfile.sandbox-browser — 浏览器沙箱：

• 基于 sandbox-common
• 包含 Chromium
• 用于浏览器自动化任务

docker-compose.yml 编排：

services:
  gateway:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - ./config:/root/.openclaw
    environment:
      - ANTHROPIC_API_KEY
      - TELEGRAM_BOT_TOKEN
    restart: unless-stopped

21.3 部署方案

支持多种部署方式：

方式	命令/说明	适用场景
npm 全局安装	npm install -g openclaw	个人开发者
pnpm 全局安装	pnpm add -g openclaw	个人开发者
Docker	docker run openclaw	服务器部署
Podman	podman run openclaw	无 root Docker 替代
Nix	nix profile install openclaw	Nix 用户
Fly.io	fly launch	边缘部署
Render	render.yaml 自动部署	PaaS
DigitalOcean	Droplet + Docker	VPS
Hetzner	VPS + Docker	欧洲 VPS
Raspberry Pi	ARM 原生运行	家庭服务器
Ansible	自动化部署脚本	批量部署

---

第二十二部分：测试体系

22.1 测试框架

使用 Vitest 测试框架，V8 覆盖率引擎：

配置文件：

文件	用途
vitest.config.ts	默认单元测试
vitest.e2e.config.ts	Gateway E2E 测试
vitest.extensions.config.ts	扩展测试
vitest.gateway.config.ts	网关测试
vitest.live.config.ts	提供商实时测试

覆盖率要求：全局 70% 阈值

22.2 测试策略

测试采用分层策略：

1. 单元测试：与源码同目录的 *.test.ts 文件，测试单个函数/模块
2. 集成测试：测试模块间交互（如插件注册 → 渠道启动）
3. E2E 测试：完整的 Gateway 启动 → 消息收发 → 关闭流程
4. 实时测试：连接真实的 AI 提供商 API 验证兼容性
5. Docker 测试：容器化环境中的端到端测试
6. 模型基准测试：bench-model.ts 测量各模型的延迟和吞吐
7. 烟雾测试：Docker E2E 引导测试、QR 导入测试

# 运行测试示例
pnpm test                  # 全部单元测试
pnpm test:coverage         # 带覆盖率报告
pnpm test:e2e              # E2E 测试
pnpm test:live -- --model anthropic/claude-opus-4-6  # 实时提供商测试
pnpm test:docker:onboard   # Docker 引导烟雾测试

---

第二十三部分：Webhook 与自动化

23.1 Webhook 机制

Webhook 提供 HTTP 端点用于外部系统触发 Agent 操作：

内置端点：

• /hooks/wake：唤醒 Agent（触发心跳检查）
• /hooks/agent：触发 Agent 任务
• 自定义映射：通过配置添加自定义 Webhook 路由

{
  "hooks": {
    "webhooks": {
      "enabled": true,
      "endpoints": {
        "/hooks/deploy-notify": {
          "agent": "assistant",
          "template": "Deploy notification: {{body.message}}"
        }
      }
    }
  }
}

Webhook 请求会被转换为 Agent 任务，结果可以通过配置的渠道投递。

23.2 自动化集成

自动化能力总结：

机制	触发方式	会话上下文	适用场景
Cron	时间表达式	隔离会话	定时报告、定期检查
Heartbeat	间隔时间	主会话	批量状态更新、轮询
Webhook	HTTP 请求	新建/指定会话	外部系统集成
Hook	内部事件	事件上下文	消息预处理、自动操作

---

第二十四部分：Clawnet 重构规划

24.1 重构目标

Clawnet 是一个正在规划中的重大重构项目，目标是将现有的两套通信协议统一为一个：

现状：

1. Gateway WS 控制面：CLI/App → Gateway 的 RPC 协议
2. Bridge 节点传输：移动节点 → Gateway 的数据传输协议

目标：统一为一个 WS 协议，支持：

• 角色：node（设备节点）vs operator（管理者）
• 范围：read/write/admin
• 统一认证 + 配对（设备绑定密钥）
• 全链路 TLS
• 集中化审批路由到操作者客户端
• 稳定设备 ID + 龙虾主题别名
• 6 阶段迁移计划

24.2 迁移计划

Clawnet 迁移分为 6 个阶段：

1. 协议定义：设计统一的 WS 帧格式和认证流程
2. 双协议支持：Gateway 同时支持旧协议和新协议
3. 客户端迁移：CLI、iOS/macOS/Android 应用迁移到新协议
4. 节点迁移：设备节点迁移到新协议
5. 旧协议废弃：标记旧协议为已废弃
6. 清理：移除旧协议代码

---

第二十五部分：全部扩展清单与分析

25.1 通信渠道扩展

22 个通信渠道扩展

扩展	文件数	协议/SDK	核心实现方式
discord	201	Discord.js / Gateway WebSocket	WebSocket 实时监听，2000 字符分块，Embeds/Components/Polls
telegram	166	Telegram Bot API / HTTP Long Polling	fetch 直接调用 API，update_offset 追踪，4096 字符限制
slack	144	@slack/bolt / Events API	Bolt 框架，线程回复，OAuth 安装
feishu	113	飞书开放平台 API	消息+Bitable+Doc+Drive+Wiki+Perm 六大工具集
whatsapp	100	WhatsApp Web Protocol	QR 码登录，多设备协议
matrix	98	Matrix Client-Server API	去中心化协议，端到端加密
msteams	85	Microsoft Bot Framework	Azure Bot Service 集成
mattermost	57	Mattermost REST API + WebSocket	开源企业通讯
bluebubbles	51	BlueBubbles REST API + WebSocket	iMessage 桥接（需 macOS）
signal	48	Signal Protocol / signal-cli	端到端加密消息
imessage	47	AppleScript / SQLite	直接读取 iMessage 数据库（仅 macOS）
zalouser	44	Zalo User API	越南社交平台用户模式
tlon	41	Urbit / Tlon API	Urbit 去中心化社交
nextcloud-talk	36	Nextcloud Talk API	自托管通讯平台
zalo	34	Zalo Official API	越南社交平台官方 API
twitch	33	Twitch IRC / TMI.js	直播聊天 IRC 协议
irc	31	IRC Protocol	Internet Relay Chat
googlechat	29	Google Chat API	Google Workspace 集成
nostr	29	Nostr Protocol (NIP)	去中心化社交协议
synology-chat	20	Synology Chat API	NAS 内置通讯
line	13	LINE Messaging API	日韩社交平台
xiaomi	3	小米 IoT 协议	小米生态集成

每个渠道扩展遵循相同的开发模式：实现 ChannelPlugin 接口 → defineChannelPluginEntry 注册 → 提供 setup-entry.ts → 声明 openclaw.plugin.json。

25.2 AI/LLM 提供商扩展

30+ 个 AI/LLM 提供商扩展

扩展	说明	认证方式	特殊能力
anthropic	Anthropic Claude	setup-token / api-key	思考模式、提示缓存、1M 上下文
openai	OpenAI GPT	api-key / OAuth	5 项注册（LLM+Codex+Speech+Media+Image）
google	Google Gemini	api-key / OAuth	多模态理解
ollama	Ollama 本地模型	local	自动发现、模型拉取、云模型
mistral	Mistral AI	api-key	欧洲 AI 提供商
moonshot	Kimi / Moonshot	api-key	中文优化
perplexity	Perplexity AI	api-key	搜索增强生成
openrouter	OpenRouter	api-key	多模型路由聚合
xai	xAI Grok	api-key	实时信息
together	Together AI	api-key	开源模型托管
huggingface	Hugging Face	api-key	开源模型 Hub
vllm	vLLM	local	本地高性能推理
byteplus	字节跳动 BytePlus	api-key	豆包模型
qianfan	百度千帆	api-key	文心一言
volcengine	火山引擎	api-key	豆包/火山模型
minimax	MiniMax	api-key	MiniMax 模型
modelstudio	阿里模型工坊	api-key	通义千问
amazon-bedrock	AWS Bedrock	aws-credentials	多模型托管
nvidia	NVIDIA NIM	api-key	GPU 加速推理
kimi-coding	Kimi Coding	api-key	代码生成优化
chutes	Chutes AI	api-key	Chutes 平台
venice	Venice AI	api-key	隐私优先 AI
sglang	SGLang	local	结构化生成
synthetic	Synthetic	-	合成/模拟提供商（测试用）
zai	Z.AI	api-key	Z.AI 平台
qwen-portal-auth	通义千问	oauth	通义门户认证
cloudflare-ai-gateway	Cloudflare	api-key	AI Gateway 代理
vercel-ai-gateway	Vercel	api-key	AI Gateway 代理
copilot-proxy	GitHub Copilot	oauth	Copilot 代理
github-copilot	GitHub Copilot	oauth	Copilot 直接集成

所有提供商通过 definePluginEntry + api.registerProvider() 注册，遵循统一的 ProviderPlugin 接口。

25.3 工具与服务扩展

21 个工具与服务扩展

扩展	文件数	类型	功能说明
acpx	22	服务	ACP 运行时后端，提供沙箱化 Agent 执行环境
firecrawl	7	工具+搜索	Web 搜索提供商 + firecrawl_search/firecrawl_scrape 工具
lobster	6	工具	确定性多步骤工作流运行时，支持审批门和恢复令牌
memory-core	1	记忆	记忆系统核心接口
memory-lancedb	4	记忆	LanceDB 向量记忆，自动召回/捕获，3 个工具+CLI+2 个 Hook
voice-call	65	服务+工具	电话通话（Telnyx/Twilio/Plivo），6 个 Gateway 方法
diagnostics-otel	4	服务	OpenTelemetry 诊断集成
diffs	25	工具	Diff 处理与比较工具
thread-ownership	3	服务	线程所有权管理
shared	8	库	扩展间共享工具函数
device-pair	3	服务	设备配对 API 与通知
phone-control	2	工具	手机远程控制
talk-voice	3	服务	语音对话服务
elevenlabs	1	语音	ElevenLabs TTS 提供商
brave	1	搜索	Brave Search 提供商
open-prose	1	工具	文本编辑/写作辅助
openshell	12	工具	终端操作工具集
llm-task	4	工具	LLM 子任务委托
opencode	2	工具	OpenCode 编码 Agent 集成
opencode-go	2	工具	OpenCode Go 版本集成
kilocode	3	工具	KiloCode 编码 Agent 集成

扩展间共享基础设施 (extensions/shared/)

extensions/shared/ 提供了 8 个文件的通用工具：

文件	功能
runtime.ts	resolveLoggerBackedRuntime() — 创建日志后端运行时降级方案
passive-monitor.ts	runStoppablePassiveMonitor() — 可停止的被动监听器管理
deferred.ts	createDeferred<T>() — 经典的 Deferred Promise 模式
config-schema-helpers.ts	requireChannelOpenAllowFrom() — 配置 schema 验证辅助
status-issues.ts	状态诊断字段提取与标准化
resolve-target-test-helpers.ts	目标解析共享测试用例

---

第二十六部分：关键依赖与第三方库

26.1 核心依赖

以下是 OpenClaw 的核心第三方依赖及其在系统中的作用：

协议与通信

依赖	版本	用途
ws	—	高性能 WebSocket 库，Gateway 核心通信
@modelcontextprotocol/sdk	—	MCP (Model Context Protocol) SDK，Agent 工具协议
@agentclientprotocol/sdk	—	ACP (Agent Control Protocol) SDK

渠道 SDK

依赖	用途
discord.js	Discord Bot 开发框架
grammy	Telegram Bot API 框架
@slack/bolt	Slack 应用开发框架
whatsapp-web.js	WhatsApp Web 协议库
matrix-js-sdk	Matrix 客户端 SDK

数据处理

依赖	用途
sharp	高性能图像处理（缩放、格式转换、元数据提取）
pdfjs-dist	PDF 文本提取
json5	JSON5 解析（支持注释的配置文件）
zod	运行时类型校验与 Schema 验证

存储

依赖	用途
better-sqlite3	SQLite 数据库绑定（本地持久化）
sqlite-vec	SQLite 向量扩展
@lancedb/lancedb	LanceDB 嵌入式向量数据库（记忆系统）

自动化

依赖	用途
playwright-core	Chromium 浏览器自动化
croner	时区感知的 Cron 表达式解析和调度

CLI 工具

依赖	用途
commander	CLI 命令解析框架
chalk	终端文本着色
inquirer	交互式命令行提示

AI/LLM

依赖	用途
@mariozechner/pi-*	Pi Agent 框架（嵌入式 Agent 运行时）
@anthropic-ai/sdk	Anthropic API 客户端
openai	OpenAI API 客户端

网络与安全

依赖	用途
dotenv	.env 文件加载
node-fetch	HTTP 请求（某些环境兼容）
gaxios	Google API HTTP 客户端

---

附录

A. 配置文件完整参考

完整的 openclaw.json 配置文件参考：

{
  // ===== 模型配置 =====
  "models": {
    "default": "anthropic/claude-opus-4-6",    // 默认模型
    "fallback": [                               // 故障转移链
      "openai/gpt-5.4",
      "ollama/llama3"
    ],
    "providers": {
      "anthropic": {
        "apiKey": "${ANTHROPIC_API_KEY}",
        "apiKeys": ["key1", "key2"],            // 多密钥轮换
        "cacheRetention": "short",              // 提示缓存 (none/short/long)
        "cooldownProfiles": {}
      },
      "openai": {
        "apiKey": "${OPENAI_API_KEY}"
      },
      "ollama": {
        "baseUrl": "http://localhost:11434",
        "command": "ollama"
      }
    }
  },

  // ===== Agent 配置 =====
  "agents": {
    "default": "assistant",
    "defaults": {                                // Agent 默认配置
      "timeout": 120000,
      "memory": { "enabled": false },
      "tools": { "policy": "allow-all" }
    },
    "list": {
      "assistant": {
        "model": "anthropic/claude-opus-4-6",
        "identity": { "name": "助手" },
        "skills": ["coding-agent", "github", "weather"],
        "memory": { "enabled": true },
        "workspace": "~/workspace",
        "tools": {
          "policy": "allow-all",
          "deny": ["dangerous_exec"],
          "elevated": ["exec"]
        },
        "subagents": {
          "enabled": true,
          "maxConcurrent": 3
        },
        "sandbox": {
          "enabled": false,
          "mode": "docker"
        }
      }
    }
  },

  // ===== 渠道配置 =====
  "channels": {
    "telegram": {
      "token": "${TELEGRAM_BOT_TOKEN}",
      "dmPolicy": "paired",                     // open/paired/closed
      "allowFrom": ["*"],
      "replyTo": "thread"
    },
    "discord": {
      "token": "${DISCORD_BOT_TOKEN}",
      "dmPolicy": "paired",
      "guildAllowlists": {}
    },
    "slack": {
      "botToken": "${SLACK_BOT_TOKEN}",
      "appToken": "${SLACK_APP_TOKEN}"
    }
  },

  // ===== 网关配置 =====
  "gateway": {
    "port": 3000,
    "bind": "loopback",                          // loopback/lan/tailnet/auto
    "auth": {
      "token": "${GATEWAY_TOKEN}"
    },
    "discovery": { "enabled": true },
    "tailscale": {
      "enabled": false,
      "hostname": "openclaw"
    }
  },

  // ===== ACP 配置 =====
  "acp": {
    "enabled": false,
    "dispatch": { "enabled": false },
    "runtime": {
      "permissionMode": "approve-all",
      "timeoutSeconds": 300
    }
  },

  // ===== 定时任务 =====
  "cron": {
    "jobs": [
      {
        "id": "morning-brief",
        "schedule": { "kind": "cron", "expression": "0 9 * * 1-5" },
        "agent": "assistant",
        "prompt": "Good morning! Give me a brief of today's schedule."
      }
    ]
  },

  // ===== 心跳 =====
  "heartbeat": {
    "enabled": false,
    "interval": "5m",
    "model": "openai/gpt-4o-mini"
  },

  // ===== 会话配置 =====
  "sessions": {
    "resetPolicy": {
      "mode": "daily"
    }
  },

  // ===== TTS 配置 =====
  "tts": {
    "auto": "off",                                // off/always/inbound/tagged
    "provider": "edge",                           // edge/openai/elevenlabs
    "voice": "en-US-JennyNeural"
  },

  // ===== 记忆配置 =====
  "memory": {
    "embedding": {
      "model": "text-embedding-3-small",
      "dimensions": 1536
    },
    "autoCapture": true,
    "autoRecall": true
  },

  // ===== Hook 配置 =====
  "hooks": {
    "enabled": true,
    "webhooks": {
      "enabled": false
    }
  },

  // ===== 搜索配置 =====
  "search": {
    "provider": "brave",                          // brave/perplexity/firecrawl
    "brave": { "apiKey": "${BRAVE_API_KEY}" },
    "firecrawl": { "apiKey": "${FIRECRAWL_API_KEY}" }
  },

  // ===== 浏览器配置 =====
  "browser": {
    "enabled": false,
    "headless": true
  },

  // ===== 日志配置 =====
  "logging": {
    "level": "info",                              // debug/info/warn/error
    "file": {
      "enabled": true,
      "level": "debug",
      "path": "~/.openclaw/logs"
    }
  },

  // ===== 安全配置 =====
  "sandbox": {
    "enabled": false,
    "image": "openclaw-sandbox:latest"
  },

  // ===== 环境变量 =====
  "env": {
    "ANTHROPIC_API_KEY": "sk-xxx"
  },

  // ===== Shell 环境导入 =====
  "shellEnv": {
    "enabled": false
  }
}

B. Gateway RPC 方法完整列表

以下是 Gateway 支持的全部 RPC 方法：

连接管理:
  connect.hello          — 获取服务器能力
  connect.auth           — 客户端认证

Agent 操作:
  agent.run              — 执行 Agent 任务
  agent.status           — 查询运行状态
  agent.cancel           — 取消运行中的任务
  agent.config           — Agent 配置查询/修改
  agents.list            — 列出所有 Agent

聊天操作:
  chat.send              — 发送消息到渠道
  chat.history           — 获取聊天历史
  chat.inject            — 注入系统消息
  chat.stream            — 流式消息输出

渠道管理:
  channels.start         — 启动渠道账户
  channels.stop          — 停止渠道账户
  channels.status        — 渠道状态查询
  channels.config        — 渠道配置
  channels.list          — 渠道列表

配置管理:
  config.get             — 获取配置值
  config.set             — 设置配置值
  config.reload          — 重新加载配置

会话管理:
  sessions.list          — 会话列表
  sessions.reset         — 重置会话
  sessions.export        — 导出会话记录
  sessions.delete        — 删除会话

系统管理:
  system.info            — 系统信息
  system.shutdown        — 关闭网关
  system.restart         — 重启网关

健康与诊断:
  health.check           — 健康检查
  health.audit           — 安全审计
  doctor.run             — 运行诊断

模型管理:
  models.list            — 模型列表
  models.default         — 默认模型查询/设置
  models.test            — 模型连接测试

定时任务:
  cron.list              — 任务列表
  cron.add               — 添加任务
  cron.update            — 更新任务
  cron.remove            — 删除任务
  cron.run               — 立即执行任务
  cron.status            — 任务状态

设备管理:
  devices.list           — 设备列表
  devices.pair           — 设备配对
  devices.approve        — 配对审批
  devices.remove         — 移除设备

技能管理:
  skills.list            — 技能列表
  skills.install         — 安装技能
  skills.uninstall       — 卸载技能
  skills.config          — 技能配置

TTS 操作:
  tts.speak              — 文字转语音
  tts.voices             — 可用语音列表
  tts.config             — TTS 配置

浏览器操作:
  browser.launch         — 启动浏览器
  browser.navigate       — 导航到 URL
  browser.screenshot     — 截图
  browser.close          — 关闭浏览器

日志查询:
  logs.query             — 查询日志
  logs.stream            — 流式日志

其他:
  send.message           — 发送消息（跨渠道）
  push.notify            — 推送通知
  usage.stats            — 用量统计
  update.check           — 检查更新
  update.apply           — 应用更新
  wizard.run             — 运行设置向导
  wizard.step            — 向导步骤
  web.fetch              — Web 内容获取
  tools.catalog          — 工具目录
  nodes.list             — 节点列表
  nodes.register         — 节点注册
  exec-approvals.list    — 审批列表
  exec-approvals.approve — 审批通过
  exec-approvals.deny    — 审批拒绝
  voicewake.trigger      — 语音唤醒
  voicecall.initiate     — 发起通话
  voicecall.continue     — 继续通话
  voicecall.speak        — 通话中说话
  voicecall.end          — 结束通话
  voicecall.status       — 通话状态
  voicecall.start        — 启动通话服务
  talk.start             — 开始对话
  talk.end               — 结束对话

C. 环境变量完整列表

以下是 OpenClaw 识别的环境变量：

核心变量

变量	说明
OPENCLAW_VERSION	覆盖版本号
OPENCLAW_BUNDLED_VERSION	打包版本号
OPENCLAW_SERVICE_VERSION	服务版本号
OPENCLAW_PROFILE	配置 Profile 名称
OPENCLAW_DISABLE_ROUTE_FIRST	禁用快速路由（设为 “1”）
OPENCLAW_TEST_LOG	测试中启用日志

提供商 API 密钥

变量	提供商
ANTHROPIC_API_KEY	Anthropic
ANTHROPIC_OAUTH_TOKEN	Anthropic OAuth
OPENAI_API_KEY	OpenAI
GOOGLE_AI_API_KEY	Google AI
MISTRAL_API_KEY	Mistral
MOONSHOT_API_KEY	Moonshot
PERPLEXITY_API_KEY	Perplexity
OPENROUTER_API_KEY	OpenRouter
TOGETHER_API_KEY	Together AI
HUGGINGFACE_API_KEY	Hugging Face
XAI_API_KEY	xAI
NVIDIA_API_KEY	NVIDIA
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY	Amazon Bedrock

渠道令牌

变量	渠道
TELEGRAM_BOT_TOKEN	Telegram
DISCORD_BOT_TOKEN	Discord
SLACK_BOT_TOKEN	Slack
SLACK_APP_TOKEN	Slack (Socket Mode)
SIGNAL_PHONE_NUMBER	Signal

工具服务

变量	服务
BRAVE_API_KEY	Brave Search
FIRECRAWL_API_KEY	Firecrawl
ELEVENLABS_API_KEY	ElevenLabs TTS

网关

变量	说明
GATEWAY_TOKEN	Gateway 认证令牌
GATEWAY_PORT	Gateway 端口

---

本文档基于 OpenClaw v2026.3.14 源代码和官方文档编写，涵盖了项目的完整架构、所有核心模块的设计原理和实现细节、73 个扩展的功能说明、52 个技能的用途分析。