插件与钩子——扩展 OpenClaw 的能力边界

OpenClaw 完全指南（15/18）

上一篇我们让 AI 伸出了”手脚”——通过节点系统远程控制手机和 Mac。但你有没有想过，OpenClaw 开箱就能连 Telegram，那 Discord、飞书、Slack 呢？答案藏在插件系统里。而钩子（Hooks）则像是埋在 OpenClaw 体内的”触发器”，在关键时刻自动执行你预设的逻辑。

这一篇把插件、钩子、技能三者的关系彻底讲清楚，然后带你把所有相关命令走一遍。

15.1 插件 vs 技能 vs 钩子——三者的区别与关系

刚接触 OpenClaw 的时候，最容易搞混的就是这三个概念：Plugin、Skill、Hook。它们都是”扩展 OpenClaw 能力”的方式，但作用层级完全不同。你可能会问：为什么要分这么细？直接都叫”插件”不行吗？

不行。因为它们解决的问题不在同一个层面上。

打个比方：如果把 OpenClaw 比作一个人——

• 插件（Plugin） 是器官——眼睛能看（Telegram 渠道）、嘴巴能说（语音插件）、大脑皮层能思考（Provider 插件连接 AI 模型）
• 技能（Skill） 是学会的本事——会做饭（coding-agent）、会看天气（weather）、会管 GitHub（gh-issues）
• 钩子（Hook） 是条件反射——看到亮光瞳孔自动收缩（Gateway 启动时自动读取配置）、睡前自动回忆今天的事（会话结束时保存记忆）

💡 一句话总结：插件决定 OpenClaw “能连什么”，技能决定 Agent “会干什么”，钩子决定”什么时候自动干什么”。

举个具体例子帮你理解。你想让 AI 助手在 Discord 群里每天自动播报天气预报，这三层是这样配合的：

1. 插件层：discord 渠道插件让 OpenClaw 能连上 Discord 服务器——没有这个插件，Gateway 根本不知道怎么和 Discord 通信
2. 技能层：weather 技能让 Agent 会查天气——没有这个技能，Agent 收到”今天天气怎么样”也只能干瞪眼
3. 钩子层：boot-md 钩子可以在启动时读取 BOOT.md 里写好的”每天 8 点发天气”指令——没有这个钩子，你就得每天手动去触发

三者缺一不可，但各司其职。

下面这张图展示了三者在 OpenClaw 架构中的位置：

15.2 41 个内置插件总览

OpenClaw 自带 41 个插件，不需要额外安装——它们已经在安装包里了，只是大部分默认没启用。按功能可以分成三大类。

渠道插件（18 个）——决定 AI “住在哪”

渠道插件让 OpenClaw 能连接到各种聊天平台。每启用一个，你的 AI 助手就多了一个”住址”。这也是 OpenClaw 最核心的卖点之一——一套 AI 后端，同时服务十几个聊天平台，消息路由和用户身份全由 Gateway 统一管理。

💡 表格里没列出 bluebubbles、nextcloud-talk、synology-chat 这三个——它们也是渠道插件，只是相对小众。bluebubbles 是另一种 iMessage 桥接方案，nextcloud-talk 和 synology-chat 分别对接 Nextcloud 和群晖的聊天功能。加上这三个，渠道类插件实际有 21 个，占了总数的一半。

对国内用户来说，最实用的几个是：telegram（翻墙后最方便）、feishu（飞书/Lark，企业场景首选）、discord（技术社区常用）。如果你的团队用企业微信——目前还没有官方插件，但可以通过 matrix 或 mattermost 做桥接。

Provider 插件（7 个）——决定 AI “用什么脑子”

Provider 插件负责连接不同的 AI 模型后端。你用什么模型跑推理，就需要对应的 Provider 插件。

💡 注意：OpenAI、Anthropic Claude、OpenRouter 这些不需要专门的 Provider 插件——它们走的是 OpenClaw 内置的标准 API 适配器（兼容 OpenAI API 格式的都不需要插件）。Provider 插件解决的是那些有特殊认证方式或非标准 API 的模型后端。

