openclaw v2026.4.2

原先存放于核心层 tools.web.x_search.* 的 xAI 搜索配置，已迁移至插件自有路径 plugins.entries.xai.config.xSearch.*。同时，认证方式统一使用 plugins.entries.xai.config.webSearch.apiKey 或环境变量 XAI_API_KEY。

为什么要做这个改动？ 将配置所有权还给插件本身，可以避免核心层因平台差异产生无谓耦合。旧路径的权威性配置如果被插件静默覆盖，往往是难以定位的 Bug 根源。迁移完成后，插件可以独立演进，核心层不再需要感知具体工具的配置细节。

运行 openclaw doctor --fix 可自动完成迁移。

Firecrawl 的 Web Fetch 配置从 tools.web.fetch.firecrawl.* 迁移至 plugins.entries.firecrawl.config.webFetch.*。此外，web_fetch 的回退路由从原先的「Firecrawl 独占」模式，改为通过新的 fetch-provider 边界进行分发，允许用户配置多个 fetch provider 互为备份。

实际影响： 如果你在配置文件里手写了 tools.web.fetch.firecrawl.*，升级后该配置将被忽略，请务必在升级前运行迁移命令。

Task Flow 是 OpenClaw 最重要的基础设施之一，允许将复杂任务拆解为多个「流」并在后台持久化执行，而不依赖 LLM 的单次会话上下文。此次版本对其进行了全面重建：

• Managed vs. Mirrored 同步模式：Managed 模式由 OpenClaw 运行时完全接管流的生命周期；Mirrored 模式则允许外部系统驱动流的状态变化，OpenClaw 作为从属方跟踪状态。两种模式可以在不同场景下灵活切换。
• 持久化流状态追踪：即使 OpenClaw 重启，正在执行的 Task Flow 也能从中断点恢复，而不是从头开始。对于耗时数小时的后台任务（例如批量爬取、文档处理），这一特性极为关键。
• Revision 管理：每次流定义的变更都会生成新的 Revision，允许并行运行不同版本的流，同时保留历史快照供回溯。
• openclaw flows 检查与恢复原语：新的 CLI 子命令允许列出、检查、暂停和恢复后台流，无需重启整个服务。

OpenClaw 现在支持作为 Android Google Assistant 的 App Action 目标。这意味着用户可以直接通过语音或 Assistant 触发 OpenClaw，并将 prompt 直接注入聊天输入框，无需手动切换 App。

技术细节： 本次新增了 assistant-role 入口点和 Google Assistant App Actions 元数据声明。当系统收到 Assistant 触发事件时，OpenClaw 会解析 Intent 参数并将其转化为 chat composer 的预填充内容，用户只需确认即可执行。

典型场景： 「嘿 Google，让 OpenClaw 总结一下我今天的邮件」—— 这类需要跨应用协作的任务，现在可以无缝完成。

新增 before_agent_reply 钩子，允许插件在 LLM 生成回复之前进行拦截，并用合成回复（Synthetic Reply）直接短路返回，完全绕过 LLM 调用。

使用场景：

• 缓存常见问题的预设答案，跳过 LLM 以节省 Token；
• 对特定格式的输入（如命令式 prompt）直接由插件处理并返回结构化数据；
• 合规过滤：如果检测到敏感内容，在到达 LLM 之前返回拒绝提示。

与 after_agent_reply 的区别： after_agent_reply 是在 LLM 已经生成回复之后修改，而 before_agent_reply 可以完全跳过 LLM 调用，成本更低，延迟更短。

Provider Runtime 现在暴露了三类新的插件自有钩子挂载点，允许插件精细控制 AI 提供商的行为：

1. Transcript Policy Hook：在回复写入对话历史之前，插件可以决定哪些内容应该保留或裁剪，避免敏感信息残留在上下文中。

2. Cleanup Hook：提供商会话结束时的清理逻辑，插件可以在此释放资源或上报遥测。

