tg-bot-binding

Telegram Bot 绑定指南

当用户询问 Telegram Bot 绑定、设置、连接、验证或任何相关主题时，请向其提供以下指南。始终使用用户的语言回复。

概述

Starchild 支持连接你自己的 Telegram Bot，让你可以直接在 Telegram 中与自己的 AI Agent 聊天。绑定 Bot 有两种方式：

1. 扫码创建 Bot（推荐） — 扫描二维码，在 Telegram 中确认创建，Starchild 随即自动完成绑定。无需复制令牌，也无需验证码。
2. 手动绑定 — 通过 @BotFather 创建 Bot，在 Dashboard 中粘贴令牌，然后使用验证码验证所有权。

尽可能优先使用扫码创建方式 — 这种方式更快，步骤也更少。

---

方法 A：扫码创建 Bot（推荐）

此方式会为你创建一个新 Bot，并在一个流程中完成绑定 — 无需令牌，也无需验证码。

第 1 步：打开 Telegram Bot 区域

1. 前往 Starchild Dashboard（Web 界面）。
2. 点击页面左下角的头像。
3. 在账户管理弹窗中找到 Telegram Bot 区域。
4. 点击 “扫码创建 Bot”。

第 2 步：扫描二维码

页面上会显示一个二维码和一个链接。请任选以下一种方式：

• 使用 Telegram 应用扫描二维码（打开相机 → 扫描），或
• 点击 “在 Telegram 中打开”，直接跳转到创建页面。

第 3 步：在 Telegram 中确认创建

Telegram 会打开 Bot 创建页面。请确认创建 Bot。

第 4 步：完成！

Starchild 会检测到新 Bot，并自动完成绑定。Bot 会直接进入**“运行中”**状态 — 无需验证码。在 Telegram 中发送 /start，即可开始与 AI Agent 聊天。

注意： 以此方式创建的 Bot 由 Starchild 的 Bot 基础设施管理。之后如需移除，请在 Dashboard 中使用删除 Bot操作（不要通过 @BotFather 操作）。

---

方法 B：手动绑定（BotFather + 令牌）

如果你希望通过 @BotFather 自行创建 Bot 并持有其令牌，请使用此流程。

第 1 步：通过 BotFather 创建 Telegram Bot

1. 打开 Telegram，搜索 @BotFather（Telegram 官方 Bot 创建工具）。
2. 向 BotFather 发送 /newbot。
3. 按照提示操作：
   • 输入 Bot 的显示名称（例如，“My Starchild Agent”）。
   • 输入 Bot 的用户名（必须以 bot 结尾，例如 my_starchild_bot）。
4. BotFather 会回复你的 Bot Token — 一串类似 123456789:ABCdefGHIjklMNOpqrsTUVwxyz 的字符。**复制并妥善保管此令牌。**请勿公开分享。

第 2 步：在 Starchild Dashboard 中添加 Bot Token

1. 前往 Starchild Dashboard（Web 界面）。
2. 点击页面左下角的头像。
3. 在账户管理弹窗中找到 Telegram Bot 区域。
4. 粘贴你的 Bot Token 并提交。
5. 系统将：
   • 通过 Telegram API 验证令牌（调用 getMe）。
   • 生成一个6 位验证码（有效期为 5 分钟）。
   • 将 Bot 状态设为**“待处理”**。
6. 验证码会显示在 Dashboard 上。复制此验证码。

第 3 步：在 Telegram 中验证 Bot 所有权

有两种验证方式：

选项 A：深层链接（推荐）

点击 Dashboard 上提供的验证链接。该链接会在 Telegram 中打开你的 Bot，并自动提交验证码。链接格式为：

https://t.me/<your_bot_username>?start=verify_<CODE>

选项 B：手动验证

1. 在 Telegram 中打开你的 Bot（搜索 @<your_bot_username>）。
2. 发送 /start — Bot 会提示你输入验证码。
3. 输入6 位验证码并发送。

第 4 步：完成！

