Workspace Admin APIs

July 9, 2026 · View on GitHub

OpenClaw.NET exposes a set of admin endpoints under /admin/workspace/* for workspace file management and MCP server configuration. These APIs are designed for operator workflows and are separate from the MCP App host/proxy surface.

Endpoints

Workspace Files

MethodEndpointPurpose
GET/admin/workspace/browse?path=<relative-path>Flat directory listing with file metadata
GET/admin/workspace/tree?path=<relative-path>&depth=<max-depth>Recursive directory tree (default depth: 6)
POST/admin/workspace/upload?dir=<relative-path>Upload files (multipart) or extract ZIP archives
GET/admin/workspace/download?path=<relative-path>Download a single file

Browse Response

{
  "success": true,
  "files": [
    { "name": "readme.md", "path": "docs/readme.md", "isDirectory": false, "size": 2048 }
  ]
}

Tree Response

{
  "success": true,
  "root": "docs",
  "entries": [
    {
      "name": "docs",
      "path": "docs",
      "isDir": true,
      "children": [
        { "name": "readme.md", "path": "docs/readme.md", "isDir": false, "size": 2048 }
      ]
    }
  ]
}

Upload

  • Single ZIP file: extracted into the target directory with ZIP-slip protection
  • Multiple regular files: saved directly to the target directory
  • Maximum file size: configurable via MaxUploadBytes

Workspace MCP

MethodEndpointPurpose
GET/admin/workspace/mcpGet current workspace MCP server config
PUT/admin/workspace/mcpPersist and hot-reload MCP server config

This surface is for ordinary Plugins:Mcp server definitions. When the config is updated via PUT, the gateway hot-reloads the live MCP tool surface without a restart. This is separate from MCP Apps — see MCPAPP.md for the manifest-discovered MCP App flow.

Media

MethodEndpointPurpose
POST/media/uploadUpload media files for channel use
GET/media/{id}Serve uploaded media

Digital Employee

MethodEndpointPurpose
POST/admin/digital-employee/uploadUpload a digital employee ZIP package

Authentication

All /admin/* endpoints require operator authentication. See GLOSSARY.md for auth mode details (bootstrap token, operator account token, browser session, OIDC JWT).

Security

  • ZIP-slip protection: all extracted paths are validated to stay within the target directory
  • File size limits prevent resource exhaustion
  • Path traversal is rejected with a 400 response
  • Audit entries are written for upload operations