@clawpilot-app/clawpilot-media-bridge

ClawPilot media bridge plugin for OpenClaw.

It lets an OpenClaw agent:

• upload a gateway-local image or file to ClawPilot R2-backed media storage
• get back a stable capability URL
• return structured upload metadata that ClawPilot App can render as attachment cards
• fetch a ClawPilot capability URL back to a local temp file when the agent needs bytes

The plugin is intentionally tool-first. It does not hijack Feishu, Discord, Telegram, or any other channel send path.

What This Plugin Registers

• Tool: clawpilot_media_upload
• Tool: clawpilot_media_fetch
• Gateway RPC: clawpilot_media.status
• Skill: clawpilot-media-bridge

Install

Canonical npm install command:

openclaw plugins install @clawpilot-app/clawpilot-media-bridge

Local archive install is also supported:

openclaw plugins install ./clawpilot-media-bridge.tgz

After installation, restart the gateway.

Config

Add or update the plugin entry in ~/.openclaw/openclaw.json:

{
  plugins: {
    allow: ["clawpilot-media-bridge"],
    entries: {
      "clawpilot-media-bridge": {
        enabled: true,
        config: {
          serverBaseUrl: "https://api.clawpilot.me",
          gatewayClientId: "YOUR_GATEWAY_CLIENT_ID",
          mediaBridgeToken: "mbt_xxx",
          uploadMaxBytes: 104857600,
          downloadHostAllowlist: ["api.clawpilot.me", "media.clawpilot.me"],
          allowedMessageChannels: ["webchat"],
        },
      },
    },
  },
}

Field notes:

• plugins.allow: if you maintain an explicit plugin allowlist, include clawpilot-media-bridge here. If you already trust other plugins, append this id instead of replacing the list.
• serverBaseUrl: ClawPilot server origin or origin+base-path.
• gatewayClientId: the gateway client id bound in ClawPilot server.
• mediaBridgeToken: bearer token issued by ClawPilot server for this gateway.
• uploadMaxBytes: hard transport cap. Default 104857600 (100 MB).
• downloadHostAllowlist: hosts that clawpilot_media_fetch may download from.
• allowedMessageChannels: defaults to ["webchat"] so the plugin stays scoped to ClawPilot App style sessions.
• allowedAgentIds: optional extra guard if you only want this plugin available to a dedicated app agent.

App Onboarding Flow

Recommended product flow:

1. User installs the plugin with openclaw plugins install @clawpilot-app/clawpilot-media-bridge
2. User restarts the gateway
3. ClawPilot App calls clawpilot_media.status
4. If hasMediaBridgeToken is false, the app requests a token from ClawPilot server
5. The app writes plugins.entries.clawpilot-media-bridge.config
6. User restarts the gateway again so the new config takes effect

Model-Facing Usage

This section is written so both humans and agents can understand the intended usage.

Sending a generated image or file back to the user

1. Generate or locate a local file path on the gateway host.
2. Call clawpilot_media_upload.
3. In normal ClawPilot App replies, return a short natural sentence and let the app render attachment cards from tool events.

Do not hand-write capability URLs. Do not hand-write CP_MEDIA_V1 payloads.

The plugin returns:

• CP_MEDIA_V1:<base64url-json> for images and generic files

Only when the user explicitly asks for the raw link/directive line should the agent return assistantDirective verbatim.

Reading a file that came from ClawPilot App

If the user message already contains a ClawPilot capability URL or a CP_MEDIA_V1 block and the agent needs the local bytes, call clawpilot_media_fetch.

That tool downloads the file to a local temp path and returns:

• localPath
• fileName
• mimeType
• sizeBytes

Tool Reference

clawpilot_media_upload

Purpose:

• Upload a gateway-local file to ClawPilot media storage.
• Return structured media metadata and a backward-compatible directive line.

Input:

{
  "path": "/tmp/report.pdf",
  "kind": "auto",
  "fileName": "report.pdf",
  "mimeType": "application/pdf"
}

Key output fields:

{
  "ok": true,
  "mediaId": "med_xxx",
  "publicId": "mpub_xxx",
  "kind": "file",
  "capabilityUrl": "https://media.clawpilot.me/openclaw-media/2026/03/19/med_xxx/report.pdf",
  "assistantDirective": "CP_MEDIA_V1:...",
  "markdownLink": "[report.pdf](https://media.clawpilot.me/openclaw-media/2026/03/19/med_xxx/report.pdf)"
}

clawpilot_media_fetch

Purpose:

• Download an allowed ClawPilot capability URL to a temp file on the gateway host.

Input:

{
  "capabilityUrl": "https://media.clawpilot.me/openclaw-media/2026/03/19/med_xxx/report.pdf",
  "expectedFileName": "report.pdf",
  "expectedMimeType": "application/pdf"
}

clawpilot_media.status

Purpose:

• Let ClawPilot App detect whether the plugin is installed, enabled, and configured.

Example success payload:

{
  "ok": true,
  "pluginId": "clawpilot-media-bridge",
  "version": "1.1.0",
  "enabled": true,
  "configured": false,
  "hasMediaBridgeToken": false,
  "serverBaseUrl": "https://api.clawpilot.me",
  "gatewayClientId": null,
  "needsRestart": false
}

Safety Boundaries

• This plugin does not register a global outbound hook.
• This plugin does not rewrite every MEDIA: line in every channel.
• Runtime checks still require a valid session context and allowed message channel.
• Default scope is webchat, which is the OpenClaw path most aligned with ClawPilot App usage.

Recommended Agent Policy

For strongest isolation, enable these tools only for your ClawPilot App agent:

• clawpilot_media_upload
• clawpilot_media_fetch

Do not enable them globally for every channel-facing agent unless that is explicitly what you want.