Typebot插件开发指南：5步扩展聊天机器人功能

2026-02-05 04:36:03作者：胡易黎Nicole

你是否曾因Typebot内置功能无法满足特定业务需求而苦恼？客户需要与私有CRM系统对接？想实现自定义数据分析追踪？本文将通过5个清晰步骤，带你掌握Typebot插件开发全流程，从环境搭建到功能部署，让你的聊天机器人轻松扩展无限可能。

插件开发准备工作

在开始编写插件前，需要准备基础开发环境。首先克隆官方仓库并安装依赖：

git clone https://gitcode.com/GitHub_Trending/ty/typebot.io
cd typebot.io
bun install

Typebot插件开发基于Forge SDK，核心代码位于packages/forge/目录。该SDK提供了完整的插件开发框架，包括认证管理、动作定义和数据流处理等模块。开发工具链已内置插件脚手架，可通过CLI快速生成项目结构。

第1步：创建插件项目

使用Forge CLI创建新插件项目，支持交互式配置或命令行参数直接生成：

cd packages/forge/cli
bun create-new-block --name "客户管理" --id "customer-management" --auth "apiKey"

命令执行后将自动生成标准插件目录结构：

customer-management/
├── src/
│   ├── index.ts        # 插件入口
│   ├── auth.ts         # 认证配置
│   ├── logo.tsx        # 图标组件
│   └── schemas.ts      # 类型定义
├── package.json
└── tsconfig.json

脚手架已预置基础代码框架，例如src/index.ts中自动生成的插件注册代码：

export const customerManagementBlock = createBlock({
  id: 'customer-management',
  name: '客户管理',
  tags: ['crm', 'database'],
  LightLogo: CustomerManagementLogo,
  auth,
  actions: [],
})

第2步：定义认证机制

根据插件需求选择合适的认证方式，Typebot支持API Key、OAuth和自定义加密数据三种认证模式。以API Key认证为例，编辑src/auth.ts文件：

export const auth = {
  type: 'encryptedCredentials',
  name: '客户管理系统账号',
  schema: option.object({
    apiKey: option.string.layout({
      label: 'API密钥',
      isRequired: true,
      inputType: 'password',
      helperText: '从客户管理系统控制台获取API密钥',
      withVariableButton: false
    })
  })
}

认证配置将在Typebot编辑器中生成可视化配置界面，用户可安全存储敏感信息。

第3步：实现核心功能

插件功能通过Action定义实现，每个Action对应一个具体业务操作。例如创建"添加客户"功能：

actions: [
  {
    name: '添加客户',
    options: option.object({
      name: option.string.layout({ label: '客户姓名' }),
      email: option.string.layout({ label: '电子邮箱' })
    }),
    run: {
      server: async ({ credentials, options, variables, logs }) => {
        const response = await fetch('https://api.example.com/customers', {
          method: 'POST',
          headers: { 'Authorization': `Bearer ${credentials.apiKey}` },
          body: JSON.stringify({
            name: options.name,
            email: options.email
          })
        })
        if (!response.ok) throw new Error('添加客户失败')
        logs.add('客户添加成功')
      }
    }
  }
]