Lesson 4 · LINE 整合

Lesson 2 你已經把 hermes 接到 Telegram，從手機就能對話。為什麼還要再接 LINE？兩個理由：

• LINE 是台 / 港學員每天最常用的 messenger，比 Telegram 親民，朋友家人都已經在裡面；
• 接 LINE 後 hermes 真正變「隨身助手」——通勤、會議、走路時都能丟訊息給它處理。

Lesson 2 跟本堂的差別：LINE 強制要求公開 webhook URL（不像 Telegram 可以長 polling），所以多一層 ngrok 概念——把本機 hermes 暴露給 LINE 雲端。學完本堂你會懂 ngrok 怎麼用，未來想接任何 webhook 平台都用得到。

結束時你會有

1. ✓ 一支自己的 LINE bot 已加為好友、能用手機送訊息給它
2. ✓ ngrok tunnel 跑在背景（前景版；24/7 守護是加碼預告）
3. ✓ hermes gateway 跑著，會即時把 LINE 訊息 dispatch 給 LLM
4. ✓ 知道 LINE 四大 quirks（Markdown 不 render / 雙 send / reply token TTL / ngrok URL 重啟會換），不會誤以為 bot 壞了

動工前先確認 4 件事到位。

前置 checklist

• ✓ Lesson 1 完成：hermes CLI 能對話。沒做過？先去 Lesson 1。
• ✓ Lesson 2 完成：Telegram bot 端到端可用，已熟悉 ~/.hermes/.env 與 hermes gateway 概念。沒做過？先去 Lesson 2。
• ✓ 手機 LINE app 已登入個人帳號（或一個還沒用過的測試帳號，避免跟個人 ID 撞）。
• ✓ WSL / Linux shell 同一個（跟 Lesson 1 / 2 用的）。

動工前升級 hermes 到最新版

LINE plugin 的必要 fix 在較新 release 才完整收錄。動工前先升級到最新版：

npm update -g @nousresearch/hermes && hermes --version

看到新版本號顯示就過了，繼續往下看。

這 7 步在做什麼

1. Step 2：到 LINE Developers Console 申請 bot，拿到 Channel Access Token + Channel Secret（外連既有教學）
2. Step 3：裝 ngrok 並設 authtoken（讓 LINE webhook 能從 internet 打進本機 hermes）
3. Step 4：開 ngrok tunnel、把 LINE 相關變數寫進 ~/.hermes/.env
4. Step 5：回 LINE Console 填 webhook URL + 設 5 個 toggles
5. Step 6：啟動 hermes gateway、手機送訊息驗證、抓自己 LINE User ID 收緊 allowlist
6. Step 7：收尾 + LINE quirks 警告 + 進階預告

LINE Developers Console 的 bot 申請流程已有完整中文外部教材，照著做就好：

→ 開啟 LINE Bot 申請教材

結束時你應該有

• Channel Access Token（長 ~170 字元的 base64 字串）
• Channel Secret（32 hex 字元）
• Bot basic ID（@ 開頭，例：@123abcde）— 在 LINE Console → Messaging API 分頁的 Bot information 區塊可看到

✓ token 跟 secret 都暫存到記事本，接著 Step 3 裝 ngrok。

ngrok 是把 LINE 雲端送來的 webhook 訊息轉發到你本機 hermes 的橋樑。LINE 不接受 localhost 或內網 IP，必須公開 HTTPS URL，ngrok free tier 適合學員入門。

動作

1. 裝 ngrok（aarch64 / amd64 都用同一個 apt repo）

curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
  | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null \
  && echo "deb https://ngrok-agent.s3.amazonaws.com bookworm main" \
  | sudo tee /etc/apt/sources.list.d/ngrok.list \
  && sudo apt update && sudo apt install ngrok

裝完驗證：

ngrok version

預期：ngrok version 3.x.x

2. 註冊 ngrok 帳號

瀏覽器開 https://dashboard.ngrok.com/signup → 用 GitHub 或 Google OAuth 註冊（最快）→ 進 Dashboard。

3. 取 authtoken

Dashboard sidebar → Your Authtoken → 複製顯示的字串。

4. 設定 authtoken

把剛複製的 authtoken 貼到下面命令的 <your-authtoken> 位置（含 <> 一起換掉），執行：

