编者摘要：OpenClaw 2026.5.5是小型bug 修复版本，核心修复飞书、LINE、Telegram、Discord等聊天通道问题，优化控制UI/TUI 响应性、插件更新、网关状态等能力，同步完善xAI/Fireworks 模型适配、Docker 安全、媒体生成等细节，支持超20 类聊天平台接入，提供完整插件管理、CLI 指令、权限与故障排查体系，本次main 分支累计393 次提交，覆盖69 项问题修复。

惯例三个问题Q&A

问题1：OpenClaw 2026.5.5 版本的核心定位与修复重点是什么？

答：该版本为小型bug 修复版，无新功能，核心修复飞书、LINE、Telegram、Discord等聊天通道异常，优化控制UI/TUI 响应性、插件更新保链接、网关状态与重启，同时完善模型适配、Docker 安全、会话清理等问题。

问题2：OpenClaw 插件管理的核心规则与常见故障怎么解决？

答：核心规则为黑名单优先于白名单，支持本地/ 包两种格式，官方插件更新自动同步、第三方保留固定设置；常见故障如插件冲突可禁用重复插件，所有权异常用chown 修复，注册失败用openclaw plugins registry –refresh刷新并重启网关。

问题3：该版本对网关与部署做了哪些关键优化？

答：优化心跳确认超时避免误重连，清晰化网关状态与重启日志；Docker 容器移除高危权限提升安全；插件更新时保持SDK 链接不丢失；快速重启抑制后台计时器，避免孤立进程；支持openclaw gateway status –deep查看详细运行状态。

附录1 OpenClaw 2026 5.5

💬飞书, LINE, Telegram, Discord 修复

🖥️控制用户界面/终端用户界面保持响应性

🔌插件更新时保持SDK链接不丢失

🛠️网关状态/重启更清晰

小bug 修复版本。非常小。

openclaw 2026.5.5

steipete发布版本 自本次发布以来，main 分支共有393 次提交

v2026.5.5b1abf9d

问题修复

1.飞书：在会话路由之前补充缺失的本地主题发起者线程ID，以确保首次转发和后续跟进保持在同一主题会话中。修复了#78262。感谢@joeyzenghuan。

2.LINE: 拒绝dmPolicy: “open” 配置，未使用通配符allowFrom，因此webhook DMs 无法通过验证，而不是在入站处理之前被确认并静默阻止。修复#78316。

3.Telegram/Codex：保持消息工具仅可见的进度草稿，并每个工具渲染一次原生Codex工具进度，而不是重复项目/工具草稿行。修复了#75641。(#77949)

4.供应商/xAI：停止向本地Grok响应模型发送OpenAI风格的推理努力控制，因此xai/grok-4.3不再因无效的推理努力而导致实时Docker/网关运行失败。

5.Providers/xAI: 将捆绑的xAI思维档案限制为关闭，以便实时网关运行无法将不支持的推理级别发送到本地Grok响应模型。

