How to Set Up OpenClaw Agent Workspaces

What Is an OpenClaw Agent Workspace?

An OpenClaw agent workspace is a persistent cloud environment for OpenClaw agents to store, organize, and collaborate on files.

OpenClaw is an open-source framework for building multi-agent AI systems (see openclaw.dev). Agents handle tasks like data extraction, report generation, but struggle with file persistence across sessions or machines.

Fast.io provides the backend: unlimited workspaces, 50GB free storage, built-in RAG, sharing. The ClawHub skill (install via clawhub install dbalve/fast-io) gives agents 14 natural language tools.

Key Benefits

• Persistence: Files survive agent restarts.
• Organization: Folders, permissions, search.
• Intelligence: Semantic queries with citations.
• Collaboration: Share with humans/clients.

Without workspaces, files clutter local disks or vanish. Fast.io solves this for production agents. Unlike short-term APIs such as OpenAI Files,

Key Features Available

Fast.io workspaces give OpenClaw agents reliable file management.

Storage and Uploads Upload files up to 1GB per file using resumable chunked uploads. This handles large artifacts like generated reports, datasets, or media files from agent tasks.

Universal Previews Preview PDFs, HLS-streamed videos (adaptive bitrate for smooth playback), images, audio with interactive waveforms, and spreadsheets. No additional software needed. Everything works via MCP tools.

Intelligence Mode (RAG) Enable per workspace for automatic indexing. Files are semantically searchable. Agents can ask "find budget discussions from Q1" and get cited answers.

Advanced Sharing Send mode for one-way delivery, Receive for client uploads, Exchange for back-and-forth collaboration. Add passwords, expiration dates, and domain restrictions.

Anchored Comments Pin comments to image regions, video timestamps (frame-accurate), or PDF pages. Great for agent-human review loops.

Reactive Webhooks Get notified on file events (upload, edit, download). Build workflows like "summarize new uploads automatically."

URL Imports Import from Google Drive, Dropbox, OneDrive via OAuth. Agents pull files without local I/O, perfect for cloud-native agents.

The free agent plan provides 50GB storage and 5,000 credits monthly. No credit card required.

Agents use 251 MCP tools matching UI capabilities, hosted at mcp.fast.io. See the MCP docs for tool list.

How to Install the Fast.io ClawHub Skill

Setting up the Fast.io skill in OpenClaw takes minutes.

Step 1: Install the Skill In your terminal, run:

npx clawhub@latest install dbalve/fast-io

Or if ClawHub CLI installed:

clawhub install dbalve/fast-io

This adds the Fast.io skill to your OpenClaw environment.

Step 2: Authenticate On first tool use, your agent opens a browser to fast.io. Create a free agent account, no credit card, no trial. Authentication tokens persist across sessions.

Step 3: Verify Call session-status to confirm. Your agent now has 14 tools: org-create-workspace, workspace-storage-list, ai-chat-create, share-send-create, and more.

Pro Tip Add llms.txt context from fast.io/llms.txt for self-onboarding. Works with Claude, GPT, Gemini, or local LLMs.

If issues, check OpenClaw docs or MCP skill page.

How to Create and Manage Workspaces

With the skill ready, agents manage workspaces like humans.

1. Create Organization Agents auto-sign up to the free plan (50GB, 5k credits). Use org-create if needed.

2. Create Workspace

workspace = await mcp.call("org-create-workspace", {"name": "client-project", "description": "Q1 deliverables"})

Workspaces scope files, permissions, and costs.

3. Upload Files Local: storage-upload-local URL: storage-import-url from Drive/Dropbox. Chat: Pipe attachments directly.

4. Enable Intelligence Toggle via workspace-update-intelligence {"enabled": true}. Files index for RAG queries.

Example: Full Upload Flow

// Create session
session = await mcp.call("upload-create-session", {
  "workspace": "project", 
  "path": "/reports/", 
  "filename": "q1.pdf"
})

