一、插件功能介绍
插件是企业微信智能机器人的能力拓展工具集，单个插件可包含一个或多个工具，支持API、MCP两种类型，核心作用是帮助企业打通自有系统，实现内部数据调取、系统请求发送，进一步拓展智能机器人的业务处理边界。
成员可在「工作台-智能机器人」使用插件功能，管理员还可在「管理后台-安全与管理-管理工具-智能机器人」中操作。
二、插件功能操作入口
可在「智能机器人应用-插件tab」完成所有插件相关操作，包括查看已添加的插件列表、新增API/MCP类型插件，是插件配置、管理、使用的核心入口。
三、插件的添加与编辑流程
插件的添加与编辑分为配置插件基础信息和添加/编辑工具两个核心步骤，其中MCP插件可自行拉取tool list，API插件需开发者手动添加下属工具（API），以下为详细配置规则。
1、配置插件基础信息
需按要求填写插件通用信息，配置鉴权与访问规则，所有带*项为必填项，具体配置项说明如下：
- 插件名称：自定义插件标识名称，便于识别用途。
- 插件描述：记录插件的核心用途、适用场景，便于后续管理与模型理解。
插件URL：
● 为API/MCP服务部署的基础地址，需输入包含协议、域名/IP、端口号的完整访问前缀，且确保公网可访问。
● 格式要求：必须以http://或https://开头；建议末尾不带/，配合工具路径开头的/保证拼接逻辑清晰。
● 安全建议：服务支持SSL时优先使用https，保障数据传输安全。请求头：配置HTTP请求头的参数列表（Key-Value形式）。
授权方式：支持API key/Service token鉴权、无需授权两种，若选择鉴权需配置以下三要素：
● 位置：鉴权信息存放位置，可选Header（请求头中，如Authorization）、Query（URL参数拼接，如?api_key=xxx）。
● 参数名（Parameter name）：接口约定的鉴权字段名称。
● 参数值（Service token/API key）：企业的私钥、Token或API Key内容。
传输协议：仅MCP插件需配置，支持SSE/Streamable HTTP。
可使用的成员：配置可在智能机器人中添加该插件的成员范围，仅插件创建者拥有插件编辑权限。
2、添加/编辑插件下属工具
该步骤为API插件核心配置项，MCP插件可自动拉取工具列表，无需手动配置，工具配置分为基础信息、输入参数、输出参数、调试验证四部分。
（1）工具基础信息配置
- 工具名称：自定义工具标识，明确工具功能（如「查询员工订单」「获取打卡数据」）。
- 工具描述：详细说明工具的功能、使用场景，帮助大模型理解并按需自动调用。
工具路径：
● 为API接口的具体资源路由，插件会自动将「插件URL」与「工具路径」拼接为完整接口地址。
● 格式要求：通常以/开头；含动态变量（如ID、订单号）时，用{variable}作为占位符（示例：/api/orders/{order_id}、/v1/users/{user_id}）。请求方法：支持Get、Post、Put、Delete、Patch五种HTTP请求方法。
（2）工具输入参数配置
通过结构化表单定义API请求所需参数，为大模型调用提供清晰规则，每一项参数需填写名称、描述、类型等核心信息，具体要求如下：
a. 核心配置项
- 参数名称：接口接收的变量键名（如user_id、order_id）。
- 参数描述：说明参数用途，便于大模型识别并自动传参。
- 传入方法：参数在HTTP请求中的存放位置，可选Path、Query、Header、Body。
- 参数类型：参数的数据格式，受传入方法约束（详见下表）。
- 是否必填：标注参数是否为接口必传项，该信息会暴露给大模型。
- 默认值：参数的固定默认值，可选配置。
- 模型是否可见：若配置默认值且关闭该开关，大模型不会推理该参数，直接使用默认值。
b. 传入方法与参数类型的约束关系
| 传入方法 | 可选类型 | 关键约束、说明 |
|---|---|---|
| Path | String |
参数名称必须与“工具路径”中的 {占位符}名称完全一致。（区分大小写） |
| Header | String |
请求头名称中不能包含:，请求头 value中不能包含换行符，部分系统请求头将被忽略 如Content-Type、Host 等 |
| Query | String |
拼接在 URL 问号后的参数（如 ?key=value）。 |
| Body | String, Number, Boolean, Object, Array, Int |
Body 根节点默认为 Object，您在此处定义其内部字段。 |
c. 路径动态参数绑定配置
若工具路径含{占位符}动态变量，需按以下步骤完成绑定，确保参数正常传递：
步骤1：在工具路径中用{变量名}定义动态部分（如/employees/{emp_id}）。
步骤2：在输入参数列表中添加同名参数。
步骤3：将该参数的「传入方法」设置为Path，参数类型为String。配置示例：假设您需要调用一个查询员工详情的接口，其完整路径为
https://api.corp.com/employees/123：
○ 接口地址 (URL)：https://api.corp.com
○ 工具路径 (Tool Path)：/employees/{emp_id}
○ 输入参数：
| 参数名称 | 参数类型 | 传入方法 | 说明 |
|---|---|---|---|
emp_id |
String | Path | 必须与路径中的占位符名称完全一致 |
（3）工具输出参数配置
配置API接口返回的JSON数据字段规则，帮助大模型识别、提取有效返回信息，核心要求与配置项如下：
a. 核心配置项
● 参数名称：与接口返回JSON体中的Key完全一致。
● 参数类型：支持String、Number、Boolean、Object、Array、Int，需与接口返回数据类型匹配。
● 参数描述：说明字段含义，为大模型解读返回结果提供上下文。
b. 硬性配置规则
● 仅支持JSON输出：接口HTTP响应内容必须为JSON格式（Content-Type为json），否则API工具调用失败。
● 参数严格匹配：只有在“输出参数”中明确配置的字段才会被提取。如果实际 API 返回的字段比配置的多，未配置的返回字段将被自动忽略。
● 类型严格匹配：系统会校验返回数据类型，与配置不一致的字段（例如配置为Number但返回了String）将被视为无效并忽略。
（4）工具调试验证
API插件下的所有工具必须调试通过后，才能完成插件保存，调试的核心目的是验证接口地址、参数配置、鉴权规则是否正确，确保工具可正常调用。
3、插件配置注意事项
● 动态参数的{占位符}名称与输入参数名称需严格一致，区分大小写。
● 路径中的动态变量，其输入参数的「传入方法」必须设为Path，不可选Query/Body，否则系统无法正确替换占位符。
● 插件URL与工具路径的拼接需遵循「插件URL末尾无/，工具路径开头有/」的原则，避免拼接错误。
● MCP插件无需手动配置工具列表，系统将自动拉取，仅需完成基础信息配置。
四、插件的使用场景与操作方法
配置完成的插件可在智能机器人编辑和工作流节点配置两个场景中使用，实现简单/复杂业务场景的系统对接，具体操作方法如下：
1、智能机器人直接添加使用
在智能机器人创建/编辑页面，找到「API/MCP插件」模块，点击「添加插件」，选择已配置完成的插件及下属工具，保存后机器人即可根据任务意图，自动判断是否调用插件工具完成业务处理（如调取自有系统数据回答用户问题）。
2、工作流节点中添加使用
在工作流创建/编辑页面，在「添加指定操作」模块中选择「插件」，添加已配置的API/MCP插件，将插件工具与条件分支、循环、Python等节点串联，实现复杂业务流程的自动化处理（如权限校验→调用插件调取数据→规则判断→结果推送）。
五、提问者身份信息传递规则
若插件URL配置为企业域名，系统会自动向API服务传递发起请求的企业微信用户身份信息，企业后端服务可通过解析HTTP请求头获取该信息，具体规则如下：
| 请求头名称 | 说明 | 示例值 |
|---|---|---|
X-WeCom-User-Id |
与企业微信管理后台-通讯录-组织架构中，成员的账号一致 |
E001827 |
通过该规则，企业可在自有系统中实现用户身份校验，确保数据调取的安全性与针对性。
六、常见问题
1、添加插件提示“插件工具获取失败，请检查插件配置”
需确认填写的插件url在公网能否正常访问，需确保能在公网访问后再添加。
2、创建智能机器人插件提示“创建失败”
请检查插件url配置中是否含有问号等特殊字符，目前不建议在插件url中添加带有特殊字符的参数，若有需要可将url的参数放到工具路径中。