在我们的实测环境中，主模型是 vllm/Huihui-Qwen3.5-35B-A3B-abliterated（一个本地部署的 35B 参数模型），通过 vLLM Provider 插件接入。同时还加载了 Ollama 和 SGLang 两个 Provider 作为备选，加上 OpenRouter 转发的 11 个回退模型（Claude、GPT、Qwen、Grok、GLM 等），AI 可用的”脑子”相当充裕。👉 详见第 3 篇《模型配置》了解多模型配置和回退机制。

功能插件（12 个）——杂而不乱的增强能力

功能插件比较杂，从设备配对到语音通话到记忆引擎都有。它们的共同点是：不归类于渠道，也不归类于模型，但缺了它们某些功能就用不了。

当前加载状态一览

实测环境（OpenClaw 2026.3.13）中，41 个插件里有 8 个已加载：

1. Device Pairing（设备配对）
2. Memory Core（核心记忆）
3. Ollama Provider
4. Phone Control（手机控制）
5. SGLang Provider
6. Talk Voice（语音选择）
7. Telegram（Telegram 渠道）
8. vLLM Provider

剩下 33 个处于”已发现但未加载”状态——它们的代码已经在本地了，只是没有启用。

你可能会好奇：为什么不全开？两个原因：

1. 资源占用：每个加载的插件都会占用内存和 CPU。渠道插件还会维持长连接，开 20 个渠道意味着 20 条 WebSocket 连接常驻内存
2. 配置要求：大部分渠道插件需要对应平台的 Bot Token 才能正常工作，没有 Token 的插件加载了也只会报错

所以正确做法是：用什么开什么，而不是贪多求全。

15.3 openclaw plugins 全部命令详解

插件管理的所有操作都通过 openclaw plugins 完成。总共 8 个子命令，覆盖了从查看到安装到排障的完整生命周期。

plugins list —— 查看所有插件（已加载/已禁用）

openclaw plugins list

这条命令列出 OpenClaw 发现的所有插件，包括已加载的和未加载的。输出会标明每个插件的状态：

• loaded（已加载）：正在运行，Gateway 启动时成功初始化
• discovered（已发现）：代码在本地但没有在配置中启用
• disabled（已禁用）：在配置中被手动禁用了

这是你排查问题的第一步——”这个插件到底装了没有？加载了没有？”用 plugins list 一看便知。在我们的实测环境中，这条命令会输出 41 行，其中 8 行状态是 loaded，其余是 discovered。

💡 小技巧：如果插件列表太长，可以配合 grep 快速过滤。比如只看已加载的：openclaw plugins list | grep loaded。

plugins info <name> —— 查看插件详情

# 查看 Telegram 插件的详细信息openclaw plugins info telegram# 查看 vLLM Provider 的详细信息openclaw plugins info vllm

info 会显示插件的版本、描述、依赖关系、配置项等完整信息。当你想知道一个插件”到底能干什么、需要什么配置”的时候，先用这个命令看看。

这个命令特别有用的场景是：你想启用一个新渠道，但不确定它需要哪些配置项。比如 openclaw plugins info feishu 会告诉你飞书插件需要 App ID、App Secret 和事件回调 URL。

plugins install <spec> —— 安装插件

这是插件管理的核心命令。<spec> 支持三种来源：

方式一：从 npm 安装

# 从 npm 仓库安装一个社区插件openclaw plugins install @openclaw/plugin-example# 安装特定版本openclaw plugins install @openclaw/plugin-example@1.2.0

npm 是最标准的安装方式，社区贡献的第三方插件一般都发布在 npm 上。

方式二：从本地路径安装

# 从本地目录安装openclaw plugins install /opt/my-plugins/custom-channel# 开发模式：用 --link 创建软链接而不是复制openclaw plugins install /opt/my-plugins/custom-channel --link

--link 参数非常适合插件开发调试——修改源码后不需要重新安装，直接重启 Gateway 就能生效。

方式三：从归档文件安装

# 从 tar.gz 归档安装openclaw plugins install /tmp/my-plugin.tar.gz# 从 zip 归档安装openclaw plugins install /tmp/my-plugin.zip

