Summary

As OpenClaw adoption grows in containerized and cloud-native environments, users increasingly need a way to manage agent workspace files without direct filesystem access. The current agents.files.* API restricts file operations to a predefined whitelist of bootstrap files (AGENTS.md, MEMORY.md, etc.), which prevents users from:

• Uploading custom configuration files or knowledge bases
• Organizing files in subdirectories
• Downloading generated artifacts or logs
• Managing dynamic file content in remote deployments

This feature request proposes a new agents.workspace.* API namespace that provides comprehensive file management capabilities while maintaining OpenClaw's security boundaries through the existing fs-safe.ts infrastructure.

Problem to solve

Problem Statement

Many OpenClaw users deploy the gateway in containers or cloud environments where direct filesystem access to agent workspaces is difficult or impossible. Currently, the agents.files.* API only allows access to a hardcoded whitelist of files (AGENTS.md, MEMORY.md, etc.), which limits the ability to:

• Upload custom configuration files
• Manage subdirectories within workspaces
• Download generated files (logs, exports, artifacts)
• Organize files in a structured way

Use Cases

1. Cloud Deployment: Users running OpenClaw on VPS/cloud need to upload/download files via Web UI instead of SSH/SCP
2. Container Environments: Docker/Kubernetes deployments without host volume mounts need a way to manage files through the API
3. Multi-agent File Sharing: Copy files between agent workspaces for shared knowledge or configurations
4. Backup/Restore: Export and import entire workspace directories for migration or disaster recovery

Proposed Solution

Add a new agents.workspace.* API namespace with full file management capabilities:

Security Design

The implementation will leverage OpenClaw's existing security infrastructure:

• Workspace Boundaries: All operations are restricted to the agent's workspace directory using resolveAgentWorkspaceDir
• Path Validation: Uses fs-safe.ts infrastructure (resolvePinnedPathWithinRoot) to prevent path traversal attacks
• Permission Control: Read operations require READ_SCOPE, write operations require ADMIN_SCOPE
• Link Protection: Symbolic links and hardlinks are validated and rejected if they escape workspace boundaries
• File Size Limits: Configurable limits (default 10MB) to prevent DoS via large file uploads

Web UI Enhancement

A new "Workspace Files" tab will be added to the Agents page in the Control UI:

• File Tree Browser: Navigate directories with expandable folders
• File Upload: Drag & drop support for uploading files
• File Download: Download individual files or directories as zip
• File Operations: Create new files/folders, delete, rename
• Breadcrumb Navigation: Show current path with clickable parent directories
• File Preview: Text editor for code/markdown files, image preview for common formats

Backward Compatibility

The existing agents.files.* API remains unchanged for accessing core bootstrap files (AGENTS.md, MEMORY.md, etc.). The new agents.workspace.* API provides additional capabilities for full filesystem access within workspace boundaries. Both APIs can coexist:

• agents.files.* - Simple access to core agent files (backward compatible)
• agents.workspace.* - Full filesystem management (new capability)

Implementation Plan

Phase 1: Protocol Schema

• Define TypeBox schemas for all methods
• Add validators to protocol index
• Export types for client use

Phase 2: Gateway Implementation

• Implement server method handlers
• Register methods in server-methods-list
• Configure permission scopes in method-scopes
• Add comprehensive unit tests

Phase 3: Web UI

• Create workspace file controller
• Build file manager UI component
• Integrate into Agents page
• Add e2e tests

Phase 4: Documentation

• API documentation
• User guide for file manager
• Security considerations doc

Questions for Maintainers

1. Security Review: Is the proposed security model (using fs-safe.ts + scope-based permissions) aligned with OpenClaw's security architecture?

2. File Restrictions: Should we enforce specific file type restrictions (e.g., block executable files) beyond the size limit?

3. Audit Logging: Would you like audit logging for file operations (especially deletions and overwrites)?

4. API Naming: Is agents.workspace.* the right namespace, or would you prefer something else?

5. Scope Assignment: Should any write operations (like mkdir) be available with WRITE_SCOPE instead of requiring ADMIN_SCOPE?

6. Binary Handling: Is base64 encoding acceptable for binary file transfer, or would you prefer a different approach?

Looking forward to feedback from the maintainers and community!

Proposed solution

API Design

Introduce seven new gateway methods under the agents.workspace namespace:

