文档版本：2026.3.24　　最后更新：2026-03-25

openclaw版本：v2026.3.24

1. 层概述

职责: 为 AI 代理层提供所有"外部能力"：浏览器控制、画布渲染、媒体处理、语音合成、定时任务、记忆检索等

定位: 系统的"外设层"，将现实世界的能力（网络、文件、音视频、UI 渲染）包装为 AI 可调用的工具接口

核心特性:

• Playwright 全功能浏览器自动化（含 Chrome 扩展支持）
• Canvas / A2UI 交互式可视化渲染
• 全媒体管道（图像/音频/视频/PDF）
• 多引擎 TTS（OpenAI / ElevenLabs / Edge TTS / sherpa-onnx 本地）
• Cron 定时任务服务（cron 表达式 + 自然语言调度）
• 向量记忆系统（SQLite-vec 本地存储 + 远程嵌入）

---

2. 主要组件

2.1 浏览器工具 (Browser Tools)

路径: src/browser/

职责: 通过 Playwright + Chrome DevTools Protocol (CDP) 实现完整的浏览器自动化，供 AI 执行网页操作、截图、表单填写等任务。

关键子模块:

模块	文件	说明
Playwright 会话	pw-session.ts	Playwright 会话管理，连接/断开/页面切换
CDP 代理	cdp.ts, cdp-proxy-bypass.ts	CDP 协议封装，支持绕过代理
工具核心	pw-tools-core.ts	截图、交互、表单操作、下载
AI 操作接口	pw-ai.ts, pw-ai-module.ts	AI 驱动的高层操作封装
角色快照	pw-role-snapshot.ts	无障碍角色树快照（替代 DOM dump）
Chrome 管理	chrome.ts, chrome.executables.ts	Chrome 可执行文件发现、用户目录管理
服务器控制	server.ts, server-context.ts, server-lifecycle.ts	HTTP 控制服务器（本地页面/截图 API）
多 Profile	profiles.ts, profiles-service.ts	多 Chrome Profile 管理（同时登录多账号）
扩展中继	extension-relay.ts	Chrome 扩展消息中继
导航守卫	navigation-guard.ts	防止导航到受限 URL
认证	control-auth.ts, http-auth.ts	本地控制服务认证

浏览器工具调用示例:

// AI 调用 browser.navigate
await pwToolsCore.navigate(page, 'https://example.com')

// AI 调用 browser.screenshot
const screenshot = await pwToolsCore.screenshot(page)

// AI 调用 browser.click
await pwToolsCore.click(page, { selector: '#button' })

关键依赖:

• playwright — 浏览器自动化
• chrome-launcher — Chrome 启动管理

新增组件 (v2026.3):

Chrome MCP (src/browser/chrome-mcp.ts)

将 Chrome 浏览器作为 MCP（Model Context Protocol）服务器暴露给代理，提供基于 MCP 协议的浏览器操作接口，支持多 Profile、多标签页管理。

功能	函数
截图	takeChromeMcpScreenshot()
DOM 快照	takeChromeMcpSnapshot()
导航	navigateChromeMcpPage()
点击/填表	clickChromeMcpElement(), fillChromeMcpElement()
标签管理	openChromeMcpTab(), closeChromeMcpTab(), focusChromeMcpTab()
JS 执行	evaluateChromeMcpScript()

会话管理: ChromeMcpSession + pendingSessions/sessions 会话池，支持多 Profile 并发

Browser Bridge Server (src/browser/bridge-server.ts)

启动 NoVNC 桥接服务器（startBrowserBridgeServer()），将浏览器视频流通过 WebSocket 代理到远端观察者，适用于远程调试和监控场景。

关键函数	说明
startBrowserBridgeServer()	启动 NoVNC 桥接代理服务器
stopBrowserBridgeServer()	停止桥接服务器
buildNoVncBootstrapHtml()	生成引导页 HTML

Client Actions API (src/browser/client-actions-core.ts 等)

提供高层浏览器客户端操作接口，将底层 Playwright / CDP 操作封装为可跨 Profile、跨标签页调用的统一 API。