验证成功后，Bot 状态会短暂变为**“活跃”，随后自动切换为“运行中”** — 这表示你的 Bot 已上线并准备就绪。现在可以通过 Telegram 与 AI Agent 聊天。发送 /start 即可查看欢迎消息和可用命令。

---

Bot 状态参考

状态	含义
pending	已添加 Bot Token，等待所有权验证（仅限手动流程）
active	已验证所有权，正在切换到运行状态
running	Bot 已上线，可以使用
deleted	用户已移除 Bot

---

故障排除

“验证码已过期”

验证码有效期为 5 分钟。如果验证码过期：

• 返回 Dashboard 并点击 “Refresh Code”，生成新的验证码。
• 然后在 Telegram 中使用新验证码重新验证。

“失败尝试次数过多”

连续输入 5 次错误验证码后，验证码会因安全原因失效：

• 前往 Dashboard，删除 Bot，然后重新添加以获取新验证码。

“Bot Token 已被其他用户注册”

每个 Bot Token 只能绑定到一个 Starchild 账户。如果看到此错误：

• 确认你使用的是全新且未使用过的 Bot Token。
• 如果你之前用过此 Token，旧绑定可能仍然存在。通过 @BotFather 创建一个新 Bot。

“你已经有一个活跃的 Bot”

每个账户一次只能有一个活跃的 Bot：

• 要切换 Bot，请先从 Dashboard 删除当前 Bot，然后添加新的 Bot。
• 注意：删除 Bot 后，需要等待 1 小时才能添加新的 Bot。

“冷却时间尚未结束——请稍候再添加新 Bot”

删除 Bot 后，必须等待 1 小时才能添加新的 Bot。Dashboard 会显示冷却时间结束时间。

“尝试次数过多。请稍候片刻，然后重试。”

扫描创建流程有速率限制。如果看到此消息，请稍等片刻，然后再次点击 “Scan to create bot”。

“授权已过期。请重试。”

扫描创建二维码 / 链接仅在有限时间内有效。如果过期：

• 取消当前配对，然后再次点击 “Scan to create bot”，获取新的二维码。

Bot 在 Telegram 中没有响应

• 在 Dashboard 中检查 Bot 状态——状态应为 “running”。
• 如果状态为 “pending”，请完成验证步骤（手动流程）。
• 尝试向 Bot 发送 /start。
• 如果问题仍然存在，请尝试删除并重新添加 Bot（需等待 1 小时冷却时间）。

---

快速参考

操作	位置
创建并绑定 Bot（最快方式）	Starchild Dashboard → 左下角头像 → Account Management → Telegram Bot → “Scan to create bot” → 扫描二维码 → 在 Telegram 中确认
手动创建新的 Telegram Bot	Telegram → @BotFather → /newbot
添加 Bot Token	Starchild Dashboard → 左下角头像 → Account Management → Telegram Bot
验证所有权	Telegram → 你的 Bot → 输入验证码
刷新验证码	Starchild Dashboard → Account Management → Telegram Bot → “Refresh Code”
删除 Bot	Starchild Dashboard → Account Management → Telegram Bot → “Delete Bot”
查看 Bot 状态	Starchild Dashboard → Account Management → Telegram Bot

---

重要说明

• 推荐流程：使用 “Scan to create bot”——此流程会自动创建并绑定 Bot，无需 Token 或验证码。
• 通过扫描创建的 Bot 由 Starchild 管理：这些 Bot 通过 Starchild 的 Bot 基础设施创建。请从 Dashboard 删除，而不要从 @BotFather 删除。
• 安全性：在手动流程中，Bot Token 会在存储前使用 AES-256 加密。它绝不会出现在 API 响应中。
• 每个账户一个 Bot：每次只能有一个活跃的 Telegram Bot。
• 冷却时间：删除 Bot 后，等待 1 小时再添加新的 Bot。
• 速率限制：添加 Bot 和刷新验证码的操作限制为每分钟 3 次请求。
• 验证尝试次数：你有 5 次输入正确验证码的机会，之后验证码将失效。