扣子自定义插件开发教程：手把手零基础入门

2026-06-11阅读 0热度 0

机器人

假设你希望扣子（Coze）机器人能调用自己写的接口，读取内部系统数据，或者执行特定的业务逻辑——但翻遍官方插件市场，找不到现成的方案。这时候，唯一的出路就是自己动手开发一个自定义插件。别担心，整个过程不依赖任何前端框架，只用浏览器就能完成。下面直接进入正题。

注册插件开发者身份

打开 Coze 插件控制台，点击右上角「创建插件」，选择「自定义插件」。然后填写插件名称（比如“内部工单查询”）、描述和图标（建议上传128×128的PNG）。最后勾选「我已阅读并同意《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）。

在「请求体」区域选择「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 这条数据。

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