适合离线环境或者从别人那里拿到一个打包好的插件。比如公司内网不能访问 npm，就可以在外网下载好归档包，再拷贝到服务器上安装。

⚠️ 安装第三方插件前请注意安全。插件在 Gateway 进程中运行，拥有相当大的权限。只安装你信任的来源——官方的 @openclaw/ 包或者你自己开发的插件。

plugins uninstall <name> —— 卸载插件

# 卸载一个插件openclaw plugins uninstall my-plugin

卸载会移除插件的代码文件和相关数据。内置的 41 个插件一般不需要卸载——直接 disable 就行。uninstall 主要用于清理那些通过 install 手动安装的第三方插件。

⚠️ 卸载前先 disable 并重启 Gateway，确保插件已经停止运行，再执行 uninstall。直接卸载一个正在运行的插件可能导致 Gateway 异常。

plugins enable / disable <name> —— 启用和禁用

# 启用插件openclaw plugins enable discord# 禁用插件openclaw plugins disable discord

启用和禁用会修改配置文件中的 plugins.entries.<name>.enabled 值。注意：改完之后需要重启 Gateway 才能生效。

# 启用后重启 Gateway 让配置生效openclaw plugins enable telegramopenclaw gateway restart

你也可以用 config set 命令达到同样的效果：

# 等价于 plugins enable telegramopenclaw config set plugins.entries.telegram.enabled true# 等价于 plugins disable telegramopenclaw config set plugins.entries.telegram.enabled false

plugins update —— 更新插件

# 更新所有已安装的插件openclaw plugins update# 更新特定插件openclaw plugins update my-plugin

更新命令会检查 npm 上是否有新版本，然后自动拉取并替换。内置插件随 OpenClaw 主程序更新（也就是 openclaw update 的时候会一起更新），一般不需要单独 update。plugins update 主要面向通过 install 安装的第三方插件。

更新完之后别忘了重启 Gateway：

openclaw plugins update my-pluginopenclaw gateway restart

plugins doctor —— 诊断插件问题

openclaw plugins doctor

这是排障利器。当你发现某个插件应该加载却没加载的时候，doctor 会报告加载失败的原因——是缺少依赖？配置有误？还是版本不兼容？它会逐个检查所有已注册的插件，然后输出一份”体检报告”。

典型的排障流程分三步走：

# 第一步：看看插件在不在、状态是什么openclaw plugins list# 第二步：看看它需要什么配置和依赖openclaw plugins info my-plugin# 第三步：让 doctor 诊断加载问题openclaw plugins doctor

doctor 常见的诊断结果包括：

• missing dependency：缺少 Node.js 依赖包，需要在插件目录里 npm install
• configuration required：插件需要特定配置项（比如 Bot Token）但你还没配
• version mismatch：插件要求的 OpenClaw 版本和当前版本不匹配
• load error：插件代码有 bug 或者运行时出错

遇到问题先跑 doctor，90% 的插件加载问题都能在这里找到线索。

15.4 openclaw hooks 全部命令详解

钩子的管理命令和插件类似，但更简单——因为钩子数量少（目前只有 4 个内置钩子），操作也比较直接。不过千万别因为数量少就忽视它们，这 4 个钩子承担着 OpenClaw 最核心的自动化逻辑。

hooks list —— 列出所有钩子

openclaw hooks list

显示所有已注册的钩子及其状态（enabled/disabled）。在我们的实测环境中，4 个钩子全部处于就绪状态——这是推荐的默认配置，除非你有明确的理由，否则不要随便关。

hooks info <name> —— 查看钩子详情

# 查看 session-memory 钩子的详情openclaw hooks info session-memory# 查看 boot-md 钩子的详情openclaw hooks info boot-md

会输出钩子的触发时机、功能描述、依赖的配置项等信息。

hooks enable / disable <name> —— 启用和禁用

# 禁用命令审计日志（比如觉得日志太多了）openclaw hooks disablecommand-logger# 重新启用openclaw hooks enablecommand-logger