文件	说明
client-actions-core.ts	导航、截图、下载、表单等核心操作
client-actions-observe.ts	页面观察（等待内容/事件）
client-actions-state.ts	客户端状态查询
client-actions-url.ts	URL 操作工具

---

2.2 Canvas / A2UI 渲染

路径: src/canvas-host/

职责: 为 AI 提供可视化渲染画布，通过嵌入式 Web 服务器渲染交互式 A2UI 界面（JSON 驱动的组件树）。

关键组件:

文件	说明
server.ts	Canvas Host HTTP 服务器（Fastify）
a2ui.ts	A2UI 渲染引擎接口
file-resolver.ts	静态文件解析（HTML/JS/CSS）
a2ui/	A2UI 前端 Bundle 目录

Canvas 服务器配置:

CanvasHostServer {
  port: number           // 监听端口（默认随机）
  basePath: string       // URL 基础路径
  canvasRoot: string     // 静态文件根目录
}

Node 端可调用的 Canvas 命令（通过 ACP 协议下发）:

命令	说明
canvas.present	打开/展示 Canvas 窗口
canvas.hide	隐藏 Canvas 窗口
canvas.navigate	导航到指定 URL
canvas.evalJS	在 Canvas 上下文执行 JavaScript
canvas.snapshot	截取 Canvas 快照
canvas.a2ui.push	推送 A2UI 组件数据
canvas.a2ui.pushJSONL	批量推送 A2UI JSON Lines
canvas.a2ui.reset	重置 A2UI 状态

---

2.3 媒体处理管道 (Media Pipeline)

路径: src/media/

职责: 处理所有媒体资产的加载、转换、存储和服务，包括图像压缩、音频转码、视频处理和 PDF 提取。

媒体流程:

输入（URL / Base64 / 文件路径）
      ↓
inbound-path-policy — 路径安全检查
      ↓
fetch.ts — 下载/加载媒体内容
      ↓
store.ts — 写入临时媒体目录（带 TTL 清理）
      ↓
处理（image-ops / ffmpeg-exec / pdf-extract）
      ↓
outbound-attachment.ts — 打包为渠道附件格式

子模块详情:

模块	文件	说明
媒体存储	store.ts	临时文件管理（TTL 自动清理，DEFAULT_TTL_MS）
HTTP 获取	fetch.ts	媒体内容获取（含限速保护）
图像处理	image-ops.ts	图像压缩/裁剪/格式转换
音频处理	audio.ts, audio-tags.ts	音频格式转换、ID3 标签读取
FFmpeg	ffmpeg-exec.ts, ffmpeg-limits.ts	FFmpeg 进程调用封装
PDF 提取	pdf-extract.ts	PDF 文本/图像提取
PNG 编码	png-encode.ts	像素缓冲区编码为 PNG
MIME 检测	mime.ts	MIME 类型检测/归一化
Base64	base64.ts	Base64 编码/解码工具
媒体服务	server.ts	媒体文件 HTTP 服务（供渠道引用）
媒体服务	host.ts	媒体宿主注册

媒体目录: ~/.openclaw/media/ （临时缓存，按 TTL 清理）

大小限制: MEDIA_MAX_BYTES（默认保护，拒绝超大文件）

---

2.4 语音合成 TTS (Text-to-Speech)

路径: src/tts/

职责: 将 AI 输出的文本转为语音，支持多种 TTS 引擎，适配不同平台和质量需求。

支持的 TTS 引擎:

引擎	函数	说明
OpenAI TTS	openaiTTS()	tts-1 / tts-1-hd，6 种声音
ElevenLabs	elevenLabsTTS()	高质量语音克隆，需 API Key
Edge TTS	edgeTTS()	微软 Edge 免费 TTS（多语言）
sherpa-onnx	本地推理	完全离线（src/agents/skills.sherpa-onnx-tts-bin.test.ts）

TTS 指令解析: parseTtsDirectives() — 从 AI 回复中提取 [tts: voice=xxx] 等指令

文本预处理: prepare-text.ts — Markdown 清理、长文本分段

