LINE 設置

通過官方 LINE Messaging API 將 Hermes Agent 作為 LINE 機器人運行。該適配器以捆綁平臺插件的形式位於 plugins/platforms/line/ 下——無需修改核心代碼，只需像啟用其他平臺一樣啟用它即可。

LINE 是日本、臺灣和泰國占主導地位的即時通訊應用。如果您的用戶位於這些地區，這是他們聯繫您的方式。

運行 hermes gateway setup 並選擇 LINE 以獲取引導式 walkthrough。

機器人如何響應

上下文	行為
1:1 聊天（`U` ID）	響應每條消息
群聊（`C` ID）	當群組在允許列表中時響應
多用戶房間（`R` ID）	當房間在允許列表中時響應

入站的文本、圖片、音頻、視頻、文件、貼紙和位置信息均會被處理。出站文本優先使用免費回覆令牌（單次使用，約 60 秒窗口期），當令牌過期後，則回退到計費的 Push API。

步驟 1：創建 LINE Messaging API 渠道

前往 LINE Developers Console。
創建一個 Provider，然後在其下創建一個 Messaging API 渠道。
從渠道的 Basic settings 選項卡中，複製 Channel secret。
從 Messaging API 選項卡中，滾動到 Channel access token (long-lived) 並點擊 Issue。複製該令牌。
在 Messaging API 選項卡中，禁用 Auto-reply messages 和 Greeting messages，以免它們與機器人的回覆衝突。

步驟 2：暴露 Webhook 端口

LINE 通過公共 HTTPS 交付 Webhook。默認端口為 8646——如有需要，可使用 LINE_PORT 進行覆蓋。

# Cloudflare Tunnel (recommended for production — fixed hostname)
cloudflared tunnel --url http://localhost:8646

# ngrok (good for dev)
ngrok http 8646

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

複製 https://... URL——您將在下面將其設置為 Webhook URL。在測試期間保持隧道運行。對於生產環境，請設置固定的 Cloudflare 命名隧道，以便 Webhook URL 在重啟時不會更改。

步驟 3：配置 Hermes

添加到 ~/.hermes/.env：

LINE_CHANNEL_ACCESS_TOKEN=YOUR_LONG_LIVED_TOKEN
LINE_CHANNEL_SECRET=YOUR_CHANNEL_SECRET

# Allowlist — at least one of these (or LINE_ALLOW_ALL_USERS=true for dev)
LINE_ALLOWED_USERS=U1234567890abcdef...           # comma-separated U-prefixed IDs
LINE_ALLOWED_GROUPS=C1234567890abcdef...          # optional group IDs
LINE_ALLOWED_ROOMS=R1234567890abcdef...           # optional room IDs

# Required for image / audio / video sends — the public HTTPS base URL
# the tunnel resolves to.  Without it, send_image/voice/video will refuse.
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。

步驟 4：設置 Webhook URL

回到 LINE 控制檯：

打開您的渠道 → Messaging API 選項卡。
在 Webhook settings → Webhook URL 下，粘貼 https://<your-tunnel>/line/webhook（注意 /line/webhook 路徑——適配器在此處監聽）。
點擊 Verify。LINE 會 ping 該 URL；您應該看到狀態碼 200。
將 Use webhook 切換為 On。

步驟 5：運行網關

hermes gateway

代理日誌顯示：

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

從 LINE 應用添加機器人為好友（掃描渠道 Messaging API 選項卡中的二維碼）並向其發送消息。

LLM 響應緩慢

LINE 的回覆令牌是單次使用的，並在入站事件發生後約 60 秒過期。緩慢的 LLM 無法及時回覆，這通常會導致強制調用付費的 Push API。

當 LLM 運行時間超過 LINE_SLOW_RESPONSE_THRESHOLD 秒（默認 45）時，適配器會使用原始回覆令牌發送一個 Template Buttons 氣泡：

🤔 仍在思考。點擊下方以便在答案准備好時獲取。

[ 獲取答案 ]

