一、为什么熙瑾会悟需要接 OpenClaw？

熙瑾会悟本身已经具备比较完整的会议智能化能力。

比如：

以前这些能力更多是通过独立客户端或者 Web 服务调用。

但随着 Agent 类应用越来越多，一个很明显的问题出现了：

如果 Agent 能够直接调用“会议转写”“查询会议”“生成会议纪要”“搜索知识库”这些能力，很多业务流程其实可以直接自动化。

例如用户对 Agent 说：

“帮我找一下昨天销售会议中关于华东区域的讨论，并总结一下有哪些待办。”

传统方式需要：

如果接入 Agent，则可以变成：

这也是我们开始研究 OpenClaw 插件机制的主要原因。

目前 OpenClaw 官方文档把插件定位为一种不修改核心代码即可扩展运行能力的机制，可以扩展消息渠道、模型提供商、Agent 工具、Hook、媒体能力等。

二、先搞清楚 OpenClaw 插件到底是什么

刚开始接触的时候，很容易把 OpenClaw Plugin 理解成普通的“第三方 JavaScript 插件”。

实际上它更接近：

OpenClaw Runtime + Plugin SDK + Manifest + Agent Tool 的扩展体系。

从工程角度来看，可以简单理解成：

官方目前支持多种插件形态，包括 Channel Plugin、Provider Plugin、CLI Backend Plugin、Tool Plugin 等。

对于熙瑾会悟而言，第一阶段最适合的其实不是开发一个复杂 Provider，而是：

Tool Plugin。

原因很简单。

我们不是马上替换 OpenClaw 的模型，而是希望让 Agent 能够调用熙瑾会悟已有的业务能力。

三、插件开发环境需要注意什么？

这里第一个坑就出现了。

OpenClaw 当前插件开发文档要求使用：

类别	要求
运行时	Node.js 22.22.3+
运行时	Node.js 24.15+
运行时	Node.js 25.9+
语言	TypeScript
模块规范	ESM
包管理器	npm / pnpm

内置插件源码开发则要求使用 pnpm。

所以如果之前项目习惯还是：

Java 8 Spring Boot Maven 突然进入：

Node TypeScript ESM pnpm 第一感觉确实有点割裂。

熙瑾会悟本身后端还是 Java 技术栈，因此我们的思路并不是把原来的 Java 服务全部改掉，而是：

这样改造成本低很多。

插件负责“接入”，Java 后端负责“业务”。

四、插件目录结构怎么设计？

实际开发时，我比较建议不要一上来把所有逻辑全部塞进 index.ts。

可以按照下面这种方式拆：

这样后面继续扩展会舒服很多。

例如：

meeting-search

meeting-summary

knowledge-search

speaker-query

todo-extract

分别对应不同 Agent Tool。

五、第一个真正容易踩坑的问题：ESM

OpenClaw 插件要求 TypeScript ESM 模块。

也就是说，不能继续按照以前 CommonJS 的思路写：

const xxx = require("xxx");

更推荐：

import xxx from "xxx";

同时 package.json 中需要：

{
  "type": "module"
}

这一点看起来很简单，但实际项目里特别容易出现。

尤其是一些旧 Node 项目混用：

require module.exports import export 最后启动插件的时候就会出现类似：

ERR_REQUIRE_ESM 或者：

Cannot use import statement outside a module 这种问题。

所以我个人比较建议：

从项目第一天开始，就把 ESM 体系统一下来。

不要等插件写完了再改。

六、第二个问题：Plugin Manifest 不能随便写

OpenClaw 原生插件需要：

openclaw.plugin.json 这个文件不是装饰品。

它负责描述插件本身的元数据以及能力。

官方文档明确要求原生 OpenClaw 插件在插件根目录提供 openclaw.plugin.json，如果 Manifest 缺失或者无效，会导致配置校验失败。

例如可以设计成：

{
  "id": "xj-huiwu",
  "name": "熙瑾会悟",
  "description": "熙瑾会悟会议智能能力插件",
  "contracts": {
    "tools": [
      "huiwu_meeting_search",
      "huiwu_meeting_summary",
      "huiwu_knowledge_search"
    ]
  },
  "activation": {
    "onStartup": true
  }
}

这里有一个容易忽略的点：

