快速上手:从零到跑通,一步不落
默认走云托管:只需一部手机、约 10 分钟,不需要服务器、不需要写代码。每一步都标注了在哪个界面点什么,以及最容易踩的坑。
🧾 准备清单
- 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. 开启 Business Mode(必做)
还是在 BotFather 里:
/mybots→
@my_lingodesk_bot→
Bot Settings→
Business Mode→
Turn on
不开 Business Mode,第 2 步在 Telegram Business 的机器人列表里根本搜不到你的 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
- 在搜索框输入你的 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 · 云托管(推荐:无需服务器、无需代码)
- 把第 1 步拿到的 BOT_TOKEN 发给我们:点此一键生成开通邮件(模板已备好,粘贴 token 发送即可)。
- 我们在 24 小时内为你开通并邮件回复确认。内测期免费,翻译引擎也由我们提供,不用申请任何 API Key。
- 收到确认后,在你的控制台群里发一句
/bind —— bot 回复「✅ 已绑定」,全部完成,直接跳到第 5 步试聊。
担心 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 # 打开 .env,只需填 BOT_TOKEN 和 ANTHROPIC_API_KEY 两行
npm run db:push # 初始化数据库(仅首次)
npm run dev
🚀 LingoDesk 已启动,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 会把它记录进话题存档。
🔧 常见问题排查
客户发消息了,控制台群什么都不弹
按顺序检查:① BotFather 里 Business Mode 是否 Turn on(第 1a 步);② Telegram Business → Chatbots 是否绑定了 bot、该聊天是否在覆盖范围内(第 2 步);③ bot 是否是群管理员且有「管理话题」权限(第 3 步);④ 控制台群是否已绑定 —— 在群里发一句 /bind;⑤ 自托管用户:终端里 bot 是否还在跑、有无报错。
在群里发 /bind,bot 没反应
① Group Privacy 没关(第 1b 步),关掉后把 bot 踢出群重新拉进来;② 群还没开启「话题(Topics)」;③ 云托管用户:确认已收到我们的开通邮件(开通前 bot 还没运行);④ 自托管用户:确认终端里 bot 正在运行。
云托管要交出 BOT_TOKEN,安全吗?
token 只被用来收发你在 Telegram Business 里授权范围内的会话,你也可以把私人联系人加入排除列表(第 2 步)。主动权在你:任何时候去 BotFather → /mybots → API Token → Revoke 重置,旧 token 立即失效,服务即刻中断。停用前发邮件告知一声即可。
我在话题里打中文,bot 没反应
九成是 Group Privacy 没关(第 1b 步)。去 BotFather → Bot Settings → Group Privacy → Turn off,然后把 bot 踢出群再重新拉进来(权限变更需要重进群才生效),重新设为管理员。
启动报 409 Conflict
同一 token 有两个实例在跑。找到并停掉旧进程(Ctrl+C 或 pkill -f "tsx.*main.ts"),等十秒再启动。
点「发送给客户」报错:客户太久没往来
Telegram 限制:太久没互动的对话,bot 不能替你主动发起(报 BUSINESS_PEER_USAGE_MISSING)。让对方先随便发一句激活,或这一次你在手机上手动回。
发送报错:Business 连接失效
去 设置 → Telegram Business → Chatbots 里把 bot 移除再重新添加,或让客户发条新消息——bot 会自动捕获新的连接并恢复。
翻译语种不对 / 想换目标语言
语种在客户第一条消息时锁定(避免短消息误判来回跳)。在该客户的话题里发 /lang 语种码 即可纠正,如 /lang pt(葡语)、/lang ar(阿语)。
bot 重启后,之前的「发送/取消」按钮点了没反应
待确认的译文预览存在内存里,重启会失效(按钮会提示)。在话题里把中文重新打一遍即可。客户映射和聊天记录都在数据库里,不会丢。