1. agents.workspace.list

List directory contents with file metadata.

Use case: Browse workspace structure, populate file tree UI.

// Request
{
  agentId: string;           // Target agent
  path?: string;             // Relative path (default: "")
  recursive?: boolean;       // Include subdirectories (default: false)
}

// Response
{
  agentId: string;
  workspace: string;         // Absolute workspace path
  path: string;              // Current relative path
  entries: Array<{
    name: string;
    path: string;            // Relative to workspace
    type: "file" | "directory" | "symlink";
    size?: number;           // Bytes (files only)
    updatedAtMs?: number;    // Modification time
    createdAtMs?: number;    // Creation time
  }>;
}

2. agents.workspace.get

Read file content with flexible encoding.

Use case: Load file for editing, download binary files.

// Request
{
  agentId: string;
  path: string;              // Relative path to file
  encoding?: "utf8" | "base64";  // Default: "utf8"
}

// Response
{
  agentId: string;
  workspace: string;
  path: string;
  content: string;           // UTF-8 text or base64-encoded binary
  encoding: "utf8" | "base64";
  size: number;              // Actual file size in bytes
  updatedAtMs?: number;
}

3. agents.workspace.set

Write or overwrite file content.

Use case: Save edited files, upload new content.

// Request
{
  agentId: string;
  path: string;              // Relative path (parent dirs created if needed)
  content: string;           // UTF-8 text or base64-encoded binary
  encoding?: "utf8" | "base64";  // Default: "utf8"
  createDirs?: boolean;      // Auto-create parent directories (default: true)
}

// Response
{
  ok: true;
  agentId: string;
  path: string;
  size: number;
  updatedAtMs: number;
}

4. agents.workspace.delete

Remove files or directories.

Use case: Clean up temporary files, remove obsolete data.

// Request
{
  agentId: string;
  path: string;              // Relative path to file or directory
  recursive?: boolean;       // Delete non-empty directories (default: false)
}

// Response
{
  ok: true;
  agentId: string;
  path: string;
  deleted: boolean;          // True if existed and was deleted
}

5. agents.workspace.mkdir

Create new directories.

Use case: Organize files into folders, create project structure.

// Request
{
  agentId: string;
  path: string;              // Relative path to new directory
  parents?: boolean;         // Create parent directories if needed (default: true)
}

// Response
{
  ok: true;
  agentId: string;
  path: string;
  created: boolean;          // True if created, false if already existed
}

6. agents.workspace.move

Move or rename files and directories.

Use case: Rename files, reorganize directory structure.

// Request
{
  agentId: string;
  from: string;              // Source relative path
  to: string;                // Destination relative path
  overwrite?: boolean;       // Overwrite if exists (default: false)
}

// Response
{
  ok: true;
  agentId: string;
  from: string;
  to: string;
}

7. agents.workspace.stat

Get file/directory metadata without reading content.

Use case: Check file existence, get size/timestamp info.

// Request
{
  agentId: string;
  path: string;              // Relative path
}

// Response
{
  agentId: string;
  workspace: string;
  path: string;
  type: "file" | "directory" | "symlink";
  size?: number;             // Undefined for directories
  updatedAtMs?: number;
  createdAtMs?: number;
  isWritable: boolean;       // Current user has write permission
}

Security Architecture

The implementation leverages OpenClaw's existing security infrastructure:

Path Safety

All file operations use the fs-safe.ts module which provides:

• Path traversal prevention: Rejects paths containing .. or absolute paths
• Workspace boundary enforcement: Validates resolved paths stay within resolveAgentWorkspaceDir
• Symbolic link validation: Follows symlinks and verifies targets remain in workspace
• Hardlink protection: Rejects files with nlink > 1

Example validation flow:

const resolved = await resolvePinnedPathWithinRoot({
  rootDir: workspaceDir,
  relativePath: userProvidedPath,
});
// Throws SafeOpenError if path escapes workspace

Permission Model

Resource Limits

Default constraints (configurable):

• Maximum file size: 10MB for uploads
• Maximum directory depth: 10 levels for recursive operations
• Maximum entries per list: 1000 files (pagination support for future)

Web UI Integration

A new "Workspace Files" tab will be added to the Agents page:

Layout

