H繁中版
文件user-guideline
<!-- Source: https://hermesbible.com/docs/user-guide/messaging/line -->

Section: 訊息平台 · URL: https://hermesbible.com/docs/user-guide/messaging/line

LINE 設定

透過官方 LINE Messaging API，將 Hermes Agent 作為 LINE 機器人運行。適配器作為內建平台外掛程式位於 plugins/platforms/line/ 目錄下——無需修改核心程式碼，只需像其他平台一樣啟用即可。

LINE 是日本、台灣和泰國最主流的訊息應用程式。如果您的用戶在這些地區，LINE 就是他們聯繫您的管道。

執行 hermes gateway setup 並選擇 LINE 即可獲得引導式設定流程。

機器人的回應方式

情境行為
一對一聊天（U 開頭的 ID）回覆每則訊息
群組聊天（C 開頭的 ID）當群組在允許清單中時回覆
多用戶聊天室（R 開頭的 ID）當聊天室在允許清單中時回覆

支援接收的文字、圖片、音訊、影片、檔案、貼圖和位置資訊。傳送文字時，會優先使用免費回覆權杖（單次使用，約 60 秒有效期），當權杖過期後才會回退到計費的 Push API。

步驟一：建立 LINE Messaging API 頻道

  1. 前往 LINE Developers Console。
  2. 建立一個 Provider，然後在其下建立一個 Messaging API 頻道。
  3. 在頻道的基本設定分頁中，複製 Channel secret。
  4. 在 Messaging API 分頁中，找到 Channel access token（長期有效） 並點擊 Issue。複製該權杖。
  5. 在 Messaging API 分頁中，同時關閉自動回覆訊息和歡迎訊息，以免它們與您的機器人回覆衝突。

步驟二：暴露 Webhook 連接埠

LINE 透過公開的 HTTPS 傳送 Webhook。預設連接埠為 8646——如需變更，可透過 LINE_PORT 覆蓋。

# Cloudflare Tunnel（建議用於生產環境——固定主機名稱）
cloudflared tunnel --url http://localhost:8646

# ngrok（適合開發環境）
ngrok http 8646

# devtunnel
devtunnel create hermes-line --allow-anonymous
devtunnel port create hermes-line -p 8646 --protocol https
devtunnel host hermes-line

複製 https://... 網址——您將在下方將其設定為 Webhook URL。測試期間請保持隧道運行。在生產環境中，請設定固定的 Cloudflare 名稱隧道，以確保 Webhook URL 不會在重啟後變更。

步驟三：設定 Hermes

在 ~/.hermes/.env 中加入以下內容：

LINE_CHANNEL_ACCESS_TOKEN=YOUR_LONG_LIVED_TOKEN
LINE_CHANNEL_SECRET=YOUR_CHANNEL_SECRET

# 允許清單——至少需要設定其中一項（開發環境可設定 LINE_ALLOW_ALL_USERS=true）
LINE_ALLOWED_USERS=U1234567890abcdef...           # 以逗號分隔、U 開頭的用戶 ID
LINE_ALLOWED_GROUPS=C1234567890abcdef...          # 選填的群組 ID
LINE_ALLOWED_ROOMS=R1234567890abcdef...           # 選填的聊天室 ID

# 發送圖片/音訊/影片時必須設定——即隧道解析到的公開 HTTPS 基礎網址
# 若未設定，send_image/voice/video 將無法運作
LINE_PUBLIC_URL=https://my-tunnel.example.com

然後在 ~/.hermes/config.yaml 中加入：

gateway:
  platforms:
    line:
      enabled: true

這樣就足夠了——gateway/config.py 中的內建外掛程式掃描會自動偵測到 plugins/platforms/line/。無需修改 Platform.LINE 列舉，也無需註冊 _create_adapter。

步驟四：設定 Webhook URL

回到 LINE 開發者控制台：

  1. 開啟您的頻道 → Messaging API 分頁。
  2. 在 Webhook 設定 → Webhook URL 中，貼上 https://<your-tunnel>/line/webhook（注意 /line/webhook 路徑——適配器在此監聽）。
  3. 點擊 Verify。LINE 會向該網址發送 ping 檢查；您應該會看到回應狀態碼 200。
  4. 將 Use webhook 切換為 On。

步驟五：啟動 Gateway

hermes gateway

代理日誌將顯示：

