{"_id":"@clawpilot-app/openclaw-media-bridge","name":"@clawpilot-app/openclaw-media-bridge","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@clawpilot-app/openclaw-media-bridge","version":"0.1.0","description":"ClawPilot media bridge plugin for OpenClaw","license":"MIT","type":"module","keywords":["openclaw","clawpilot","plugin","media","r2"],"scripts":{"check":"node --check index.js && node --check src/*.js","pack:dry-run":"npm pack --dry-run"},"publishConfig":{"access":"public"},"openclaw":{"extensions":["./index.js"]},"_id":"@clawpilot-app/openclaw-media-bridge@0.1.0","gitHead":"b48a678f609aa3756db463f5ab29966e184de74c","_nodeVersion":"22.17.1","_npmVersion":"11.6.0","dist":{"integrity":"sha512-uqjJnUhesl4eMDI5p5NffaZv1+JCWfGO7w0XfzUS/encUnoZ2veDih5RBZHyHS3ZMvpHWe4/mA1i6Z+Y4ID9jg==","shasum":"3ee375d10715fa0f46b6fa37f8da30ffab9c6678","tarball":"https://registry.npmjs.org/@clawpilot-app/openclaw-media-bridge/-/openclaw-media-bridge-0.1.0.tgz","fileCount":16,"unpackedSize":35631,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIH3DxtERVsNVBjKo8I8lWz0MIg0vtZ0Qzz044jmIHWBQAiEA5WX5+C+YYaOneEA0442kb9WmIYs/iOz98lVFYUQBuNY="}]},"_npmUser":{"name":"yanghangbin","email":"yanghangbin@gmail.com"},"directories":{},"maintainers":[{"name":"yanghangbin","email":"yanghangbin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/openclaw-media-bridge_0.1.0_1773847558011_0.5687818432414593"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-18T15:25:57.910Z","0.1.0":"2026-03-18T15:25:58.166Z","modified":"2026-03-18T15:25:58.358Z"},"maintainers":[{"name":"yanghangbin","email":"yanghangbin@gmail.com"}],"description":"ClawPilot media bridge plugin for OpenClaw","keywords":["openclaw","clawpilot","plugin","media","r2"],"license":"MIT","readme":"# @clawpilot-app/openclaw-media-bridge\n\nClawPilot media bridge plugin for **OpenClaw**.\n\nIt lets an OpenClaw agent:\n\n- upload a gateway-local image or file to ClawPilot R2-backed media storage\n- get back a stable capability URL\n- emit the exact attachment directive that ClawPilot App can render\n- fetch a ClawPilot capability URL back to a local temp file when the agent needs bytes\n\nThe plugin is intentionally **tool-first**. It does **not** hijack Feishu, Discord, Telegram, or any other channel send path.\n\n## What This Plugin Registers\n\n- Tool: `clawpilot_media_upload`\n- Tool: `clawpilot_media_fetch`\n- Gateway RPC: `clawpilot_media.status`\n- Skill: `clawpilot-media-bridge`\n\n## Install\n\nCanonical npm install command:\n\n```bash\nopenclaw plugins install @clawpilot-app/openclaw-media-bridge\n```\n\nLocal archive install is also supported:\n\n```bash\nopenclaw plugins install ./openclaw-media-bridge.tgz\n```\n\nAfter installation, restart the gateway.\n\n## Config\n\nAdd or update the plugin entry in `~/.openclaw/openclaw.json`:\n\n```json5\n{\n  plugins: {\n    entries: {\n      \"clawpilot-media-bridge\": {\n        enabled: true,\n        config: {\n          serverBaseUrl: \"https://api.clawpilot.me\",\n          gatewayClientId: \"YOUR_GATEWAY_CLIENT_ID\",\n          mediaBridgeToken: \"mbt_xxx\",\n          uploadMaxBytes: 104857600,\n          downloadHostAllowlist: [\"api.clawpilot.me\"],\n          allowedMessageChannels: [\"webchat\"],\n        },\n      },\n    },\n  },\n}\n```\n\nField notes:\n\n- `serverBaseUrl`: ClawPilot server origin or origin+base-path.\n- `gatewayClientId`: the gateway client id bound in ClawPilot server.\n- `mediaBridgeToken`: bearer token issued by ClawPilot server for this gateway.\n- `uploadMaxBytes`: hard transport cap. Default `104857600` (100 MB).\n- `downloadHostAllowlist`: hosts that `clawpilot_media_fetch` may download from.\n- `allowedMessageChannels`: defaults to `[\"webchat\"]` so the plugin stays scoped to ClawPilot App style sessions.\n- `allowedAgentIds`: optional extra guard if you only want this plugin available to a dedicated app agent.\n\n## App Onboarding Flow\n\nRecommended product flow:\n\n1. User installs the plugin with `openclaw plugins install @clawpilot-app/openclaw-media-bridge`\n2. User restarts the gateway\n3. ClawPilot App calls `clawpilot_media.status`\n4. If `hasMediaBridgeToken` is false, the app requests a token from ClawPilot server\n5. The app writes `plugins.entries.clawpilot-media-bridge.config`\n6. User restarts the gateway again so the new config takes effect\n\n## Model-Facing Usage\n\nThis section is written so both humans and agents can understand the intended usage.\n\n### Sending a generated image or file back to the user\n\n1. Generate or locate a local file path on the gateway host.\n2. Call `clawpilot_media_upload`.\n3. Use the returned `assistantDirective` **verbatim** in the final assistant message.\n\nDo not hand-write capability URLs.\nDo not hand-write `CP_MEDIA_V1` payloads.\n\nThe plugin returns:\n\n- `MEDIA:<url>` for images\n- `CP_MEDIA_V1:<base64url-json>` for generic files\n\n### Reading a file that came from ClawPilot App\n\nIf 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`.\n\nThat tool downloads the file to a local temp path and returns:\n\n- `localPath`\n- `fileName`\n- `mimeType`\n- `sizeBytes`\n\n## Tool Reference\n\n### `clawpilot_media_upload`\n\nPurpose:\n\n- Upload a gateway-local file to ClawPilot media storage.\n- Return the exact directive line that ClawPilot App understands.\n\nInput:\n\n```json\n{\n  \"path\": \"/tmp/report.pdf\",\n  \"kind\": \"auto\",\n  \"fileName\": \"report.pdf\",\n  \"mimeType\": \"application/pdf\"\n}\n```\n\nKey output fields:\n\n```json\n{\n  \"ok\": true,\n  \"mediaId\": \"med_xxx\",\n  \"publicId\": \"mpub_xxx\",\n  \"kind\": \"file\",\n  \"capabilityUrl\": \"https://api.clawpilot.me/api/v1/openclaw/media/f/mpub_xxx?token=...\",\n  \"assistantDirective\": \"CP_MEDIA_V1:...\",\n  \"markdownLink\": \"[report.pdf](https://api.clawpilot.me/api/v1/openclaw/media/f/mpub_xxx?token=...)\"\n}\n```\n\n### `clawpilot_media_fetch`\n\nPurpose:\n\n- Download an allowed ClawPilot capability URL to a temp file on the gateway host.\n\nInput:\n\n```json\n{\n  \"capabilityUrl\": \"https://api.clawpilot.me/api/v1/openclaw/media/f/mpub_xxx?token=...\",\n  \"expectedFileName\": \"report.pdf\",\n  \"expectedMimeType\": \"application/pdf\"\n}\n```\n\n### `clawpilot_media.status`\n\nPurpose:\n\n- Let ClawPilot App detect whether the plugin is installed, enabled, and configured.\n\nExample success payload:\n\n```json\n{\n  \"ok\": true,\n  \"pluginId\": \"clawpilot-media-bridge\",\n  \"version\": \"0.1.0\",\n  \"enabled\": true,\n  \"configured\": false,\n  \"hasMediaBridgeToken\": false,\n  \"serverBaseUrl\": \"https://api.clawpilot.me\",\n  \"gatewayClientId\": null,\n  \"needsRestart\": false\n}\n```\n\n## Safety Boundaries\n\n- This plugin does **not** register a global outbound hook.\n- This plugin does **not** rewrite every `MEDIA:` line in every channel.\n- Runtime checks still require a valid session context and allowed message channel.\n- Default scope is `webchat`, which is the OpenClaw path most aligned with ClawPilot App usage.\n\n## Recommended Agent Policy\n\nFor strongest isolation, enable these tools only for your ClawPilot App agent:\n\n- `clawpilot_media_upload`\n- `clawpilot_media_fetch`\n\nDo not enable them globally for every channel-facing agent unless that is explicitly what you want.\n","readmeFilename":"README.md","_rev":"1-851f89bee6d24cfa65f22dd10f284bc1"}