6.Matrix/approvals: 重新尝试审批交付最多3次，设置短暂的延迟，以便瞬态的Matrix发送失败不会导致待处理的审批提示被搁置。(#78179) 感谢@Patrick-Erichsen。

7.Discord/gateway: 从实际心跳发送中测量心跳确认超时，防止初始心跳延迟触发错误的重连循环，同时频道仍在等待就绪。修复#77668. (#78087) 感谢@bryce-d-greybeard 和@NikolaFC。

8.Discord/公会：将诸如/steer的纯文本控制命令通过正常的授权和提及网关传递，而不是在智能体会话看到它们之前静默丢弃它们。修复了#78080。感谢@ramitrkar-hash。

9.控制UI/会话：使压缩计数成为紧凑的N 检查点披露，并在响应式表布局中显示现代检查点历史卡片的扩展会话级详细信息。感谢@BunsDev。

10.控制用户界面/性能：在历史数据负载和频道探测较慢时保持聊天和频道标签的响应性，标记部分频道状态，并在事件日志中记录慢速聊天/配置渲染时间。感谢@BunsDev。

11.控制UI/会话：仅为显式控制UI 会话创建触发文档中的/new 命令和生命周期钩子，恢复会话内存和自定义钩子捕获，而不更改SDK 父会话的创建。修复#76957。感谢@BunsDev。

12.Exec approvals: 当Windows 拒绝对exec-approvals.json 进行重命名覆盖时，退回到受保护的副本，同时保留符号链接、硬链接和仅所有者权限的保护措施。修复#77785。(#77907) 感谢@Alex-Alaniz 和@MilleniumGenAI。

13.Slack：在重新连接日志中保留Socket Mode SDK 错误上下文和结构化Slack API 字段，以便启动失败不再简化为一个未知错误。

14.iOS 配对：允许使用设置代码和手动ws:// 连接到私有LAN 和.local 网关，同时确保Tailscale/public 路由在wss:// 上，并在混合身份验证重连时更偏向显式网关密码而非过期的引导令牌。修复#47887；向前支持#65185。感谢@draix 和@BunsDev。

15.插件/诊断：通过解释缺少编译运行时输出是发布者打包问题，使源代码仅TypeScript 包警告变得可操作，并指引用户更新/重装或禁用/卸载插件。修复#77835。感谢@googlerest。

16.控制UI/聊天：当相同的文字记录回合还包含工具使用元数据时，保持持续的助手进展文本可见，这样聊天历史重载后不会在下一个用户消息后使这些回复消失。修复 #77374。感谢 @BunsDev。

17.TUI：跳过用于交互式启动的通用CLI重生包装，在终端丢失时干净退出，并拒绝恢复作为记忆聊天会话的心跳会话，防止首次启动时出现过时的心跳历史和孤立的openclaw-tui进程。感谢@vincentkoc。

18.Doctor/sessions: 将心跳污染的默认主会话存储条目移至恢复密钥，并清除过期的TUI 恢复指针，以便doctor –fix 可以修复已卡在agent:main:main 心跳历史上的实例。感谢@vincentkoc。

19.智能体/上下文引擎：在上下文引擎的组装、回合后和摄取钩子中保留隐藏的OpenClaw运行时上下文自定义消息，使得转录重建插件只能看到对话消息。谢谢@vincentkoc。

20.Gateway/shutdown: 取消关闭期间的延迟后准备维护，并在快速重启后抑制维护/cron 启动，以防止孤立的后台计时器。感谢@vincentkoc。

21.智能体/生成的媒介：将附件式消息工具操作视为已完成的聊天发送，以防止在已上传生成文件的情况下重复回退媒介帖子。

22.控制UI/会话：在会话表中显示每个会话的智能体运行时，并允许按运行时标签进行过滤，与智能体面板的运行时措辞相匹配。谢谢@vincentkoc。

23.Discord/streaming: 在进行中的草稿中显示实时推理文本，而不是仅显示简单的推理状态行。

24.网关/状态：在网关积累一个持续的采样窗口之前，避免仅因CPU/利用率而将快速重复的健康/状态样本标记为事件循环降级。谢谢@shakkernerd。

25.插件/更新：在主机更新期间，即使已禁用或以前精确固定的情况下，保持已安装的官方npm和ClawHub插件（如Codex、Discord、WhatsApp和诊断插件）同步，同时保留第三方插件的固定设置。感谢@vincentkoc。

26.Doctor/status: 当OPENCLAW_GATEWAY_TOKEN 会覆盖其他活动的gateway.auth.token 来源用于本地CLI 命令时发出警告，同时在配置指向相同环境令牌时避免错误的警报。修复#74271。感谢@yelog。

27.Gateway/HTTP: 避免为不相关的请求加载托管的外部图像媒体处理程序，因此禁用的OpenAI兼容路由返回404，而无需等待懒加载媒体边车。感谢@vincentkoc。

28.Gateway/OpenAI兼容：在接受流式聊天完成头之后，尽快发送助手角色SSE块，以便冷智能体设置不会让/v1/chat/completions客户端在其空闲超时触发之前收到无主体的200响应。

29.智能体/媒体：在announce-agent运行仍在等待时，避免直接生成媒体的完成回退，以便异步视频和音乐完成不会重复原始媒体消息。(#77754)

30.WebChat/Codex 媒体：在网关显示之前，对Codex 应用服务器生成的本地图像进行了管理，确保Codex-home 图像路径不再触发LocalMediaAccessError，同时保持Codex home 在显示白名单之外。感谢@frankekn。

31.TUI/sessions: 将会话选择器绑定到最近的行，并对活动会话使用精确查找式刷新，因此过时的存储不再导致TUI 在变得响应之前加载数周前的记录。感谢@vincentkoc。

32.医生/网关：在openclaw doctor –deep中报告最近的主管重启交接，使用已安装的服务环境（如有）以使服务管理的干净退出在指导诊断中可见。感谢@shakkernerd。

33.网关/状态：在openclaw 网关状态–deep 中显示最近的主管重启交接，包括JSON 详细信息，因此干净的服务管理重启被报告为重启交接，而不是不透明的停止服务诊断。谢谢@shakkernerd。

34.Providers/Fireworks: 将Kimi模型暴露为思考关闭状态，并保持K2.5/K2.6请求处于思考：禁用状态，因此手动模型切换不会发送Fireworks拒绝的推理*参数。Refs #74289。感谢@frankekn。

35.WhatsApp响应性：仅在经过验证的陈旧本地TUI客户端降低网关事件循环并延迟回复时停止它们。谢谢@vincentkoc。

36.插件/更新：在插件安装之前修复过时的托管npm根 openclaw peer包，以便beta渠道的官方插件更新不会因旧的核心包锁定状态而被降级。感谢 @vincentkoc。

37.插件/安装：在共享根npm安装、更新和卸载后重新确认管理的npm插件openclaw对等链接，以便变更一个插件不会导致之前安装的使用SDK的插件无法解析openclaw/plugin-sdk/*。

38.Hooks/session-memory: 为备用内存文件名添加冲突后缀，以便在同一分钟内重复的 /new 或 /reset 捕获不会覆盖早期的会话档案。感谢 @vincentkoc。

39.智能体/config: 从运行时路径中删除模糊的遗留主智能体目录助手; 模型、认证、网关、打包插件和测试助手现在通过agents.list/agent-scope助手解析默认/会话智能体目录，而插件SDK保持一个已弃用的兼容性导出。

40.CLI/status: 在openclaw 状态会话行中显示选定的智能体运行时/工具，以便终端状态与/status 运行行匹配。谢谢@vincentkoc。

41.CLI/sessions: 在正常会话清理期间修剪旧的未引用的转录、本地压缩检查点和轨迹工件，以便网关重启或崩溃的孤立对象不会在sessions.json 中无限累积。修复#77608。感谢@slideshow-dingo。

42.医生/编码器：修复主模型中的遗留openai-codex/* 路径，回退、心跳/子智能体/压缩覆盖、钩子、通道覆盖和过期会话固定，统一为openai/*，只有在安装、启用、贡献codex 附加组件并具有可用OAuth 时选择agentRuntime.id: “codex”；否则选择agentRuntime.id: “pi”。感谢@vincentkoc。

43.插件/更新：在主机更新期间，即使已禁用或以前精确固定的情况下，保持已安装的官方npm和ClawHub插件（如Codex、Discord、WhatsApp和诊断插件）同步，同时保留第三方插件的固定设置。感谢@vincentkoc。

44.视频生成：在工具边界接受提供商特定的宽高比和分辨率提示，将720P标准化为MiniMax支持的768P，并停止在Gemini视频请求中发送Google generateAudio，以便提供商回退能够从模型特定的参数差异中恢复。感谢@vincentkoc。

45.状态：在/status中显示紧凑的网关进程运行时间和主机系统运行时间，使重启和主机生命周期检查在聊天中可见。谢谢@vincentkoc。

46.WhatsApp响应性：仅在经过验证的陈旧本地TUI客户端降低网关事件循环并延迟回复时停止它们。谢谢@vincentkoc。

47.Hooks/session-memory: 在命令回复路径上运行重置内存捕获，并使模型生成的内存文件名缩写与llmSlug: true 选项相结合，因此/new 和/reset 不再在钩子维护或嵌套模型调用时阻塞WhatsApp 和其他消息通道的重置回复。感谢@vincentkoc。

48.CLI/gateway: 在完整的CLI命令完成后暂停非TTY标准输入，并在网关请求/认证失败后阻止openclaw智能体回退到嵌入模式，以便父命令能干净地退出，作用域交付探针立即显示真实的网关错误。感谢@vincentkoc。

49.网关/模型目录：缓存空的只读模型目录结果直到重新加载，因此当当前没有可用模型时，TUI和控制平面的刷新循环不能频繁读取插件元数据。感谢@vincentkoc。

50.Hooks/session-memory: 添加碰撞后缀到回退内存文件名，以便在同一分钟内重复的/new 或/reset 捕获不会覆盖早期的会话归档。感谢@vincentkoc。

51.TUI/sessions: 将会话选择器绑定到最近的行，并对活动会话使用精确查找式刷新，因此过时的存储不再导致TUI 在变得响应之前加载数周前的记录。感谢@vincentkoc。

52.智能体/上下文引擎：在上下文引擎的组装、回合后和摄取钩子中保留隐藏的OpenClaw运行时上下文自定义消息，使得转录重建插件只能看到对话消息。谢谢@vincentkoc。

53.TUI：跳过用于交互式启动的通用CLI重生包装，在终端丢失时干净退出，并拒绝恢复作为记忆聊天会话的心跳会话，防止首次启动时出现过时的心跳历史和孤立的openclaw-tui进程。感谢@vincentkoc。

54.Doctor/sessions: 将心跳污染的默认主会话存储条目移至恢复密钥，并清除过期的TUI 恢复指针，以便doctor –fix 可以修复已卡在agent:main:main 心跳历史上的实例。感谢@vincentkoc。

55.Gateway/shutdown: 通过ShutdownResult 报告结构化的关机警告和HTTP 关闭超时警告，同时保持生命周期钩子的强化。承接#41296。感谢@edenfunf。

56.CLI/update: 使开发频道的预检lint 成为可选，并在启用时进行约束，因此openclaw update –channel dev 不再在Ubuntu 主机OOM-kill 或并行oxlint 分片失败时回退其他良好的主提交。感谢@vincentkoc。

57.CLI/channels：跳过配置、智能体、通道选项目录、横幅配置和插件启动引导，针对bare openclaw channels parent-help命令，因此在打印帮助信息后能及时退出，而不是加载配置的通道插件。感谢@vincentkoc。

58.Gateway/shutdown: 取消关闭期间的延迟后准备维护，并在快速重启后抑制维护/cron 启动，以防止孤立的后台计时器。感谢@vincentkoc。

59.CLI/status: 在openclaw状态会话行中显示所选智能体的运行时/执行环境，以便终端状态与/status运行行匹配。谢谢@vincentkoc。

60.Sessions CLI：在openclaw 会话表中显示选定智能体的运行时，以便终端输出与JSON/status 界面中已存在的运行时可见性相匹配。感谢@vincentkoc。

61.控制UI/会话：在会话表中显示每个会话的智能体运行时，并允许按运行时标签进行过滤，与智能体面板的运行时措辞相匹配。谢谢@vincentkoc。

62.Docker/Gateway: 通过在捆绑的docker-compose.yml 中删除NET_RAW 和NET_ADMIN 权限并启用no-new-privileges 来加强网关容器的安全性。感谢@VintageAyu。

63.OpenAI/Gateway: 正确刷新初始聊天流块，以便首次令牌流可见，而不是被后续块延迟。

64.网关/媒体：跳过与HTTP路由无关的媒体边车处理，以便非媒体请求不受媒体路由行为的影响。

65.Discord：在进行草稿时显示推理文本，以便流式回复暴露有用的思考/进展，而不是空白的草稿更新。

66.认证配置文件：避免因格式级别的拒绝而使提供者进入冷却状态，以便在模型名称不受支持时仍可以尝试后备配置文件。

67.更新/插件：在更新过程中容忍损坏的管理插件记录，以便核心包更新仍然可以完成并报告插件修复路径。

68.更新：在获取失败后干净地停止开发频道更新，而不是继续进行后续更新步骤。

69.智能体/生成的媒介：将附件式消息工具操作视为已完成的聊天发送，以防止在已上传生成文件的情况下重复回退媒介帖子。

附录2、概述 聊天频道

文档索引

使用此文件在进一步探索之前发现所有可用页面。

OpenClaw可以在您已经使用的任何聊天应用上与您交谈。每个通道通过网关连接。文本在各处均被支持；媒体和反应因通道而异。

交货单

Telegram回复中包含markdown 图片语法，例如 ，在最终的外发路径中会尽可能转换为媒体回复。

Slack多人私信作为群聊进行路由，因此群组策略、提及行为和群组会话规则适用于MPIM 对话。

WhatsApp的设置是按需安装：入门过程可以在插件包安装之前展示设置流程，而网关仅在通道实际激活时加载WhatsApp运行时。

支持的频道

BlueBubbles –推荐用于iMessage；使用BlueBubbles macOS 服务器REST API，具备完整功能支持（捆绑插件；编辑、撤回、效果、反应、群组管理– 目前在macOS 26 Tahoe 上编辑功能损坏）。

Discord – Discord机器人API + 网关；支持服务器、频道和DM。

飞书– 通过WebSocket 的飞书/飞书机器人（打包插件）。

Google Chat- Google Chat API 应用通过HTTP webhook（可下载插件）。

iMessage (legacy) –通过imsg CLI 的旧版macOS 集成（已弃用，请使用BlueBubbles 进行新设置）。

IRC –经典IRC服务器；频道+ 直接消息，带有配对/允许列表控制。

LINE – LINE消息API机器人（可下载插件）。

Matrix – Matrix协议（可下载插件）。

Mattermost – Bot API + WebSocket；频道，组，私信（可下载插件）。

Microsoft Teams – Bot Framework；企业支持（捆绑插件）。

Nextcloud Talk –通过Nextcloud Talk（捆绑插件）自托管聊天。

Nostr –通过NIP-04（捆绑插件）实现去中心化的直接消息。

QQ Bot – QQ Bot API；私聊、群聊和富媒体（捆绑插件）。

信号– signal-cli；注重隐私。

Slack – Bolt SDK;工作区应用程序。

Synology Chat – Synology NAS通过出站+入站webhooks进行聊天（捆绑插件）。

Telegram – Bot API通过grammY；支持群组。

Tlon –基于Urbit的消息传递工具（捆绑插件）。

Twitch –通过IRC 连接的Twitch 聊天（打包插件）。

语音通话– 通过Plivo 或Twilio 进行电话通信（插件，单独安装）。

WebChat – Gateway WebChat UI over WebSocket.

微信– 腾讯iLink Bot插件通过二维码登录；仅限私聊（外部插件）。

WhatsApp –最受欢迎；使用Baileys并需要二维码配对。

Yuanbao –腾讯Yuanbao机器人（外部插件）。

Zalo – Zalo Bot API；越南的热门即时通讯工具（捆绑插件）。

Zalo个人– 通过二维码登录的Zalo 个人账户（捆绑插件）。

笔记

通道可以同时运行；配置多个，OpenClaw将按聊天进行路由。

最快的设置通常是Telegram（简单的机器人令牌）。WhatsApp 需要QR 配对并在磁盘上存储更多状态。

群体行为因渠道而异；参见群组。

DM配对和白名单出于安全原因而被强制执行；请参见安全性。

故障排除：频道故障排除。

模型提供者已单独记录；请参见模型提供者。

附录3 插件文档索引

获取完整文档索引请访问：https://docs.openclaw.ai/llms.txt

使用此文件在进一步探索之前发现所有可用页面。

插件通过Channels、模型提供者、智能体框架、工具、技能、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网络搜索等新功能扩展OpenClaw。部分插件是核心插件（与OpenClaw 一起发布），其他则是外部插件。大多数外部插件通过ClawHub 发布和发现。Npm 仍然支持直接安装以及一组临时的OpenClaw 拥有的插件包，直到迁移完成。

有关复制粘贴安装、列出、卸载、更新和发布示例，请参阅 管理插件。

openclaw插件列表

安装插件

#搜索ClawHub 插件

openclaw插件搜索“calendar”

#来自ClawHub

openclaw插件安装clawhub:openclaw-codex-app-server

#来自npm

openclaw插件安装npm:@acme/openclaw-plugin

openclaw plugins install npm-pack:./openclaw-plugin-1.2.3.tgz

#从git

openclaw插件安装git:github.com/acme/openclaw-plugin@v1.0.0

#从本地目录或归档中

openclaw插件安装./my-plugin

openclaw插件安装./my-plugin.tgz

重启网关

openclaw网关重启

然后在你的配置文件中配置plugins.entries.\<id\>.config。

聊天原生管理

在运行的网关中，拥有者专用的/plugins enable 和 /plugins disable 会触发网关配置重载器。网关在进程中重新加载插件运行时表面，而新的智能体则从刷新后的注册表中重建它们的工具列表。 /plugins install 会更改插件源代码，因此网关要求重启，而不是假装当前进程可以安全地重新加载已导入的模块。

验证插件

openclaw插件检查<plugin-id> –runtime –json

如果插件注册了CLI 根，则从该根运行一个命令。

openclaw <插件命令> –help

使用–runtime 当您需要证明已注册的工具、服务、网关方法、钩子或插件拥有的CLI 命令时。普通的inspect 是一次冷静的清单/注册检查，故意避免导入插件运行时。

如果您更喜欢聊天原生控制，请启用commands.plugins: true 并使用：

/plugin install clawhub:<package>

/plugin show <plugin-id>

/插件启用<插件-id>

安装路径使用与CLI相同的解析器：本地路径/归档、显式的clawhub:<pkg>、显式的npm:<pkg>、显式的npm-pack:<path.tgz>、显式的git:<repo>，或通过npm的裸包规格。如果配置无效，安装通常会失败并指向openclaw doctor –fix。唯一的恢复例外是针对选择参与openclaw.install.allowInvalidConfigRecovery的插件的窄范围捆绑插件重新安装路径。在网关启动期间，无效的插件配置像任何其他无效配置一样会失败。运行openclaw doctor –fix以通过禁用该插件条目和删除其无效的配置负载来隔离不良的插件配置；正常配置备份会保留之前的值。当通道配置引用一个不再可发现的插件，但相同的过期插件ID仍然保留在插件配置或安装记录中时，网关启动记录警告信息并跳过该通道，而不是阻止其他通道。运行openclaw doctor –fix以移除过期的通道/插件条目；没有过期插件证据的未知通道密钥仍然会失败验证，因此拼写错误是可见的。如果设置了plugins.enabled: false，过期的插件引用将被视为惰性：网关启动跳过插件发现/加载工作，openclaw doctor保留禁用的插件配置，而不是自动移除它。如果希望删除过期插件ID，请在运行医生清理之前重新启用插件。插件依赖的安装仅在显式的安装/更新或医生修复流程中进行。网关启动、配置重新加载和运行时检查不会运行包管理器或修复依赖树。本地插件必须已经安装其依赖项，而npm、git和ClawHub插件则在OpenClaw的管理插件根下安装。npm依赖可能在OpenClaw的管理npm根目录中被提升；安装/更新扫描会在信任之前扫描该管理根，卸载通过npm移除npm管理的包。外部插件和自定义加载路径仍必须通过openclaw plugins install安装。使用openclaw plugins list –json查看每个可见插件的静态dependencyStatus，而无需导入运行时代码或修复依赖关系。有关安装时间生命周期，请参阅插件依赖解析。

阻塞的插件路径所有权

如果插件诊断显示被阻止的插件候选：可疑的所有权（… uid=1000，预期uid=0 或root），并且配置验证的结果为插件存在但被阻止，OpenClaw 发现插件文件的拥有者与加载它们的进程的Unix 用户不同。保持插件配置不变；修复文件系统所有权或以拥有状态目录的相同用户身份运行OpenClaw。对于Docker 安装，官方映像以node（uid 1000）身份运行，因此主机绑定挂载的OpenClaw 配置和工作区目录通常应由uid 1000 拥有：

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

如果您故意以root身份运行OpenClaw，请修复受管理插件的root到root所有权。

sudo chown -R root:root /path/to/openclaw-config/npm

修复所有权后，重新运行 openclaw doctor –fix 或 openclaw plugins registry –refresh，以便持久化的插件注册表与修复后的文件匹配。对于npm 安装，可变选择器，如 latest 或一个dist-tag 在安装前被解析，然后固定为OpenClaw 管理的npm 根目录中的确切验证版本。npm 完成后，OpenClaw 验证已安装的 package-lock.json 条目仍然与解析后的版本和完整性匹配。如果npm 写入不同的包元数据，则安装失败，管理包将回滚，而不是接受不同的插件工件。源代码检出是pnpm 工作空间。如果你克隆OpenClaw 来处理捆绑插件，请运行 pnpm install; 然后OpenClaw 从 extensions/<id> 加载捆绑插件，以便直接使用编辑和包本地依赖。普通npm 根目录安装适用于已打包的OpenClaw，而不是源代码检出开发。

插件类型

OpenClaw识别两种插件格式：

格式	工作原理	示例
本地	openclaw.plugin.json + 运行时模块；在进程中执行	官方插件，社区npm包
包	与Codex/Claude/Cursor兼容的布局；映射到OpenClaw特性	.codex-plugin/, .claude-plugin/, .cursor-plugin/

两者都出现在openclaw 插件列表中。有关捆绑包的详细信息，请参见插件捆绑包。如果您正在编写原生插件，请从构建插件和插件SDK 概述开始。

包入口点

本地插件npm 包必须在package.json 中声明openclaw.extensions。每个条目必须保留在包目录内，并解析为可读取的运行时文件，或解析为具有推断构建后JavaScript 对应文件的TypeScript 源文件，例如src/index.ts 到dist/index.js。打包的安装必须包含该JavaScript 运行时输出。TypeScript 源文件回退是为了源代码检出和本地开发路径，而不是安装到OpenClaw 管理的插件根目录中的npm 包。如果一个管理包警告表示它需要TypeScript 条目的编译运行时输出…，那么该包是在没有OpenClaw 运行时所需的JavaScript 文件的情况下发布的。这是一个插件打包问题，而不是本地配置问题。更新或重新安装插件，待发布者重新发布编译后的JavaScript，或在可用修复包之前禁用/卸载该插件。当发布的运行时文件不位于与源条目相同的路径时，请使用openclaw.runtimeExtensions。当存在时，runtimeExtensions 必须包含每个extensions 条目的恰好一个条目。不匹配的列表会导致安装和插件发现失败，而不是默默地回退到源路径。如果您还发布了openclaw.setupEntry，请为其构建的JavaScript 对应文件使用openclaw.runtimeSetupEntry；声明时需要该文件。

{

“openclaw”: {

“extensions”: [“./src/index.ts”],

“runtimeExtensions”: [“./dist/index.js”]

}

}

官方插件

OpenClaw拥有的npm包在迁移过程中

ClawHub是大多数插件的主要分发路径。当前打包的OpenClaw 版本已经捆绑了许多官方插件，因此在正常设置中不需要单独的npm 安装。在每个OpenClaw 拥有的插件迁移到ClawHub 之前，OpenClaw 仍在npm 上提供一些@openclaw/* 插件包以供旧版/自定义安装和直接npm 工作流使用。如果npm 报告某个@openclaw/* 插件包已弃用，该包版本来自一个较旧的外部包版本。请使用当前OpenClaw 捆绑的插件或本地检出，直到发布更新的npm 包。

插件	包	文档
BlueBubbles	@openclaw/bluebubbles	BlueBubbles
Discord	@openclaw/discord	Discord
Feishu	@openclaw/feishu	Feishu
Matrix	@openclaw/matrix	Matrix
Mattermost	@openclaw/mattermost	Mattermost
Microsoft Teams	@openclaw/msteams	Microsoft Teams
Nextcloud Talk	@openclaw/nextcloud-talk	Nextcloud Talk
Nostr	@openclaw/nostr	Nostr
Synology Chat	@openclaw/synology-chat	Synology Chat
Tlon	@openclaw/tlon	Tlon
WhatsApp	@openclaw/whatsapp	WhatsApp
Zalo	@openclaw/zalo	Zalo
Zalo Personal	@openclaw/zalouser	Zalo Personal

核心（随OpenClaw一起发布）

模型提供者（默认启用）

内存插件

语音提供者（默认启用）

其他

寻找第三方插件？请查看社区插件。

配置说明

{

plugins: {

enabled: true,

allow: [“语音通话“],

deny: [“不可信的插件“],

load: { paths: [“~/Projects/oss/voice-call-plugin”] },

entries: {

“voice-call”: { enabled: true, config: { provider: “twilio” } },

},

},

}

字段	描述
enabled	主切换（默认值：true）
allow	插件白名单（可选）
bundledDiscovery	捆绑插件发现模式（默认白名单）
deny	插件黑名单（可选；黑名单优先）
load.paths	额外的插件文件/目录
slots	独占槽选择器（例如：memory, contextEngine）
entries.\<id\>	每个插件的切换+ 配置

plugins.allow是独占的。当它非空时，只有列出的插件可以加载或暴露工具，即使tools.allow 包含“*” 或特定插件拥有的工具名称。如果工具允许列表引用插件工具，请将拥有插件的ID 添加到plugins.allow 中，或移除plugins.allow；openclaw doctor 会对此形状发出警告。plugins.bundledDiscovery 默认值为“allowlist” 适用于新的配置，因此，限制性的plugins.allow 清单也会阻止被省略的捆绑提供插件，包括运行时网页搜索提供者发现。在迁移过程中，Doctor 会在较旧的限制性允许列表配置上标记“compat”，以便升级时保持遗留捆绑提供者的行为，直到操作员选择进入更严格的模式。一个空的plugins.allow 仍然被视为未设置/开放。通过/plugins enable 或/plugins disable 进行的配置更改会触发正在进行的Gateway 插件重载。新的智能体会根据刷新后的插件注册表重新构建其工具列表。源代码更改操作，如安装、更新和卸载，仍会重启Gateway 进程，因为已经导入的插件模块不能安全地就地替换。openclaw plugins list 是本地插件注册表/配置快照。那里启用的插件意味着持久化的注册表和当前配置允许该插件参与。这并不能证明已经运行的远程Gateway 已经重新加载或重新启动到相同的插件代码。在具有包装进程的VPS/容器设置中，请将重启或触发重新加载的写入发送到实际的openclaw gateway 运行进程，或者在重新加载报告失败时针对正在运行的Gateway 使用openclaw gateway restart。

插件状态：禁用vs 缺失vs 无效

发现与先例

OpenClaw按照以下顺序扫描插件（第一个匹配的获胜）：

原文段落内容：\n1\n\n所需要的语言：\n中文\n\n翻译结果：\n1

配置路径

plugins.load.paths –显式文件或目录路径。指向OpenClaw 自带的插件目录的路径将被忽略；运行openclaw doctor –fix 以删除那些过时的别名。

工作区插件

\<workspace\>/.openclaw/<plugin-root>/*.ts和\<workspace\>/.openclaw/<plugin-root>/*/index.ts。

全球插件

~/.openclaw/<plugin-root>/*.ts和 ~/.openclaw/<plugin-root>/*/index.ts.

捆绑插件

与OpenClaw一起发货。许多功能默认为启用（模型提供者、语音）。其他功能需要明确启用。

打包安装和Docker 镜像通常从编译后的dist/extensions 树中解析捆绑插件。如果捆绑插件的源目录被绑定挂载到匹配的打包源路径上，例如/app/extensions/synology-chat，OpenClaw 会将该挂载的源目录视为捆绑源覆盖，并在打包的/app/dist/extensions/synology-chat 捆绑包之前发现它。这使得维护者容器循环保持工作状态，而无需将每个捆绑插件切换回TypeScript 源。设置OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1 可以强制使用打包的dist 捆绑包，即使存在源覆盖挂载。

赋能规则

plugins.enabled: false禁用所有插件并跳过插件发现/加载工作

plugins.deny始终优先于allow

plugins.entries.\<id\>.enabled: false禁用该插件

工作区来源插件默认情况下是禁用的（必须显式启用）

捆绑插件遵循内置的默认开启设置，除非被覆盖。

独占插槽可以强制启用该插槽所选的插件

一些捆绑的自愿插件在配置指定插件拥有的表面时会自动启用，例如提供者模型引用、频道配置或工具运行时。

在plugins.enabled: false 激活期间，过期的插件配置将被保留；如果您希望删除过期的ID，请在运行医生清理之前重新启用插件。

OpenAI-family Codex路由保持独立的插件边界：openai-codex/* 属于OpenAI 插件，而捆绑的Codex 应用服务器插件由agentRuntime.id: “codex” 或遗留的codex/* 模型引用选择。

故障排除运行时钩子

如果插件出现在插件列表中，但register(api)副作用或钩子在在线聊天流量中未运行，请首先检查以下事项：

运行openclaw gateway status –deep –require-rpc 并确认活动的Gateway URL、配置文件、配置路径和进程是您正在编辑的。

在插件安装/配置/代码更改后重新启动实时网关。在包装容器中，PID 1可能只是一个监视器；请重启或发送信号给子级openclaw 网关运行进程。

使用openclaw 插件inspect <id> –runtime –json 来确认钩子注册和诊断。非捆绑的对话钩子，例如llm_input、llm_output、before_agent_finalize 和agent_end 需要 plugins.entries.<id>.hooks.allowConversationAccess=true。

对于模型切换，优先使用before_model_resolve。它在智能体回合的模型解析之前运行；llm_output 仅在模型尝试产生助手输出后运行。

为了证明有效的会话模型，使用openclaw 会话或网关会话/状态表面，并且在调试提供者负载时，使用–raw-stream –raw-stream-path <path> 启动网关。

缓慢的插件工具设置

如果智能体转变在准备工具时似乎停滞不前，请启用跟踪日志，并检查插件工具工厂的时间线：

openclaw config set logging.level trace

openclaw logs –follow

寻找：

[trace:plugin-tools] factory timings …

摘要列出了总工厂时间和最慢的插件工具工厂，包括插件ID、声明的工具名称、结果形状，以及该工具是否是可选的。当单个工厂的耗时达到至少1 秒或总插件工具工厂准备时间达到至少5 秒时，慢行将被提升为警告。OpenClaw 为具有相同有效请求上下文的重复解析缓存成功的插件工具工厂结果。缓存键包括有效的运行时配置、工作区、智能体/会话ID、沙箱策略、浏览器设置、交付上下文、请求者身份和所有权状态，因此当上下文发生变化时，依赖这些受信字段的工厂会重新运行。如果某个插件主导了时间，请检查其运行时注册：

openclaw插件检查<plugin-id> –runtime –json

然后更新、重新安装或禁用该插件。插件作者应将昂贵的依赖加载移到工具执行路径之后，而不是在工具工厂内部进行。

重复的频道或工具所有权

症状：

通道已经注册：<channel-id> (<plugin-id>)

频道设置已注册：<channel-id>（<plugin-id>）

插件工具名称冲突(<plugin-id>): <tool-name>

这些意味着多个启用的插件试图拥有相同的通道、设置流程或工具名称。最常见的原因是一个外部通道插件与一个已捆绑的插件一起安装，而该插件现在提供相同的通道ID。调试步骤：

运行openclaw plugins list –enabled –verbose 可以查看所有启用的插件及其来源。

运行openclaw 插件inspect <id> –runtime –json 对每个可疑插件进行检查，并比较channels、channelConfigs、tools 和diagnostics。

在安装或移除插件包后，运行openclaw plugins registry –refresh，以便持久化的元数据反映当前安装状态。

安装、注册或配置更改后重启网关。

修复选项：

如果一个插件故意替换另一个具有相同通道ID 的插件，则首选插件应声明channelConfigs.<channel-id>.preferOver 以表示较低优先级的插件ID。请参阅/plugins/manifest#replacing-another-channel-plugin。

如果重复是意外的，可以通过plugins.entries.<plugin-id>.enabled: false 禁用一侧，或移除过期的插件安装。

如果您明确启用了这两个插件，OpenClaw将保留该请求并报告冲突。为通道选择一个所有者，或者重命名插件拥有的工具，以确保运行时界面没有歧义。

插件插槽（独占类别）

某些类别是独占的（一次只能激活一个）：

{

plugins: {

slots: {

memory: “内存核心“, // or “none” to disable

contextEngine: “legacy”, // 或者一个插件ID

},

},

}

插槽	控制内容	默认值
内存	活动内存插件	内存核心
上下文引擎	活动上下文引擎	传统（内置）

CLI参考

openclaw插件列表                       # 紧凑清单

openclaw插件列表–enabled            # 仅启用的插件

openclaw插件列表—详细            # 每个插件的详细信息

openclaw plugins list –json # 机器可读的清单

openclaw插件搜索<query>            # 搜索ClawHub 插件目录

openclaw插件检查<id>              # 静态细节

openclaw插件检查<id> –runtime    # 注册的钩子/工具/CLI/网关方法

openclaw插件检查<id> –json       # 机器可读

openclaw plugins inspect –all # fleet-wide table

openclaw插件信息<id>                 # 检查别名

openclaw插件医生                    # 诊断

openclaw插件注册表                  # 检查持久化注册表状态

openclaw插件注册表–refresh        # 重建持久化注册表

openclaw doctor –fix # 修复插件注册状态

openclaw插件安装<package>         # 默认从npm 安装

openclaw插件安装clawhub:<pkg>     # 仅从ClawHub 安装

openclaw插件安装npm:<pkg>         # 仅从npm 安装

openclaw插件安装git:<repo>        # 从git 安装

openclaw插件安装git:<repo>@<ref>  # 从git 引用安装

openclaw plugins install <spec> –force # 覆盖现有安装

openclaw插件安装<path>            # 从本地路径安装

openclaw插件安装-l <path>         # 链接（不复制）用于开发

openclaw plugins install <plugin> –marketplace <source>

openclaw plugins install <plugin> –marketplace https://github.com/<owner>/<repo>

openclaw plugins install <spec> –pin # 记录确切解析的npm 规格

openclaw plugins install <spec> –dangerously-force-unsafe-install

openclaw插件更新<id-or-npm-spec> # 更新一个插件

openclaw插件更新<id-or-npm-spec> –dangerously-force-unsafe-install

openclaw plugins update –all # 更新所有

openclaw插件卸载<id>          # 移除配置和插件索引记录

openclaw插件卸载<id> —保留文件

openclaw插件市场列表<source>

openclaw插件市场列表<source> –json

#安装后验证运行时注册。

openclaw插件检查<id> –runtime –json

直接从OpenClaw 根CLI 运行插件所有的CLI 命令。

openclaw <插件命令> –help

openclaw插件启用<id>

openclaw插件禁用<id>

插件API 概述

本地插件导出一个条目对象，该对象暴露register(api)。较旧的插件仍可以使用 activate(api) 作为旧版别名，但新插件应该使用 register。

export default definePluginEntry({

id: “my-plugin”

name: “我的插件“,

register(api) {

api.registerProvider({

});

api.registerTool({

});

api.registerChannel({

});

},

});

OpenClaw加载入口对象并在插件激活时调用register(api)。加载器仍然会为旧插件回退到activate(api)，但捆绑插件和新的外部插件应该将register视为公共合同。api.registrationMode告诉插件为什么其入口被加载：

模式	含义
full	运行时激活。注册工具、钩子、服务、命令、路由和其他实时副作用。
discovery	只读能力发现。注册提供者和元数据；受信任的插件入口代码可以加载，但跳过实时副作用。
setup-only	通过轻量级设置入口加载通道设置元数据。
setup-runtime	同时需要运行时入口的通道设置加载。
cli-metadata	仅收集CLI命令的元数据。

打开套接字、数据库、后台工作者或长时间运行客户端的插件条目应将这些副作用与api.registrationMode === “full” 进行保护。发现加载与激活加载分开缓存，且不会替换正在运行的网关注册。发现是非激活的，不是无导入的：OpenClaw 可能会评估可信插件条目或通道插件模块以构建快照。保持模块顶层轻量且无副作用，并将网络客户端、子进程、监听器、凭证读取和服务启动移动到全运行时路径后。常见注册方法：

方法	注册内容
registerProvider	模型提供者(LLM)
registerChannel	聊天频道
registerTool	智能体工具
registerHook / on(…)	生命周期钩子
registerSpeechProvider	文本转语音/ STT
registerRealtimeTranscriptionProvider	流媒体STT
registerRealtimeVoiceProvider	双向实时语音
registerMediaUnderstandingProvider	图像/音频分析
registerImageGenerationProvider	图像生成
registerMusicGenerationProvider	音乐生成
registerVideoGenerationProvider	视频生成
registerWebFetchProvider	网页获取/ 抓取提供者
registerWebSearchProvider	网页搜索
registerHttpRoute	HTTP 端点
registerCommand / registerCli	CLI 命令
registerContextEngine	上下文引擎
registerService	后台服务

类型生命周期钩子的钩子保护行为：

before_tool_call:{ block: true } 是终止的；低优先级的处理程序会被跳过。

before_tool_call: { block: false }是一个无操作，并且不会清除之前的块。

before_install:{ block: true } 是终端；低优先级处理程序被跳过。

before_install: { block: false }是一个无操作的指令，不会清除之前的阻塞。

message_sending:{ cancel: true } 是终止的；较低优先级的处理程序被跳过。

message_sending: { cancel: false }是一个无操作，并不会清除之前的取消。

本地Codex 应用服务器将桥接Codex-native 工具事件回传到此钩子表面。插件可以通过before_tool_call 阻止原生Codex 工具，通过after_tool_call 观察结果，并参与Codex PermissionRequest 的批准。桥接尚未重写Codex-native 工具参数。确切的Codex 运行时支持边界存在于Codex harness v1 支持合同中。如需完整的类型化钩子行为，请参阅SDK 概览。