ngrok config add-authtoken <your-authtoken>

預期輸出：

Authtoken saved to configuration file: ~/.config/ngrok/ngrok.yml

✓ ngrok version 報 3.x、~/.config/ngrok/ngrok.yml 已存。接著 Step 4 開 tunnel。

三件事：(1) 第二個 shell 跑 ngrok 抓 public URL、(2) 編輯 ~/.hermes/.env 加 LINE 區塊、(3) redacted verify 確認都填對沒漏字元（不直接 cat .env，避免 secret 暴露）。

1. 第二個 shell（Window B）跑 ngrok

開新的 Windows Terminal 分頁（Ctrl+Shift+T）進 WSL，跑：

ngrok http 8646

ngrok 終端機 panel 出現後，看 Forwarding 那行的 URL（類似 https://abcd-12-34-56-78.ngrok-free.app），完整含 https:// 一起抄，下一步要用。

Session Status                online
Account                       your-email@example.com (Plan: Free)
Version                       3.x.x
Region                        Asia Pacific (ap)
Forwarding                    https://abcd-12-34-56-78.ngrok-free.app -> http://localhost:8646
Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

2. 回 Window A 編輯 .env

回到 Lesson 1/2 用的 shell（Window A），打開 ~/.hermes/.env：

nano ~/.hermes/.env

nano 編輯器開啟後，捲到檔尾（Ctrl+End 或一直按 ↓），手動 append 以下區塊。注意 hermes .env 預設沒有 LINE 區塊，要自己加：

# =============================================================================
# LINE INTEGRATION
# =============================================================================
LINE_CHANNEL_ACCESS_TOKEN=<貼 Step 2 拿到的 token>
LINE_CHANNEL_SECRET=<貼 Step 2 拿到的 secret>
LINE_PUBLIC_URL=<貼上面 ngrok 那條 URL>
LINE_ALLOWED_USERS=
LINE_ALLOW_ALL_USERS=true

三個 <占位符> 都要連 <> 一起換掉。完成後 Ctrl+O 存檔 → Enter 確認 → Ctrl+X 退出。

3. Redacted verify（不要 cat .env）

直接 cat 會把 token 噴到螢幕。改用下面這條 awk 只看「變數名 + 值的長度」：

awk -F= '/^LINE_/{print $1, "len="length($2)}' ~/.hermes/.env

預期輸出（長度可能略有出入，重點是 ratio 對得上）：

LINE_CHANNEL_ACCESS_TOKEN len=170
LINE_CHANNEL_SECRET len=32
LINE_PUBLIC_URL len=40
LINE_ALLOWED_USERS len=0
LINE_ALLOW_ALL_USERS len=4

判讀：

• LINE_CHANNEL_ACCESS_TOKEN len=170（或 ~160-180）→ token 對 ✓
• LINE_CHANNEL_SECRET len=32 → secret 對 ✓（hex 32 字元 = 16 bytes）
• LINE_PUBLIC_URL len=40（前後可能差 5-10）→ ngrok URL 對 ✓
• LINE_ALLOWED_USERS len=0 → 空字串，Step 6 收緊 ✓
• LINE_ALLOW_ALL_USERS len=4 → 字面 "true" ✓

補救：用 sed 直接改 .env（同 Lesson 1 / 2 paste 雷的解法）

跟 Lesson 1 Step 7 同根因（hermes .env 編輯 paste 雷），同模式。兩個 variant 擇一：

Variant A · 互動腳本（推薦）

三個值都會用 read -p 個別問：token / secret 不回顯（避免肩膀後面被看到），URL 回顯（純文字無妨）：

