OpenClaw 2026.3.22 Plugin SDK 重构深度解析

> 版本: OpenClaw v2026.3.22 (beta.1 → stable)

> 发布日期: 2026-03-22

> 影响范围: 所有第三方插件、WhatsApp/Matrix/微信等频道集成

> 社区评价: ⚠️ Reddit 发帖警告"不要安装"，已知打包 Bug

一句话总结

2026.3.22 是 OpenClaw 的架构大版本：Plugin SDK 从单入口拆成 10+ 子模块、多个频道插件移到独立包、删除所有旧版兼容层。改动量大，但 npm 打包出了两个严重 Bug（Dashboard 503 + WhatsApp 挂），社区建议回滚到 2026.3.13 等补丁。

核心变化：Plugin SDK 从"大包"拆成"小包"

之前（旧 SDK）

所有东西从一个入口导入，插件不管用什么功能都拉整个 SDK：


import { normalizeAccountId, ChannelPlugin, resolvePreferredOpenClawTmpDir,
         createTypingCallbacks, stripMarkdown, ... } from "openclaw/plugin-sdk";
// 或更老的：
import { ... } from "openclaw/extension-api";

现在（新 SDK）

按功能职责拆成细粒度子路径：

子路径	职责	典型导出
`openclaw/plugin-sdk/core`	核心类型	`PluginRuntime`, `OpenClawConfig`, `ChannelPlugin`
`openclaw/plugin-sdk/plugin-entry`	插件注册入口	`OpenClawPluginApi`
`openclaw/plugin-sdk/account-id`	账号标准化	`normalizeAccountId`
`openclaw/plugin-sdk/infra-runtime`	基础设施	`resolvePreferredOpenClawTmpDir`, `withFileLock`
`openclaw/plugin-sdk/channel-runtime`	频道运行时	`createTypingCallbacks`
`openclaw/plugin-sdk/channel-contract`	频道契约类型	`ChannelAccountSnapshot`
`openclaw/plugin-sdk/channel-config-schema`	频道配置 Schema	`buildChannelConfigSchema`
`openclaw/plugin-sdk/text-runtime`	文本处理	`stripMarkdown`
`openclaw/plugin-sdk/command-auth`	命令鉴权	`resolveSenderCommandAuthorization...`
`openclaw/plugin-sdk/reply-runtime`	回复 payload	`ReplyPayload`
`openclaw/plugin-sdk/config-runtime`	读写配置（新能力）	`loadConfig`, `writeConfigFile`
`openclaw/plugin-sdk/testing`	测试工具（新）	插件作者的测试 helpers

旧的 openclaw/extension-api 直接删除，无兼容层（no compatibility shim）。

为什么要拆？

1. Tree-shaking — 插件只加载用到的模块，启动更快，内存更小

2. 权限隔离 — 频道插件碰不到 agent 运行时的内部 API；config-runtime（读写配置）和 channel-runtime（处理消息）分离

3. 独立演进 — 子模块可以独立升级，不互相牵连

4. 测试友好 — 新增 openclaw/plugin-sdk/testing，插件作者可以用官方 test helpers 写单测

5. 安全边界 — 明确哪些 API 是"公开稳定的"，哪些是"内部随时可能变"

实际影响：微信插件的迁移示例

以 @tencent-weixin/openclaw-weixin 为例（1.0.3 → 2.0.1 详细对比），SDK 导入的变化：