┌─────────────────────────────────────────────────────────┐
│ [New File] [New Folder] [Upload] [Download] [Refresh]   │
├─────────────────────────────────────────────────────────┤
│ Workspace / agent-name / 📁 subdir / 📄 current-file    │
├────────────────────────┬────────────────────────────────┤
│ 📁 folder1             │ ┌────────────────────────────┐ │
│ 📁 folder2             │ │ File Editor / Preview      │ │
│   📄 nested.md         │ │                            │ │
│ 📄 file1.md            │ │ [Content area with syntax  │ │
│ 📄 file2.json          │ │  highlighting for code]    │ │
│ 📄 image.png           │ │                            │ │
│                        │ └────────────────────────────┘ │
│                        │ [Save] [Delete] [Rename]       │
└────────────────────────┴────────────────────────────────┘

Features

• Tree Navigation: Expandable folder tree with lazy loading
• Breadcrumb Path: Clickable navigation to parent directories
• Drag & Drop Upload: Drop files from desktop to upload
• Context Menu: Right-click for file operations (rename, delete, download)
• Keyboard Shortcuts: F2 (rename), Delete, Ctrl+S (save)
• File Preview:
  • Text editor with syntax highlighting for code/markdown
  • Image preview for PNG/JPG/GIF/SVG
  • Download button for binary files

Backward Compatibility

The existing agents.files.* API remains fully functional and unchanged:

• agents.files.list - Continues to show whitelist files (AGENTS.md, MEMORY.md, etc.)
• agents.files.get - Continues to read whitelist files
• agents.files.set - Continues to write whitelist files

The new agents.workspace.* API operates independently:

• No changes to existing API behavior
• No migration required
• Both APIs can be used simultaneously
• Existing scripts and integrations continue to work

Implementation Phases

Phase 1: Protocol Schema (2-3 days)

• Define TypeBox schemas for all methods
• Add validators to src/gateway/protocol/index.ts
• Export types for TypeScript clients
• Add method names to src/gateway/server-methods-list.ts
• Configure scopes in src/gateway/method-scopes.ts

Phase 2: Gateway Implementation (5-7 days)

• Implement handlers in src/gateway/server-methods/agents-workspace.ts
• Use fs-safe.ts utilities for all file operations
• Add comprehensive unit tests covering:
  • Normal operations
  • Path traversal attacks
  • Symbolic link edge cases
  • Permission checks
  • Error handling

Phase 3: Web UI (5-7 days)

• Create ui/src/ui/controllers/agent-workspace.ts
• Build ui/src/ui/views/agents-panels-workspace.ts
• Integrate into Agents page tab navigation
• Add e2e tests for file manager workflows

Phase 4: Documentation (2-3 days)

• API documentation in docs/gateway/workspace-api.md
• User guide for file manager UI
• Security considerations document
• Update changelog

Error Handling

Standardized error responses:

Open Questions for Maintainers

1. Scope Assignment: Should mkdir require ADMIN_SCOPE, or would WRITE_SCOPE be sufficient for directory creation?

2. Binary Transfer: Is base64 encoding acceptable for binary files, or should we consider alternative approaches like multipart/form-data for uploads?

3. Audit Logging: Should file operations (especially deletions) be logged for security auditing?

4. File Type Restrictions: Beyond size limits, should we block specific file types (executables, scripts) from upload?

5. Batch Operations: Should we support batch operations (delete multiple files, upload multiple files) in the initial implementation or as a future enhancement?

Alternatives considered

No response

Impact

Overview

This feature significantly expands OpenClaw's deployment flexibility and user experience, particularly for production and enterprise use cases. Below is a comprehensive analysis of the impact across multiple dimensions.

User Impact

Who Benefits

Use Cases Enabled

1. Cloud-Native Deployments

Before: Deploy OpenClaw on VPS → SSH into server → Use vim/nano to edit files → Restart services

After: Open Web UI → Navigate to Workspace Files → Edit directly in browser → Changes apply immediately

Impact: Reduces file management time from minutes to seconds; no SSH knowledge required.

2. Knowledge Base Management

Before: Limited to AGENTS.md and MEMORY.md; large knowledge bases must be external

After: Create knowledge/ subdirectory → Upload multiple markdown files → Agent can reference organized documentation

Impact: Enables sophisticated knowledge organization for complex domains.

3. Multi-Agent Collaboration

Before: Each agent isolated; sharing requires manual file copying

