openclaw-skill-qiniu/SKILL.md

name, description

name	description
qiniu-uploader	七牛云文件上传和管理。支持命令触发和飞书卡片交互两种方式。

七牛云上传 Skill

使用方式

本 Skill 支持两种使用方式：

方式 1：命令触发（简单）

命令	说明	示例
/upload	上传文件到七牛云	/upload /config/file.txt
/u	上传快捷命令（别名）	/u file.txt
/qiniu-config	管理七牛云配置	/qiniu-config list
/qc	配置管理快捷命令（别名）	/qc list
/qiniu-help	查看帮助	/qiniu-help
/qh	帮助快捷命令（别名）	/qh

方式 2：飞书卡片交互（可选）

通过飞书消息卡片按钮操作，体验更佳。需要独立部署监听器。

注意： OpenClaw 集成模式下推荐使用命令触发方式。

命令格式

上传文件

/upload [目标路径] [存储桶名]
/upload --original [存储桶名]

参数说明：

• 目标路径：可选，指定上传到七牛云的路径（如 /config/test/file.txt）
• 存储桶名：可选，默认使用 default 存储桶
• --original：使用原始文件名

示例：

/upload                          # 使用原文件名上传到 default
/upload --original               # 同上
/upload /config/test.txt         # 上传到指定路径
/upload /docs/r.pdf production   # 指定路径和存储桶

文件覆盖行为：

• ✅ 上传同名文件会自动覆盖旧文件
• ✅ 支持指定路径覆盖（如 /config/test.txt）
• ✅ 覆盖后 CDN 会自动刷新（可能有几秒延迟）

配置管理

/qiniu-config list                        # 查看当前配置
/qiniu-config set <键> <值>               # 修改单个配置项
/qiniu-config set-bucket <名> <JSON>      # 添加/修改存储桶
/qiniu-config reset                       # 重置配置

配置项说明：

• default.accessKey - 七牛访问密钥
• default.secretKey - 七牛密钥
• default.bucket - 存储桶名称
• default.region - 区域代码（z0/z1/z2/na0/as0）
• default.domain - CDN 域名

示例：

/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"}

配置文件

位置：~/.openclaw/credentials/qiniu-config.json

{
  "buckets": {
    "default": {
      "accessKey": "YOUR_ACCESS_KEY",
      "secretKey": "YOUR_SECRET_KEY",
      "bucket": "your-bucket-name",
      "region": "z0",
      "domain": "https://your-cdn-domain.com"
    },
    "production": {
      "accessKey": "...",
      "secretKey": "...",
      "bucket": "prod-bucket",
      "region": "z0",
      "domain": "https://prod-cdn.com"
    }
  }
}

执行脚本

核心脚本：~/.openclaw/workspace/skills/qiniu-uploader/scripts/upload-to-qiniu.js

调用方式

# 上传文件
node scripts/upload-to-qiniu.js upload --file <文件路径> --key <目标路径> --bucket <存储桶名>

# 配置管理
node scripts/upload-to-qiniu.js config list
node scripts/upload-to-qiniu.js config set <键> <值>
node scripts/upload-to-qiniu.js config set-bucket <名> <JSON>

回复格式

上传成功

✅ 上传成功！

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

上传失败

❌ 上传失败：文件不存在

配置列表

📋 当前配置：

存储桶配置：

  🪣 [default]
     accessKey: YO_W...S_pK
     secretKey: NlcJ...rMX7
     bucket:    daoqires
     region:    z0
     domain:    https://daoqi.daoqi888.cn

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

处理流程

1. 识别命令：检测消息是否以 /upload、/qiniu-config 或 /qiniu-help 开头
2. 解析参数：提取目标路径、存储桶名等参数
3. 下载文件：从飞书/钉钉下载附件到临时目录
4. 执行上传：调用 upload-to-qiniu.js 脚本上传到七牛云
5. 刷新 CDN：自动刷新 CDN 缓存
6. 回复结果：在聊天中回复上传结果
7. 清理临时文件：删除临时下载的文件

依赖

• Node.js v14+
• 七牛云账号和存储桶
• 飞书/钉钉机器人配置

注意事项

1. 文件需要先下载：从聊天平台下载附件到临时目录
2. 上传后清理：完成后删除临时文件
3. 配置安全：AccessKey/SecretKey 妥善保管
4. 路径规范：建议使用 / 开头的路径（如 /config/file.txt）
5. 区域代码：确保 region 与存储桶实际区域一致
6. 文件覆盖：上传同名文件会自动覆盖（insertOnly: 0）

区域代码

代码	区域
z0	华东（浙江）
z1	华北（河北）
z2	华南（广东）
na0	北美
as0	东南亚

故障排查

上传失败

1. 检查配置文件是否存在：~/.openclaw/credentials/qiniu-config.json
2. 检查 AccessKey/SecretKey 是否正确
3. 检查存储桶名称是否匹配
4. 检查区域代码是否正确

同名文件无法覆盖 ⚠️

原因： 七牛云存储桶启用了"防覆盖"设置

解决方法 1：通过七牛云控制台

1. 登录七牛云控制台：https://portal.qiniu.com/
2. 进入"对象存储" → 选择你的存储桶
3. 点击"设置" → "空间设置"
4. 找到"防覆盖"选项，关闭它
5. 保存设置后重试上传

解决方法 2：通过命令行

# 1. 检查当前设置
node scripts/check-bucket-override.js default

# 2. 关闭防覆盖
node scripts/update-bucket-setting.js mybucket noOverwrite 0

# 3. 重启 Gateway
openclaw gateway restart

解决方法 3：修改上传脚本（临时） 在上传时使用不同的文件名（如添加时间戳）：

/upload /config/file_$(date +%Y%m%d_%H%M%S).txt

配置命令无响应

1. 检查脚本权限：chmod +x scripts/upload-to-qiniu.js
2. 手动测试：node scripts/upload-to-qiniu.js config list
3. 查看日志输出

文件下载失败

1. 检查飞书/钉钉 App ID 和 App Secret 配置
2. 检查机器人权限（im:message, im:file）
3. 检查网络连接

诊断工具

# 检查存储桶覆盖设置
node scripts/check-bucket-override.js [bucket-name]

# 更新存储桶设置
node scripts/update-bucket-setting.js <bucket> <setting> <value>

相关文件

• scripts/upload-to-qiniu.js - 核心上传脚本
• scripts/feishu-listener.js - 飞书独立监听器（可选）
• ~/.openclaw/credentials/qiniu-config.json - 七牛云配置
• README.md - 完整使用文档
• CHEATSHEET.md - 快速参考卡片