LINE: webhook listening on 0.0.0.0:8646/line/webhook (public: https://my-tunnel.example.com)

從 LINE 應用程式中將機器人加為好友（掃描頻道 Messaging API 分頁中的 QR Code），然後向它發送訊息。

LLM 回應過慢

LINE 的回覆權杖是單次使用的，且在收到訊息事件後約 60 秒即過期。較慢的 LLM 無法及時回覆，這通常會導致強制使用付費的 Push API。

當 LLM 執行時間超過 LINE_SLOW_RESPONSE_THRESHOLD 秒（預設值為 45）時，適配器會消耗原始回覆權杖來傳送一個互動按鈕氣泡：

🤔 還在思考中。準備就緒後點擊下方取得答案。

[ 取得答案 ]

用戶可在方便時點擊取得答案——該回傳動作會提供一個全新的回覆權杖，適配器利用它來傳送已快取的答案（仍然是免費的）。

狀態機：PENDING → READY → DELIVERED，另有 ERROR 用於已取消的執行（在 /stop 之後，孤立的 PENDING 狀態會解析為「執行已被中斷。」，以避免持久性按鈕產生迴圈）。

若要停用回傳按鈕，並始終使用 Push 回退：

LINE_SLOW_RESPONSE_THRESHOLD=0

為了讓回傳流程可靠觸發，需要抑制會消耗回覆權杖的非必要訊息：

# ~/.hermes/config.yaml
display:
  interim_assistant_messages: false
  platforms:
    line:
      tool_progress: off

定時任務 / 通知推送

LINE_HOME_CHANNEL=Uxxxxxxxxxxxxxxxxxxxx     # 預設推送目標

設定 deliver: line 的定時任務會路由至 LINE_HOME_CHANNEL。適配器內建了獨立的 Push 專用發送器，因此即使定時任務在與 Gateway 不同的進程中執行也能正常運作。

環境變數參考

變數是否必填預設值說明
LINE_CHANNEL_ACCESS_TOKEN是—長期有效的頻道存取權杖
LINE_CHANNEL_SECRET是—頻道密鑰（用於 HMAC-SHA256 Webhook 驗證）
line_host否0.0.0.0Webbook 綁定的主機位址
LINE_PORT否8646Webhook 綁定的連接埠
LINE_PUBLIC_URL發送媒體時必填—公開 HTTPS 基礎網址；發送圖片/音訊/影片時必須設定
LINE_ALLOWED_USERS至少一項—以逗號分隔的用戶 ID（U 開頭）
LINE_ALLOWED_GROUPS至少一項—以逗號分隔的群組 ID（C 開頭）
LINE_ALLOWED_ROOMS至少一項—以逗號分隔的聊天室 ID（R 開頭）
LINE_ALLOW_ALL_USERS僅限開發環境false完全跳過允許清單
LINE_HOME_CHANNEL否—預設定時任務/通知的推送目標
LINE_SLOW_RESPONSE_THRESHOLD否45觸發回傳按鈕前的等待秒數（0 表示停用）
LINE_PENDING_TEXT否"🤔 還在思考中…"與回傳按鈕一起顯示的氣泡文字
LINE_BUTTON_LABEL否"取得答案"按鈕標籤文字
LINE_DELIVERED_TEXT否"已回覆 ✅"當已被送達的按鈕被再次點擊時的回覆文字
LINE_INTERRUPTED_TEXT否"執行已被中斷。"當 /stop 孤立按鈕被點擊時的回覆文字

疑難排解

Webhook 驗證時出現 "invalid signature"。 Channel secret 複製錯誤，或您的隧道改寫了請求內容。請先使用 curl -i https://<tunnel>/line/webhook/health 進行驗證——該端點應回傳 {"status":"ok","platform":"line"}。

機器人在群組中收不到任何訊息。 請檢查 LINE_ALLOWED_GROUPS 是否包含 C... 開頭的群組 ID。若要取得群組 ID，可發送一則測試訊息，然後在 ~/.hermes/logs/gateway.log 中搜尋 LINE: rejecting unauthorized source——被拒絕的來源字典中會包含相關 ID。

send_image 報錯 "LINE_PUBLIC_URL must be set"。 LINE 的 Messaging API 不接受二進位上傳——圖片、音訊和影片必須是可透過 HTTPS 存取的網址。請將 LINE_PUBLIC_URL 設定為隧道的公開主機名稱，適配器會自動從 /line/media/<token>/<filename> 提供檔案。

回傳按鈕從未出現。 可能是 LLM 回應速度快於 LINE_SLOW_RESPONSE_THRESHOLD，或者另一個氣泡（工具進度、串流訊息）先消耗了回覆權杖。請參閱「LLM 回應過慢」章節中的抑制設定。

"already in use by another profile"。 同一個頻道存取權杖已綁定到另一個正在運行的 Hermes 設定檔。請停止另一個 Gateway 或使用不同的頻道。

限制

  • 氣泡與長度上限。 每個 LINE 文字氣泡上限為 5000 字元。較長的回應會在約 4500 字元處智慧分段，每次 Reply/Push 呼叫最多分為 5 個氣泡，盡可能在自然斷點處分割。
  • 不支援原生訊息編輯。 LINE 沒有訊息編輯 API——串流回應始終傳送新的氣泡，不會編輯先前的氣泡。
  • 不支援 Markdown 渲染。 粗體（**）、斜體（*）、程式碼區塊和標題會以純文字字元顯示。適配器會在傳送前將其移除；網址會被保留（[label](url) 會轉換為 label (url)）。
  • 載入指示器僅限一對一聊天。 LINE 拒絕群組和聊天室的聊天/載入 API，因此輸入指示器僅在一對一聊天中顯示。

Microsoft Graph Webhook Listener

indexmatrix