After: Agent A generates report → Save to shared workspace → Agent B reads and processes

Impact: Enables agent workflows and specialization (researcher → writer → reviewer).

4. Backup and Migration

Before: Must tar.gz workspace directories manually

After: Download entire workspace as zip → Upload to new instance → Done

Impact: Simplifies disaster recovery and environment migration.

Technical Impact

Architecture Alignment

Performance Considerations

Resource Usage

• Memory: Minimal increase; file operations are streaming where possible
• CPU: Path validation adds ~1-2ms per operation (negligible)
• Storage: No change; uses existing workspace directories
• Network: Base64 encoding adds ~33% overhead for binary transfers

Scalability

• Concurrent Operations: Handled by Node.js event loop; no blocking
• Large Files: 10MB default limit prevents memory issues
• Deep Directories: 10-level depth limit prevents recursion issues
• Rate Limiting: Can leverage existing gateway rate limiting

Security Impact

Attack Surface Analysis

Security Benefits

• Audit Trail: API operations can be logged (future enhancement)
• No Shell Access: File operations don't require system shell
• Workspace Isolation: Agents cannot access each other's files
• Input Validation: Strict schema validation on all inputs

Ecosystem Impact

Integration Possibilities

Third-Party Tools

• VS Code Extension: Edit agent files directly in IDE
• Obsidian Plugin: Sync knowledge base with agent workspace
• CI/CD Pipelines: Deploy configurations to agents automatically
• Backup Services: Automated workspace backup to S3/cloud storage

Skill Development

Skills can now:

• Generate and save artifacts (reports, exports, summaries)
• Read configuration from JSON/YAML files
• Maintain persistent state across sessions
• Share data between different skill invocations

Example skill use case:

// A research skill that saves findings for later analysis
await saveToWorkspace('research/findings.json', JSON.stringify(results));

// A report skill that reads and compiles previous findings
const findings = await readFromWorkspace('research/findings.json');

Community Impact

Contribution Opportunities

• UI Improvements: File manager can be enhanced with themes, plugins
• New Skills: File-based skills become possible
• Documentation: Community can share workspace templates
• Tooling: CLI tools, desktop apps can use the API

Learning Curve

• Beginners: Easier to get started (no SSH needed)
• Advanced Users: More powerful automation possibilities
• Enterprise: Better fits existing security/audit requirements

Business Impact

Adoption Enablers

Cost Implications

Infrastructure

• No additional costs: Uses existing workspace storage
• Optional: Can integrate with S3/MinIO for larger storage (future)

Operational

• Reduced support burden: Self-service file management
• Faster onboarding: New users don't need SSH training
• Easier debugging: Download logs and state files directly

Migration and Compatibility

Backward Compatibility

100% Backward Compatible

• Existing agents.files.* API unchanged
• All existing scripts continue to work
• No configuration changes required
• No database migrations needed

Upgrade Path

Risk Assessment

Potential Risks and Mitigations

Fallback Strategy

If critical issues are discovered:

1. Disable via config: Add features.workspaceFiles: false option
2. Scope restriction: Require stricter scopes temporarily
3. Rate limiting: Aggressive limits to reduce impact
4. Full rollback: Remove endpoints without affecting existing functionality

Success Metrics

Quantitative

Qualitative

• User Feedback: Positive mentions in Discord/community
• Documentation: Reduced "how to manage files" questions
• Adoption: More cloud/container deployment success stories
• Contributions: Community contributions to file manager UI

Long-Term Vision

Phase 2 Possibilities

1. Remote Storage: S3, GCS, Azure Blob integration for unlimited storage
2. Version Control: Git integration for workspace versioning
3. Collaboration: Real-time collaborative editing
4. Templates: Pre-built workspace templates for common use cases
5. Sync: Desktop sync client for local file editing

Alignment with Project Goals

Conclusion

This feature addresses a critical gap in OpenClaw's deployment story while maintaining the project's high security standards. The impact is:

• Immediate: Better UX for existing users
• Short-term: Enables new deployment patterns
• Long-term: Foundation for advanced features

The implementation is low-risk due to:

• Use of proven security infrastructure (fs-safe.ts)
• Additive-only changes (no breaking changes)
• Comprehensive test coverage
• Clear rollback path

Recommendation: Proceed with implementation.

Evidence/examples

No response

Additional information

No response