声音选项（OpenAI）: alloy, echo, fable, onyx, nova, shimmer

---

2.5 Cron 定时任务服务

路径: src/cron/

职责: 提供定时/周期性 AI 任务调度，支持 cron 表达式、自然语言时间表达式，并管理任务执行历史。

核心类: CronService（src/cron/service.ts）

关键子模块:

文件	说明
service.ts	Cron 服务主类：任务注册/调度/执行/持久化
schedule.ts	调度时间计算（next run time）
normalize.ts	时间表达式规范化
parse.ts	Cron 表达式解析
isolated-agent.ts	隔离的代理执行环境（每个 cron 任务独立上下文）
delivery.ts	任务结果投递到目标渠道
store.ts	任务持久化存储
run-log.ts	任务执行日志记录
session-reaper.ts	旧会话清理器
heartbeat-policy.ts	心跳 OK 消息抑制策略（避免重复通知）
stagger.ts	整点任务错峰执行（避免集中负载）

Cron 任务格式:

{
  "id": "daily-summary",
  "schedule": "0 9 * * *",       // Cron 表达式 或自然语言
  "prompt": "生成今日新闻摘要",
  "agentId": "my-agent",
  "deliverTo": { "channel": "telegram", "account": "user123" }
}

任务存储路径: ~/.openclaw/agents/<agentId>/cron/jobs.json

---

2.6 向量记忆系统 (Memory System)

路径: src/memory/

职责: 为 AI 提供长期记忆存储和语义检索能力，基于向量嵌入实现相似度搜索和混合（BM25 + 向量）检索。

架构:

用户消息 / AI 输出
      ↓
embedding 生成（多提供者）
      ↓
SQLite-vec 向量存储 + FTS5 全文索引
      ↓
MMR 排序（最大边际相关性）
      ↓
注入 System Prompt 或作为工具调用结果返回

关键组件:

文件	说明
manager.ts	MemoryIndexManager — 向量索引核心管理类
embeddings.ts	嵌入向量生成（统一接口）
embeddings-openai.ts	OpenAI 嵌入（text-embedding-ada-002 等）
embeddings-gemini.ts	Google Gemini 嵌入
embeddings-voyage.ts	Voyage AI 嵌入（专为检索优化）
embeddings-ollama.ts	Ollama 本地嵌入
embeddings-mistral.ts	Mistral 嵌入
sqlite-vec.ts	SQLite-vec 向量存储接口
hybrid.ts	BM25 全文 + 向量混合检索
mmr.ts	最大边际相关性（MMR）结果去重排序
search-manager.ts	搜索管理器（聚合多种检索策略）
qmd-manager.ts	QMD（Query→Memory→Docs）管道管理
backend-config.ts	存储后端配置（本地 vs 远程）
batch-runner.ts	批量嵌入任务队列
temporal-decay.ts	时间衰减因子（老记忆权重降低）

新增组件 (v2026.3):

文件	说明
query-expansion.ts	多语言查询展开（expandQueryForFts / expandQueryWithLlm），支持中/英/日/韩/阿/西/葡停用词过滤
multimodal.ts	多模态记忆（图像/音频/视频文件嵌入），MEMORY_MULTIMODAL_SPECS 定义各模态规范
embeddings-remote-client.ts	远程嵌入客户端（HTTP 调用外部嵌入服务）
embeddings-remote-provider.ts	远程嵌入提供者适配层
batch-gemini.ts	Gemini 批量嵌入
batch-http.ts	HTTP 通用批量嵌入
batch-openai.ts	OpenAI 批量嵌入
batch-voyage.ts	Voyage 批量嵌入
qmd-query-parser.ts	QMD 查询解析器
qmd-scope.ts	QMD 作用域管理（按 agentId 隔离）
qmd-process.ts	QMD 管道执行器
session-files.ts	会话文件内存索引（把会话文件纳入记忆检索范围）

嵌入提供者优先级: Voyage → OpenAI → Gemini → Mistral → Ollama（本地）；远程提供者通过 embeddings-remote-provider.ts 接入

