宜博 / pixelphone

gateway-setup.md 4.17 KB

Feishu/Lark Gateway 配置指南

概述

Hermes Gateway 支持飞书平台，可以接收和发送消息。本文档记录完整的配置步骤和故障排除。

前置条件

  1. 已创建飞书应用（https://open.feishu.cn/app）
  2. 已获取 App ID 和 App Secret
  3. 已启用机器人能力（应用能力 -> 机器人）
  4. 已配置权限（消息、群聊、通讯录等）

配置步骤

1. 安装 hermes-feishu 插件（可选但推荐）

hermes plugins install arkseek/hermes-feishu
hermes plugins enable hermes-feishu

2. 配置环境变量

编辑 ~/.hermes/.env：

FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
HERMES_FEISHU_CHAT_ID=oc_xxxxxxxxxxxxxxxx  # 默认群聊ID（可选）
GATEWAY_ALLOW_ALL_USERS=true  # 允许所有用户使用（开发环境）

3. 配置 platforms（config.yaml）

hermes config set platforms.feishu.streaming true
hermes config set platforms.feishu.app_id cli_xxxxxxxxxxxxxxxx
hermes config set platforms.feishu.domain feishu  # 或 lark（国际版）
hermes config set platforms.feishu.allow_all_users true

验证配置：

hermes config show | grep -A 10 "feishu"

4. 启动 Gateway

# 检查状态
hermes gateway status

# 启动（前台，用于调试）
hermes gateway run

# 后台启动（Termux 环境）
nohup hermes gateway run > ~/.hermes/logs/gateway.log 2>&1 &

5. 验证连接

查看日志：

tail -f ~/.hermes/logs/gateway.log

应看到：

INFO gateway.run: Connecting to feishu...
INFO gateway.platforms.feishu: [Feishu] Connected in websocket mode (feishu)
INFO gateway.run: ✓ feishu connected
INFO gateway.run: Gateway running with X platform(s)

6. 用户授权

方式一：自动授权（allow_all_users=true）

  • 所有用户都可以使用，无需额外操作

方式二：手动授权

  • 用户首次使用时，机器人会回复配对码
  • 执行授权命令： bash hermes pairing approve feishu <PAIRING_CODE>

Termux 环境特殊配置

日志目录权限

Gateway 默认写入 ~/.hermes/logs，但 Termux 可能有权限问题：

# 创建日志目录到 /sdcard
mkdir -p /sdcard/.hermes/logs

# 删除旧目录并创建链接
rm -rf ~/.hermes/logs
ln -s /sdcard/.hermes/logs ~/.hermes/logs

DNS 配置

如果 DNS 解析失败：

# 配置 DNS
echo "nameserver 8.8.8.8
nameserver 114.114.114.114" > /data/data/com.termux/files/usr/etc/resolv.conf

# 添加 hosts
echo "198.18.0.87 accounts.feishu.cn" >> /data/data/com.termux/files/usr/etc/hosts

故障排除

问题：用户 @ 机器人但无回复

检查清单：

  1. Gateway 是否运行？hermes gateway status
  2. 用户是否授权？查看日志中的 Unauthorized user 警告
  3. 飞书连接是否正常？查看日志中的 Connected in websocket mode
  4. 应用是否启用机器人能力？检查飞书开放平台

问题：Gateway 启动后立即退出

可能原因：

  • 日志目录权限问题
  • 端口冲突
  • 配置错误

解决：

# 检查日志
cat ~/.hermes/logs/gateway.log | tail -50

# 修复权限
mkdir -p /sdcard/.hermes/logs
rm -rf ~/.hermes/logs
ln -s /sdcard/.hermes/logs ~/.hermes/logs

# 重新启动
hermes gateway run

问题：DNS 解析失败

错误：dial tcp: lookup accounts.feishu.cn: no such host

解决：

# 检查 DNS
cat /etc/resolv.conf

# 配置 DNS
echo "nameserver 8.8.8.8" > /data/data/com.termux/files/usr/etc/resolv.conf

# 测试连接
ping open.feishu.cn

问题：消息发送失败（错误 9499）

错误：{"code":9499,"msg":"Bad Request"}

原因：content 格式错误

解决：

import json

# 错误：直接传递 dict
content = {"text": "Hello"}  # ❌

# 正确：使用 json.dumps 转义
content = json.dumps({"text": "Hello"})  # ✅

# 发送时
message_data = {
    "receive_id": "oc_xxxxxx",
    "msg_type": "text",
    "content": content  # 这是 JSON 字符串
}

参考