cd ~/.hermes && read -sp "Paste LINE Channel Access Token: " TOKEN && echo && read -sp "Paste LINE Channel Secret: " SECRET && echo && read -p "Paste ngrok HTTPS URL: " PUBURL && { grep -q '^LINE_CHANNEL_ACCESS_TOKEN=' .env || echo 'LINE_CHANNEL_ACCESS_TOKEN=' >> .env; grep -q '^LINE_CHANNEL_SECRET=' .env || echo 'LINE_CHANNEL_SECRET=' >> .env; grep -q '^LINE_PUBLIC_URL=' .env || echo 'LINE_PUBLIC_URL=' >> .env; grep -q '^LINE_ALLOWED_USERS=' .env || echo 'LINE_ALLOWED_USERS=' >> .env; grep -q '^LINE_ALLOW_ALL_USERS=' .env || echo 'LINE_ALLOW_ALL_USERS=true' >> .env; } && sed -i "s|^LINE_CHANNEL_ACCESS_TOKEN=.*|LINE_CHANNEL_ACCESS_TOKEN=$TOKEN|" .env && sed -i "s|^LINE_CHANNEL_SECRET=.*|LINE_CHANNEL_SECRET=$SECRET|" .env && sed -i "s|^LINE_PUBLIC_URL=.*|LINE_PUBLIC_URL=$PUBURL|" .env && unset TOKEN SECRET PUBURL

跑完後再執行上方的 redacted verify 命令確認長度。

Variant B · 手動範本

把 YOUR_TOKEN / YOUR_SECRET / YOUR_NGROK_URL 三個占位字串替換成實際值再貼進終端機（這次不用連 <>，因為原字串就沒有）：

cd ~/.hermes && { grep -q '^LINE_CHANNEL_ACCESS_TOKEN=' .env || echo 'LINE_CHANNEL_ACCESS_TOKEN=' >> .env; grep -q '^LINE_CHANNEL_SECRET=' .env || echo 'LINE_CHANNEL_SECRET=' >> .env; grep -q '^LINE_PUBLIC_URL=' .env || echo 'LINE_PUBLIC_URL=' >> .env; grep -q '^LINE_ALLOWED_USERS=' .env || echo 'LINE_ALLOWED_USERS=' >> .env; grep -q '^LINE_ALLOW_ALL_USERS=' .env || echo 'LINE_ALLOW_ALL_USERS=true' >> .env; } && sed -i 's|^LINE_CHANNEL_ACCESS_TOKEN=.*|LINE_CHANNEL_ACCESS_TOKEN=YOUR_TOKEN|' .env && sed -i 's|^LINE_CHANNEL_SECRET=.*|LINE_CHANNEL_SECRET=YOUR_SECRET|' .env && sed -i 's|^LINE_PUBLIC_URL=.*|LINE_PUBLIC_URL=YOUR_NGROK_URL|' .env

跑完任一個之後，再跑 awk redacted verify 確認長度合理。接著 Step 5 回 LINE Console 設 webhook。

外部教材 Step 6（Bot 回應方式）我們剛剛跳過了，現在 ngrok URL 在手，回去把它填完。

1. 進 channel 的 Messaging API 分頁

瀏覽器開 https://developers.line.biz/console/ → 你的 Provider → 你的 channel → 點 Messaging API 分頁。

2. 設 Webhook URL

在 Webhook settings section：

1. Webhook URL 欄填：<ngrok URL>/line/webhook
   • 例：https://abcd-12-34-56-78.ngrok-free.app/line/webhook
   • 結尾必須是 /line/webhook，不要漏 path。沒這個 path hermes 收不到（其他 path 是給別的 platform 用）。
2. 按 Update（或 更新）儲存

3. 5 個 Toggles 對照表

同樣在 Messaging API 分頁，下半部有 5 個 toggle，外部教材只教前 3 個；後 2 個是本課新增，學員容易漏。

✓ webhook URL 已存、5 個 toggle 已設。Verify 按鈕下一步啟動 gateway 後再回來按。

串起所有東西的關鍵步驟：(1) 跑 gateway、(2) LINE Console 按 Verify、(3) 手機加好友送訊息、(4) 從 log 抓自己 U-ID、(5) 收緊 allowlist、(6) 重啟驗證。

1. 第三個 shell（Window C）啟動 gateway

開另一個 Windows Terminal 分頁進 WSL（這是 Window C，與 Window A 編輯用、Window B 跑 ngrok 並列），執行：

hermes gateway run

預期看到啟動 banner，含關鍵字（任何一個 traceback 都先停下查 log）：

• ✓ line connected
• Gateway running with 1 platform(s)
• Secret redaction: ENABLED

2. 回 LINE Console 按 Verify

切回瀏覽器 LINE Console → Messaging API 分頁 → Webhook URL 旁邊的 Verify 按鈕，點下去。

