快速上手:从零到跑通,一步不落
默认走云托管:只需一部手机、约 10 分钟,不需要服务器、不需要写代码。每一步都标注了在哪个界面点什么,以及最容易踩的坑。
先确认:本教程需要 Telegram Premium。 本页配置的「隐形中继」跑在 Telegram Business 上,是 Premium 专属功能。没有 Premium?不用往下看 —— 直接私聊 @LingoDeskbot 发 /free:群双向同传、内联翻译、Bot 门面控制台全部免费可用。
🧾 准备清单
- Telegram Premium 会员 —— Telegram Business 功能(消息回灌给 bot)是 Premium 专属,没有 Premium 整套流程无法工作。
- 一部手机 —— 云托管模式(默认)只需要这个:第 1–3 步在手机上完成,把 token 发给我们就开通。
- 仅自托管需要:Node.js ≥ 20(或 Docker)、Anthropic API Key、一台常开的电脑/服务器。代码免费开源在 GitHub。
1在 BotFather 创建 bot
在 Telegram 搜索 @BotFather(认准官方蓝 V),对话如下:
🤖 BotFather
/newbot
BotFatherAlright, a new bot. How are we going to call it? Please choose a name for your bot.
LingoDesk 助手
BotFatherGood. Now let's choose a username for your bot. It must end in bot.
my_lingodesk_bot
BotFatherDone! Use this token to access the HTTP API:
8123456789:AAHfK3xxxxxxxxxxxxxxxxxxxxxxxxx
Keep your token secure and store it safely…
- 「名字」随意,是显示名;「username」必须全局唯一且以
bot 结尾,被占用就换一个。
- 最后回复里那串
数字:字母 就是 BOT_TOKEN,先复制存好。它等于 bot 的密码,别发给任何人。
1a. 开启 Secretary Mode(必做;旧称 Business Mode)
⚠️ 2026 年 5 月起 Telegram 把这个开关改名为 Secretary Mode(秘书模式),老客户端里可能仍显示 Business Mode——是同一个东西。在 @BotFather 的聊天里操作(不是你 bot 的资料页,也不是手机的 Telegram 设置),两套界面任选:
界面 ① 经典命令版 —— 直接发消息:
/mybots→
@my_lingodesk_bot→
Bot Settings→
Secretary Mode→
Turn on
界面 ② 新版管理面板 —— 点 BotFather 输入框旁的蓝色 Open 按钮:
Open(打开面板)→
选你的 bot→
Settings→
Mode Settings→
Secretary Mode 开关打开
找不到这一项?① 记住它有两个名字:新版叫 Secretary Mode,旧版叫 Business Mode,找其中任意一个;② 确认你是在 @BotFather 里操作,不是在自己 bot 的设置里;③ 这个开关和 Telegram Premium 无关——Premium 只影响第 2 步你账号侧的绑定,BotFather 里人人都能开。
不开 Secretary Mode,第 2 步添加 bot 时 Telegram 会弹窗提示「此机器人暂不支持 Telegram 企业版」——这是全流程最常见的卡点。看到这个弹窗就回到本步骤把开关打开:立即生效,不用重建 bot,回去重新添加即可。
1b. 关闭 Group Privacy(必做)
/mybots→
@my_lingodesk_bot→
Bot Settings→
Group Privacy→
Turn off
Privacy 默认开启,开启状态下 bot 看不到你在控制台群里打的中文——表现为「我在话题里发消息,bot 毫无反应」。务必关掉(BotFather 会显示 Privacy mode is disabled 才算成功)。
2在 Telegram Business 里绑定 bot
用手机版 Telegram(此设置目前只在手机端有):
⚙️ 设置→
💼 Telegram Business→
🤖 聊天机器人 Chatbots
新版客户端里这一项叫「自动聊天(Chat Automation)」——名字不同,是同一个入口。
- 在搜索框输入你的 bot username(如
my_lingodesk_bot),点选它。
- 权限:把「回复消息 / Reply to messages」打开——不开的话 bot 只能看不能替你发。
- 「哪些聊天」建议选 所有一对一聊天(All 1:1 Chats);不想让 bot 看到的私人联系人,加到排除列表(Excluded Chats)即可。
绑定成功后,你私聊里收到的每条消息都会静默「抄送」给 bot——对方完全无感知,你手机上的聊天体验也没有任何变化。
3创建控制台论坛群
这个群是你的工作台:每个客户一个话题(Topic),双语卡片都弹在这里。
- 新建群组:Telegram 里点新建 → 新建群组,成员就选你的 bot(搜 username 能搜到),群名随意,比如「LingoDesk 控制台」。
- 开启话题:进群 → 点群名进资料页 → 编辑 → 找到「话题 Topics」→ 打开。群会自动升级为超级群,界面变成左侧话题列表。
- 把 bot 提为管理员:资料页 → 管理员 → 添加管理员 → 选你的 bot → 勾选「管理话题 Manage Topics」(其余默认即可)→ 保存。
bot 要为每个客户自动创建话题,没有管理员的「管理话题」权限就会失败——表现为「客户发消息了,群里却什么都不弹」。
这个群只有你和 bot,不用拉任何真人。想加合伙人一起盯也可以,TA 在话题里打中文同样能触发翻译发送。
4二选一:☁️ 云托管 或 💻 自托管
到这里,手机上的准备已全部完成。接下来选一条路——没有服务器就选 A,什么都不用装。
☁️ 方式 A · 云托管(推荐:无需服务器、无需代码,秒级开通)
- 私聊官方开通机器人 @LingoDeskbot,发
/start,然后把第 1 步拿到的 BOT_TOKEN 直接发给它。
- 秒级自动开通:校验通过立即回复「🎉 开通成功」(你发的 token 消息会被自动删除)。免费版每月含 300 条翻译回复,随时可升级 Pro(500⭐/月)解锁无限;翻译引擎由我们提供,不用申请任何 API Key。
- 按它回复的指引完成绑定,最后在你的控制台群里发一句
/bind —— bot 回复「✅ 已绑定」,全部完成,直接跳到第 5 步试聊。随时私聊它发 /status 查状态、/native en 切换你的母语。
担心 token 交出去不安全?token 加密存储,只被用于收发你在 Business 里授权的会话;你随时可以在 BotFather 里(/mybots → API Token → Revoke)重置它,旧 token 立即失效,主动权始终在你手里。
💻 方式 B · 自托管(自己的电脑/服务器,数据完全自持)
先去 console.anthropic.com → API Keys → Create Key 拿一个 sk-ant-…(翻译引擎;Billing 充几美元,一条译文约 $0.001,够用很久)。然后:
git clone https://github.com/sanxiaozi/lingodesk.git
cd lingodesk
npm install
cp .env.example .env # open .env — only BOT_TOKEN and ANTHROPIC_API_KEY are required
npm run db:push # initialize the database (first run only)
npm run dev
🚀 LingoDesk is up, bot = @my_lingodesk_bot
看到启动横幅后,在控制台群里发一句 /bind 完成绑定(群 ID、你的用户 ID 全部自动识别,不用再查任何数字)。服务器上推荐 Docker:docker compose up -d,详见 GitHub README。
同一个 bot token 全球只能有一个实例在跑(报 409 Conflict = 有旧进程没停)。已开通云托管的话,就不要再自己启动本地实例。
5试聊验证
找一个别的 Telegram 账号(小号或朋友),用外语私聊你的真人号(不是私聊 bot!),比如发一句西语「Hola, ¿cuánto cuesta?」。控制台群里应该几秒内弹出一个以对方命名的新话题:
📋 LingoDesk 控制台 · 话题:@amigo_es
my_lingodesk_bot🆕新客户 @amigo_es(es)
原文:Hola, ¿cuánto cuesta?
🇨🇳 你好,多少钱?
─────
↳ 本话题内打中文,自动译 es 以你名义发出
套餐 A 是 100 美元,包含全部功能。
my_lingodesk_bot📤 译文预览(→es),确认后才发给客户:
El paquete A cuesta 100 dólares e incluye todas las funciones.
(你的中文:套餐 A 是 100 美元…)
[ ✅ 发送给客户 ] [ ✏️ 取消 ]
点「✅ 发送给客户」,对方会看到你的真人账号用流利西语回复了 TA。到这里,整条链路就通了 🎉
- 对方发图片/文件/语音 → 自动转进话题并存档。
- 语种识别错了?在话题里发
/lang es 手动纠正,发 /help 看全部命令。
- 你在手机上直接手动回复客户也没问题,bot 会把它记录进话题存档。
- 主动发起也行,不必等对方先来:你在真人号对任意人说句话(比如「hi」),TA 立刻出现在控制台并自动建话题,之后你在这里打中文就能继续跟 TA 聊。
🔧 常见问题排查
客户发消息了,控制台群什么都不弹
按顺序检查:① BotFather 里 Business Mode 是否 Turn on(第 1a 步);② Telegram Business → Chatbots 是否绑定了 bot、该聊天是否在覆盖范围内(第 2 步);③ bot 是否是群管理员且有「管理话题」权限(第 3 步);④ 控制台群是否已绑定 —— 在群里发一句 /bind;⑤ 自托管用户:终端里 bot 是否还在跑、有无报错。
添加机器人时弹窗:「此机器人暂不支持 Telegram 企业版」
BotFather 里没开 Business Mode(第 1a 步)。去 @BotFather → /mybots → 选你的 bot → Bot Settings → Business Mode → Turn on。开启立即生效:不用重建 bot、不用重发 token,回到 Telegram Business → Chatbots 重新添加即可。云托管用户可私聊 @LingoDeskbot 发 /status 复查这一项。
在群里发 /bind,bot 没反应
① Group Privacy 没关(第 1b 步),关掉后把 bot 踢出群重新拉进来;② 群还没开启「话题(Topics)」;③ 云托管用户:确认 @LingoDeskbot 已回复你「开通成功」(私聊它发 /status 可查);④ 自托管用户:确认终端里 bot 正在运行。
云托管要交出 BOT_TOKEN,安全吗?
token 加密存储,只被用来收发你在 Telegram Business 里授权范围内的会话,你也可以把私人联系人加入排除列表(第 2 步)。主动权在你:任何时候去 BotFather → /mybots → API Token → Revoke 重置,旧 token 立即失效,服务即刻中断;想恢复就把新 token 再发给 @LingoDeskbot。
我在话题里打中文,bot 没反应
九成是 Group Privacy 没关(第 1b 步)。去 BotFather → Bot Settings → Group Privacy → Turn off,然后把 bot 踢出群再重新拉进来(权限变更需要重进群才生效),重新设为管理员。
启动报 409 Conflict
同一 token 有两个实例在跑。找到并停掉旧进程(Ctrl+C 或 pkill -f "tsx.*main.ts"),等十秒再启动。
点「发送给客户」提示发送失败
按概率排查:① 「回复消息」权限没开(最常见)——设置 → Telegram Business → 聊天自动化(Chatbots)→ 选中你的 bot → 打开「回复消息(Reply to messages)」,不开则 bot 能收不能发;② 该客户不在 bot「可访问的聊天」范围内(同一页面检查);③ 对方超过 24 小时没发过消息,Telegram 不允许 bot 主动发起——让对方先发一句。云托管用户私聊 @LingoDeskbot 发 /status,「回复权限」一行会直接告诉你答案。
点「发送给客户」报错:客户太久没往来
Telegram 限制:太久没互动的对话,bot 不能替你主动发起(报 BUSINESS_PEER_USAGE_MISSING)。让对方先随便发一句激活,或这一次你在手机上手动回。
发送报错:Business 连接失效
去 设置 → Telegram Business → Chatbots 里把 bot 移除再重新添加,或让客户发条新消息——bot 会自动捕获新的连接并恢复。
翻译语种不对 / 想换目标语言
语种在客户第一条消息时锁定(避免短消息误判来回跳)。在该客户的话题里发 /lang 语种码 即可纠正,如 /lang pt(葡语)、/lang ar(阿语)。
bot 重启后,之前的「发送/取消」按钮点了没反应
待确认的译文预览存在内存里,重启会失效(按钮会提示)。在话题里把中文重新打一遍即可。客户映射和聊天记录都在数据库里,不会丢。