hermes教程-LINE 设置 - 字节笔记本

LINE 设置

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

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

运行 hermes gateway setup 并选择 LINE 即可获得引导式操作指南。

机器人如何响应

上下文	行为
一对一聊天（`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 覆盖。

bash

## 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 中添加：

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 中：

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：运行网关

bash

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）时，适配器会消耗原始回复令牌，发送一个模板按钮气泡：

🤔 仍在思考。准备好后点击下方获取答案。

[ 获取答案 ]

用户方便时点击 获取答案——该回传会提供一个新的回复令牌，适配器使用它发送缓存的答案（仍然免费）。

状态机：PENDING → READY → DELIVERED，加上 ERROR 用于取消的运行（孤立的 PENDING 状态在 /stop 后解析为“运行在完成前被中断。”，这样持久按钮不会循环）。

要禁用回传按钮并始终回退到 Push：

env

LINE_SLOW_RESPONSE_THRESHOLD=0

为了可靠触发回传流程，请抑制会在阈值前消耗回复令牌的中间消息：

yaml

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

Cron / 通知投递

env

LINE_HOME_CHANNEL=Uxxxxxxxxxxxxxxxxxxxx     # 默认投递目标

带有 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`	否	—	默认的 cron / 通知投递目标
`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 调用最多 5 个气泡，每个气泡约 4500 字符，尽可能在自然边界处分割。
无原生消息编辑。 LINE 没有编辑消息的 API——流式响应始终发送新气泡，从不编辑之前的气泡。
不支持 Markdown 渲染。 粗体（**）、斜体（*）、代码块和标题会以字面字符形式显示。适配器在发送前会去除它们；URL 会保留（[label](url) 变为 label (url)）。
加载指示器仅限私聊。 LINE 拒绝群组和房间的 chat/loading API，因此打字指示器仅在一对一聊天中显示。