預期：✅ Success

失敗對策：

• "Status 4xx" → webhook URL 路徑漏 /line/webhook，回 Step 5 補
• "Signature mismatch" → Channel Secret 抄錯，回 Step 4 redacted verify 確認 LINE_CHANNEL_SECRET len=32
• "Timeout" → Window B 的 ngrok 斷了；切到 Window B 看 panel 還在不在；若已斷，Ctrl+C 再重跑 ngrok http 8646，注意新 URL 跟舊的不同，回 Step 4 用 sed 補救改 LINE_PUBLIC_URL，然後 LINE Console 也要把 webhook URL 改成新的

3. 手機 LINE 加 bot 為好友 → 送第一則訊息

加好友兩條路徑：

• 掃 LINE Console → Messaging API 分頁 → QR code（最快）
• 或 LINE app 搜尋 Step 2 拿到的 Bot basic ID（@xxxxxx）

加好友成功後，送一句測試：

測試

4. 看 Window C 的 gateway log，抓你的 U-ID

切回 Window C，會看到類似輸出：

inbound message: platform=line user=U0123456789abcdef0123456789abcdef chat=U0123456789abcdef0123456789abcdef msg='測試'
response ready: platform=line chat=U0123456789abcdef0123456789abcdef time=5.x s api_calls=1 response=N chars
[Line] Sending response (N chars) to U0123456789abcdef0123456789abcdef

抓那段 U + 32 hex 字元（總長 33 字元的 user ID），等下要寫進 allowlist。

5. 手機 LINE 確認收到 bot 回應

• ✅ 收到回應 → 鏈路通了！
• ❌ 沒收到但 log 顯示 Send 成功 → 手機 LINE 設定有擋（極少見），先擱著
• ❌ log 完全沒看到 inbound → Verify 沒過 / ngrok URL 對不上 / hermes 沒接到 platform line，回 Step 5 / 6 上方檢查

6. 收緊 LINE_ALLOWED_USERS 為單一 U-ID

現在 LINE_ALLOW_ALL_USERS=true，bot 是公開的，任何加好友的人都會用你的 OpenRouter 額度。馬上收緊：

cd ~/.hermes && read -p "Paste your LINE User ID (U<32-hex>): " USER_ID && sed -i "s|^LINE_ALLOWED_USERS=.*|LINE_ALLOWED_USERS=$USER_ID|" .env && sed -i 's|^LINE_ALLOW_ALL_USERS=.*|LINE_ALLOW_ALL_USERS=false|' .env && grep -E '^LINE_(ALLOWED_USERS|ALLOW_ALL_USERS)' .env && unset USER_ID

跑完預期輸出（USER_ID 那段會是你剛貼的值）：

LINE_ALLOWED_USERS=U0123456789abcdef0123456789abcdef
LINE_ALLOW_ALL_USERS=false

7. 重啟 gateway，驗證收緊有效

切到 Window C，Ctrl+C 殺掉 gateway。再跑：

hermes gateway run

啟動 banner 同前。再回手機 LINE 送一句訊息：

測試 2

預期：自己仍能收到 bot 回應 ✅。代表 allowlist 收緊但你自己沒被擋掉。

✓ Verify 過、手機通、allowlist 收緊。最後 Step 7 收尾。

你做到了

1. ✓ 一個跑著的 LINE bot（手機 LINE → ngrok → hermes → OpenRouter）
2. ✓ 自己 LINE User ID 已寫進 allowlist、別人不能用你 OpenRouter 額度
3. ✓ 學到 redacted-verify 命令模式（awk 看長度、不噴 secret）
4. ✓ 學會 ngrok tunnel（任何未來要接的 webhook 平台都用得到）

⚠️ LINE quirks 必須知道（避免之後誤判 bot 壞了）

下次預告

下次（Lesson 5 暫定 / 未排）可能會涵蓋：

• LINE Rich Menu 客製化按鈕
• 多 platform 同跑（Telegram + LINE 同支 hermes）
• 或你想學什麼下次告訴我

hermes gateway status

hermes gateway restart

hermes gateway stop

tail -f ~/.hermes/logs/gateway.log

到這邊就是 Lesson 4 全部內容。下次見。