OpenClaw 3.2 重磅更新：PDF 原生支持上线，4 项破坏性变更你必须知道！

导读： OpenClaw 于 2026-03-03 发布 3.2 版本，本次共计 20 项新功能、4 项破坏性变更、176 项 Bug 修复。PDF 一等公民工具、Secrets 体系全面化、Plugin SDK 大扩张是三大核心主线。升级前务必读完破坏性变更一节。

一、你需要先看这个：4 项破坏性变更

Danger ⚠️ 升级前必读以下变更会直接影响已有配置，请逐一排查后再升级。

变更 1｜新安装默认工具集缩减

旧行为： 新安装默认包含编程、系统等全套工具。 新行为：tools.profile 默认值改为 messaging，不再自动加载代码执行和系统操作类工具。

# 如果你需要保留原有工具集，请在配置中显式声明：
tools:
  profile: coding  # 或 full

影响人群： 依赖默认工具集跑代码任务的用户。

变更 2｜ACP Dispatch 默认启用

旧行为： ACP 调度默认关闭，需手动开启。 新行为： ACP dispatch 默认启用。

# 如需关闭：
acp:
  dispatch:
    enabled: false

影响人群： 未明确配置 ACP 的存量用户，升级后可能出现意料外的 Agent 路由行为。

变更 3｜Plugin SDK：HTTP Handler 注册 API 变更

旧 API api.registerHttpHandler(...)已被彻底移除，必须迁移到新接口：

// ❌ 旧方式（不再可用）
api.registerHttpHandler(path, handler)

// ✅ 新方式
api.registerHttpRoute({
  path: '/my-webhook',
  auth: 'token',       // 必填，强制鉴权
  match: ...,
  handler: async (req, res) => { ... }
})

影响人群： 所有自研插件中使用过 registerHttpHandler 的开发者。

变更 4｜Zalo Personal 插件：移除外部 CLI 依赖

@openclaw/zalouser 不再依赖外部 openzca / zca-cli 二进制文件，已内置 zca-js 原生实现。

# 升级后需重新登录：
openclaw channels login --channel zalouser

影响人群： 使用 Zalo Personal 频道的所有用户，升级后必须重新扫码登录。

二、重点新功能详解

🔥 PDF 工具：终于成为一等公民

这是本次最受关注的新增能力。新的 pdf 工具带来原生级 PDF 理解支持：

支持的 Provider：

• • Anthropic Claude — 原生 PDF 解析
• • Google Gemini — 原生 PDF 解析
• • 其他模型 — 自动降级为文本提取模式

可配置项：

agents:
  defaults:
    pdfModel: claude-opus-4-6    # 指定 PDF 处理模型
    pdfMaxBytesMb: 20            # 单文件大小上限
    pdfMaxPages: 100             # 页数上限

此前处理 PDF 需要自行接入解析库或通过 OCR 中转，3.2 版本彻底消灭这个痛点。同时，Diff 工具也新增了 PDF 格式输出，附带 fileQuality/fileScale/fileMaxWidth 渲染质量控制。

🔐 Secrets / SecretRef：凭证管理全面覆盖

SecretRef 支持扩展至 64 个凭证目标，覆盖范围：

• • 运行时采集器
• • openclaw secrets 规划 / 应用 / 审计全流程
• • Onboarding SecretInput UX

行为变化：

• • 活跃面（Active Surface）：未解析的 SecretRef → 立即报错，快速失败
• • 非活跃面：报告非阻断诊断，不中断流程

这意味着配置错误的凭证不会再悄悄跑到线上才暴露。

📦 Sessions Spawn：子 Agent 现在可接收附件

sessions_spawn（子 Agent 运行时专属）现在支持内联文件附件：

tools:
  sessions_spawn:
    attachments:
      maxFiles: 5
      maxTotalMb: 10

• • 支持 base64 / utf8 编码传入
• • Transcript 中的附件内容自动脱敏
• • 生命周期结束后自动清理

🤖 MiniMax M2.5-highspeed 正式集成

