DeBox 机器人开发总览

本文是 DeBox Bot 的总览文档，覆盖从 BotMother 找到入口、创建机器人、管理配置，到基于 SDK 二次开发的完整路径。

1. 找到并打开 BotMother

在 DeBox App 中，推荐按下面的路径进入：

朋友 → AI 助手 → BotMother → 聊天 → 指令菜单

第一步：进入朋友页面，点击 AI 助手。

第二步：在 AI 助手列表找到并打开 BotMother。

第三步：在 BotMother 主页点击聊天按钮。

第四步：进入聊天后，点击左下角的指令按钮。

第五步：打开指令列表。图中箭头标出的是 /start；创建 Bot 时请选择 /newbot。

还可以通过以下两种方式找到 BotMother：

1. 在 DeBox App 内打开深链接 https://m.debox.pro/user/chat?id=u7ooqdjt&start=。
2. 在 DeBox 中搜索地址 0xda521900ac9dfeff8a8e692bb627ff8cd80a7b28。

1.1 BotMother 指令

指令	用途
/start	查看 BotMother 说明和管理入口。
/newbot	开始创建 Bot。
/mybots	查看当前账号已经创建的 Bot。
/cancel	取消 BotMother 中正在进行的操作。

这些指令用于通过 BotMother 创建和管理 Bot，与创建完成后为 Bot 配置的业务指令不是一回事。添加或修改 Bot 指令菜单里的内容，只会改变菜单中显示的文字，不会自动实现或改变 Bot 功能。如果修改了指令关键词，还必须同步修改 Bot 服务中处理该指令的消息逻辑。

2. 通过 BotMother 创建 Bot

输入 /newbot，然后按照 BotMother 当前提示完成创建：

1. 设置 Bot 的名称、头像和简介等基础信息。
2. 确认信息并完成创建。
3. 输入 /mybots 打开 Bot 管理列表。

每个账号最多可以创建 5 个 Bot。

3. Bot 管理与配置修改

输入 /mybots 可以查看已经创建的 Bot，并进入单个 Bot 的管理页面。已经创建的 Bot 目前不能删除， 因此完成创建前应先检查基础信息。

3.1 Bot 管理首页

你可以在这里：

• 查看已有 Bot 列表
• 进入单个 Bot 管理页
• 在未达到 5 个 Bot 的上限时继续创建 Bot

3.2 单个 Bot 管理页

该页面会显示 Bot 凭证，并提供编辑信息、指令设置、隐私设置、Webhook 设置和权限申请入口。

3.2.1 凭证

• App Key 就是 SDK 和 OpenAPI 文档中的 API Key。Bot 服务调用 DeBox OpenAPI 时，使用它 作为 X-API-KEY。
• App Secret 就是 SDK 文档中的 API Secret。初始化官方 SDK 时需要一并配置；调用需要签名的 API 时，也会使用该凭证。

凭证只能保存在服务端

App Key 和 App Secret 只能保存在可信的后端服务或环境变量中。不要把它们写入 H5、浏览器端代码、 公开仓库、日志或截图。如果凭证泄露，请立即在 Bot 管理页面重置，并同步更新 Bot 服务配置。

3.2.2 指令与隐私设置

指令设置用于管理 Bot 指令菜单中显示的指令和描述。添加或修改菜单内容不会自动实现 Bot 功能；如果修改 了指令关键词，还需要同步修改 Bot 服务中处理该指令的消息逻辑。

在聊天中使用 Bot 指令

聊天场景	唤出指令列表的方法
与 Bot 私聊	点击输入框左侧的指令按钮，或者在输入框输入 /。
群聊	在输入框输入 /；群聊没有私聊中的指令按钮入口。

唤出指令列表后，选择需要执行的指令即可。

私聊第一步：点击指令按钮，或者在输入框输入 /。

私聊第二步：选择需要执行的指令；图中以 /start 为例。

群聊：在输入框输入 /，然后从列表中选择指令。

填写指令关键词和菜单中显示的描述。

设置哪些人可以私信 Bot 或邀请 Bot 加入群聊。

隐私设置目前包含以下范围：

• 私信：我关注的人、所有人或朋友。
• 群邀请：所有人或我关注的人。

