Dropbox 集成

概述

本技能提供对您的 Dropbox 账户的只读访问权限，使您能够通过 OpenClaw 浏览文件夹、搜索文件以及下载内容。它采用 OAuth 2.0 认证机制，并支持自动刷新访问令牌，从而实现无缝的长期访问。

适用场景：在无需担心误修改或误删除的情况下，安全访问您的 Dropbox 文件。

功能特性

浏览文件与文件夹

• 列出 Dropbox 中任意文件夹的内容
• 查看文件大小与最后修改时间
• 遍历文件夹层级结构

搜索文件

• 基于文件名的全文检索
• 在 Dropbox 全局范围内查找文件
• 获取匹配文件的元数据及路径信息

下载文件

• 从 Dropbox 下载任意文件
• 保存至本地文件系统
• 支持批量下载

自动令牌管理

• 使用 OAuth 2.0 认证并配套刷新令牌（refresh token）
• 自动刷新访问令牌（无需手动重新授权）
• 安全存储凭据
• 令牌过期处理具备 5 分钟缓冲期

安全与权限

本技能配置为只读访问，所需 Dropbox 权限范围（scopes）如下：

• files.metadata.read — 读取文件/文件夹元数据
• files.content.read — 读取文件内容
• account_info.read — 读取账户信息

未包含的权限：

• ❌ files.content.write — 不可上传或修改文件
• ❌ files.metadata.write — 不可重命名或移动文件
• ❌ files.permanent_delete — 不可删除文件

该设计确保您的 Dropbox 内容不会因误操作而被修改。

前提条件

在使用本技能前，您需要完成以下准备：

1. 一个Dropbox 账户（免费或付费均可）
2. 一次Dropbox App 注册（耗时约 5 分钟）
3. 从您的 Dropbox App 获取的App key 和App secret
4. 已安装 Node.js，并包含 dropbox 包（将自动安装）

配置耗时：约 10 分钟

详见《配置指南》获取分步说明。

快速上手

1. 创建 Dropbox App

访问 https://www.dropbox.com/developers/apps/create 创建新应用：

• API 类型：Scopes-based access（基于权限范围的访问）
• 访问类型：Full Dropbox（或选择 App folder 以限制访问范围）
• 应用名称：请使用唯一名称，例如 "OpenClaw-YourName"

2. 配置 OAuth

在您的 App 设置中执行以下操作：

1. 添加重定向 URI：http://localhost:3000/callback
2. 复制您的App key 和App secret
3. 在Permissions（权限）标签页中启用以下权限：
   • files.metadata.read
   • files.content.read
   • account_info.read

3. 保存凭据

在技能目录下创建 credentials.json 文件：

{
  "app_key": "your_dropbox_app_key_here",
  "app_secret": "your_dropbox_app_secret_here"
}

重要提示：该文件已被加入 .gitignore，绝不会被提交至版本库。

4. 运行 OAuth 配置脚本

node setup-oauth.js

该命令将执行以下操作：

1. 在浏览器中打开 Dropbox 授权页面
2. 启动本地服务器用于接收授权码（authorization code）
3. 使用授权码换取访问令牌（access token）和刷新令牌（refresh token）
4. 将令牌安全地保存至 token.json

5. 测试连接

node test-connection.js

若成功，您将看到自己的 Dropbox 账户信息！

使用示例

浏览文件夹

# 列出根目录
node browse.js

# 列出指定文件夹
node browse.js "/Documents"
node browse.js "/Photos/2024"

输出示例：

📁 Listing: /Documents

📄 report.pdf (2.3 MB) - 2024-02-01
📄 presentation.pptx (5.1 MB) - 2024-01-28
📁 Projects
📁 Archive

Total: 4 items

搜索文件

node search-files.js "budget 2024"
node search-files.js "contract"

输出示例：

🔍 Searching for: "budget 2024"

✅ Found 3 matches:

📄 /Finance/budget-2024-q1.xlsx
   Size: 156.3 KB
   Modified: 2024-01-15T10:30:00Z

📄 /Reports/budget-2024-summary.pdf
   Size: 2.1 MB
   Modified: 2024-02-01T14:22:00Z

下载文件

# 下载至本地指定路径
node download.js "/Documents/report.pdf" "./downloads/report.pdf"

# 下载至当前目录
node download.js "/Photos/vacation.jpg" "./vacation.jpg"

输出示例：

📥 Downloading: /Documents/report.pdf
✅ Saved to: ./downloads/report.pdf (2.3 MB)

与 OpenClaw 的集成

在 OpenClaw 中，您可通过 exec 工具运行这些脚本：

浏览文件：

Run: node /path/to/dropbox-integration/browse.js "/Documents"

搜索文件：

Run: node /path/to/dropbox-integration/search-files.js "contract"

下载文件：