// Upload chunks
await mcp.call("upload-append-chunk", {"session": session.id, "chunk": bytes_data})

// Complete
result = await mcp.call("upload-complete", {"session": session.id})

Management Commands

• workspace-storage-list: Browse files
• storage-move: Organize
• storage-delete: Cleanup
• file-lock-acquire: Multi-agent safety

See agent storage docs for full API.

Best Practices for OpenClaw Agents

Follow these best practices for reliable OpenClaw agent file management.

Workspace Organization Create one workspace per project or client (e.g., "acme-q1-reports"). This scopes storage, permissions, and costs. Avoid single massive workspaces.

Intelligence Mode Wisely Enable only for workspaces needing queries or summaries. Disable for pure storage to save credits.

Sharing Best Practices Use shared folders for live team views, data rooms for client snapshots. Set expirations and passwords for security.

Multi-Agent Safety Acquire locks with file-lock-acquire before edits. Release after. Prevents conflicts in supervisor-worker patterns.

Credit Monitoring Poll auth-status weekly. If low, create transfer-token to hand off to human, or optimize (e.g., delete old versions).

Automated Organization Parse chat attachments: WhatsApp images to /chats/whatsapp/images/, PDFs to /documents/. Use storage-move in post-import hooks.

Reactive Workflows Webhooks on "file_uploaded" trigger summarization or notifications. POST payloads include file metadata and diffs.

Version Control Every edit creates a version. List with storage-versions-list, restore via storage-version-restore. Audit with workspace-activity-list.

Check the pricing page for usage details. These practices help agents scale from prototype to production.

Advanced Workflows

Access advanced features for complex agent systems.

Scoped RAG Queries Limit searches:

response = await mcp.call("ai-chat-create", {
  "workspace": "project",
  "query": "What is the Q1 budget overrun?",
  "scope_folders": ["/reports/", "/budgets/"]
})

Returns cited excerpts from scoped files.

Ownership Transfer Workflow

1. Agent builds org and workspaces.
2. Generate token: token = await mcp.call("transfer-token-create", {"target_email": "client@example.com"})
3. Share claim URL: https://fast.io/claim/${token.id} Human claims ownership; agent keeps admin access.

Human-Agent Collaboration Invite humans: workspace-member-invite {"email": "teammate@company.com", "role": "editor"} Humans use web UI for previews/comments; agents MCP for automation. Anchored comments sync across.

Multi-LLM Compatibility ClawHub skill works with any LLM: Claude (Anthropic), GPT-4o (OpenAI), Gemini (Google), LLaMA (local). Switch providers without recoding.

File Locks for Concurrency

lock = await mcp.call("file-lock-acquire", {"workspace": "proj", "path": "/shared/report.md"})
// Edit file
await mcp.call("file-lock-release", {"lock": lock.id})

Webhook Integration Register: webhook = await mcp.call("webhook-register", {"events": ["file_uploaded"], "url": "https://your-agent/webhook"}) Handles real-time triggers without polling.

Integrate with product AI features for full stack.

Troubleshooting Common Setup Issues

Authentication Problems Symptom: "Invalid session" errors. Fix: Run auth-logout, then retry tool call to re-auth. Tokens persist across sessions.

Upload Failures Symptom: Chunk errors on large files. Fix: Always use upload-create-session for large files. Check network and session status.

Credit Limits Hit Symptom: rate limit errors. Fix: auth-status shows breakdown. Delete old files (storage-delete-batch), disable intelligence on low-query workspaces.

RAG Returns Nothing Symptom: Empty responses. Fix: Indexing is async; wait a few minutes. Check workspace-intelligence-status. Re-ingest if changed.

Webhook Silent Symptom: No events. Fix: Verify endpoint responds successfully. Test with webhook-test.

Skill Not Found Fix: Reinstall clawhub install dbalve/fast-io. Check ClawHub directory.

Full logs in storage for OpenClaw page. Community support via GitHub issues.