和插件一样，也可以用 config set 直接改配置：

# 禁用 session-memory 钩子openclaw config set hooks.internal.entries.session-memory.enabled false# 启用 command-logger 钩子openclaw config set hooks.internal.entries.command-logger.enabled true

配置文件中钩子的结构长这样：

"hooks": {"internal": {"enabled": true,"entries": {"boot-md": { "enabled": true },"bootstrap-extra-files": { "enabled": true },"command-logger": { "enabled": true },"session-memory": { "enabled": true }    }  }}

⚠️ 最外层的 hooks.internal.enabled 是总开关。如果设为 false，所有钩子都不会执行，不管单个钩子的 enabled 是 true 还是 false。

hooks install <spec> —— 安装钩子

# 从本地路径安装自定义钩子openclaw hooks install /path/to/my-hook

目前 OpenClaw 的钩子生态还比较早期，4 个内置钩子已经覆盖了最常见的需求。但如果你有特殊需求——比如想在每次会话开始前自动从公司内部 API 拉取最新产品价格表、或者在每次命令执行后自动发一条 Slack 通知——可以自己开发一个钩子安装上去。

钩子本质上是一个 Node.js 模块，实现特定的接口就行。不过这个话题比较深入，超出了本篇的范围。

hooks update —— 更新钩子

# 更新所有已安装的钩子openclaw hooks update

hooks check —— 检查钩子状态

# 检查所有钩子的资格状态openclaw hooks check

check 和插件的 doctor 类似，会验证每个钩子是否满足运行条件（资格检查）。比如 session-memory 钩子需要记忆系统正常工作，如果记忆后端配置有误，check 会报告出来。boot-md 钩子需要 Agent 工作区中存在 BOOT.md 文件，如果文件缺失，check 也会提示。

建议在修改钩子配置后养成跑一次 check 的习惯，确认所有钩子都正常：

# 改完配置后验证一下openclaw hooks check

15.5 4 个内置钩子详解

4 个钩子各管一件事，但都很关键。下面逐个展开，让你搞清楚每个钩子到底在什么时候被触发、做了什么事、以及你能怎么利用它。

boot-md：Gateway 启动时的”开机自检”

触发时机：Gateway 启动时做什么：读取 Agent 工作区中的 BOOT.md 文件并执行其中的指令

这是 OpenClaw 的启动引导机制。BOOT.md 里可以写启动时要执行的初始化逻辑——比如检查外部服务是否可用、预加载某些数据、发送一条”我上线了”的通知。

<!-- 示例：BOOT.md -->检查天气 API 是否可用，如果不可用就在日志里记一条警告。读取 memory/ 目录下最近的 3 条记忆，作为今天对话的上下文。

💡 BOOT.md 的内容会作为 Agent 的第一条指令执行。所以你可以把它当作 Agent 的”开机脚本”——每次 Gateway 重启，Agent 都会先按这个文件的指示做一轮初始化。👉 详见第 7 篇《工作区调教指南》了解 BOOT.md 的完整用法。

bootstrap-extra-files：注入额外启动文件

触发时机：Agent 启动初始化阶段做什么：在标准的 SOUL.md、MEMORY.md 之外，额外加载其他启动文件

说白了就是让你往 Agent 的初始上下文里”塞私货”。标准启动流程是读 SOUL.md（人设）和 MEMORY.md（记忆），这个钩子允许你额外注入文件——比如一份产品知识库、一个 FAQ 文档、或者一组固定的行为规则。

这对企业场景特别有用：你可能有一份不想写在 SOUL.md 里的合规要求文档，用这个钩子在启动时悄悄注入就行。

具体的使用方式取决于你的 Agent 工作区配置。一般来说，把额外文件放在 Agent 工作区目录下，然后在 Agent 配置中指定哪些文件需要被 bootstrap 加载即可。比如你有一份 COMPLIANCE.md（合规要求）和一份 PRODUCT-FAQ.md（产品 FAQ），都可以通过这个钩子在启动时注入到 Agent 的上下文中。