选择需要的范围后保存即可。

让用户从 AI 助手私聊 Bot

如果希望用户在 AI 助手板块找到 Bot 后，可以直接与 Bot 私聊，请在 Bot 的“隐私设置”中将“私信”设为 “所有人”。“发布机器人”审核只负责让 Bot 显示在 AI 助手板块，不会自动放宽私信权限；如果私信范围 不是“所有人”，不在允许范围内的用户仍然无法私聊该 Bot。

3.2.3 权限申请

目前可以申请以下三项权限，三项都需要平台审核：

权限	审核通过后的能力
监听群消息	接收普通群聊消息。
订阅号	使 Bot 具备订阅号身份，并可通过 POST /openapi/bot/sendMessageToFans 向粉丝群发消息。
发布机器人	让 Bot 显示在 AI 助手板块，方便用户查找并添加到群聊，或与 Bot 私聊使用。

发布机器人申请顺序

提交“发布机器人”权限申请前，请按以下顺序准备：

1. 完成 Bot 开发和测试。
2. 准备一份说明 Bot 使用方法的介绍文件。
3. 在 DeBox App 内加入 OpenBOX Bot Release Review 群， 并将使用说明文件发送到群内。
4. 文件发送完成后，再回到 Bot 管理页面提交“发布机器人”权限申请。

为了方便审核和后续使用，介绍文件建议包括 Bot 名称与用途、开始使用的方法、主要指令与功能、私聊或 群聊中的操作步骤、必要的权限或使用条件，以及相关功能截图或演示结果。

开发群消息功能时，建议按以下顺序测试：

1. 先通过私聊完成基础消息流程测试。
2. 权限审核通过前，可以在群内明确 @Bot 进行测试；这类提及 Bot 的消息也会投递。
3. Bot 开发完成并且确实需要接收不带 @ 的普通群消息时，再提交“监听群消息”权限申请并等待审核。
4. 如果申请未通过，可以在 DeBox App 内进入 OpenBOX Bot Release Review 群中反馈。

3.2.4 发布后在群聊中添加 Bot

“发布机器人”申请审核通过后，Bot 会显示在 AI 助手板块。除了前文介绍的“朋友 → AI 助手”入口， 也可以从目标群聊的聊天设置进入 AI 助手。

从群聊添加已发布的 Bot：

1. 打开目标群聊，进入“聊天设置”，点击“AI 助手”。
2. 在 AI 助手列表中找到 Bot，点击“添加”。已经在群内的 Bot 会显示“移除”。

第 1 步：在群聊的“聊天设置”中点击“AI 助手”。

第 2 步：找到 Bot 后点击“添加”；已经在群内的 Bot 会显示“移除”。

发布审核不会绕过群邀请隐私设置

“发布机器人”审核决定 Bot 是否显示在 AI 助手板块，不会绕过 Bot 的隐私设置。如果希望任何用户都能 通过群聊的 AI 助手添加该 Bot，需要先在 Bot 隐私设置中将“群邀请”设为“所有人”。如果选择了限制 更严格的范围，仍会按照普通邀请 Bot 加群的规则检查隐私权限，Bot 可能无法添加进群。

3.3 Bot 等级与图片发送

DeBox 普通账号和 Bot 发送图片时，发送方原则上需要达到 Lv.2，私聊与群聊都适用。Bot 在群聊中有一项管理员例外：

发送场景	图片发送要求
私聊	Bot 必须达到 Lv.2。
Bot 不是管理员的群聊	Bot 必须达到 Lv.2。
Bot 已被设为管理员的目标群	Bot 在该群内不受图片发送等级限制。

管理员例外只免除 Bot 在该群内发送图片的等级要求，不会免除其他接口、权限、隐私或平台限制。 Bot 在私聊中以及在其他未被设为管理员的群内发送图片时，仍然需要达到 Lv.2。

普通账号可以在“等级能量”页面通过当前提供的方式获得能量并升级。具体任务和能量数值可能调整， 请以 DeBox App 实时显示为准。