Manifest 和实际运行时代码不是一回事。

Manifest 更像“身份证”。

Runtime Module 才是真正干活的代码。

七、第三个问题：package.json 中的 OpenClaw 配置

除了 Manifest，package.json 同样非常重要。

官方示例中使用了类似：

{
  "name": "@myorg/openclaw-my-plugin",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": [
      "./index.ts"
    ]
  }
}

同时还可以通过 peerDependencies、compat 等字段声明 OpenClaw 版本兼容关系。

我们在设计熙瑾会悟插件的时候，也需要重点考虑：

这几个版本不能完全脱钩。

否则非常容易出现：

本地可以运行 生产环境启动失败 这种比较难查的问题。

八、Tool Plugin 是整个接入过程的核心

对于熙瑾会悟来说，最重要的是 Tool。

比如：

huiwu_meeting_search huiwu_meeting_summary huiwu_knowledge_search 这些工具对 Agent 来说，就是它可以使用的“业务能力”。

官方目前提供了 defineToolPlugin 用于构建只添加 Agent Tool 的插件，并要求 typebox 位于运行时依赖中。

为什么这里要强调 TypeBox？

因为 Agent Tool 最终不是简单的方法调用。

它实际上需要描述：

工具名称 工具用途 参数 参数类型 参数约束 返回结果 例如：

{
  name: "huiwu_meeting_search",
  description: "搜索熙瑾会悟中的历史会议内容",
  parameters: {
    keyword: "string",
    date: "string"
  }
}

这样大模型才能理解：

什么情况下应该调用这个工具？

九、真正困难的地方：Tool Description 怎么写？

这个问题一开始很容易被忽略。

比如：

搜索会议 这种描述对人来说已经很明确。

但对于 Agent 来说太模糊。

更好的方式是：

搜索熙瑾会悟中已经完成转写的历史会议。

适用于：

1. 用户查询某次会议内容；
2. 用户搜索某个关键词是否在会议中出现；
3. 用户要求查找某段历史讨论；
4. 用户需要根据日期、会议标题、关键词定位会议。

不适用于：

1. 实时语音转写；
2. 删除会议；
3. 修改会议内容。

这实际上就是在做一种“工具级 Prompt Engineering”。

十、Agent Tool Calling 背后的模型逻辑

OpenClaw 插件接入之后，真正决定调用哪个 Tool 的，还是模型。

例如用户：

“帮我找一下昨天关于项目验收的会议内容。”

模型大概会完成这样的判断：

因此这里会涉及：

序号	术语
1	LLM Function Calling
2	Tool Calling
3	Schema Constraint
4	Intent Recognition
5	Context Management
6	Agent Planning

如果后续使用 Qwen、DeepSeek、Llama 等模型，也可以进一步结合模型自身的 Tool Calling 能力。

十一、熙瑾会悟的 Tool 不应该直接暴露底层接口

这一点是我们比较看重的。

例如后端存在：

GET /api/meeting/search GET /api/meeting/detail POST /api/meeting/summary POST /api/knowledge/search 不要简单地把这些 API 一一映射成 Tool。

否则最终 Agent 看到的是：

meeting_api_001 meeting_api_002 meeting_api_003 meeting_api_004 工具数量一多，模型反而容易选错。

更合理的做法是：

也就是说：

Plugin Tool 应该是业务语义层，而不是 HTTP API 的简单包装层。

这一点对于后续稳定性影响很大。

十二、第四个问题：Gateway 重启

这是另一个特别容易让人误判的问题。

插件明明已经安装：

openclaw plugins list

也能看到。

但是：

Agent就是调用不到。 这时候不要马上怀疑模型。

OpenClaw 官方文档明确说明，安装、更新或卸载插件涉及运行时代码变化时，需要 Gateway 重启；如果是受管理的 Gateway 且开启配置重载，也可能自动处理。

手动情况下可以：

openclaw gateway restart

然后检查：

openclaw plugins inspect --runtime --json

个命令非常有用。

因为：

plugins list 更偏向“插件是否存在”。

而：

plugins inspect --runtime 更接近：

这个插件到底有没有被当前 Runtime 加载？

十三、第五个问题：插件安装成功 ≠ 插件运行成功

实际排查时，我建议把问题分成四层。

第一层：文件

