Dropbox Integration

Dropbox Integration

Overview

This skill provides read-only access to your Dropbox account, allowing you to browse folders, search files, and download content from OpenClaw. It uses OAuth 2.0 authentication with automatic token refresh for seamless long-term access.

Perfect for: Safely accessing your Dropbox files without worrying about accidental modifications or deletions.

Capabilities

Browse Files & Folders

Search Files

Download Files

Automatic Token Management

Security & Permissions

This skill is configured for read-only access with the following Dropbox scopes:

NOT included:

This ensures your Dropbox content remains safe from accidental modifications.

Prerequisites

Before using this skill, you need:

1. A Dropbox account (free or paid) 2. A Dropbox App registration (takes 5 minutes) 3. App key and App secret from your Dropbox App 4. Node.js with dropbox package (auto-installed)

Setup time: ~10 minutes

See Setup Guide for step-by-step instructions.

Quick Start

1. Create Dropbox App

Visit https://www.dropbox.com/developers/apps/create and create a new app:

2. Configure OAuth

In your app's settings: 1. Add redirect URI: http://localhost:3000/callback 2. Copy your App key and App secret 3. Under Permissions tab, enable: - files.metadata.read - files.content.read - account_info.read

3. Save Credentials

Create credentials.json in the skill directory:

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

Important: This file is gitignored and will never be committed.

4. Run OAuth Setup

node setup-oauth.js

This will: 1. Open your browser for Dropbox authorization 2. Start a local server to capture the authorization code 3. Exchange the code for access + refresh tokens 4. Save tokens securely to token.json

5. Test Connection

node test-connection.js

If successful, you'll see your Dropbox account information!

Usage Examples

Browse a Folder

# List root folder
node browse.js
List specific folder
node browse.js "/Documents"
node browse.js "/Photos/2024"

Output:

📁 Listing: /Documents
📄 report.pdf (2.3 MB) - 2024-02-01
📄 presentation.pptx (5.1 MB) - 2024-01-28
📁 Projects
📁 Archive
Total: 4 items

Search Files

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

Output:

🔍 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

Download Files

# Download to local file
node download.js "/Documents/report.pdf" "./downloads/report.pdf"
Download to current directory
node download.js "/Photos/vacation.jpg" "./vacation.jpg"

Output:

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

Integration with OpenClaw

From OpenClaw, you can use the exec tool to run these scripts:

Browse files:

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

Search for files:

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

Download a file:

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

Or create custom automation workflows that use the dropbox-helper.js module directly.

How It Works

Authentication Flow

1. Initial Setup: User authorizes the app via OAuth 2.0 2. Token Storage: Access token + refresh token saved to token.json 3. Auto-Refresh: Before each API call, checks if token needs refresh 4. Seamless Access: Automatically refreshes tokens 5 minutes before expiration

Token Lifecycle

File Structure

dropbox-integration/
├── SKILL.md                 # This file
├── dropbox-helper.js        # Auto-refresh Dropbox client
├── setup-oauth.js           # OAuth setup script
├── browse.js                # Browse folders
├── search-files.js          # Search files
├── download.js              # Download files
├── test-connection.js       # Test authentication
├── credentials.json.example # Template for credentials
├── .gitignore               # Excludes credentials.json and token.json
└── references/
    └── setup-guide.md       # Detailed setup instructions

Troubleshooting

"credentials.json not found"

"Token refresh failed"

"Permission denied" errors

"redirect_uri_mismatch"

OAuth setup gets stuck

Limitations

Security Best Practices

1. Never commit credentials: credentials.json and token.json are gitignored 2. File permissions: Tokens are saved with mode 0600 (user read/write only) 3. App-specific tokens: Each app has its own tokens (easily revokable) 4. Scope limitation: Only request permissions you actually need 5. Token rotation: Refresh tokens are rotated automatically

Resources

References

Dropbox Developer Resources

Advanced Usage

Using the Helper Module

For custom integrations, import the helper directly:

const { getDropboxClient } = require('./dropbox-helper');
async function myCustomFunction() {
  const dbx = await getDropboxClient(); // Auto-refreshing client
  
  // Use any Dropbox SDK method
  const response = await dbx.filesListFolder({ path: '/Photos' });
  console.log(response.result.entries);
}

The helper automatically handles token refresh, so you never need to worry about expiration.

Batch Operations

Download multiple files in sequence:

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

Dependencies

This skill requires the dropbox npm package:

npm install dropbox

The package is automatically installed when you install this skill via ClawHub.

License

MIT - Free to use, modify, and distribute.

Support

For issues or questions:

Note: This skill is designed for personal use. For production applications with multiple users, consider implementing proper OAuth flow with state management and error handling for concurrent users.

1. Create Dropbox App

Visit https://www.dropbox.com/developers/apps/create and create a new app:

2. Configure OAuth

In your app's settings: 1. Add redirect URI: http://localhost:3000/callback 2. Copy your App key and App secret 3. Under Permissions tab, enable: - files.metadata.read - files.content.read - account_info.read

3. Save Credentials

Create credentials.json in the skill directory:

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

Important: This file is gitignored and will never be committed.

4. Run OAuth Setup

node setup-oauth.js

This will: 1. Open your browser for Dropbox authorization 2. Start a local server to capture the authorization code 3. Exchange the code for access + refresh tokens 4. Save tokens securely to token.json

5. Test Connection

node test-connection.js

If successful, you'll see your Dropbox account information!

Before using this skill, you need:

1. A Dropbox account (free or paid) 2. A Dropbox App registration (takes 5 minutes) 3. App key and App secret from your Dropbox App 4. Node.js with dropbox package (auto-installed)

Setup time: ~10 minutes

See Setup Guide for step-by-step instructions.

"credentials.json not found"

"Token refresh failed"

"Permission denied" errors

"redirect_uri_mismatch"

OAuth setup gets stuck