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

• - List contents of any folder in your Dropbox
• View file sizes and modification dates
• Navigate folder hierarchies

Search Files

• - Full-text search across file names
• Find files anywhere in your Dropbox
• Get file metadata and locations

Download Files

• - Download any file from your Dropbox
• Save to local filesystem
• Batch download support

Automatic Token Management

• - OAuth 2.0 authentication with refresh tokens
• Automatic token refresh (no manual re-authentication)
• Secure credential storage
• Token expiration handling with 5-minute buffer

Security & Permissions

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

• - files.metadata.read - Read file/folder metadata
• INLINECODE1 - Read file content
• INLINECODE2 - Read account information

NOT included:

• - ❌ files.content.write - Cannot upload or modify files
• ❌ files.metadata.write - Cannot rename or move files
• ❌ files.permanent_delete - Cannot delete files

This ensures your Dropbox content remains safe from accidental modifications.

Prerequisites

Before using this skill, you need:

1. 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:

• - API: Scoped access
• Access type: Full Dropbox (or App folder for restricted access)
• App name: Something unique like "OpenClaw-YourName"

2. Configure OAuth

In your app's settings:

1. 1. Add redirect URI: INLINECODE7
2. Copy your App key and App secret
3. Under Permissions tab, enable:

- files.metadata.read
- files.content.read
- INLINECODE10

3. Save Credentials

Create credentials.json in the skill directory:

CODEBLOCK0

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

4. Run OAuth Setup

CODEBLOCK1

This will:

1. 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 INLINECODE12

5. Test Connection

CODEBLOCK2

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

Usage Examples

Browse a Folder

CODEBLOCK3

Output:
CODEBLOCK4

Search Files

CODEBLOCK5

Output:
CODEBLOCK6

Download Files

CODEBLOCK7

Output:
CODEBLOCK8

Integration with OpenClaw

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

Browse files:
CODEBLOCK9

Search for files:
CODEBLOCK10

Download a file:
CODEBLOCK11

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

How It Works

Authentication Flow

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

Token Lifecycle

• - Access Token: Short-lived (typically 4 hours)
• Refresh Token: Long-lived (doesn't expire unless revoked)
• Auto-refresh: Happens transparently in INLINECODE16
• Refresh Buffer: 5 minutes before expiration to prevent edge cases

File Structure

CODEBLOCK12

Troubleshooting

"credentials.json not found"

Create credentials.json with your Dropbox app key and secret (see Quick Start step 3).

"Token refresh failed"

Your refresh token may have been revoked. Re-run node setup-oauth.js to re-authenticate.

"Permission denied" errors

Check that you enabled the required permissions in your Dropbox App settings under the Permissions tab.

"redirecturimismatch"

Make sure you added http://localhost:3000/callback to your app's redirect URIs in Dropbox App Console.

OAuth setup gets stuck

If the local server doesn't catch the redirect, manually copy the full URL from your browser after authorization and look for the code= parameter.

Limitations

• - Read-only: Cannot upload, modify, or delete files (by design)
• File size: Practical limit ~150MB per download (Dropbox API constraint)
• Rate limits: Dropbox API has rate limits (typically not an issue for personal use)
• Shared folders: Access depends on your Dropbox account permissions

Security Best Practices

1. 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

• - Setup Guide - Detailed step-by-step instructions with screenshots
• Dropbox API Documentation
• OAuth 2.0 Guide

Dropbox Developer Resources

• - App Console - Manage your apps
• API Explorer - Test API calls
• SDK Documentation - JavaScript SDK reference

Advanced Usage

Using the Helper Module

For custom integrations, import the helper directly:

CODEBLOCK13

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

Batch Operations

Download multiple files in sequence:

CODEBLOCK14

Dependencies

This skill requires the dropbox npm package:

CODEBLOCK15

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:

• - Check the Setup Guide for detailed instructions
• Review Dropbox API errors in the API documentation
• Open an issue on the skill repository

---

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.