package.json openclaw.plugin.json dist/ 是否完整。

第二层：Manifest

检查：

plugin id tool declaration config schema entry point 第三层：Runtime

检查：

openclaw plugins inspect --runtime --json

第四层：Agent

最后才看：

模型是否选择了正确 Tool 参数是否正确 业务接口是否正常 这四层不要混在一起排查。

否则非常容易出现：

后端接口正常，但 Agent 不调用。

然后开始疯狂改 Java。

其实可能只是 Plugin Runtime 没加载。

十四、第六个问题：配置 Schema

企业场景里面，插件通常不是写死配置。

比如熙瑾会悟需要：

serverUrl apiKey tenantId timeout knowledgeBase 可以把这些配置统一放到插件配置中。

结构大概是：

这里建议使用严格 Schema。

例如：

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "serverUrl": {
      "type": "string"
    },
    "apiKey": {
      "type": "string"
    },
    "timeout": {
      "type": "number"
    }
  },
  "required": [
    "serverUrl"
  ]
}

为什么要设置：

"additionalProperties": false

因为企业项目最怕配置文件越改越乱。

今天：

apiUrl 明天：

serverUrl 后天：

endpoint 最后三个字段都存在。

严格 Schema 可以早点发现问题。

十五、从熙瑾会悟实际业务看，建议先做三个 Tool

不要第一次开发就把所有能力全部塞进去。

可以先做三个：

1. 会议搜索

huiwu_meeting_search 解决：

“帮我找会议。”

2. 会议摘要

huiwu_meeting_summary 解决：

“帮我总结这次会议。”

3. 知识库搜索

huiwu_knowledge_search 解决：

“根据公司知识库回答这个问题。”

这三个 Tool 已经可以形成一个比较完整的 Agent 场景。

十六、如果加入 RAG，能力会再提升一个层次

熙瑾会悟原本就有知识库能力，因此可以继续往：

例如用户：

“我们上次讨论的数据安全规范里面，关于离线部署有什么要求？”

Agent 不需要自己“记住”。

而是：

这里可以继续使用：

BGE Embedding

BGE Reranker

Qwen

DeepSeek

Milvus

Elasticsearch

OpenSearch

具体选型还是根据部署环境和数据规模来定。

十七、离线部署场景尤其需要注意安全

熙瑾会悟有一个比较明显的应用场景：

政企内网、私有化部署以及对数据安全要求比较高的场景。

所以 OpenClaw 插件接入之后，并不是“能调用就结束”。

至少需要考虑：

尤其不能因为 Agent 是内部系统，就默认：

Agent = 超级管理员 这个思路风险比较大。

例如：

用户A 只能查看销售会议 用户B 可以查看研发会议 管理员 可以查看全部会议 那么 Tool 调用时就应该把用户身份上下文带进去。

十八、不要把 API Key 写死在插件代码里

下面这种写法尽量避免：

const API_KEY = "xxxxxxxx";

尤其是：

Git Docker npm ClawHub 这些环境一旦把密钥提交进去，后面处理起来会非常麻烦。

推荐：

同时日志里面也不要打印：

Authorization: Bearer xxxxx 最好统一脱敏。

十九、插件安装方式也需要区分开发和生产

OpenClaw 目前支持多种来源，例如：

openclaw plugins install clawhub:<package>

也可以使用：

openclaw plugins install npm:<package>

Git：

openclaw plugins install git:github.com/<owner>/<repo>@<ref>

本地开发：

openclaw plugins install ./my-plugin

以及：

openclaw plugins install --link ./my-plugin

官方文档也建议在需要可重复生产安装时考虑固定版本。

这对于企业部署非常重要。

开发环境可以：

--link 方便修改代码。

生产环境则建议：

固定版本 + 制品仓库 + 版本校验 不要生产环境直接跟着 Git main 分支跑。

二十、实际排错可以按照这个顺序来

这是我觉得比较值得留下来的一套排查顺序。

不要一开始就看模型。

很多所谓的“Agent 不会调用工具”，最后发现其实是：

插件根本没加载。

二十一、建议增加自动化测试

插件虽然体量通常没有 Java 后端那么大，但是测试还是不能省。

至少测试：

Tool 参数校验 API 请求 异常处理 超时 鉴权 返回值解析

