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
327
INTEGRATION.md
Normal file
327
INTEGRATION.md
Normal file
@@ -0,0 +1,327 @@
|
||||
# 🍙 七牛云 Skill - OpenClaw 集成指南
|
||||
|
||||
## 概述
|
||||
|
||||
这是一个 OpenClaw Skill，用于在飞书/钉钉等聊天平台中处理七牛云文件上传和配置管理。
|
||||
|
||||
**特点：**
|
||||
- ✅ 无需修改飞书开放平台配置
|
||||
- ✅ 与 OpenClaw 无缝集成
|
||||
- ✅ 保持现有机器人对话功能
|
||||
- ✅ 支持文件上传、配置管理、多存储桶
|
||||
|
||||
---
|
||||
|
||||
## 文件结构
|
||||
|
||||
```
|
||||
~/.openclaw/workspace/skills/qiniu-uploader/
|
||||
├── SKILL.md # Skill 元数据和说明
|
||||
├── package.json # Skill 配置
|
||||
├── openclaw-processor.js # OpenClaw 消息处理器 ⭐
|
||||
├── README.md # 使用文档
|
||||
├── scripts/
|
||||
│ ├── upload-to-qiniu.js # 七牛云上传脚本
|
||||
│ └── feishu-listener.js # 独立监听器（可选）
|
||||
└── ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 集成方式
|
||||
|
||||
### 方式一：OpenClaw 自动加载（推荐）
|
||||
|
||||
OpenClaw 会自动扫描 `~/.openclaw/workspace/skills/` 目录下的 Skill。
|
||||
|
||||
**步骤：**
|
||||
|
||||
1. **确保 Skill 目录存在**
|
||||
```bash
|
||||
ls ~/.openclaw/workspace/skills/qiniu-uploader/
|
||||
```
|
||||
|
||||
2. **重启 OpenClaw Gateway**
|
||||
```bash
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
3. **测试**
|
||||
在飞书中发送：
|
||||
```
|
||||
/qiniu-config list
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 方式二：手动注册
|
||||
|
||||
在 OpenClaw 配置中手动注册 Skill：
|
||||
|
||||
**编辑：** `~/.openclaw/openclaw.json`
|
||||
|
||||
添加 Skill 配置：
|
||||
|
||||
```json
|
||||
{
|
||||
"skills": {
|
||||
"qiniu-uploader": {
|
||||
"enabled": true,
|
||||
"path": "~/.openclaw/workspace/skills/qiniu-uploader",
|
||||
"triggers": ["/upload", "/qiniu-config", "/qiniu-help"],
|
||||
"handler": "openclaw-processor.js"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
然后重启 OpenClaw：
|
||||
|
||||
```bash
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 方式三：使用独立监听器（备选）
|
||||
|
||||
如果不想集成到 OpenClaw，可以使用独立监听器：
|
||||
|
||||
```bash
|
||||
cd ~/.openclaw/workspace/skills/qiniu-uploader
|
||||
|
||||
# 修改飞书请求地址到 3000 端口
|
||||
# http://47.83.185.237:3000
|
||||
|
||||
# 启动独立监听器
|
||||
node scripts/feishu-listener.js
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 使用方式
|
||||
|
||||
### 上传文件
|
||||
|
||||
```
|
||||
/upload [目标路径] [存储桶名]
|
||||
/upload --original [存储桶名]
|
||||
[附上文件]
|
||||
```
|
||||
|
||||
**示例：**
|
||||
```
|
||||
/upload /config/test.txt
|
||||
[附上文件]
|
||||
|
||||
/upload --original
|
||||
[附上文件]
|
||||
|
||||
/upload /docs/report.pdf production
|
||||
[附上文件]
|
||||
```
|
||||
|
||||
### 配置管理
|
||||
|
||||
```
|
||||
/qiniu-config list # 查看配置
|
||||
/qiniu-config set <键> <值> # 修改配置
|
||||
/qiniu-config set-bucket <名> <JSON> # 添加存储桶
|
||||
/qiniu-config reset # 重置配置
|
||||
```
|
||||
|
||||
**示例：**
|
||||
```
|
||||
/qiniu-config list
|
||||
/qiniu-config set default.accessKey YOUR_KEY
|
||||
/qiniu-config set default.domain https://cdn.example.com
|
||||
/qiniu-config set-bucket production '{"accessKey":"...","secretKey":"...","bucket":"prod","region":"z0","domain":"https://prod-cdn.com"}'
|
||||
```
|
||||
|
||||
### 查看帮助
|
||||
|
||||
```
|
||||
/qiniu-help
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 配置说明
|
||||
|
||||
### 七牛云配置
|
||||
|
||||
位置：`~/.openclaw/credentials/qiniu-config.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"buckets": {
|
||||
"default": {
|
||||
"accessKey": "YO_Wi-aMubLmZJr_X5EFOI3WC2a9rfif1fBsS_pK",
|
||||
"secretKey": "NlcJJKlZjK6CF2irT3SIw5e4pMPeL4S3IHFRrMX7",
|
||||
"bucket": "daoqires",
|
||||
"region": "z0",
|
||||
"domain": "https://daoqi.daoqi888.cn"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 飞书配置
|
||||
|
||||
位置：`~/.openclaw/workspace/skills/qiniu-uploader/openclaw-processor.js`
|
||||
|
||||
```javascript
|
||||
feishu: {
|
||||
appId: 'cli_a92ce47b02381bcc',
|
||||
appSecret: 'WpCWhqOPKv3F5Lhn11DqubrssJnAodot'
|
||||
}
|
||||
```
|
||||
|
||||
或使用环境变量：
|
||||
|
||||
```bash
|
||||
export FEISHU_APP_ID=cli_a92ce47b02381bcc
|
||||
export FEISHU_APP_SECRET=WpCWhqOPKv3F5Lhn11DqubrssJnAodot
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 测试
|
||||
|
||||
### 测试配置命令
|
||||
|
||||
```bash
|
||||
cd ~/.openclaw/workspace/skills/qiniu-uploader
|
||||
node openclaw-processor.js --message '{"content":{"text":"/qiniu-config list"}}'
|
||||
```
|
||||
|
||||
应该输出：
|
||||
```json
|
||||
{
|
||||
"handled": true,
|
||||
"reply": "📋 当前配置：..."
|
||||
}
|
||||
```
|
||||
|
||||
### 测试上传（需要实际文件）
|
||||
|
||||
```bash
|
||||
echo "test" > /tmp/test.txt
|
||||
node openclaw-processor.js --message '{"content":{"text":"/upload /test.txt"},"chat_id":"test"}'
|
||||
```
|
||||
|
||||
### 在飞书中测试
|
||||
|
||||
1. 确保 OpenClaw Gateway 运行中
|
||||
2. 在飞书中发送：`/qiniu-config list`
|
||||
3. 应该收到配置信息回复
|
||||
|
||||
---
|
||||
|
||||
## 工作流程
|
||||
|
||||
```
|
||||
飞书消息
|
||||
↓
|
||||
OpenClaw Gateway (17733 端口)
|
||||
↓
|
||||
识别七牛云命令 (/upload, /qiniu-config)
|
||||
↓
|
||||
调用 openclaw-processor.js
|
||||
↓
|
||||
处理命令
|
||||
├─ 下载文件（如果有附件）
|
||||
├─ 调用 upload-to-qiniu.js
|
||||
├─ 上传到七牛云
|
||||
├─ 刷新 CDN
|
||||
└─ 返回结果
|
||||
↓
|
||||
OpenClaw 回复消息
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 优势
|
||||
|
||||
### 与独立监听器对比
|
||||
|
||||
| 特性 | OpenClaw Skill | 独立监听器 |
|
||||
|------|---------------|-----------|
|
||||
| 飞书配置修改 | ❌ 不需要 | ✅ 需要 |
|
||||
| 架构统一性 | ✅ 统一 | ❌ 分散 |
|
||||
| 消息上下文 | ✅ 完整 | ❌ 部分 |
|
||||
| 维护成本 | ✅ 低 | ⭐ 中 |
|
||||
| 实现复杂度 | ⭐ 中 | ✅ 低 |
|
||||
| 可靠性 | ✅ 高 | ⭐ 中 |
|
||||
|
||||
---
|
||||
|
||||
## 故障排查
|
||||
|
||||
### Skill 未触发
|
||||
|
||||
1. 检查 OpenClaw 是否加载了 Skill：
|
||||
```bash
|
||||
openclaw status
|
||||
```
|
||||
|
||||
2. 检查 Skill 目录是否存在：
|
||||
```bash
|
||||
ls ~/.openclaw/workspace/skills/qiniu-uploader/
|
||||
```
|
||||
|
||||
3. 重启 OpenClaw：
|
||||
```bash
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
### 上传失败
|
||||
|
||||
1. 检查七牛云配置：
|
||||
```bash
|
||||
cat ~/.openclaw/credentials/qiniu-config.json
|
||||
```
|
||||
|
||||
2. 手动测试上传脚本：
|
||||
```bash
|
||||
node scripts/upload-to-qiniu.js config list
|
||||
```
|
||||
|
||||
3. 查看 OpenClaw 日志：
|
||||
```bash
|
||||
openclaw logs --tail 100
|
||||
```
|
||||
|
||||
### 文件下载失败
|
||||
|
||||
1. 检查飞书 App ID/Secret：
|
||||
```bash
|
||||
echo $FEISHU_APP_ID
|
||||
echo $FEISHU_APP_SECRET
|
||||
```
|
||||
|
||||
2. 检查机器人权限（im:message, im:file）
|
||||
|
||||
---
|
||||
|
||||
## 总结
|
||||
|
||||
✅ **已完成：**
|
||||
- OpenClaw Skill 处理器
|
||||
- 七牛云上传脚本
|
||||
- 配置管理功能
|
||||
- 测试通过
|
||||
|
||||
✅ **优势：**
|
||||
- 无需修改飞书配置
|
||||
- 与 OpenClaw 无缝集成
|
||||
- 保持现有机器人功能
|
||||
|
||||
🎯 **下一步：**
|
||||
1. 重启 OpenClaw Gateway
|
||||
2. 在飞书中测试 `/qiniu-config list`
|
||||
3. 测试文件上传功能
|
||||
|
||||
---
|
||||
|
||||
**集成完成！** 🍙
|
||||
Reference in New Issue
Block a user