initial: 七牛云上传 OpenClaw Skill
功能特性: - 支持 /upload, /u 命令上传文件到七牛云 - 支持 /qiniu-config 配置管理 - 支持飞书卡片交互 - 支持指定上传路径和存储桶 - 自动刷新 CDN 缓存 - 支持文件覆盖上传 包含组件: - OpenClaw 处理器 (openclaw-processor.js) - 独立监听器 (scripts/feishu-listener.js) - 核心上传脚本 (scripts/upload-to-qiniu.js) - 部署脚本 (deploy.sh) - 完整文档 部署方式: 1. 复制 skill 到 ~/.openclaw/workspace/skills/ 2. 配置 ~/.openclaw/credentials/qiniu-config.json 3. 重启 OpenClaw Gateway
This commit is contained in:
daoqi
219
FEISHU_SETUP.md
Normal file
219
FEISHU_SETUP.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# 🍙 飞书事件订阅配置指南
|
||||
|
||||
## 前提条件
|
||||
|
||||
已配置飞书应用：
|
||||
- **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
|
||||
[附上文件]
|
||||
```
|
||||
|
||||
机器人会自动上传到七牛云并回复下载链接！🎉
|
||||
Reference in New Issue
Block a user