hermes-agent/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/line.md

sidebar_position	title	description
17	LINE	将 Hermes Agent 设置为 LINE Messaging API 机器人

LINE 配置

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

LINE 是日本、台湾和泰国的主流即时通讯应用。如果你的用户在这些地区，这就是他们与你沟通的方式。

机器人响应方式

场景	行为
1:1 聊天（U 开头 ID）	响应每条消息
群聊（C 开头 ID）	仅当群组在白名单中时响应
多人房间（R 开头 ID）	仅当房间在白名单中时响应

入站的文本、图片、音频、视频、文件、贴纸和位置信息均可处理。出站文本优先使用免费 reply token（单次使用，有效期约 60 秒），token 过期后回退至计费的 Push API。

---

第一步：创建 LINE Messaging API 频道

1. 前往 LINE Developers Console。
2. 创建一个 Provider，然后在其下创建一个 Messaging API 频道。
3. 在频道的 Basic settings 标签页中，复制 Channel secret。
4. 在 Messaging API 标签页中，滚动至 Channel access token (long-lived) 并点击 Issue，复制该 token。
5. 在 Messaging API 标签页中，同时禁用 Auto-reply messages 和 Greeting messages，避免与机器人回复冲突。

---

第二步：暴露 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 变更。

---

第三步：配置 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 基础 URL
# 未设置时，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 settings → Webhook URL 下，粘贴 https://<your-tunnel>/line/webhook（注意 /line/webhook 路径 — 适配器在此监听）。
3. 点击 Verify。LINE 会 ping 该 URL，你应看到 200 响应。
4. 将 Use webhook 切换为 On。

---

第五步：运行 gateway

hermes gateway

Agent 日志显示：

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，发送一个 Template Buttons 气泡：

🤔 Still thinking. Tap below to fetch the answer when it's ready.

[ Get answer ]

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

状态机：PENDING → READY → DELIVERED，以及 ERROR（用于已取消的运行 — 执行 /stop 后，孤立的 PENDING 状态会解析为"Run was interrupted before completion."，避免持久按钮循环触发）。

如需禁用 postback 按钮并始终回退至 Push API：

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	是	—	长期有效的频道访问 token
LINE_CHANNEL_SECRET	是	—	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	否	"🤔 Still thinking…"	postback 按钮旁显示的气泡文本
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 中搜索 LINE: rejecting unauthorized source — 被拒绝的 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，要么其他气泡（工具进度、流式输出）已提前消耗了 reply token。参见"LLM 响应缓慢"中的抑制配置。

"already in use by another profile"。 同一个频道访问 token 已被另一个运行中的 Hermes profile 占用。请停止另一个 gateway，或使用独立的频道。

---

限制

• 每个分块仅一个气泡。 每个 LINE 文本气泡最多 5000 个字符，每次 Reply/Push 调用最多发送 5 个气泡。超出长度的响应将被截断并附加省略号。
• 不支持原生消息编辑。 LINE 没有编辑消息的 API — 流式响应始终发送新气泡，不会编辑已有气泡。
• 不支持 Markdown 渲染。 粗体（**）、斜体（*）、代码块和标题均以字面字符显示。适配器在发送前会将其剥离；URL 会被保留（[label](url) 转换为 label (url)）。
• 加载指示器仅限私聊。 LINE 对群组和房间拒绝 chat/loading API，因此输入指示器仅在 1:1 聊天中显示。