// ❌ 1.0.3（旧 SDK，单入口）
import type { ChannelPlugin, OpenClawConfig } from "openclaw/plugin-sdk";
import { normalizeAccountId, resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk";

// ✅ 2.0.1（新 SDK，子模块）
import type { ChannelPlugin, OpenClawConfig } from "openclaw/plugin-sdk/core";
import { normalizeAccountId } from "openclaw/plugin-sdk/account-id";
import { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk/infra-runtime";

新增能力：config-runtime 让插件可以直接读写 openclaw.json，微信插件 2.0.1 用这个实现了"扫码后自动写入频道配置"。

其他 Breaking Changes

2026.3.22 不只是 SDK 重构，是一大堆 breaking changes 的集合：

插件系统

变更	影响
WhatsApp 移到独立包 `@openclaw/whatsapp`	npm 未发布 → WhatsApp 挂了 🐛
插件安装优先 ClawHub	`openclaw plugins install` 先查 ClawHub 市场，npm 变 fallback
新增 Claude/Codex/Cursor bundle 发现和安装	第三方 IDE bundle 可直接安装为 OpenClaw 技能
消息发现 API 改为 `describeMessageTool()`	旧的 `listActions`/`getCapabilities`/`getToolSchema` 删除
新增 Matrix 插件（官方 SDK 重写）	旧 Matrix 插件需迁移

浏览器 & 工具

变更	影响
Chrome 扩展 relay 移除	浏览器控制改为纯 CDP，需 `openclaw doctor --fix` 迁移
图片生成标准化到 `image_generate`	旧 nano-banana-pro 示例删除，改用 `agents.defaults.imageGenerationModel`
默认 OpenAI 模型改为 gpt-5.4	包括 chat/image/TTS/transcription/embedding

配置 & 安全

变更	影响
删除旧环境变量 `CLAWDBOT_` / `MOLTBOT_`	只认 `OPENCLAW_*`
删除旧状态目录 `~/.moltbot` 自动迁移	需手动移到 `~/.openclaw`
Exec 沙箱加固	屏蔽 JVM/glibc/.NET 注入攻击向量
语音通话 webhook 加固	未认证请求 body 限制 64KB/5s

新功能

功能	说明
`/btw` 命令	快速侧问不影响当前会话上下文
`/plugins` 命令	聊天内管理插件（list/enable/disable）
per-agent thinking 默认值	每个 Agent 可独立配置推理模式
ClawHub 市场	类似 npm 的技能/插件市场，`openclaw skills search\	install\	update`
`openclaw update --tag main`	可直接从 GitHub main 分支安装

已知 Bug（⚠️ 严重）

Bug 1: Dashboard UI 503 错误

现象：升级后打开控制面板白屏/503

原因：dist/control-ui/ 目录在打 npm 包时意外漏掉了。Git 仓库和 Docker 镜像里有，npm 包里没有。

跟踪: GitHub #52808

Bug 2: WhatsApp 静默失败

现象：WhatsApp 不工作，日志显示 plugin not found: whatsapp (stale config entry ignored)

原因：WhatsApp 代码移到独立包 @openclaw/whatsapp，旧的 extensions/whatsapp/ 从主包删除——但新包还没发布到 npm。配置指向一个不存在的插件。

跟踪: GitHub #52838

社区反馈

Reddit r/openclaw 已有多个帖子警告：

> "Do not install 2026.3.22 - package issues" — Both whatsapp and the control UI are broken.

DEV.to 上也有 Agent（Paaru）专门写了修复教程，建议回滚到 2026.3.13。

回滚方案


# 回滚到上一个稳定版
npm i -g openclaw@2026.3.13

# 验证配置
openclaw doctor --non-interactive

# 重启
openclaw gateway restart

升级建议

你的情况	建议
当前 < 2026.3.22，一切正常	不要升级，等 2026.3.23+ 修复补丁
已经升了 3.22，Dashboard/WA 挂了	回滚到 2026.3.13
用 Docker 部署	Docker 镜像不受 npm 打包 Bug 影响，但仍建议等补丁
想体验新功能（/btw, ClawHub）	等 2026.3.23 稳定版
微信插件用户	先保持 1.0.3，等 OpenClaw 3.23+ 后一步到位升 2.0.1

对小虾（xiaoxia.app）的启发

1. 插件 SDK 的子模块化是大势所趋——小虾的 Worker Agent 如果未来开放插件，可以参考这个模式

2. 版本兼容检查（compat.ts）是好实践——插件启动时 fail-fast 比运行时莫名其妙崩好

3. ClawHub 市场的出现说明——插件生态需要一个中心化发现机制（npm 对非 JS 生态不友好）

4. ⚠️ 打包质量是血泪教训——OpenClaw 这种级别的项目，npm 发版漏文件 + 新包没发布就删旧代码，说明 CI/CD 流程有缺口