目录
本指南介绍如何在 WOZTELL 中将现有的 AI 聊天机器人从 GPT Assistant v1.2.0（基于 OpenAI 的 Assistants API）迁移到 GPT Assistant v1.3.0（基于 OpenAI 的 Responses API）。
这次迁移是什么，不是什么
| 迁移不是自动的 | 没有可以把 v1.2.0 升级到 v1.3.0 的按钮。你需要创建一个新的 v1.3.0 扩展并重新进行配置。 |
| 会创建一个新的扩展 | 你的 v1.2.0 扩展保持不变。你会在它旁边单独安装一个 v1.3.0 扩展。 |
| 你的 v1.2.0 聊天机器人继续运行 | 在新机器人完全验证通过之前，保持旧机器人在线，这样你的客户始终不会收不到回复。 |
| 终端用户不受影响 | 客户仍然通过同一个 WhatsApp、Instagram、Facebook Messenger 或 Webchat 渠道发消息。改变的只是与 OpenAI 的内部连接。 |
推荐做法：先测试再迁移。: 先创建新的 v1.3.0 聊天机器人，在测试环境中用一小组测试人员进行验证，等到你完全有把握后再切换到生产环境。这样在整个过程中，你的客户始终在与已经验证过的 v1.2.0 聊天机器人对话，不会中断。
开始之前
请确保你具备：
- 访问 v1.2.0 扩展配置的权限（你需要从中复制设置）。
- 你的 OpenAI API Key（可以复用同一个密钥）。
- 在 WOZTELL 中已连接至少一个渠道（WhatsApp Business Platform / Cloud API、Instagram、Facebook Messenger 或 Webchat）。
- 几位测试人员，你可以用他们的账号或电话号码安全地测试新的聊天机器人。
最快的迁移方式是：在一个标签页打开 v1.2.0 的配置，在另一个标签页打开新的 v1.3.0 扩展，然后逐项把设置复制过去。
步骤 1: 保持 v1.2.0 聊天机器人在线
暂时不要断开或删除当前的聊天机器人。在你搭建和测试新机器人的整个过程中，它都保持在线并继续回复客户。你只会在最后切换到生产环境时（步骤 6）才将其停用。
步骤 2: 创建新的 v1.3.0 扩展
你将作为一个独立的扩展，从头创建新的聊天机器人。
- 前往 Marketplace → + New Extension。
- 找到 ChatGPT 扩展卡片（Artificial Intelligence · OpenAI | WOZTELL），点击 Learn More。
- 在 Extension Version 中，选择 v1.3.0。
- 输入一个唯一的 Alias（小写、无空格），例如 my-gpt-assistant-v13。
- 点击 Install，然后在 Installed Extensions 中打开新的扩展。
- 在 API Key Setup 区域，粘贴你的 OpenAI API Key 并点击 Save。出现绿色对勾即表示密钥有效，并会解锁 Configuration 和 Connect to Channel 区域。
步骤 3: 复制你的配置
在 v1.2.0 中，聊天机器人的所有行为都写在 prompt（Instructions）里。迁移它，主要就是把这个 prompt 复制过来并选择合适的模型。
在新的 v1.3.0 扩展中，打开 Configuration → AI Chatbot，设置 Instructions（prompt）、Model、Transcription model 以及高级设置。
了解渠道与环境
这是让安全迁移成为可能的关键概念，因此在连接任何东西之前值得先了解清楚。
- 渠道是连接到 WOZTELL 的沟通渠道，例如 WhatsApp、Instagram、Facebook Messenger 或 Webchat。
- 环境是渠道内部的一个工作空间，用于将测试与生产分开。如果你没有创建额外的环境，渠道会使用 Default 环境。
在迁移期间，环境让你可以在测试环境中运行新的 v1.3.0 聊天机器人，同时让你的 v1.2.0 聊天机器人继续留在线上（Default/生产）环境。在你决定切换之前，客户始终在与经过验证的旧聊天机器人对话。
步骤 4: 将新聊天机器人连接到测试环境
现在连接新的聊天机器人——但要连接到测试环境，而不是生产环境。
- 如果还没有测试环境，请为你的渠道创建一个测试环境并指定测试人员。参阅：如何创建测试环境。
- 在 v1.3.0 扩展中，打开 Connect to Channel 区域。
- 找到你的渠道，选择你创建的测试环境——不要选择 v1.2.0 正在运行的 Default/生产环境。
- 点击 Connect。
- 如有要求，输入一个 Prefix Name；使用清晰的标签，例如 AI-CHATBOT-WHATSAPP-TEST。
- 点击 Confirm，然后再次点击 Connect。
当按钮变为 Disconnect 时，说明新的聊天机器人已仅在测试环境中上线。
步骤 5: 测试与验证
现在，只有你白名单中的测试人员才会被引导到测试环境和新的 v1.3.0 聊天机器人。生产环境——以及你真正的客户——仍然停留在 v1.2.0，不受影响。
让你的测试人员对新聊天机器人进行充分测试：
- 用白名单中的设备或号码，向该渠道发送消息。
- 确认聊天机器人会回复，并且回复内容与你的 Instructions 一致。
- 测试不同类型的问题和边界情况（包括超出聊天机器人范围的问题）。
- 如果你添加了 Knowledge Base / File Search，提出一些应当依据你的文档来回答的问题，确认其正常工作。
- 查看 logs，检查是否有错误（API Key、模型、tools、File Search 或渠道连接问题）。
步骤 6: 切换到生产环境
当你对新聊天机器人有把握后，把线上渠道从 v1.2.0 切换到 v1.3.0。
- 将 v1.2.0 聊天机器人从生产（Default）渠道/环境断开。
- 将 v1.3.0 聊天机器人连接到该生产环境（步骤与步骤 4 相同，但这一次选择生产环境）。
- 发送最后一次实时测试，确认新聊天机器人在生产环境中正常回复。
确认 v1.3.0 在生产环境中正常运行后，你就可以安全地删除旧的 v1.2.0 扩展了。
迁移期间的常见问题
| 问题 | 原因 | 解决方法 |
|---|---|---|
| 回复不可预测／用户被引导到错误的机器人 | 两个聊天机器人在同一个环境中同时处于激活状态。 | 让 v1.2.0 和 v1.3.0 处于不同的环境。切换时，先断开一个，再在同一环境中连接另一个。 |
| 测试人员无法访问新的聊天机器人 | 没有分配 Priority Group，或测试人员未被加入其中。 | 确认 Priority Group 已分配给测试环境，并且每位测试人员都在白名单中（WhatsApp 测试人员必须先向 WABA 发送消息）。 |
| 某些基于 prompt 的逻辑表现不同 | Responses API 处理上下文的方式与 Assistants API 不同。 | 在验证期间检查并调整 prompt；可考虑将参考内容移到 File Search。 |
| 助手在测试环境中没有回复 | 未保存 API Key、未连接聊天机器人，或选择了错误的环境。 | 确认 API Key 已保存、聊天机器人已连接，并且你是在向正确的环境发送消息。 |
常见问题
为什么需要从 GPT Assistant v1.2.0 迁移到 v1.3.0？
OpenAI 将于 2026 年 8 月 26 日停用 Assistants API，而 v1.2.0 正是基于它构建的。在该日期之后，仍在 v1.2.0 上的聊天机器人可能停止工作。v1.3.0 基于 OpenAI 较新的 Responses API，因此迁移可以让你的聊天机器人继续运行。
迁移是自动的吗？
不是。没有可以把 v1.2.0 升级到 v1.3.0 的按钮。你需要创建一个新的 v1.3.0 扩展并重新配置，同时你的 v1.2.0 聊天机器人会继续运行，直到新机器人准备就绪。
迁移期间会影响我的客户吗？
如果你先测试再迁移，就不会。你保持 v1.2.0 在线，在独立的测试环境中创建并验证 v1.3.0，等到你有把握后再切换到生产环境，这样客户始终不会中断服务。
什么是测试环境，为什么要使用它？
环境是渠道内部的一个工作空间，用于将测试与生产分开。在测试环境中运行 v1.3.0，可以让一小组测试人员先行体验，而真实客户仍停留在 v1.2.0，从而避免两个聊天机器人在同一环境中发生冲突。
我需要重建 prompt 和设置吗？
需要。在 v1.2.0 中，聊天机器人的行为都写在 prompt 里。把该 prompt 复制到新的 v1.3.0 扩展，选择 model 和 transcription model，并匹配你的高级设置。你也可以选择把大量参考内容移到 File Search。
迁移的截止日期是什么时候？
2026 年 8 月 26 日，OpenAI 停用 Assistants API 的日子。请在此之前完成迁移，以避免任何中断。
