手把手教你开发第一个扣子自定义插件-人工智能-PHP中文网

需开发自定义插件以调用自有接口：先注册开发者并创建插件，配置基础信息（含唯一不可改的插件id）、权限、http请求逻辑（含变量须拖入）、用户输入参数（文本+单选），最后调试通过后提交审核。

手把手教你开发第一个扣子自定义插件

你想让扣子（Coze）机器人调用自己写的接口、读取内部系统数据或执行特定业务逻辑，但官方插件市场里找不到现成方案——这时候必须开发一个自定义插件。本教程从零开始，不依赖任何前端框架，只用浏览器就能完成全部操作。

注册插件开发者身份

打开 Coze 插件控制台 → 点击右上角「创建插件」→ 选择「自定义插件」→ 填写插件名称（如“内部工单查询”）、描述、图标（可上传PNG，尺寸建议128×128）。

勾选「我已阅读并同意《Coze 自定义插件开发者协议》」→ 点击「创建」。这一步必须完成，否则后续所有配置都无法保存。

进入新创建的插件编辑页，在「基本信息」标签页中填写：插件ID（自动生成，不可修改）、调用名称（机器人对话中触发该插件的关键词，如“查工单”）、版本号（初始填 1.0.0）。

【插件ID一旦生成就无法更改，且将作为API路由唯一标识，务必记录下来】

在「权限声明」区域，根据实际需要勾选：读取用户消息、发送消息、访问网络（必须勾选才能调用外部接口）。如果插件不需要发消息给用户，就不要勾选「发送消息」，否则上线后会因权限不匹配被拦截。

切换到「插件逻辑」标签页，点击「添加动作」→ 选择「HTTP 请求」→ 在「请求方法」下拉框中选 POST → 在「URL」栏填写你自己的服务地址，例如 https://api.yourcompany.com/v1/ticket/search。

在「请求头」区域点击「+ 添加请求头」，输入 Key 为 Content-Type，Value 为 application/json；再添加一个 Key 为 Authorization，Value 填写你的服务认证 token（如 Bearer abc123xyz）。

coze智能体系统源码

下载

在「请求体」区域选择「JSON」格式，粘贴如下结构（注意替换 actual_user_id 和 query 字段）：

{ "user_id": "{{user_id}}", "query": "{{input.query}}" }

这一步不能手敲双大括号，必须从右侧「变量面板」里拖入 user_id 和 input.query，否则运行时变量不会被替换。手动输入 {{user_id}} 看似一样，但 Coze 解析器会忽略未通过变量面板声明的占位符。

切换到「用户输入」标签页 → 点击「+ 添加参数」→ 参数名填 query，显示名填“工单编号或关键词”，类型选「文本」，是否必填选「是」。

再添加第二个参数：参数名填 channel，显示名填“所属渠道”，类型选「单选」→ 点击「编辑选项」→ 输入三个选项：客服系统、钉钉群、企业微信（每行一个，不加标点）→ 保存。

这个 channel 参数会在调用时作为 query string 附加到你配置的 URL 后面，例如 ?channel=钉钉群。如果你的服务端没做对应解析，请求会失败。

回到插件编辑页顶部，点击「调试」按钮 → 在弹出窗口中输入测试值：query 填 “TK-2024-789”，channel 选 “客服系统” → 点击「运行」。

观察右侧返回结果：状态码应为 200，响应体是合法 JSON，且包含 ticket_id、status、title 等字段。如果出现 401 错误，检查 Authorization 请求头里的 token 是否过期；如果返回空数组，确认你后端服务是否真能查到 TK-2024-789 这条数据。

调试通过后，点击右上角「提交审核」→ 填写变更说明（如“初版上线，支持按编号查工单”）→ 点击「确定」。