LINE 配置指南

将 Hermes Agent 作为 LINE 机器人运行，基于官方 LINE Messaging API。适配器以 bundled 平台插件形式存在于 plugins/platforms/line/ 目录下——无需修改核心代码，像其他平台一样启用即可。

LINE 是日本、台湾和泰国主流的消息应用。如果你的用户在这些地区，这是他们联系你的方式。

机器人响应规则

场景	行为
一对一聊天（`U` 开头的 ID）	回复每条消息
群聊（`C` 开头的 ID）	仅当群组在白名单中时回复
多人聊天室（`R` 开头的 ID）	仅当聊天室在白名单中时回复

支持处理入站文本、图片、音频、视频、文件和位置信息。出站文本优先使用免费的 reply token（单次使用，约 60 秒窗口），token 过期后回退到计费的 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（生产环境推荐——固定主机名）
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://... URL——后续将其设置为 webhook URL。测试期间保持隧道运行。生产环境请设置固定的 Cloudflare 命名隧道，避免重启后 webhook URL 发生变化。

步骤 3：配置 Hermes

在 ~/.hermes/.env 中添加：

LINE_CHANNEL_ACCESS_TOKEN=YOUR_L...OKEN
LINE_CHANNEL_SECRET=YOUR_C...CRET

# 白名单——至少设置以下其中一项（开发环境可设 LINE_ALLOW_ALL_USERS=true）
LINE_ALLOWED_USERS=U1234567890abcdef...           # 逗号分隔的 U 前缀用户 ID
LINE_ALLOWED_GROUPS=C1234567890abcdef...          # 可选，群组 ID
LINE_ALLOWED_ROOMS=R1234567890abcdef...           # 可选，聊天室 ID

# 发送图片/音频/视频时必需——公开 HTTPS 基础 URL
# 隧道解析到的地址。不设置的话，send_image/voice/video 会拒绝执行。
LINE_PUBLIC_URL=https://my-tunnel.example.com

然后在 ~/.hermes/config.yaml 中：

gateway:
  platforms:
    line:
      enabled: true

这样就够了——gateway/config.py 中的 bundled-plugin 扫描会自动识别 plugins/platforms/line/。无需修改 Platform.LINE 枚举，无需注册 _create_adapter。

步骤 4：设置 Webhook URL

回到 LINE 控制台：

打开你的频道 → Messaging API 标签页。
在 Webhook settings（Webhook 设置） → Webhook URL 下，粘贴 https://<你的隧道>/line/webhook（注意 /line/webhook 路径——适配器监听在此处）。
点击 Verify（验证）。LINE 会 ping 该 URL；你应该看到 200 响应。
将 Use webhook（使用 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 的 reply token 是单次使用且在入站事件后约 60 秒过期。响应慢的 LLM 无法及时回复，通常会导致需要使用计费的 Push API 调用。

当 LLM 运行超过 LINE_SLOW_RESPONSE_THRESHOLD 秒（默认 45）时，适配器会消耗原始 reply token 发送一个模板按钮气泡：

🤔 正在思考中。完成后点击下方获取答案。

[ 获取答案 ]

用户在方便时点击获取答案——该 postback 会传递一个全新的 reply token，适配器用它来发送缓存的答案（仍然是免费的）。

状态机：PENDING → READY → DELIVERED，以及 ERROR（对应被取消的运行，orphan PENDING 在 /stop 后解析为"运行在完成前被中断。"，避免持久按钮造成循环）。

要禁用 postback 按钮并始终回退到 Push 方式：

LINE_SLOW_RESPONSE_THRESHOLD=0

要让 postback 流程可靠触发，需抑制可能在阈值前消耗 reply token 的闲聊消息：

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

Cron / 通知投递

LINE_HOME_CHANNEL=Uxxxxxxxxxxxxxxxxxxxx     # 默认投递目标

带有 deliver: line 的 cron 任务会路由到 LINE_HOME_CHANNEL。适配器内置一个独立的纯 Push 发送器，因此即使 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`	否	—	默认 cron / 通知投递目标
`LINE_SLOW_RESPONSE_THRESHOLD`	否	`45`	触发 postback 按钮前的等待秒数（`0` = 禁用）
`LINE_PENDING_TEXT`	否	"🤔 正在思考中…"	随 postback 按钮显示的气泡文本
`LINE_BUTTON_LABEL`	否	"获取答案"	按钮标签
`LINE_DELIVERED_TEXT`	否	"已回复 ✅"	再次点击已投递按钮时的回复
`LINE_INTERRUPTED_TEXT`	否	"运行在完成前被中断。"	点击已被取消的按钮时的回复

故障排除

Webhook 验证时报 "invalid signature"（签名无效）。 Channel secret 复制有误，或者你的隧道重写了请求体。先用 curl -i https://<隧道>/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> 提供文件服务。

Postback 按钮从未出现。 可能是 LLM 响应速度快于 LINE_SLOW_RESPONSE_THRESHOLD，或者其他气泡（tool-progress、streaming）先消耗了 reply token。参见"LLM 响应缓慢"章节中的抑制配置块。

"already in use by another profile"（已被另一个配置文件使用）。 同一个频道访问令牌绑定到了另一个正在运行的 Hermes 配置文件。停止另一个网关，或使用不同的频道。

限制

每个 chunk 单气泡。 每条 LINE 文本气泡上限为 5000 字符，每次 Reply/Push 调用最多发送 5 个气泡。较长的回复会被截断并附上省略号。
无原生消息编辑功能。 LINE 没有编辑消息的 API——流式响应始终发送新气泡，不会编辑之前的消息。
无 Markdown 渲染。 粗体（**）、斜体（*）、代码块和标题会作为原义字符呈现。适配器在发送前会剥离它们；URL 会被保留（[label](url) 变为 label (url)）。
正在输入指示器仅限私信。 LINE 对群组和聊天室拒绝 chat/loading API，因此正在输入指示器仅在一对一聊天中显示。

机器人响应规则​

步骤 1：创建 LINE Messaging API 频道​

步骤 2：暴露 Webhook 端口​

步骤 3：配置 Hermes​

步骤 4：设置 Webhook URL​

步骤 5：运行网关​

LLM 响应缓慢时的处理​

Cron / 通知投递​

环境变量参考​

故障排除​

限制​