多模态记忆: 当 isMemoryMultimodalEnabled() 为真时，图像/音频/视频文件会同步生成多模态嵌入，MemoryMultimodalModality 包含 image / audio / video 三类

存储格式: SQLite 文件（~/.openclaw/agents/<agentId>/memory/index.sqlite）

扩展记忆后端:

• extensions/memory-core/ — 核心内存扩展
• extensions/memory-lancedb/ — LanceDB 向量存储后端

---

2.7 链接理解 (Link Understanding)

路径: src/link-understanding/

职责: 自动检测消息中的 URL，抓取并理解链接内容，将摘要或全文注入代理上下文。

关键文件:

文件	说明
detect.ts	URL 检测（正则 + 白名单过滤）
runner.ts	链接抓取 + 内容提取运行器
apply.ts	将链接内容应用到消息上下文
format.ts	链接内容格式化（Markdown）

---

2.8 媒体理解 (Media Understanding)

路径: src/media-understanding/

职责: 借助视觉模型（VLM）对图像描述生成摘要，供不支持视觉输入的模型使用。

---

3. 对外提供的接口

工具与服务层通过工具注册表（src/agents/tool-catalog.ts）向代理层暴露以下工具接口：

工具名	说明	实现路径
browser.navigate	导航到 URL	src/browser/pw-tools-core.ts
browser.screenshot	页面截图	src/browser/pw-tools-core.ts
browser.click/fill/select	页面交互	src/browser/pw-tools-core.ts
canvas.present	渲染 Canvas	src/canvas-host/ + ACP
canvas.a2ui.push	推送 A2UI	src/canvas-host/a2ui.ts
media.save	保存媒体	src/media/store.ts
tts.speak	文本转语音	src/tts/tts.ts
cron.add/list/remove	Cron 任务管理	src/cron/service.ts
memory.search	语义记忆检索	src/memory/search-manager.ts
memory.add	写入记忆	src/memory/manager.ts

---

4. 与其他层的交互

4.1 上游（Agent 层 → 工具服务层）

AI 决策调用工具（tool_use block）
      ↓
tool-policy-pipeline 验证权限
      ↓
分发到对应工具服务（browser / canvas / media 等）
      ↓
执行结果返回 tool_result，注入对话历史

4.2 下游（工具服务层 → 数据存储层）

媒体文件 → ~/`.openclaw/media/` (临时缓存)
记忆数据 → ~/`.openclaw/agents/<id>/memory/*.sqlite`
Cron 状态 → ~/`.openclaw/agents/<id>/cron/`
Canvas 静态 → `src/canvas-host/a2ui/`

4.3 跨层通信（Canvas → Node）

Agent Layer 发出 canvas.present 命令
      ↓
通过 ACP 协议下发到目标 Node（macOS/iOS/Android）
      ↓
Node 的 CanvasHostServer 渲染 A2UI 界面

---

5. 关键代码路径

src/browser/
├─ pw-session.ts          # Playwright 会话管理
├─ pw-tools-core.ts       # 截图/交互工具核心
├─ pw-ai.ts               # AI 高层操作封装
├─ chrome.ts              # Chrome 启动/管理
├─ server.ts              # 控制 HTTP 服务器
├─ server-context.ts      # 服务器状态上下文
├─ cdp.ts                 # CDP 协议封装
├─ profiles.ts            # 多 Profile 管理
├─ chrome-mcp.ts          # Chrome as MCP Server（新增）
├─ bridge-server.ts       # NoVNC 桥接服务器（新增）
├─ client-actions-core.ts # 客户端操作核心 API（新增）
└─ client-actions-*.ts    # 客户端操作分模块（新增）

src/canvas-host/
├─ server.ts              # Canvas Host HTTP Server
├─ a2ui.ts                # A2UI 引擎接口
└─ a2ui/                  # 前端 Bundle

src/media/
├─ store.ts               # 媒体临时存储（TTL 清理）
├─ fetch.ts               # 媒体获取
├─ image-ops.ts           # 图像处理
├─ audio.ts               # 音频处理
├─ ffmpeg-exec.ts         # FFmpeg 封装
└─ pdf-extract.ts         # PDF 内容提取