OpenClaw 内置模型目录新增 MiniMax-M2.5-highspeed，同时向后兼容MiniMax-M2.5-Lightning 旧配置，存量用户无需修改即可继续使用。

📡 Telegram 体验全面升级

🧩 Plugin SDK：能力边界大幅扩张

本次 SDK 扩展是近期版本中力度最大的一次，新增 API 一览：

频道运行时访问

// 外部插件现在可以直接访问共享运行时，无需 internal import
context.channelRuntime.reply(...)
context.channelRuntime.session.get(...)

音频转录

// 扩展可调用 OpenClaw 配置的 STT Provider 转录本地音频
const transcript = await api.runtime.stt.transcribeAudioFile('/path/to/audio.mp3')

Session 唤醒

// 立即唤醒指定 Session，无需等待下次心跳
runtime.system.requestHeartbeatNow(sessionKey)

事件订阅

// 新增两个可订阅事件
runtime.events.onAgentEvent(handler)
runtime.events.onSessionTranscriptUpdate(handler)
// 单个监听器异常不再影响整体 fanout

新 Hook 事件：

• • message:transcribed — 转录完成
• • message:preprocessed — 预处理完成
• • message:sent 增加 isGroup / groupId 字段，方便群聊场景关联

🔊 音频 Echo：转录后发确认消息

新增 tools.media.audio.echoTranscript 配置，可在 Agent 处理前将转录结果发回原始对话，默认关闭：

tools:
  media:
    audio:
      echoTranscript: true
      echoFormat: "**[转录]** {text}"

🧠 Memory + Ollama：本地嵌入支持

记忆搜索现在可以完全在本地运行，不依赖任何外部 API：

memorySearch:
  provider: ollama
  fallback: ollama

配合 models.providers.ollama 的现有配置，零配置接入本地嵌入。

🛠️ CLI：配置验证命令上线

# 验证配置文件，支持 JSON 格式输出
openclaw config validate
openclaw config validate --json

网关启动前先跑一遍，配置错误在上线前就能捕获，报告中包含完整的无效字段路径。

🎭 其他实用新增

• • CLI Banner 定制：cli.banner.taglineMode: random | default | off，关掉启动彩蛋或保持随机
• • Zalo Personal 重构： 纯 JS-native zca-js 实现，不再依赖外部二进制，稳定性大幅提升
• • Outbound 多媒体： Discord、Slack、WhatsApp、Zalo、Zalouser 共享 sendPayload，支持多媒体迭代和 chunk-aware 文本降级

三、Bug 修复：176 项，安全加固是重点

本次修复体量庞大，覆盖几乎所有渠道，以下是高价值修复摘要：

安全相关（强烈建议升级）

• • Webhook 鉴权前置： BlueBubbles、Google Chat 等 Webhook Handler 现在在解析 Body 之前完成鉴权，防止慢速请求攻击
• • WS 本地锁定：ws:// 明文连接默认仅允许 loopback，私有网络访问需显式设置 OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1
• • macOS LaunchAgent 权限加固： 生成的 plist 写入 Umask=077，防止 npm 升级破坏文件权限
• • Gateway Host Header 校验： 本地 dev 豁免绑定到实际 socket 来源，不再信任 Host Header 声明
• • Plugin HTTP 路由鉴权强制：registerHttpRoute 必须提供 auth 字段，杜绝未鉴权路由注册

频道稳定性

工具 / CLI

• • openclaw browser --timeout 参数现在真正生效（此前被硬编码 15000ms 覆盖）
• • Exec 路径中的正则特殊字符（如 g++）不再导致崩溃
• • config validate 去重，同一错误不再重复上报

四、该不该升级？

一句话评价： 3.2 是一次「功能密度 + 安全加固」并举的版本，PDF 工具和 Plugin SDK 扩张是最值得关注的新能力，破坏性变更虽只有 4 项但影响面广，升级前务必对照检查。

官方发布页： https://github.com/openclaw/openclaw/releases/tag/v2026.3.2