第 2 课
配对 Telegram 远程与常用命令
按官方 telegram.md 创建 Bot、在 Remote access 配对自己的账号，并用 /agents 等命令遥控。
课程目录第 2 / 2 课
学习位置仅保存在当前浏览器，有效期 180 天。
配对 Telegram 远程与常用命令
配对 Telegram 远程与常用命令
本课按官方 docs/telegram.md 整理，目标是：创建 Telegram Bot、把 token 交给 Xiryn、只配对你自己的账号，并用
/agents等命令在手机上对话与接管。
前置：第 1 课已能打开http://127.0.0.1:6796。
同步摘录：README · Remote control from Telegram
你将得到什么
- 一个仅你可用来聊 Agent 的 Telegram Bot
- Settings → Remote access 显示 Paired with @你的用户名
- 会使用：
/agents/new/stop/status/help
工作原理（为何不用公网 URL）
官方说明：Xiryn 从你的电脑对外长轮询 Telegram Bot API（问「有没有新消息」），连接始终从本机出站，因此：
- 不需要公网 IP、端口转发、隧道或 webhook
- 只要电脑能上网、Xiryn 在跑，手机就能聊
- 只有配对成功的那一个 Telegram 账号会被回答；其他人找 Bot 只会收到礼貌拒绝
一、用 @BotFather 创建 Bot
- 打开 Telegram，搜索
@BotFather（认准蓝色认证标），或打开 https://t.me/BotFather 。 - 点 Start，发送
/newbot。 - 按提示设 显示名（随意，如
My Xiryn）和 username（全局唯一，且必须以bot结尾，如myname_xiryn_bot）。 - BotFather 会回复一串 token，形如：
123456789:AAHf0x-ExAmPlE_tOkEn_DoNoTuSe-12345
对照结果： 你复制到了完整 token。把它当成密码——泄露后应对 BotFather 发 /revoke 换新。
可选：
/setuserpic、/setdescription。不必/setcommands——Xiryn 会自动注册命令。
二、把 token 交给 Xiryn
任选官方推荐路径之一：
推荐：应用内
- 打开 http://127.0.0.1:6796
- 进入 Settings → Remote access
- 在步骤 2 粘贴 token → Connect
- 约一秒内应显示类似
polling as @your_bot
或：写入 .env 后重启
TELEGRAM_BOT_TOKEN=123456789:AAH…
# 可选：TELEGRAM_OWNER_ID=… （一般配对流程会处理归属）
然后：
cd xiryn
npm run dev
对照结果： Remote access 面板显示正在 polling / 已连接 Bot 用户名，而不是报错 token 无效。
三、配对你的 Telegram 账号
仍在 Settings → Remote access 步骤 3，会看到 二维码 与 配对码。任选：
| 方式 | 做法 |
|---|---|
| 扫码 | 手机相机扫 QR → 打开 Bot → 点 Start |
| 电脑打开 | 点 “Open in Telegram” → Start |
| 手打 | 向 Bot 发送 /pair YOURCODE |
页面应自动变成 Paired with @你，Bot 会问候你。此后只有该账号能用此 Bot。
对照结果：
- 面板显示已配对用户名
- 用另一 Telegram 号发消息会被拒绝（官方安全模型）
- 配对码错误会轮换（README：single-use / rotate after wrong guesses）
四、常用命令（可直接抄）
官方命令表（telegram.md）：
| 命令 | 作用 |
|---|---|
/agents | 选择当前对话的 Agent 或 Squad（按钮） |
/new | 与当前 Agent/Squad 开新线程 |
/stop | 中断正在跑的任务 |
/status | 当前对象、模型、是否有进行中的 turn |
/help | 速查 |
日常：像在网页里一样直接给 Bot 发自然语言任务。Agent 工作时会有步骤状态（如 $ git clone …），完成后给出普通消息回复。
当 Agent 需要你登录、支付、验证码或 CAPTCHA 时：
- Bot 会推送，并常带可从手机打开的桌面实时链接（若未关闭
XIRYN_PHONE_TAKEOVER） - 你在 Agent 桌面上完成操作后，回复
done（或按界面提示），Agent 继续
对照结果：
/status返回可读状态而非报错/agents能列出你在网页里创建过的 Agent- 发一条短任务能收到进度或最终答复（电脑需保持开机、Xiryn 进程在跑）
五、相关环境变量（可选加深）
摘自 README Configuration（完整见仓库 .env.example）：
| 变量 | 作用 |
|---|---|
TELEGRAM_BOT_TOKEN | Bot token |
TELEGRAM_OWNER_ID | 属主约束（若使用） |
XIRYN_TELEGRAM_NOTIFY | 任务结束通知：long（默认，≥约 1 分钟）、all、off |
XIRYN_PHONE_TAKEOVER | off 则手递链接不进 Telegram |
XIRYN_URL | 写在 Telegram 链接里的访问地址 |
六、安全提醒（必读）
- UI 只绑 127.0.0.1，并校验 Host/Origin，降低 DNS 重绑定风险（README Security）。
- 支付与登录：Vault 加密；Agent 只见掩码；每笔支付需你批准。
- 电脑休眠或关机时，本机托管的 Bot 无法继续工作——需要常开主机或另外部署（产品定位如此）。
本课小结
| 步骤 | 动作 | 成功信号 |
|---|---|---|
| 建 Bot | @BotFather /newbot | 拿到 token |
| 连接 | Settings → Remote access | polling as @bot |
| 配对 | 扫码 / /pair | Paired with @you |
| 使用 | /agents + 自然语言 | 手机收到进度/答复 |
两课合计：本机 Agent + 手机遥控。更多架构见官方 docs/architecture.md。
来源
- https://github.com/SouravBeraAkaSpeed/xiryn/blob/main/docs/telegram.md
- https://github.com/SouravBeraAkaSpeed/xiryn （README · Remote control / Security / Configuration）
- https://xiryn.com/