需要为 Bot 升级时，先在 BotMother 中运行 /mybots，打开该 Bot 的管理页，复制 Bot 名称下方显示的 EVM 地址。然后使用一个 Lv.5 及以上的 DeBox 账号完成以下操作：

1. 进入“我的”→“等级能量”。
2. 在能量中心选择“等级直升”。
3. 选择“为他人升级”，填写 Bot 的 EVM 地址，选择当前可用的支付方式，并按 App 显示的当前价格确认。

以下截图使用中文界面。升级价格和支付方式可能调整，不应把截图中的数值视为固定价格。

第 1 步：在“我的”页面打开“等级能量”。

第 2 步：选择“等级直升”。

第 3 步：选择“为他人升级”并填写 Bot 的 EVM 地址。

getMe 接口会返回 Bot 当前的 level，可以用来确认 Bot 是否满足图片发送要求。

4. 两种开发模式（必须先选）

DeBox Bot 提供两种收消息模式：

• Webhook 模式（DeBox 主动推送到你的服务）
• Long Polling 模式（你的程序主动轮询 getUpdates）

两者严格互斥：

• 在 BotMother 配置 Webhook URL 后，Webhook 是唯一有效的收消息链路。
• 只要该 Webhook URL 仍然存在，getUpdates、GetUpdates 和 GetUpdatesChan 就不能用于收消息。
• 若要改回 Long Polling，先清空 BotMother 中的 Webhook 配置。

5. Webhook 模式怎么用

BotMother 的 Webhook 设置页面目前只有 Webhook URL 和 Webhook Key 两项。

最小接入步骤：

1. 准备一个稳定、可以从公网访问的 HTTPS 回调地址。
2. 在 BotMother 中将回调地址填写为 Webhook URL，配置 Webhook Key，然后保存。
3. 服务端实现回调接口，并严格校验收到的 X-API-KEY 是否等于配置的 Webhook Key。
4. 处理回调消息，并按业务逻辑调用 OpenAPI 回复消息。

同一个请求头在两个方向中代表不同的值：DeBox 发给 Bot 服务的 Webhook 回调中，X-API-KEY 携带的是 Webhook Key；Bot 服务调用 DeBox OpenAPI 时，X-API-KEY 携带的是 App Key（API Key）。 Webhook Key 不是 App Secret（API Secret），不要混用。

Webhook Key 也只能保存在可信的后端服务或环境变量中，不要写入 H5、浏览器端代码、公开仓库或日志。

推荐参考：

• DeBox 开发者 OpenAPI

6. Long Polling 模式怎么用

最小接入步骤：

1. 确认 BotMother 中未配置 Webhook。
2. 使用 App Key（API Key）和 App Secret（API Secret）通过 SDK 初始化 Bot。
3. 开启消息监听并循环处理 GetUpdates/GetUpdatesChan。
4. 收到消息后调用发送接口回消息。

7. 三个 SDK 选型建议

DeBox 目前提供三套官方 SDK：

1. Go SDK：

• 文档：DeBox 机器人 Go SDK
• 适合高并发后端与工程化部署。

2. Nodejs SDK：

• 文档：DeBox 机器人 Nodejs SDK
• 适合 JS/TS 技术栈与快速迭代场景。

3. Python SDK：

• 文档：DeBox 机器人 Python SDK
• 适合 AI 工作流、脚本化任务与数据处理场景。

8. 接口开发主文档

SDK 负责“怎么调用”，OpenAPI 负责“参数值域和响应结构”。

新开发请同时参考：

• DeBox 开发者 OpenAPI
• 开发者 FAQ / 排障

9. 推荐实施路径

1. 先通过 BotMother 创建并完成基础配置。
2. 小流量阶段优先用 Webhook 模式联调。
3. 按团队语言栈选择 Go/Nodejs/Python SDK。
4. 统一以 OpenAPI 参数定义做最终校验。

Bot 发送的外部链接

Bot 发送的外部网页必须使用 https://，http:// 链接会被 DeBox 内置浏览器拦截。第三方 HTTPS 链接无论通过文本、按钮还是其他消息形式发送，默认都会显示“第三方网站”安全提示；改变消息形式不会 消除提示。完整规则和申请评估的联系方式请查看第三方链接与 HTTPS。