# Feishu/Lark Gateway 配置指南

## 概述

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

## 前置条件

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

## 配置步骤

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

```bash
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）

```bash
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
```

验证配置：
```bash
hermes config show | grep -A 10 "feishu"
```

### 4. 启动 Gateway

```bash
# 检查状态
hermes gateway status

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

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

### 5. 验证连接

查看日志：
```bash
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 可能有权限问题：

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

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

### DNS 配置

如果 DNS 解析失败：

```bash
# 配置 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 启动后立即退出

**可能原因**：
- 日志目录权限问题
- 端口冲突
- 配置错误

**解决**：
```bash
# 检查日志
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`

**解决**：
```bash
# 检查 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 格式错误

**解决**：
```python
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 字符串
}
```

## 参考

- 飞书开放平台：https://open.feishu.cn/
- Hermes 文档：https://hermes-agent.nousresearch.com/docs
- hermes-feishu 插件：https://github.com/arkseek/hermes-feishu