openclaw-skill-qiniu/ARCHITECTURE.md

🍙 七牛云上传 - 架构方案对比

现状

• 飞书开放平台：事件订阅已配置，使用长连接/回调模式
• OpenClaw Gateway：运行在 17733 端口，已配置飞书渠道
• 七牛云配置：已完成，存储在 ~/.openclaw/credentials/qiniu-config.json
• 监听器：运行在 3000 端口

---

方案对比

方案 A：修改飞书请求地址到 3000 端口

┌─────────┐     ┌──────────────┐     ┌──────────────────┐
│  飞书   │────▶│ 3000 端口     │────▶│ OpenClaw Gateway │
│         │     │ 七牛监听器    │     │ (17733 端口)      │
└─────────┘     └──────────────┘     └──────────────────┘
                     │
                     ├─ /upload 命令 → 七牛云上传
                     ├─ /qiniu-config → 配置管理
                     └─ 其他消息 → 转发到 OpenClaw

优势：

• ✅ 七牛云功能独立，不依赖 OpenClaw 内部实现
• ✅ 实现简单，已经完成了
• ✅ 七牛云配置独立管理

劣势：

• ❌ 需要修改飞书开放平台配置（请求地址）
• ❌ 增加了一层转发，可能引入延迟
• ❌ 转发可能失败，可靠性降低
• ❌ OpenClaw 无法获取完整的消息上下文
• ❌ 两个服务需要分别维护

---

方案 B：保持现有配置（不修改飞书请求地址）

┌─────────┐     ┌──────────────────┐
│  飞书   │────▶│ OpenClaw Gateway │
│         │     │ (17733 端口)      │
└─────────┘     └──────────────────┘
                       │
                       ├─ AI 处理普通对话
                       └─ 七牛命令 → ???

优势：

• ✅ 不需要修改飞书开放平台配置
• ✅ 架构统一，所有消息由 OpenClaw 处理
• ✅ 消息上下文完整
• ✅ 只有一个服务，维护简单

劣势：

• ❌ 需要在 OpenClaw 中集成七牛云功能
• ❌ AI 无法直接处理文件附件（需要代码下载）
• ❌ 实现相对复杂

---

方案 C：混合模式（推荐）⭐

┌─────────┐     ┌──────────────────┐
│  飞书   │────▶│ OpenClaw Gateway │
│         │     │ (17733 端口)      │
└─────────┘     └──────────────────┘
                       │
                       ├─ AI 处理普通对话
                       │
                       └─ 七牛命令 → HTTP 调用 3000 端口
                                         │
                                         ▼
                                   七牛监听器
                                   (仅处理命令)

实现方式：

1. 保持飞书请求地址不变（指向 OpenClaw Gateway）
2. 在 OpenClaw 中创建技能，识别七牛云命令
3. 七牛监听器切换到"命令模式"，只处理 API 调用，不直接接收飞书事件
4. OpenClaw 通过 HTTP 调用七牛监听器处理上传

优势：

• ✅ 不需要修改飞书开放平台配置
• ✅ OpenClaw 保持完整的消息处理
• ✅ 七牛云功能独立实现
• ✅ 架构清晰，职责分离

劣势：

• ❌ 需要修改 OpenClaw 配置或创建技能
• ❌ 实现稍微复杂

---

🎯 推荐方案：方案 A（修改请求地址）

虽然方案 C 最优雅，但方案 A 已经实现完成，且有以下优点：

1. 已经实现：代码已完成，测试通过
2. 简单可靠：转发逻辑简单，故障点少
3. 独立部署：七牛云功能可以独立于 OpenClaw 升级

实施步骤

1. 修改飞书开放平台请求地址：

   http://47.83.185.237:3000
   

2. 验证 Token保持不变：

   qiniu_upload_token_2026
   

3. 测试：

   • /qiniu-config list → 七牛云处理
   • /upload ... → 七牛云处理
   • 其他消息 → 转发到 OpenClaw

---

📋 决策建议

考虑因素	推荐方案
快速上线	方案 A ✅
不修改飞书配置	方案 B/C
架构优雅	方案 C
维护简单	方案 A ✅
可靠性	方案 A ✅

---

💡 最终建议

使用方案 A，原因：

1. 代码已完成并测试通过
2. 修改飞书配置只需要 1 分钟
3. 转发逻辑简单，可靠性高
4. 七牛云和 OpenClaw 可以独立演进

如果你坚持不修改飞书配置，我们可以实现方案 C，但需要：

• 在 OpenClaw 中创建技能来拦截七牛命令
• 修改七牛监听器为 API 模式
• 额外的工作量约 2-3 小时

---

🚀 下一步

选择方案 A（推荐）：

1. 在飞书开放平台修改请求地址为 http://47.83.185.237:3000
2. 保存并等待验证成功
3. 在飞书中测试 /qiniu-config list 和普通对话

选择方案 C（不修改飞书）：

1. 告诉我你的决定
2. 我会实现 OpenClaw 技能来拦截七牛命令
3. 修改七牛监听器为 API 模式

---

你选择哪个方案？ 🍙