和 boot-md 的区别是：boot-md 注入的是指令（Agent 会去执行），而 bootstrap-extra-files 注入的是知识（Agent 会记住但不会主动执行）。

command-logger：命令审计日志

触发时机：每次执行命令时做什么：记录所有通过 Agent 执行的命令到日志

这是安全审计的基础。在企业环境里，你需要知道 AI 代理执行了什么操作——不光是为了排查问题，也是合规需求。command-logger 会记录：

• 谁（哪个用户/渠道）触发了命令
• 什么时候执行的
• 执行了什么命令
• 执行结果如何

如果你觉得日志太多、影响性能，可以临时关掉：

openclaw hooks disablecommand-logger

但在生产环境里，强烈建议保持开启。出了问题没有审计日志，排查起来会很痛苦。尤其是当你的 AI 助手有沙箱执行能力（可以运行代码、操作文件）的时候，审计日志就是你的”黑匣子”——出了事故至少能还原现场。

💡 command-logger 和 👉 第 16 篇《安全备份监控》中讲的日志管理是配套的。审计日志的存储位置、轮转策略、保留时长等，我们下一篇会详细讲。

session-memory：会话结束时的”睡前日记”

触发时机：会话结束时做什么：自动将本次会话的关键信息保存到 memory/ 目录

这是 OpenClaw 记忆系统的核心驱动力之一。每次对话结束后，这个钩子会分析对话内容，提取重要信息（比如用户提到的偏好、待办事项、新学到的知识），然后写入 Agent 工作区的 memory/ 目录。

下一次对话开始时，boot-md 钩子又会把记忆加载回来——这样 AI 就真的”记住”了上次聊的内容。

会话结束  → session-memory 钩子触发  → 提取对话中的关键信息  → 写入 memory/ 目录  → [下次启动]  → boot-md 钩子读取 memory/  → Agent 拥有了上次的记忆

💡 session-memory 和 boot-md 配合使用，构成了一个完整的”记忆闭环”。如果你禁用了 session-memory，Agent 就不会自动保存对话记忆——虽然手动保存（通过技能或命令）还是可以的，但自动化就断了。👉 详见第 8 篇《记忆系统》了解记忆的完整机制。

15.6 启用渠道插件实战

说了这么多原理，来点实操。我们的实测环境已经启用了 Telegram，下面演示怎么启用其他几个常用渠道。每个渠道的启用分两步：第一步是在 OpenClaw 里开启插件，第二步是去对应平台创建 Bot 并获取凭据。第一步都是一样的命令，第二步各平台不同。

启用 Telegram（已实测）

Telegram 是我们实测环境中唯一启用的渠道插件。整个流程：

# 1. 确认插件存在openclaw plugins list# 输出会显示 telegram 状态为 loaded# 2. 如果没启用，手动启用openclaw plugins enable telegram# 3. 配置 Bot Token（通过 @BotFather 获取）openclaw config set plugins.entries.telegram.enabled true# 4. 重启 Gatewayopenclaw gateway restart

💡 Telegram 的详细接入步骤（创建 Bot、获取 Token、配置 Webhook）👉 详见第 4 篇《接入聊天渠道》。

启用 Discord

# 1. 启用 Discord 插件openclaw plugins enable discord# 或者用 config setopenclaw config set plugins.entries.discord.enabled true# 2. 重启 Gateway 让插件加载openclaw gateway restart# 3. 确认插件已加载openclaw plugins list# 应该能看到 discord 状态变为 loaded

启用之后，你还需要去 Discord 平台做几件事：

1. 到 Discord Developer Portal 创建一个 Bot Application
2. 在 Bot 设置页面开启 Message Content Intent（这个必须开，否则 Bot 收不到消息内容）
3. 获取 Bot Token，通过 openclaw config set 或 openclaw onboard 配置到 OpenClaw 中
4. 生成 OAuth2 邀请链接，把 Bot 邀请到你的 Discord 服务器

Discord 的好处是支持丰富的消息格式（Embed、按钮、下拉菜单），适合做交互式的 AI 助手。缺点是需要翻墙。

启用飞书 / Lark

飞书对国内企业用户很友好。启用方式一样：