例如：

正常查询 空关键词 非法日期 API 404 API 500 网络超时 Token失效 返回空数据 尤其是 Agent Tool。

因为 Tool 返回：

{
  "success": false
}

和直接抛：

Exception 对于 Agent 后续处理的影响完全不同。

二十二、一个比较实用的整体架构

如果后面继续把熙瑾会悟和 OpenClaw 做深度融合，我更倾向于下面这种架构：

这套架构有一个比较明显的好处：

OpenClaw 负责 Agent 编排，熙瑾会悟负责专业业务能力。

两边职责比较清楚。

二十三、这里其实还可以继续接入 ASR

如果后续把熙瑾会悟的语音能力也暴露出来，整个 Agent 就不只是文本 Agent 了。

例如：

再通过 OpenClaw Tool 暴露：

huiwu_transcribe huiwu_meeting_summary 那么用户甚至可以：

“把这段会议录音整理一下，输出会议主题、主要讨论内容、存在的问题和待办事项。”

这时候 Agent 才真正开始变成一个“业务助手”。

二十四、模型怎么选？

插件本身其实不绑定具体模型。

这一点非常重要。

插件解决的是：

能力 模型解决的是：

理解 + 推理 + Tool选择 + 文本生成 如果是企业内网环境，可以根据场景考虑：

场景	模型方向
通用 Agent	Qwen / DeepSeek / Llama
中文理解	Qwen 系列
长文本总结	长上下文 LLM
语音转写	Paraformer / Whisper
Embedding	BGE 系列
Rerank	BGE Reranker 等
知识问答	LLM + RAG

不要简单认为：

参数越大越好。

对于 Tool Calling 来说，模型稳定理解工具描述、正确生成参数，有时候比单纯追求参数规模更加重要。

二十五、最后总结一下这次插件开发的几个关键点

如果把整个 OpenClaw + 熙瑾会悟接入过程浓缩一下，我认为最值得注意的是下面几个地方。

1. 先确定插件类型

如果只是让 Agent 调业务能力：

Tool Plugin 通常是最合适的起点。

2. ESM 环境提前统一

不要：

CommonJS + ESM 混着搞。

3. Manifest 要严格

重点检查：

openclaw.plugin.json package.json extensions contracts configSchema 4. Tool 要按照业务语义设计

不要简单把：

REST API 全部暴露给 Agent。

5. Gateway 是运行时关键节点

安装成功不代表 Runtime 已经加载。

必要时：

openclaw gateway restart

再：

openclaw plugins inspect --runtime --json

6. 配置和密钥不能写死

尤其是企业项目。

7. Tool Calling 要和模型能力一起测试

插件没问题，不代表模型一定会正确调用。

8. 企业场景必须考虑权限

尤其是会议记录、知识库、内部文档这类数据。

这次做 OpenClaw 插件接入，最大的感受其实不是“又学了一个插件开发框架”。

真正值得关注的是：

传统业务系统正在逐渐从“被人操作”，变成“可以被 Agent 调用”。

以前我们开发一个会议系统，重点可能是：

页面做得怎么样 接口是否稳定 搜索是否够快 ASR准确率怎么样 现在还要多考虑一个问题：

如果 Agent 来使用这个系统，它知道应该什么时候调用什么能力吗？

这就把传统的软件接口设计，往前推了一步。

对于熙瑾会悟来说，OpenClaw 插件并不是为了单纯增加一个入口，而是可以作为连接：

会议数据 + 语音识别 + 知识库 + RAG + 大模型 + Agent 的一层适配能力。

后面如果继续往下做，我认为比较值得研究的方向还有三个：

第一，Agent + 会议知识库。

让 Agent 能够基于历史会议、企业文档和知识库回答问题。

第二，Agent + 会议自动化。

从录音、转写、摘要一直到待办生成、任务跟踪，尽可能减少人工操作。

第三，Agent + 私有化部署。

对于政企、金融、科研等对数据安全要求较高的场景，让模型、会议数据、知识库和 Agent 能力尽可能留在本地环境中。

这样来看，OpenClaw 插件只是第一步。

真正有价值的部分，是把熙瑾会悟原本已经具备的 AI 能力，进一步变成 Agent 能够理解、能够调用、能够组合的业务工具。