openclaw-skill-qiniu/README.md

🍙 七牛云自动上传 v2 - 完整使用指南

✨ v2 新功能

1. ✅ 支持指定上传路径 - 可以上传到存储桶的子文件夹
2. ✅ 使用原文件名 - 可选保留原始文件名
3. ✅ 聊天命令配置 - 在飞书中直接修改七牛云配置
4. ✅ 多存储桶支持 - 动态添加和管理多个存储桶

---

📤 上传文件

方式一：指定路径上传

/upload /config/test/test.txt default
[附上文件]

文件将上传到：default 存储桶的 /config/test/test.txt

方式二：使用原文件名

/upload --original default
[附上文件]

文件将使用原始文件名上传到 default 存储桶。

方式三：简单上传（默认使用原文件名）

/upload
[附上文件]

等价于：/upload --original default

方式四：指定存储桶

/upload /docs/report.pdf production
[附上文件]

---

⚙️ 配置管理（聊天命令）

查看当前配置

/qiniu-config list

回复示例：

📋 当前配置：

存储桶配置：

  🪣 [default]
     accessKey: 7hO...xyz
     secretKey: xYz...abc
     bucket:    my-files
     region:    z0
     domain:    https://cdn.example.com

💡 使用 config set <key> <value> 修改配置

修改单个配置项

/qiniu-config set default.accessKey YOUR_NEW_ACCESS_KEY

/qiniu-config set default.secretKey YOUR_NEW_SECRET_KEY

/qiniu-config set default.bucket my-new-bucket

/qiniu-config set default.region z1

/qiniu-config set default.domain https://new-cdn.example.com

添加新的存储桶

/qiniu-config set-bucket production {"accessKey":"...","secretKey":"...","bucket":"prod-bucket","region":"z0","domain":"https://prod-cdn.com"}

重置配置

/qiniu-config reset

---

📋 配置项说明

配置项	说明	示例
default.accessKey	七牛访问密钥	7hO...
default.secretKey	七牛密钥	xYz...
default.bucket	存储桶名称	my-files
default.region	区域代码	z0(华东)、z1(华北)、z2(华南)、na0(北美)、as0(东南亚)
default.domain	CDN 域名	https://cdn.example.com

---

🎯 使用示例

示例 1：上传配置文件

/upload /config/app/config.json default
[附上 config.json 文件]

回复：

✅ 上传成功！

📦 文件：config/app/config.json
🔗 链接：https://cdn.example.com/config/app/config.json
💾 原文件：config.json
🪣 存储桶：default

示例 2：上传图片到指定目录

/upload /images/2026/03/photo.jpg default
[附上照片]

示例 3：使用原文件名上传

/upload --original
[附上 report-2026-Q1.pdf]

文件将以 report-2026-Q1.pdf 上传。

示例 4：修改 CDN 域名

/qiniu-config set default.domain https://new-cdn.example.com

示例 5：添加生产环境存储桶

/qiniu-config set-bucket production {"accessKey":"AK_prod","secretKey":"SK_prod","bucket":"prod-assets","region":"z0","domain":"https://prod-cdn.example.com"}

然后上传到生产环境：

/upload /assets/main.js production
[附上 main.js]

示例 6：查看帮助

/qiniu-help

---

🔧 命令行使用

上传文件

# 使用原文件名
node scripts/upload-to-qiniu.js upload --file ./report.pdf

# 指定路径
node scripts/upload-to-qiniu.js upload --file ./report.pdf --key /docs/report.pdf

# 指定存储桶
node scripts/upload-to-qiniu.js upload --file ./report.pdf --key /docs/report.pdf --bucket production

配置管理

# 初始化配置
node scripts/upload-to-qiniu.js config init

# 查看配置
node scripts/upload-to-qiniu.js config list

# 修改配置
node scripts/upload-to-qiniu.js config set default.accessKey YOUR_KEY

# 添加存储桶
node scripts/upload-to-qiniu.js config set-bucket production '{"accessKey":"...","secretKey":"...","bucket":"prod","region":"z0","domain":"https://..."}'

# 重置配置
node scripts/upload-to-qiniu.js config reset

---

🚀 部署方式

方式一：OpenClaw 集成（推荐）

1. 复制 skill 到 OpenClaw：

cp -r qiniu-uploader ~/.openclaw/workspace/skills/

2. 配置七牛云凭证：

cp qiniu-config.example.json ~/.openclaw/credentials/qiniu-config.json
nano ~/.openclaw/credentials/qiniu-config.json

3. 重启 OpenClaw Gateway：

openclaw gateway restart

4. 在飞书中测试：

/qiniu-config list

方式二：独立监听器

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

# 配置环境变量
cp .env.example .env
nano .env  # 编辑飞书凭证

# 启动监听器
node scripts/feishu-listener.js

# 或使用 PM2 后台运行
pm2 start scripts/feishu-listener.js --name qiniu-uploader

注意： 独立监听器需要在飞书开放平台配置事件订阅地址。

---

📊 文件结构

qiniu-uploader/
├── scripts/
│   ├── upload-to-qiniu.js      # 核心上传脚本
│   ├── feishu-listener.js      # 飞书独立监听器
│   └── update-bucket-setting.js # 存储桶设置工具
├── openclaw-processor.js       # OpenClaw 处理器
├── openclaw-handler.js         # HTTP 处理器
├── deploy.sh                   # 部署脚本
├── .env.example                # 环境变量模板
├── qiniu-config.example.json   # 配置示例
└── README.md                   # 本文档

---

🔍 故障排查

上传失败

1. 检查配置：

/qiniu-config list

2. 手动测试上传：

node scripts/upload-to-qiniu.js upload --file ./test.txt --key /test.txt

3. 检查实际存储桶名称：

# 回复中的"存储桶"应显示实际桶名（如 daoqires），而不是配置别名（如 default）

配置命令无响应

1. 检查 OpenClaw Gateway 状态：

openclaw gateway status

2. 查看日志：

tail -f /tmp/openclaw/openclaw-*.log

权限错误

确保飞书应用有以下权限：

• im:message
• im:file
• im:message:send_as_bot

存储桶覆盖问题

如果同名文件无法覆盖，检查七牛云控制台的"防覆盖"设置是否已关闭。

---

💡 最佳实践

1. 路径规范：建议使用 / 开头的路径，如 /config/app/config.json
2. 存储桶命名：使用有意义的名称，如 default、production、backup
3. 定期轮换密钥：使用 /qiniu-config set 定期更新 AccessKey/SecretKey
4. 备份配置：重要配置修改前，先 /qiniu-config list 查看当前配置

---

🆘 获取帮助

• 在飞书中发送：/qiniu-help
• 查看文档：cat README.md
• 快速开始：cat QUICKSTART.md

---

祝你使用愉快！ 🍙