Coze 插件开发：从模板到上架商店全流程

30 秒了解：Coze 插件到底是什么

Coze 插件是给扣子 Bot 加「外部能力」的模块——比如查天气、调 12306、查公司订单库、读 PDF、生成 PPT，每个都是一个插件。 Bot 在对话时能自动判断「这个问题需要某个插件」并调用。

扣子官方插件库有几百个现成插件（必应搜索、图像理解、邮件发送等），你也能自己写一个挂到自家 Bot 上，或者上架插件商店给所有人用。

这篇覆盖两种开发方式：

• 基于现有 API 创建：你已经有一个外部 API（比如公司内部接口），3 分钟封装成扣子插件
• 在 Coze IDE 里写：从零写代码，扣子内置 Python/Node 环境，10 分钟出一个能用的插件

不熟悉扣子基础？先看 扣子 Coze 怎么用。

准备工作

详细操作步骤

方式 A：基于现有 API 创建插件（推荐新手）

如果你已经有一个 HTTP 接口，这是最快的路径。

第 1 步：创建插件

左侧菜单 资源库 → 插件 → 创建插件：

点 确认 进入插件编辑器。

[此处放截图：创建插件对话框，标注创建方式选择]

第 2 步：添加工具（一个 API 端点 = 一个工具）

一个插件可以含多个工具（tool），每个工具对应一个 API 端点。点 创建工具：

💡 工具描述非常关键——Bot 通过这段描述决定「这个用户问题该不该调这个工具」。写得越具体（含输入、输出、典型场景），命中率越高。

第 3 步：配置输入参数

点 输入参数 标签，按你 API 的接口规范填：

每个参数的描述要写人话——Bot 会根据描述自动从用户对话提取值填进去。

第 4 步：配置输出参数

点 输出参数 → 自动解析：

1. 在「调试 → 测试运行」里跑一次真实请求
2. 拿到返回 JSON 后点 自动解析，扣子会把字段都生成出来
3. 给每个字段加一句中文描述（让大模型理解字段含义）

第 5 步：调试

点 测试运行，填几组真实输入跑：

• 北京 / 7 / celsius
• 上海 / 3 / celsius
• 不存在的城市 / 7 / celsius（看错误处理）

每次跑完看返回是不是符合预期。调到 100% 成功率才能发布。

第 6 步：发布

右上角 发布 → 选发布范围：

• 仅自己使用：只挂到自家 Bot 上
• 发布到商店：所有扣子用户都能用

发布到商店需要：

1. 完善插件介绍（封面图 + 详细描述 + 使用示例）
2. 选合适分类（资讯阅读 / 效率办公 / 旅游出行 / 图像理解 等）
3. 等扣子官方审核（通常 1-3 个工作日）

方式 B：在 Coze IDE 里从零写

适合需要复杂逻辑、没有现成 API 的场景。

第 1 步：创建插件（IDE 模式）

创建插件时选「云侧插件」→「在 Coze IDE 中创建」。

进入后 IDE 界面分三块：

• 左侧：文件树（main.py / requirements.txt）
• 中间：代码编辑器
• 右侧：调试 + 输出面板

第 2 步：创建工具（IDE 内）

IDE 里点 + 创建工具，跟方式 A 一样填工具名、描述、输入参数、输出参数。区别是这次不指定 API URL，而是自己写函数。

第 3 步：写代码

IDE 会自动生成函数骨架：

async def handler(args: Args[Input]) -> Output:
    """
    工具描述
    """
    # 取输入参数
    city = args.input.city

    # 你的业务逻辑
    result = your_logic_here(city)

    # 返回结构化结果
    return Output(
        temperature=result["temp"],
        humidity=result["humidity"]
    )

填进真实逻辑，比如调外部 API、解析数据、查数据库等。

💡 IDE 内置常用 Python 库（requests / pandas / numpy / pillow 等）。需要别的库在 requirements.txt 里加。

第 4 步：本地调试

右侧 调试 面板填测试输入 → 点 运行，能看到：

• 输入参数值
• 函数执行日志
• 返回结果
• 报错堆栈（如有）

调到符合预期再发布。

第 5 步：发布（同方式 A 第 6 步）

让插件被 Bot 自动调用的 5 个套路

常见坑 + 解决办法

一个完整实战案例：写一个「公司订单查询」插件

