Dropbox 集成

概述

此技能提供对您 Dropbox 账户的只读访问权限，允许您在 OpenClaw 中浏览文件夹、搜索文件并下载内容。它使用 OAuth 2.0 认证，并支持自动令牌刷新，实现无缝的长期访问。

适用场景： 安全地访问您的 Dropbox 文件，无需担心意外修改或删除。

功能特性

浏览文件与文件夹

• 列出 Dropbox 中任意文件夹的内容
• 查看文件大小和修改日期
• 导航文件夹层级结构

搜索文件

• 在文件名中进行全文搜索
• 在整个 Dropbox 中查找文件
• 获取文件元数据和位置信息

下载文件

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

自动令牌管理

• 使用刷新令牌的 OAuth 2.0 认证
• 自动刷新令牌（无需手动重新认证）
• 安全存储凭证
• 在令牌过期前 5 分钟缓冲处理，防止失效

安全与权限

此技能配置为只读访问，使用以下 Dropbox 权限范围：

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

不包含：

• ❌ files.content.write - 无法上传或修改文件
• ❌ files.metadata.write - 无法重命名或移动文件
• ❌ files.permanent_delete - 无法删除文件

这确保了您的 Dropbox 内容免受意外修改。

前置条件

使用本技能前，请准备：

1. 一个 Dropbox 账户（免费或付费均可）
2. 一个 Dropbox 应用注册（耗时约 5 分钟）
3. 从您的 Dropbox 应用获取的 应用密钥 和 应用密钥
4. 安装 Node.js 及 dropbox 包（自动安装）

设置时间：约 10 分钟

详见 [设置指南](references/setup-guide.md) 获取详细步骤。

快速开始

1. 创建 Dropbox 应用

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

• API 类型： 范围访问
• 访问类型： 完整 Dropbox（或应用文件夹以限制访问）
• 应用名称： 建议使用如 "OpenClaw-YourName" 这类唯一名称

2. 配置 OAuth

在应用设置中：

1. 添加重定向 URI：http://localhost:3000/callback
2. 复制您的 应用密钥 和 应用密钥
3. 在 权限 选项卡中启用：

- 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. 启动本地服务器以捕获授权码
3. 用授权码换取访问令牌和刷新令牌
4. 将令牌安全保存至 token.json

5. 测试连接

node test-connection.js

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

使用示例

浏览文件夹

# 列出根目录
node browse.js

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

输出示例：

📁 列出：/Documents

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

总计：4 项

搜索文件

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

输出示例：

🔍 搜索关键词："budget 2024"

✅ 找到 3 个匹配项：

📄 /Finance/budget-2024-q1.xlsx
   大小：156.3 KB
   修改时间：2024-01-15T10:30:00Z

📄 /Reports/budget-2024-summary.pdf
   大小：2.1 MB
   修改时间：2024-02-01T14:22:00Z

下载文件

# 下载到本地文件
node download.js "/Documents/report.pdf" "./downloads/report.pdf"

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

输出示例：

📥 下载中：/Documents/report.pdf
✅ 已保存至：./downloads/report.pdf (2.3 MB)

与 OpenClaw 的集成

在 OpenClaw 中，您可以使用 exec 工具运行这些脚本：

浏览文件：

运行：node /path/to/dropbox-integration/browse.js "/Documents"

搜索文件：

运行：node /path/to/dropbox-integration/search-files.js "contract"

下载文件：

运行：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 分钟自动刷新，保持连接连续

令牌生命周期

• 访问令牌： 短期有效（通常为 4 小时）
• 刷新令牌： 长期有效（除非被撤销）
• 自动刷新： 在 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 未找到”

请根据快速开始第 3 步创建 credentials.json，填入您的 Dropbox 应用密钥和应用密钥。

“Token refresh failed”

您的刷新令牌可能已被撤销。请重新运行 node setup-oauth.js 以重新进行身份验证。

“Permission denied” 错误

请检查您是否已在 Dropbox App 设置的“权限”选项卡中启用了所需权限。

“redirect_uri_mismatch”

请确保已将 http://localhost:3000/callback 添加到 Dropbox App Console 中的应用程序重定向 URI 列表。

OAuth 设置卡住

如果本地服务器未捕获重定向，请在授权完成后手动复制浏览器中的完整 URL，并查找 code= 参数。

限制

• 只读模式：按设计无法上传、修改或删除文件
• 文件大小：单次下载的实际限制约为 150MB（受 Dropbox API 限制）
• 速率限制：Dropbox API 存在速率限制（个人使用通常不会成为问题）
• 共享文件夹：访问权限取决于您的 Dropbox 账户权限

安全最佳实践

1. 切勿提交凭证：credentials.json 和 token.json 文件已被 gitignore 忽略
2. 文件权限：令牌保存时设置为 0600 模式（仅用户可读写）
3. 应用专属令牌：每个应用拥有独立的令牌（可轻松撤销）
4. 权限最小化：仅请求实际需要的权限
5. 令牌轮换：刷新令牌会自动轮换

资源

参考资料

• [设置指南](references/setup-guide.md) - 带截图的分步详细说明
• [Dropbox API 文档](https://www.dropbox.com/developers/documentation)
• [OAuth 2.0 指南](https://www.dropbox.com/developers/reference/oauth-guide)

Dropbox 开发者资源

• [应用控制台](https://www.dropbox.com/developers/apps) - 管理您的应用
• [API 探索器](https://dropbox.github.io/dropbox-api-v2-explorer/) - 测试 API 调用
• [SDK 文档](https://dropbox.github.io/dropbox-sdk-js/) - JavaScript SDK 参考

高级用法

使用辅助模块

对于自定义集成，可直接导入辅助模块：

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);
}

该辅助模块会自动处理令牌刷新，您无需担心过期问题。

批量操作

按顺序下载多个文件：

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(`已下载: ${file.dropboxPath}`);
  }
}

依赖项

此技能需要 dropbox npm 包：

npm install dropbox

通过 ClawHub 安装本技能时，该包会自动安装。

许可证

MIT - 免费使用、修改和分发。

支持

如遇问题或疑问：

• 查阅 [设置指南](references/setup-guide.md) 以获取详细说明
• 在 [API 文档](https://www.dropbox.com/developers/documentation) 中查看 Dropbox API 错误信息
• 在技能仓库中提交问题

注意：本技能专为个人使用设计。如需用于支持多用户的生产环境应用，请考虑实现带有状态管理及并发用户错误处理的完整 OAuth 流程。