3. Reasoning-Mode Dispatch Hook：当用户请求「思考模式」（如 Claude Extended Thinking、o1 系列）时，插件可以拦截并注入自定义的推理前置 prompt，或切换为不同的 provider endpoint。

Matrix 协议要求通过 m.mentions 字段来触发精准的用户通知推送。此前 OpenClaw 的 Matrix 集成在多种消息类型下未能正确填充该字段，导致 @mention 不触发通知。

本次修复覆盖了以下场景：文本发送、媒体标题（caption）、消息编辑、投票回退消息（poll fallback）、以及 action 触发的编辑。现在无论哪种消息路径，m.mentions 都会被正确注入，确保 Matrix 服务器能可靠地派发推送通知。

飞书（Lark）云文档的评论场景是国内企业用户的高频需求。此前 OpenClaw 对飞书 Drive 事件的处理缺乏线程上下文，回复往往落在错误的层级。

本次新增了专用的 Drive 评论事件流，能够正确解析评论所属的文档版本、评论 ID 和线程 ID，并将 OpenClaw 的回复精准投递到对应的评论线程中，而不是在文档顶层新建评论。对于需要在飞书文档中进行 AI 审阅、AI 批注的工作流，这是一个关键改进。

WhatsApp 的附件传递依赖准确的 MIME 类型映射。此前 OpenClaw 的映射表缺少 HTML、XML、CSS 等常见开发者文件类型，导致发送这类文件时附件被丢弃（静默失败）。

本次更新：

• 补充了 text/html、application/xml、text/css 等 MIME 映射；
• 对于仍未覆盖的类型，改为优雅降级（fallback to application/octet-stream）而非静默丢弃。用户会收到「无法预览，但可下载」的提示，而不是附件凭空消失。

此前，OpenClaw 的 HTTP、流式（SSE/Streaming）、WebSocket 三条请求路径各自维护独立的认证和代理配置，存在因路径差异导致认证被绕过的风险。

本次将请求认证、代理配置、TLS 设置和 Header 注入统一收归到一个中心化的请求策略层。具体改进包括：

• 消除私有网络访问推断：不再从 base URL 推断请求是否为私有网络访问，改为显式配置，防止因 URL 伪造导致的权限提升；
• 跨端点 Policy 统一：OpenAI、Anthropic 及兼容端点的请求策略不再各自为政，防止伪造 host 继承原生默认配置。

当配置文件中出现格式错误的 security、ask 或 askFallback 值时，旧版本会将其原样写入规范化后的策略对象，导致策略解析在运行时出现不可预期的行为（有时表现为「应该审批的操作被直接放行」）。现在这些非法值会在规范化阶段被剥离，并以警告日志告知用户，而不是静默接受。

Windows 下路径通常包含空格（如 C:\Program Files\...），需要用引号包裹。旧版本的 Allowlist 匹配逻辑在遇到带引号的路径时会失败，导致原本在 Allowlist 中的命令被错误拒绝。本次修复在 gateway 层和 node execution 层同步引入了引号感知的模式匹配，确保 Windows 用户的执行审批行为与预期一致。

Chrome DevTools Protocol (CDP) 连接时，部分工具会生成带 trailing dot 的 localhost 地址（如 localhost.）。旧版本的回环地址检测逻辑不处理这种格式，导致 WebSocket URL 改写失败，CDP 连接被拒绝。现在在进行回环检测之前，会先对 host 进行 normalize（去除尾部点号），修复了远程 CDP WebSocket URL 改写的问题。

WhatsApp 的推送通知依赖 presence 状态：当客户端在线时发送 available，离线时发送 unavailable。旧版本在「自聊模式」（self-chat mode，即用个人手机号接入）断开连接时，未正确发送 unavailable presence，导致 WhatsApp 服务器认为客户端仍然在线，从而不派发推送通知。现在断开时会正确发送 unavailable，个人手机模式的推送通知恢复正常。

升级前请务必先运行迁移命令，否则 xAI 和 Firecrawl 相关配置将在升级后失效。