OpenClaw 工具与服务层 (Tools & Services Layer)分析

文档版本：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 执行网页操作、截图、表单填写等任务。

关键子模块:

浏览器工具调用示例:

// AI 调用 browser.navigateawait pwToolsCore.navigate(page, 'https://example.com')// AI 调用 browser.screenshotconst screenshot = await pwToolsCore.screenshot(page)// AI 调用 browser.clickawait 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、多标签页管理。

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

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

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

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

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

2.2 Canvas / A2UI 渲染

路径: src/canvas-host/

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

关键组件:

Canvas 服务器配置:

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

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

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 — 打包为渠道附件格式

子模块详情:

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

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

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

路径: src/tts/

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

支持的 TTS 引擎:

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）

关键子模块:

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 或作为工具调用结果返回

关键组件:

新增组件 (v2026.3):

嵌入提供者优先级: 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，抓取并理解链接内容，将摘要或全文注入代理上下文。

关键文件:

2.8 媒体理解 (Media Understanding)

路径: src/media-understanding/

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

3. 对外提供的接口

工具与服务层通过工具注册表（src/agents/tool-catalog.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/                  # 前端 Bundlesrc/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 核心技术

6.2 设计模式

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

6.3 性能优化

6.4 安全设计

7. v2026.3 变更摘要