openclaw-skill-qiniu/INTEGRATION.md

🍙 七牛云 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 目录存在

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

2. 重启 OpenClaw Gateway

   openclaw gateway restart
   

3. 测试 在飞书中发送：

   /qiniu-config list
   

---

方式二：手动注册

在 OpenClaw 配置中手动注册 Skill：

编辑： ~/.openclaw/openclaw.json

添加 Skill 配置：

{
  "skills": {
    "qiniu-uploader": {
      "enabled": true,
      "path": "~/.openclaw/workspace/skills/qiniu-uploader",
      "triggers": ["/upload", "/qiniu-config", "/qiniu-help"],
      "handler": "openclaw-processor.js"
    }
  }
}

然后重启 OpenClaw：

openclaw gateway restart

---

方式三：使用独立监听器（备选）

如果不想集成到 OpenClaw，可以使用独立监听器：

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

{
  "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

feishu: {
  appId: 'cli_a92ce47b02381bcc',
  appSecret: 'WpCWhqOPKv3F5Lhn11DqubrssJnAodot'
}

或使用环境变量：

export FEISHU_APP_ID=cli_a92ce47b02381bcc
export FEISHU_APP_SECRET=WpCWhqOPKv3F5Lhn11DqubrssJnAodot

---

测试

测试配置命令

cd ~/.openclaw/workspace/skills/qiniu-uploader
node openclaw-processor.js --message '{"content":{"text":"/qiniu-config list"}}'

应该输出：

{
  "handled": true,
  "reply": "📋 当前配置：..."
}

测试上传（需要实际文件）

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：

   openclaw status
   

2. 检查 Skill 目录是否存在：

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

3. 重启 OpenClaw：

   openclaw gateway restart
   

上传失败

1. 检查七牛云配置：

   cat ~/.openclaw/credentials/qiniu-config.json
   

2. 手动测试上传脚本：

   node scripts/upload-to-qiniu.js config list
   

3. 查看 OpenClaw 日志：

   openclaw logs --tail 100
   

文件下载失败

1. 检查飞书 App ID/Secret：

   echo $FEISHU_APP_ID
   echo $FEISHU_APP_SECRET
   

2. 检查机器人权限（im:message, im:file）

---

总结

✅ 已完成：

• OpenClaw Skill 处理器
• 七牛云上传脚本
• 配置管理功能
• 测试通过

✅ 优势：

• 无需修改飞书配置
• 与 OpenClaw 无缝集成
• 保持现有机器人功能

🎯 下一步：

1. 重启 OpenClaw Gateway
2. 在飞书中测试 /qiniu-config list
3. 测试文件上传功能

---

集成完成！ 🍙