Run: node /path/to/dropbox-integration/download.js "/path/in/dropbox" "./local/path"

您也可直接调用 dropbox-helper.js 模块构建自定义自动化工作流。

工作原理

认证流程

1. 初始配置：用户通过 OAuth 2.0 授权本应用
2. 令牌存储：访问令牌与刷新令牌保存至 token.json
3. 自动刷新：每次 API 调用前检查令牌是否需刷新
4. 无缝访问：在令牌过期前 5 分钟自动刷新

令牌生命周期

• 访问令牌（Access Token）：短期有效（通常为 4 小时）
• 刷新令牌（Refresh Token）：长期有效（除非被主动撤销，否则永不过期）
• 自动刷新：由 dropbox-helper.js 透明完成
• 刷新缓冲期：提前 5 分钟刷新，避免边界情况

文件结构

dropbox-integration/
├── SKILL.md                 # 本文档
├── dropbox-helper.js        # 支持自动刷新的 Dropbox 客户端封装
├── setup-oauth.js           # OAuth 配置脚本
├── browse.js                # 浏览文件夹
├── search-files.js          # 搜索文件
├── download.js              # 下载文件
├── test-connection.js       # 认证测试脚本
├── credentials.json.example # 凭据模板文件
├── .gitignore               # 排除 credentials.json 和 token.json
└── references/
    └── setup-guide.md       # 详细配置指南（含截图）

故障排查

"credentials.json not found"（未找到 credentials.json）

请按快速上手第 3 步说明，创建包含 Dropbox App key 和 secret 的 credentials.json 文件。

"Token refresh failed"（令牌刷新失败）

您的刷新令牌可能已被撤销。请重新运行 node setup-oauth.js 完成重新授权。

"Permission denied"（权限拒绝）错误

请确认已在 Dropbox App 控制台的 Permissions 标签页中启用了必需的权限项。

"redirect_uri_mismatch"（重定向 URI 不匹配）

请确认已在 Dropbox App Console 中将 http://localhost:3000/callback 添加至应用的重定向 URI 列表。

OAuth 配置卡住

若本地服务器未能捕获重定向，请在浏览器完成授权后，手动复制完整 URL，并从中提取 code= 参数值。

限制条件

• 只读限制：不可上传、修改或删除文件（设计使然）
• 文件大小：单次下载实际限制约为 150MB（受 Dropbox API 约束）
• 速率限制：Dropbox API 存在速率限制（个人使用通常不受影响）
• 共享文件夹：访问能力取决于您的 Dropbox 账户所拥有的具体权限

安全最佳实践

1. 切勿提交凭据：credentials.json 与 token.json 均已列入 .gitignore
2. 文件权限：令牌文件以 0600 模式（仅所有者可读写）保存
3. 应用专属令牌：每个应用拥有独立令牌（可随时单独撤销）
4. 最小权限原则：仅申请实际所需的权限范围
5. 令牌轮换：刷新令牌将自动轮换

参考资料

参考文档

• 配置指南 — 含截图的详细分步说明
• Dropbox API 文档
• OAuth 2.0 指南

Dropbox 开发者资源

• App Console — 管理您的应用
• API Explorer — 在线测试 API 请求
• SDK 文档 — JavaScript SDK 参考手册

高级用法

使用 Helper 模块

如需构建自定义集成，可直接引入 helper 模块：

const { getDropboxClient } = require('./dropbox-helper');

async function myCustomFunction() {
  const dbx = await getDropboxClient(); // 自动刷新的客户端
  
  // 可调用任意 Dropbox SDK 方法
  const response = await dbx.filesListFolder({ path: '/Photos' });
  console.log(response.result.entries);
}

该 helper 模块自动处理令牌刷新，您无需关心过期问题。

批量操作

按顺序下载多个文件：

const { getDropboxClient } = require('./dropbox-helper');
const fs = require('fs').promises;

async function downloadMultiple(files) {
  const dbx = await getDropboxClient();
  
  for (const file of files) {
    const response = await dbx.filesDownload({ path: file.dropboxPath });
    await fs.writeFile(file.localPath, response.result.fileBinary);
    console.log(`Downloaded: ${file.dropboxPath}`);
  }
}

依赖项

本技能依赖 dropbox npm 包：

npm install dropbox

当您通过 ClawHub 安装本技能时，该包将自动安装。

许可证

MIT 协议 — 免费使用、修改与分发。

支持

如遇问题或疑问，请参考以下途径：

• 查阅《配置指南》获取详细操作说明
• 参考 Dropbox API 文档排查 API 错误
• 在本技能的代码仓库中提交 Issue

注意：本技能面向个人使用场景设计。对于面向多用户的生产级应用，请考虑实现完整的 OAuth 流程，包括 state 状态管理及并发用户的错误处理机制。