下面这套是给一个 SaaS 公司客服 Bot 写的真实插件，让客服 Bot 能根据订单号查物流。

工具描述（贴在工具描述框）

查公司订单状态：

适用场景：用户提供订单号询问物流 / 发货时间 / 收货状态
输入：订单号（11-15 位字母数字混合）
输出：当前状态、最近物流节点、预计送达时间、运单号
注意：仅支持本公司订单系统，不查第三方平台订单
调用示例：用户问「我的订单 ORD20260518001 到哪了」立即调用

输入参数

代码

import os
import requests

def handler(args):
    order_id = args.input.order_id.strip().upper()

    # 输入校验
    if not order_id or len(order_id) < 8 or len(order_id) > 20:
        return {
            "success": False,
            "error_msg": "订单号格式不正确，应为 8-20 位字母数字"
        }

    # 调内部 API（Token 用环境变量存）
    api_token = os.environ.get("ORDER_API_TOKEN")
    if not api_token:
        return {
            "success": False,
            "error_msg": "服务暂不可用，请联系管理员"
        }

    try:
        resp = requests.get(
            f"https://order-api.your-company.com/v1/orders/{order_id}",
            headers={"Authorization": f"Bearer {api_token}"},
            timeout=8
        )
        if resp.status_code == 404:
            return {
                "success": False,
                "error_msg": f"订单 {order_id} 不存在，请核对订单号"
            }
        resp.raise_for_status()
        data = resp.json()

        return {
            "success": True,
            "order_id": data["id"],
            "status_chinese": data["status_label"],
            "latest_node": data["tracking"][0]["description"],
            "eta": data["estimated_arrival"],
            "tracking_number": data.get("courier_tracking_no", "暂无")
        }
    except requests.Timeout:
        return {"success": False, "error_msg": "查询超时，请稍后重试"}
    except Exception as e:
        return {"success": False, "error_msg": f"查询失败：{str(e)[:80]}"}

把这段贴进 Coze IDE、配好 ORDER_API_TOKEN 环境变量、跑通调试、发布后挂到客服 Bot 上，客户问「我的订单到哪了」就能秒查。

进阶 / 下一步

• 扣子 Coze 怎么用？1 小时搭一个 AI 客服
• Coze 工作流实战：1 个流程自动出周报
• Dify 怎么用？开源 LLMOps 平台 0 基础上手
• Function Calling 是什么？AI 调外部工具的原理
• 国内 AI Agent 平台盘点

常见问题

Q：写 Coze 插件需要会代码吗？ A：方式 A（API 封装）不用写代码——填几个表单就行；方式 B（IDE 开发）需要会 Python 或 Node。完全不会代码的话先用方式 A 起步。

Q：插件上架商店能赚钱吗？ A：目前扣子插件商店还没开放对开发者的收入分成，主要价值在打造个人技术品牌 + 让自家 Bot 调用更顺。商业付费插件路径未来可能开放。

Q：自己写的插件能给别人用吗？ A：能。两种方式：1）发布到商店所有人都能搜到用；2）通过 私享链接 给指定团队用（不上架商店）。

Q：插件调用别人 API 的鉴权 Token 怎么处理？ A：绝对不要写死在代码里。用扣子的 环境变量 或 OAuth 鉴权流程。代码里用 os.environ.get() 读，上架时不会暴露 Token。

Q：插件返回的数据 Bot 怎么用？ A：Bot 拿到插件返回的 JSON 后会自动用大模型把它转成自然语言回答用户。所以返回字段要结构化 + 字段名易懂 + 加单位。

Q：插件能调用其他插件吗？ A：不能直接调。需要在工作流里串起来——工作流节点 A 调插件 1，节点 B 调插件 2，节点 C 整合两者输出。详见 Coze 工作流实战。

Q：插件性能不好怎么优化？ A：3 招：1）加缓存（同样输入 10 分钟内复用结果）；2）异步化（IDE 用 async/await）；3）外部 API 太慢的换更快的提供商。单次调用超过 5 秒 Bot 体验就差，超过 10 秒会超时。

Q：插件出 bug 影响 Bot 怎么办？ A：扣子有 版本回滚 功能，新版本上线后旧版本保留 3 个版本，1 秒回退到上一个稳定版。所以发版前先发到「仅自己使用」测一周再推广。