# 1. 启用飞书插件openclaw plugins enable feishu# 或者openclaw config set plugins.entries.feishu.enabled true# 2. 重启 Gatewayopenclaw gateway restart

飞书的接入稍微复杂一点：

1. 到飞书开放平台创建一个企业自建应用
2. 在应用的”事件订阅”页面配置回调地址（https://你的域名/api/feishu/webhook，需要 Gateway 有公网可达的地址）
3. 获取 App ID 和 App Secret，配置到 OpenClaw 中
4. 在应用权限页面申请必要的消息读写权限
5. 发布应用（或在测试环境中使用）

飞书的优势是国内企业环境不需要翻墙，而且和飞书审批、飞书文档等生态打通后想象空间很大。比如让 AI 助手自动读取飞书文档内容、或者在群里回答同事的技术问题。

启用 Slack

# 1. 启用 Slack 插件openclaw plugins enable slack# 或者openclaw config set plugins.entries.slack.enabled true# 2. 重启openclaw gateway restart

Slack 需要到 Slack API 创建 App，配置步骤：

1. 创建 Slack App（选择 “From scratch”）
2. 在 OAuth & Permissions 页面添加 Bot Token Scopes：至少需要 chat:write（发消息）、channels:history（读消息历史）、app_mentions:read（接收 @提及）
3. 安装 App 到你的 Workspace，获取 Bot User OAuth Token（以 xoxb- 开头的那个）
4. 在 Event Subscriptions 页面配置事件回调 URL 并订阅 message.channels 和 app_mention 事件
5. 记下 Signing Secret，连同 Bot Token 一起配置到 OpenClaw 中

Slack 的优势是企业用户基数大，很多海外团队的日常沟通都在 Slack 里。把 AI 助手放进 Slack 频道，同事直接 @它就能用。

通用启用流程总结

不管什么渠道插件，启用流程都是一样的三步：

# 第一步：启用插件openclaw config set plugins.entries.<插件名>.enabled true# 第二步：重启 Gatewayopenclaw gateway restart# 第三步：确认加载成功openclaw plugins list

如果第三步发现插件没有变成 loaded 状态，用 doctor 排查：

openclaw plugins doctor

常见的加载失败原因和解决办法：

⚠️ 一个 Agent 可以同时绑定多个渠道。 比如你同时启用了 Telegram 和 Discord，同一个 Agent 可以在两个平台上同时接受消息。消息来自哪个渠道，Agent 会自动识别并在对应渠道回复。这个多渠道能力是通过 Gateway 的路由绑定（Binding）实现的。👉 详见第 9 篇《多 Agent 架构》了解绑定的详细配置。

本篇小结

这一篇我们把 OpenClaw 的插件和钩子系统掰开了讲：

1. 三者区别：插件是平台基础设施（连什么渠道、用什么模型），技能是 Agent 的能力包（会干什么活），钩子是事件触发器（什么时候自动干什么）
2. 41 个内置插件：18 个渠道插件覆盖全球主流聊天平台，7 个 Provider 插件对接各种 AI 推理引擎，12 个功能插件提供设备配对、记忆、语音等增强能力
3. 插件管理命令：list 查看、info 详情、install 安装（npm/本地/归档三种来源）、enable/disable 启停、update 更新、doctor 排障
4. 钩子管理命令：list/info/enable/disable/install/update/check 七件套
5. 4 个内置钩子：boot-md 开机自检、bootstrap-extra-files 注入额外文件、command-logger 命令审计、session-memory 自动保存记忆
6. 渠道启用实战：config set plugins.entries.<名称>.enabled true + gateway restart 就是万能公式

关键数据：实测环境 8/41 插件已加载，4/4 钩子全部就绪。大部分插件不是”装不上”，而是”没必要全开”——按需启用就好。

📖 下一篇我们讲 安全加固、备份与监控——Token 怎么保管、Gateway 怎么加固、数据怎么备份、出了问题怎么看日志。这些是把 OpenClaw 从”玩具”变成”生产工具”的关键。👉 详见第 16 篇《安全备份监控》