src/tts/
├─ tts-core.ts            # TTS 引擎实现（OpenAI/ElevenLabs/Edge）
└─ tts.ts                 # TTS 统一入口

src/cron/
├─ service.ts             # CronService 主类
├─ isolated-agent.ts      # 隔离代理执行
├─ delivery.ts            # 结果投递
└─ store.ts               # 任务持久化

src/memory/
├─ manager.ts             # MemoryIndexManager 核心
├─ embeddings.ts          # 嵌入向量统一接口
├─ sqlite-vec.ts          # SQLite-vec 存储
├─ hybrid.ts              # 混合检索
├─ mmr.ts                 # MMR 排序
├─ search-manager.ts      # 搜索管理器
├─ query-expansion.ts     # 多语言查询展开（新增）
├─ multimodal.ts          # 多模态记忆（新增）
├─ embeddings-remote-*.ts # 远程嵌入支持（新增）
├─ batch-*.ts             # 批量嵌入（Gemini/HTTP/OpenAI/Voyage，新增）
├─ qmd-query-parser.ts    # QMD 查询解析（新增）
├─ qmd-scope.ts           # QMD 作用域（新增）
└─ session-files.ts       # 会话文件索引（新增）

src/link-understanding/   # 链接内容理解
src/media-understanding/  # 媒体内容理解（VLM）

---

6. 技术实现

6.1 核心技术

技术	用途
playwright	浏览器自动化（Chromium/Firefox/WebKit）
ffmpeg	音视频转码（外部进程调用）
SQLite + sqlite-vec	本地向量存储（无需额外服务）
better-sqlite3	高性能同步 SQLite 驱动
sherpa-onnx	本地离线 TTS 推理
Fastify	Canvas Host HTTP 服务器

6.2 设计模式

• 适配器模式: TTS 引擎、嵌入提供者统一接口，可热插拔
• 策略模式: backend-config.ts 支持本地/远程记忆后端切换
• 观察者模式: 浏览器工具通过事件通知页面状态变化
• 工厂模式: MemoryIndexManager 按 agentId 按需创建实例

6.3 性能优化

策略	说明
嵌入批量处理	batch-runner.ts — 批量生成 embedding，减少 API 调用
记忆缓存	INDEX_CACHE + INDEX_CACHE_PENDING — 内存中缓存活跃索引
媒体 TTL 清理	cleanOldMedia() — 定期清理过期媒体文件
Cron 错峰	stagger.ts — 整点任务错开 60s 内随机延迟执行
导航守卫缓存	预编译 URL 黑名单正则

6.4 安全设计

机制	说明
inbound-path-policy.ts	媒体 URL 入站路径策略（拒绝内网地址）
navigation-guard.ts	浏览器导航黑名单（防止访问内部服务）
Canvas Host 认证	本地 Token 认证，防止未授权访问
媒体大小限制	MEDIA_MAX_BYTES 保护，防止超大文件攻击
记忆隔离	每个 agentId 独立向量存储，不同代理记忆完全隔离

---

7. v2026.3 变更摘要

特性	路径	说明
Chrome as MCP Server	src/browser/chrome-mcp.ts	浏览器操作通过 MCP 协议暴露给代理
NoVNC 桥接服务器	src/browser/bridge-server.ts	远程浏览器视频流代理，支持远程调试
Client Actions API	src/browser/client-actions-*.ts	高层浏览器操作 API，跨 Profile/标签页
多语言查询展开	src/memory/query-expansion.ts	FTS 关键词提取 + LLM 查询扩展（7语言停用词）
多模态记忆	src/memory/multimodal.ts	图像/音频/视频文件嵌入纳入记忆检索
远程嵌入支持	src/memory/embeddings-remote-*.ts	HTTP 调用外部嵌入服务
批量嵌入扩展	src/memory/batch-*.ts	Gemini/HTTP/OpenAI/Voyage 批量嵌入
QMD 增强	qmd-query-parser.ts, qmd-scope.ts	查询解析和作用域隔离
会话文件索引	src/memory/session-files.ts	会话历史文件纳入语义检索范围