openclaw-skill-qiniu/FEISHU_SETUP.md

# 🍙 飞书事件订阅配置指南

## 前提条件

已配置飞书应用：
- **App ID**: `cli_a92ce47b02381bcc`
- **App Secret**: `WpCWhqOPKv3F5Lhn11DqubrssJnAodot`

## 步骤一：飞书开放平台配置

### 1. 登录飞书开放平台

访问：https://open.feishu.cn/app

### 2. 进入应用管理

- 找到你的应用（或创建新应用）
- 进入「应用功能」→「事件订阅」

### 3. 配置事件订阅

#### 3.1 启用事件订阅

- 打开「启用事件订阅」开关
- 设置**请求地址**（Request URL）：
  ```
  http://你的服务器公网IP:3000
  ```
  
  > 💡 如果没有公网 IP，可以使用内网穿透工具如 ngrok：
  > ```bash
  > ngrok http 3000
  > # 然后使用 ngrok 提供的 https 地址
  > ```

#### 3.2 配置验证 Token

- 设置**验证 Token**：随便填一个字符串，例如 `qiniu_upload_token_2026`
- 记住这个值，稍后要填入配置文件

#### 3.3 配置加密密钥（可选但推荐）

- 点击「生成加密密钥」
- 复制生成的密钥
- 记住这个值，稍后要填入配置文件

#### 3.4 订阅事件

点击「添加事件」，订阅以下事件：

| 事件类型 | 说明 |
|---------|------|
| `im.message.receive_v1` | 接收消息事件 |
| `im.file.upload_v1` | 文件上传事件（可选） |

### 4. 配置应用权限

进入「应用功能」→「权限管理」，添加以下权限：

| 权限名称 | 权限标识 | 申请方式 |
|---------|---------|---------|
| 获取与发送单聊、群组消息 | `im:message` | 自动开通 |
| 获取消息中的文件 | `im:file` | 自动开通 |
| 以应用身份发送消息 | `im:message:send_as_bot` | 自动开通 |

点击「申请」并等待审核（通常自动通过）。

### 5. 发布应用

- 进入「版本管理与发布」
- 点击「创建版本」
- 填写版本说明，提交发布

## 步骤二：配置监听器

### 1. 创建环境变量配置文件

在技能目录下创建 `.env` 文件：

```bash
cd ~/.openclaw/workspace/skills/qiniu-uploader
cat > .env << 'EOF'
# 飞书应用配置
FEISHU_APP_ID=cli_a92ce47b02381bcc
FEISHU_APP_SECRET=WpCWhqOPKv3F5Lhn11DqubrssJnAodot

# 事件订阅配置（从飞书开放平台复制）
FEISHU_VERIFY_TOKEN=qiniu_upload_token_2026
FEISHU_ENCRYPT_KEY=你的加密密钥（从飞书开放平台复制）

# 监听器配置
FEISHU_LISTENER_PORT=3000
EOF
```

### 2. 编辑配置文件

根据实际情况修改 `.env` 文件中的：
- `FEISHU_VERIFY_TOKEN`：与飞书开放平台填写的一致
- `FEISHU_ENCRYPT_KEY`：从飞书开放平台复制的加密密钥

## 步骤三：启动监听器

### 方式一：直接启动

```bash
cd ~/.openclaw/workspace/skills/qiniu-uploader

# 加载环境变量并启动
set -a; source .env; set +a
node scripts/feishu-listener.js
```

### 方式二：使用启动脚本

```bash
./scripts/start-listener.sh
```

### 方式三：后台运行（推荐）

```bash
# 使用 nohup 后台运行
nohup node scripts/feishu-listener.js > listener.log 2>&1 &

# 查看日志
tail -f listener.log

# 查看进程
ps aux | grep feishu-listener

# 停止服务
pkill -f feishu-listener
```

## 步骤四：验证配置

### 1. 检查飞书开放平台状态

回到飞书开放平台的「事件订阅」页面：
- ✅ 请求地址状态应显示为「验证成功」
- 如果显示「验证失败」，检查：
  - 服务器是否可访问
  - 端口是否开放
  - Token 配置是否正确

### 2. 测试消息接收

在飞书中：
1. 找到你的机器人（或拉机器人进群）
2. 发送测试消息：
   ```
   /upload test.pdf
   [附上一个 PDF 文件]
   ```
3. 检查监听器日志是否有输出
4. 检查是否收到机器人的回复

### 3. 检查日志

```bash
# 实时查看日志
tail -f ~/.openclaw/workspace/skills/qiniu-uploader/listener.log
```

## 常见问题

### ❌ 请求地址验证失败

**原因：**
- 服务器无法从公网访问
- 端口未开放
- 防火墙阻止

**解决方案：**
```bash
# 检查端口是否监听
netstat -tlnp | grep 3000

# 开放端口（如果使用防火墙）
sudo ufw allow 3000

# 或使用内网穿透
ngrok http 3000
```

### ❌ 收不到消息

**检查清单：**
- [ ] 机器人已添加到聊天
- [ ] 事件订阅已启用
- [ ] 权限已申请
- [ ] 应用已发布
- [ ] 消息格式正确（以 /upload 或 /qiniu 开头）

### ❌ 上传失败

**检查：**
- 七牛云配置文件是否存在：`~/.openclaw/credentials/qiniu-config.json`
- AccessKey/SecretKey 是否正确
- 存储桶名称是否匹配

## 安全建议

1. **使用 HTTPS**：生产环境建议使用 HTTPS
2. **验证签名**：确保启用加密密钥验证
3. **限制 IP**：在飞书开放平台配置 IP 白名单
4. **定期轮换密钥**：定期更新 App Secret 和加密密钥

## 下一步

配置完成后，在飞书中发送：

```
/upload 文件名.pdf
[附上文件]
```

机器人会自动上传到七牛云并回复下载链接！🎉