用戶在方便時點擊 獲取答案——該 postback 會提供一個新的回覆令牌，適配器使用該令牌發送緩存的答案（仍然免費）。

狀態機：PENDING → READY → DELIVERED，以及用於取消運行的 ERROR（孤立的 PENDING 狀態在 /stop 後會解析為“Run was interrupted before completion.”，以防止持久按鈕陷入循環）。

要禁用 postback 按鈕並始終回退到 Push：

LINE_SLOW_RESPONSE_THRESHOLD=0

為了使 postback 流程可靠觸發，請抑制那些會在達到閾值前消耗回覆令牌的閒聊：

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

Cron / 通知交付

LINE_HOME_CHANNEL=Uxxxxxxxxxxxxxxxxxxxx     # default delivery target

帶有 deliver: line 的 Cron 任務會路由到 LINE_HOME_CHANNEL。該適配器附帶一個獨立的僅 Push 發送器，因此即使 Cron 在與網關不同的進程中運行，Cron 任務也能正常工作。

環境變量參考

變量	是否必需	默認值	描述
`LINE_CHANNEL_ACCESS_TOKEN`	是	—	長期有效的頻道訪問令牌
`LINE_CHANNEL_SECRET`	是	—	頻道密鑰（用於 HMAC-SHA256 Webhook 驗證）
`LINE_HOST`	否	`0.0.0.0`	Webhook 綁定主機
`LINE_PORT`	否	`8646`	Webhook 綁定端口
`LINE_PUBLIC_URL`	媒體發送必需	—	公共 HTTPS 基礎 URL；發送圖片/語音/視頻時必需
`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`	否	"🤔 Still thinking…"	與回傳按鈕一同顯示的氣泡文本
`LINE_BUTTON_LABEL`	否	"Get answer"	按鈕標籤
`LINE_DELIVERED_TEXT`	否	"Already replied ✅"	再次點擊已投遞按鈕時的回覆
`LINE_INTERRUPTED_TEXT`	否	"Run was interrupted before completion."	點擊孤立的 `/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 中 grep 搜索 LINE: rejecting unauthorized source——被拒絕的來源字典中包含這些 ID。

send_image 失敗並提示 "LINE_PUBLIC_URL must be set"。 LINE 的 Messaging API 不接受二進制上傳——圖片、音頻和視頻必須是可訪問的 HTTPS URL。將 LINE_PUBLIC_URL 設置為隧道的公共主機名，適配器將自動從 /line/media/<token>/<filename> 提供文件服務。

回傳按鈕從未出現。 要麼 LLM 響應速度快於 LINE_SLOW_RESPONSE_THRESHOLD，要麼另一個氣泡（工具進度、流式傳輸）先消耗了回覆令牌。請參閱“LLM 響應緩慢”下的抑制塊說明。

"already in use by another profile"。 相同的頻道訪問令牌已綁定到另一個正在運行的 Hermes 配置。停止另一個網關或使用單獨的頻道。

限制

氣泡和長度上限。 每個 LINE 文本氣泡上限為 5000 個字符。較長的響應會在每次 Reply/Push 調用中智能分塊為約 4500 個字符，最多分為 5 個氣泡，並儘可能在自然邊界處分割。
不支持原生消息編輯。 LINE 沒有編輯消息 API——流式響應始終發送新的氣泡，從不編輯之前的氣泡。
不支持 Markdown 渲染。 粗體（**）、斜體（*）、代碼塊和標題會呈現為字面字符。適配器在發送前會去除這些格式；URL 會被保留（[label](url) 變為 label (url)）。
加載指示器僅限私聊。 LINE 拒絕群組和聊天室的聊天/加載 API，因此打字指示器僅在 1:1 私聊中顯示。

機器人如何響應​

步驟 1：創建 LINE Messaging API 渠道​

步驟 2：暴露 Webhook 端口​

步驟 3：配置 Hermes​

步驟 4：設置 Webhook URL​

步驟 5：運行網關​

LLM 響應緩慢​

Cron / 通知交付​

環境變量參考​

故障排除​

限制​