Telegram Bot 绑定
每个 SayClaw 实例可以绑定一个专属 Telegram Bot，绑定后用户可以直接在 Telegram 与 AI 对话。
功能概览
- 自助操作：用户在 Portal 自行完成，无需管理员介入
- 一实例一 Bot：每个实例绑定一个独立 Bot Token
- 白名单访问：仅绑定时指定的 Telegram ID 可以与 Bot 对话
- 随时解绑：解绑后 Bot 停止响应，实例恢复空闲状态
前提条件
- 已在 Portal 领取实例（每人限一个）
- 准备好 Telegram Bot Token — 在 @BotFather 发送
/newbot创建 - 知道自己的 Telegram 数字 ID — 与 @getmyid_bot 对话获取
绑定步骤
1. 打开 Portal
访问 app.sayclaw.ai（PC）或 m.sayclaw.ai（手机），登录账号。
2. 进入实例卡片
在工作台找到你的实例卡片，点击「绑定 Telegram」按钮（或点击 TG 状态区域）。
3. 填写信息
在弹出的配置面板中填写：
| 字段 | 说明 | 示例 |
|---|---|---|
| Bot Token | 从 @BotFather 获取的完整 Token | 123456789:AAxxxxxxxxxxxxxxxx |
| 你的 Telegram ID | 你的数字 ID（非用户名） | 6057436537 |
4. 保存配置
点击「保存配置」，系统会：
- 验证 Bot Token 有效性（调用 Telegram API）
- SSH 到实例服务器自动写入配置
- 重启实例服务
整个过程约 10–30 秒，看到「绑定成功」提示后即可使用。
5. 开始对话
直接在 Telegram 搜索你的 Bot 用户名，发送消息即可。
解绑
在实例卡片点击「解绑」→ 确认后系统清除 Bot 配置并重启实例。
底层实现
API 接口
POST /api/v1/me/instances/:id/tg-setup
请求体：
{
"bot_token": "123456789:AAxxxxxxxxxxxxxxxx",
"tg_user_id": "6057436537"
}
响应：
{
"code": "0000",
"data": {
"bot_username": "my_ai_bot",
"bound_at": "2026-03-07T00:00:00Z"
}
}
其他接口：
| 方法 | 路径 | 说明 |
|---|---|---|
GET | /me/tg/status?instance_id=xxx | 查询绑定状态 |
DELETE | /me/tg/unbind?instance_id=xxx | 解绑 |
数据存储
绑定信息存储在 sayclaw_portal.user_instances 表：
| 字段 | 说明 |
|---|---|
tg_bot_token | Bot Token（脱敏，仅首尾可见） |
tg_bot_username | Bot 用户名（如 @my_ai_bot） |
tg_user_id | 用户的 Telegram 数字 ID |
tg_bound_at | 绑定时间 |
实例配置
绑定成功后，portal-api 通过 SSH 自动写入实例的 openclaw.json：
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "123456789:AAxxxxxxxxxxxxxxxx",
"allowedUserIds": [6057436537],
"network": {
"autoSelectFamily": false,
"dnsResultOrder": "ipv4first"
}
}
}
}
network配置为 IPv4 优先，解决 GCP Japan 区域 IPv6 不稳定导致 Bot 静默断线的问题。
常见问题
Q：Bot 绑定后没有响应？
等待 10–20 秒让实例完成重启。如果仍无响应，检查：
- Bot Token 是否填写正确（完整复制，包含冒号和后面部分）
- Telegram ID 是否是数字 ID（不是用户名 @xxx）
- 实例状态是否为「运行中」
Q：能不能多人使用同一个 Bot？
当前版本仅支持单用户白名单。如需多人共用，需要管理员在后台手动编辑 allowedUserIds 数组（后续版本将支持多人配置）。
Q：Bot Token 安全吗？
Token 在数据库中脱敏存储（仅首尾可见），API 响应中不返回完整 Token。实例配置文件存储在隔离的服务器目录中。
Q：换一个 Bot 怎么操作？
先解绑现有 Bot，再重新走绑定流程填写新 Token 即可。