前言 · 為什麼把 hermes 接到 Telegram
1 分鐘
Lesson 1 你已經在 WSL 裡裝好 hermes、做過第一次對話。但你只能坐在電腦前面跟它講話——這堂 30–45 分鐘的延伸課要把這個限制拿掉：把 hermes 接到 Telegram，從手機就能跟它對話。
結束時你會有
- ✓ 一支自己的 Telegram bot（透過 BotFather 申請）
- ✓ 你自己的 Telegram user_id（讓 bot 只回你一個人）
- ✓
hermes gateway在 WSL 背景跑著 - ✓ 至少一次「手機傳訊 → bot → hermes 回覆」的完整來回
限制：機器要開著
本堂用的是 polling 模式（hermes 每隔幾秒主動問 Telegram「有新訊息嗎」），所以你的 Windows + WSL 必須開著、gateway 必須跑著，bot 才有回應。Windows 重啟後 gateway 會掛掉、要手動重跑。「24/7 不間斷服務 / 自動啟動 / 雲端部署」不在本堂範圍，留給後續課程。
已經在 Lesson 1 Step 9 加碼 B 申請過 token？
很好——Step 2 你可以直接跳到「貼到 Notes 暫存」那段，不必重做 BotFather 流程。沒做過也沒關係，Step 2 會帶你完整走一次。
沒做過 Lesson 1？
本堂預設你已完成 Lesson 1（hermes 在 WSL 裝好、可對話）。沒做過請先去 Lesson 1，再回來。
Step 1 / 7 · 開始之前
~2 分鐘
動工前先確認 3 件事都到位：
前置 checklist
- ✓ Lesson 1 已完成。打開 Ubuntu 終端機，跑
hermes應該會進到 hermes TUI（按/exit退出）。沒做過？先去 Lesson 1。 - ✓ 手機 / 電腦上有 Telegram 帳號。沒裝？App Store / Google Play / 桌面版 隨便挑一個。
- ✓ 記事本開著（任何純文字編輯器都行）。等下要暫存 token 跟 user_id 兩個東西。
這 7 步在做什麼
- Step 2：跟 Telegram 申請一支 bot，拿到 token
- Step 3：拿你自己的 Telegram user_id（讓 bot 只回你）
- Step 4：跑
hermes gateway setup，把 token 跟 user_id 寫進設定檔 - Step 5：把 gateway 跑成背景程式
- Step 6：從手機傳訊息給 bot，確認 hermes 有回
- Step 7：收尾、加碼玩法、下一堂預告
加碼預告
- 群組使用（把 bot 加到 Telegram 群組）
- 語音訊息（直接傳語音，hermes 會自動轉字）
- session 管理（
/new、/title、/resume、/usage） - 切模型（
/model provider:model） - 24/7 服務（
hermes gateway install，超出本堂範圍但 Step 7 點到）
都會在 Step 7 用 <details> 展開介紹。
Step 2 / 7 · 申請 Telegram bot
~5 分鐘
Telegram 的 bot 申請流程超簡單，2 分鐘搞定：跟 @BotFather 講話、回答幾個問題、拿到一段 token。
跟著走
已經有一份完整的中文教材，照著做就好：
跟完到「拿到 HTTP API token」那一步即可，token 暫存到記事本，等下 Step 4 要貼進去。
token 長什麼樣？
BotFather 回的 token 大概長這樣：
1234567890:ABCdefGHIjklMNOpqrsTUVwxyz0123456789冒號前是 bot 的數字 ID，冒號後是 secret。整段都要。
🚨 主連結打不開（lewsi.ddns.net 失聯）
備援精簡版，5 句搞定：
- 手機/電腦 Telegram 開 @BotFather
- 送
/newbot - 填 bot 顯示名稱（任意，例：
my-hermes） - 填 bot username（必須以
bot結尾，且全網唯一，例：my_hermes_xyz_bot或myhermesbot） - BotFather 回的訊息裡會有一段 HTTP API token，整段複製到記事本
username 取太常見的會撞名，加亂數或日期通常就過了。
BotFather 還能做什麼？（之後想玩再回來）
/setname：改顯示名稱/setdescription：改 bot 自我介紹/setuserpic：換頭像/mybots：列出你所有 bot
關閉 Group Privacy（加群組用）
如果你之後想把 bot 加進 Telegram 群組，預設的 Privacy Mode 會讓 bot 只看得到 /指令，一般訊息全看不到。現在就先關掉，省得之後群組沒反應找半天原因。
- 開 @BotFather，送
/mybots - 選你剛建的 bot
- 點 Bot Settings
- 點 Group Privacy
- 點 Turn off（關閉後顯示 Privacy mode is disabled）
✓ token 在手、Group Privacy 已關，接著 Step 3。
Step 3 / 7 · 拿你的 Telegram user_id
~2 分鐘
hermes gateway 設定時會問你「哪些 Telegram 使用者可以跟這支 bot 講話」——這個白名單填的是 數字 user_id，不是 @username。下面 30 秒拿到。
動作
- 手機/電腦 Telegram 開 @userinfobot
- 按下方「Start」（或送
/start） - 它會立刻回一段話，裡面有 Id: 123456789（純數字，9–10 位數）
- 把那串純數字複製到記事本，跟 Step 2 的 token 放一起
user_id 是什麼？為什麼要它？
每個 Telegram 帳號都有一個唯一的數字 ID，跟 @username 不同——username 你可以隨時改、刪，但 user_id 跟著帳號一輩子。
hermes gateway 啟動後，每收到一則訊息會檢查 這個 user_id 在不在 allowlist 裡，不在就拒絕回覆。所以這個欄位填的是「哪個 Telegram 人類帳號允許用這支 bot」，不是 bot 自己的 ID。
Id 跟 Bot ID 怎麼分？
@userinfobot 回的訊息有時會列好幾項（Id、First Name、Last Name、Username、Language）。取最上面那個 Id，那是你（人類）的 ID。Bot 自己的 ID 不會出現在這裡。
✓ user_id 抄好了？接著 Step 4 把 token 跟 user_id 一起餵給 hermes。
Step 4 / 7 · hermes gateway setup
~8 分鐘
hermes gateway setup 是 hermes 把外部聊天平台接進來的設定精靈。我們要選 telegram、貼 Step 2 的 token、貼 Step 3 的 user_id。
動作
- 打開 Ubuntu 終端機，啟動精靈
hermes gateway setup- 依下面 3 個提示一個一個填
3 個提示怎麼答
| 提示 | 選 / 填 |
|---|---|
| Choose gateway | 用方向鍵選 telegram，Enter |
| Telegram bot token | ⚠️ 建議手動 key in（同 Lesson 1 Step 7 的 paste 雷），或先看下面「補救」section 用 sed 寫進 .env。若還是要 paste：Ctrl+Shift+V，Enter |
| Allowed users | 貼 Step 3 的純數字 user_id，多人用逗號分隔（本教材只填你自己）。Enter |
看到 Setup complete! 就成功，~/.hermes/.env 裡會多兩行 TELEGRAM_BOT_TOKEN= 與 TELEGRAM_ALLOWED_USERS=。
Allowed users 是什麼？為什麼要填？
沒這個欄位的話，bot 是公開的——任何陌生人 Telegram 搜到你 bot 就能丟訊息進來，你的 OpenRouter 帳號就會被陌生人花錢。Allowed users 只放你自己（或團隊夥伴）的 user_id，其他訊息會被 gateway 直接 ignore。
🚨 我卡住了
- Ctrl+C 中斷 → 重跑
hermes gateway setup - token 貼進去變空白 / Step 5 跑 gateway 立刻 401 → 用下面的補救 sed 直接改
~/.hermes/.env - user_id 貼進去多了空白 → 同上，用 sed 補救改
TELEGRAM_ALLOWED_USERS=
補救：直接改 hermes 的 .env
跟 Lesson 1 Step 7 同根因（hermes 上游 paste 雷）、同模式。下面兩個版本擇一用：
Variant A · 互動腳本（推薦）
輸入時 token 不會回顯（避免肩膀後面被看到）、user_id 會回顯（純數字無妨）：
cd ~/.hermes && read -sp "Paste your Telegram bot token: " TOKEN && echo && read -p "Paste your Telegram user_id: " USER_ID && sed -i "s/^TELEGRAM_BOT_TOKEN=.*/export TELEGRAM_BOT_TOKEN=$TOKEN/" .env && sed -i "s/^TELEGRAM_ALLOWED_USERS=.*/export TELEGRAM_ALLOWED_USERS=$USER_ID/" .env && unset TOKEN USER_IDVariant B · 手動範本
把 YOUR_BOT_TOKEN 與 YOUR_USER_ID 替換成實際值再貼進終端機：
cd ~/.hermes && sed -i 's/^TELEGRAM_BOT_TOKEN=.*/export TELEGRAM_BOT_TOKEN=YOUR_BOT_TOKEN/' .env && sed -i 's/^TELEGRAM_ALLOWED_USERS=.*/export TELEGRAM_ALLOWED_USERS=YOUR_USER_ID/' .env跑完任一個之後，下一步直接進 Step 5 啟動 gateway。
Step 5 / 7 · 啟動 hermes gateway（背景）
~5 分鐘
Token 跟 user_id 都進 .env 了，現在把 gateway 安裝成系統服務，這樣開機就自動跑、不需要每次手動啟動。
先試前景版（確認設定沒問題）
hermes gateway run會看到一段啟動 banner（含「Press Ctrl+C to stop」）。確認沒有 401 / fatal 錯誤後，按 Ctrl+C 停掉，再進行下方的服務安裝。
安裝為系統服務
執行安裝指令。過程中會看到三個選項：
- User service（不需 sudo，但關閉登入可能停止）
- System service（開機自動啟動，以你的帳號身分執行）← 選這個
- Skip service install for now
用方向鍵選第二項「System service」，按 Enter 確認。
sudo $(which hermes) gateway install --system --run-as-user安裝完成後，啟動服務：
sudo $(which hermes) gateway start --system確認跑著
hermes gateway status預期看到類似：
✓ Gateway is running (PID: 12345)
(Running manually, not as a system service)沒看到「running」→ 看 log：
tail -n 50 ~/.hermes/logs/gateway.log看 log（即時）
想盯著 gateway 的活動（debug、看訊息進來）：
tail -f ~/.hermes/logs/gateway.log離開 tail -f 用 Ctrl+C（這只是退出觀察，不會停掉 gateway 本身）。
停掉 gateway
hermes gateway stop萬一 stop 沒反應（極少見），fallback：
pkill -f "hermes gateway"🚨 我卡住了
- install 後 log 出 401 / Unauthorized → token 寫錯。
sudo $(which hermes) gateway stop --system砍掉，回 Step 4 用 sed 補救改TELEGRAM_BOT_TOKEN=，再sudo $(which hermes) gateway start --system。 - 看到
Gateway already running→sudo $(which hermes) gateway restart --system直接重啟。 - log 出現 network error → WSL 網路問題，
ping 8.8.8.8確認連得到外網。
✓ hermes gateway status 報 running 就成功，下一步進 Step 6 用手機測。
Step 6 / 7 · 第一次手機 ↔ hermes
~5 分鐘
Gateway 跑著、token 跟 user_id 都對，現在用手機驗證整條鏈路通了。
動作
- 打開手機 Telegram，搜尋你 Step 2 設的 bot username（一般是
@xxx_bot） - 進到對話畫面，按下方「Start」（或送
/start） - 傳第一句話，例如：
hello, you there? - 等 1–5 秒（看模型 response 速度），bot 應該會回
- 再傳一句相關的，例如：
what was my first message?，確認 context 連動（hermes 應該記得你問過什麼）
看 gateway log 確認訊息有進來
另開一個 Ubuntu 終端機分頁、跑：
tail -f ~/.hermes/logs/gateway.log傳訊時 log 應該會即時跑出新行，類似「Received message from user 12345」之類。
🚨 傳了訊息但 bot 沒回
看 ~/.hermes/logs/gateway.log，三類最常見：
- log 顯示 unauthorized user → user_id 寫錯。回 Step 4 用 sed 補救改
TELEGRAM_ALLOWED_USERS=，hermes gateway restart。 - log 完全沒新訊息 → bot username 找錯了（你連到的是別人的 bot）。回 BotFather 用
/mybots確認你 bot 的 username 跟你 Telegram 對話畫面的 @ 一致。 - log 有訊息進來、但回應 timeout / API error → OpenRouter 那邊的問題，看 log 有沒有 401（key 過期 / 額度不足）或 5xx（暫時故障）。
🚨 Telegram 完全找不到我的 bot
- 確認 bot username 沒打錯（含
@） - 用瀏覽器開
https://t.me/<your_bot_username>直接連 - 還不行 → 回 BotFather
/mybots，看你 bot 是不是被 BotFather 自動 disable 了（極少見）
✓ 傳訊有回 + context 對得上 → 4 個 checkpoints 完成，進 Step 7 收尾。
Step 7 / 7 · 完成 + 加碼 + 下一步
~5 分鐘
恭喜，4 個 checkpoints 都完成：
- ✓ Telegram bot 已申請、token 在手
- ✓ user_id 已寫進 hermes allowlist
- ✓
hermes gateway在背景跑著 - ✓ 至少一次「手機 → bot → hermes 回覆」完成
日常常用指令速查
📱 Telegram 對話指令
| 指令 | 說明 |
|---|---|
/new | 清掉目前 context，開全新對話（切話題必用） |
/title 名稱 | 幫目前 session 取名，方便之後找回來 |
/resume 名稱 | 找回某個舊 session，繼續對話 |
/sessions | 列出所有 session 名稱 |
/usage | 查本次 session 的 token 用量與費用估算 |
/model | 查目前使用的模型 |
/model provider:model | 切換模型，例如 /model openrouter:deepseek/deepseek-r1-distill-llama-70b:free |
/help | 列出所有可用指令 |
🖥 Terminal：Gateway 管理
| 指令 | 說明 |
|---|---|
sudo $(which hermes) gateway status --system | 查 gateway 是否在跑 |
sudo $(which hermes) gateway restart --system | 重啟 gateway（改設定後必跑） |
sudo $(which hermes) gateway stop --system | 停掉 gateway |
sudo $(which hermes) gateway start --system | 啟動 gateway |
tail -f ~/.hermes/logs/gateway.log | 即時看 gateway log（Ctrl+C 退出） |
🔧 Terminal：hermes CLI 常用
| 指令 | 說明 |
|---|---|
hermes model | 新增 / 管理 AI provider 與 API key |
hermes gateway setup | 重新設定 gateway（換 token 或新增 channel） |
hermes --version | 查目前 hermes 版本 |
npm update -g @nousresearch/hermes | 升級 hermes 到最新版 |
建議下一步
- Gateway 已裝成 System service，Windows 重啟後會自動跑，不需要手動重啟
- 把這個頁面加書籤，下次想複習隨時回來
加碼 1：把 bot 加到 Telegram 群組
讓多人都能跟同一支 hermes 講話：
- Telegram 開群組 → 加成員 → 搜你 bot 的 username → 加入
- BotFather
/mybots→ 選你的 bot →Bot Settings→Group Privacy→Disable（這樣 bot 才看得到群組裡所有訊息，而不是只 @ 它的） - 群組裡每個要用 bot 的人都要把自己 user_id 加進
TELEGRAM_ALLOWED_USERS=，逗號分隔。改完hermes gateway restart。
加碼 2：傳語音訊息
hermes gateway 預設會把語音訊息自動轉文字再丟給模型——直接按 Telegram 對話框右下角的麥克風講就好，不用 /voice 之類指令。
轉字準確度看你 OpenRouter 帳號用什麼底層 ASR 模型。中文識別偶爾會不準，講慢一點會比較穩。
加碼 3：/new + /title 管理對話
傳 /new → 清掉目前 context，開全新對話（適合切話題、避免歷史污染）。
傳 /title 旅遊 → 給目前 session 一個名字；之後用 /resume 旅遊 找回，/sessions 列出所有已命名的 session。
傳 /usage → 看本次 session 用了多少 token、估算花了多少錢。
更多指令參考上方「日常常用指令速查」表。
加碼 4：/model 中途切模型
傳 /model（不帶參數）→ 看目前模型。傳 /model openrouter:deepseek/deepseek-r1-distill-llama-70b:free 或 /model anthropic:claude-sonnet-4 → 切到那個模型。語法是 /model provider:model。
費用敏感的話，預設用 OpenRouter free model、特定問題切貴的。
注意：只能切已經設定過的 provider。要新增 provider 請退出 chat、在 terminal 跑 hermes model 設定。
加碼 5：管理 gateway 服務
更多指令請參考上方「日常常用指令速查」的 Terminal 區塊。快速複製用：
sudo $(which hermes) gateway status --systemsudo $(which hermes) gateway restart --systemsudo $(which hermes) gateway stop --system下次預告
- Lesson 3 · hermes 日常使用入門：context 管理、skills、cron、background sessions 完整介紹
- Lesson 4 · LINE gateway 設定：把同一支 hermes 也接到 LINE，讓 LINE 朋友也能用（已上線）
到這邊就是 Lesson 2 的全部內容。下次見。