Skill Hub Gateway

---

name: skill-hub-gateway description: Unified gateway skill for async execute/poll, portal user closure, and telemetry feedback workflows. version: 2.4.2 metadata: openclaw: skillKey: skill-hub-gateway emoji: "🧩" homepage: https://gateway.binaryworks.app requires: bins: - node

---

Skill Hub Gateway

Default API base URL: https://gateway-api.binaryworks.app

Default site base URL (for upload route): https://gateway.binaryworks.app

Chinese documentation: SKILL.zh-CN.md

Version Check Protocol (Agent)

Official latest version source: GET /skills/manifest.json -> data.version.

Local current version source: this installed SKILL.md frontmatter version.

Compare versions using semantic version order (major.minor.patch).

Check timing: once at session start, then at most once every 24 hours within the same session.

If version check fails (network/timeout/parse error), do not block runtime execution. Continue current workflow and retry at the next allowed check window.

Agent Decision Flow

If latest_version > current_version, read the matching section under Release Notes in this document to build update_summary.

Agent should show the user:

- current_version - latest_version - update_summary

User decision options:

- Update now - Remind me later in this session

If user chooses Remind me later in this session, suppress repeated prompts for the same target version until a new session starts.

First-Time Onboarding (install_code)

Scripts auto-complete onboarding by default:

1. POST /agent/install-code/issue with {"channel":"local"} or {"channel":"clawhub"}. 2. Read data.install_code. 3. POST /agent/bootstrap with {"agent_uid":"","install_code":""}. 4. Read data.api_key, then call runtime APIs with X-API-Key or Authorization: Bearer .

Manual override:

You can still provide api_key explicitly.

If agent_uid and owner_uid_hint are omitted, scripts derive stable local defaults from the current workspace path.

Legacy Runtime Contract (Compatibility)

Execute: POST /skill/execute

Poll: GET /skill/runs/:run_id

Portal Actions (User Closure)

Action catalog (single default path per action):

portal.me -> GET /user/me

portal.balance -> GET /user/points/balance

portal.ledger.query -> GET /user/points/ledger

portal.usage.query -> GET /user/usage

portal.skill.execute -> POST /user/skills/execute

portal.skill.poll -> GET /user/skills/runs/:runId

portal.skill.presentation -> GET /user/skills/runs/:runId/presentation

portal.voucher.redeem -> POST /user/vouchers/redeem (write)

portal.recharge.create -> POST /user/recharge/orders (write)

portal.recharge.get -> GET /user/recharge/orders/:orderId

Write safety gate:

portal.voucher.redeem and portal.recharge.create require payload.confirm === true.

If confirm is missing or not true, action runner rejects the call locally and does not send write traffic.

Payload Contract

Default payload conventions:

payload.input is the primary input object for portal.skill.execute.

payload.request_id is optional and passed through as-is.

Query actions use payload fields directly as query params (date_from, date_to, service_id, channel).

Media normalization conventions:

Prefer explicit URL fields already present in input: image_url, audio_url, file_url.

If attachment.url exists, map it to the capability target URL field.

If file_path exists, auto-upload through {site_base}/api/blob/upload, with fallback to {site_base}/api/blob/upload-file when @vercel/blob/client is unavailable, then backfill URL into input before execution.

For agent runtimes that do not include @vercel/blob/client, you can also pre-upload media via your backend (for example Vercel Blob) and pass attachment.url or explicit URL fields.

site_base_url is a guarded field: runtime only accepts the trusted configured site base URL (default https://gateway.binaryworks.app or env SKILL_SITE_BASE_URL).

Users should not need to manually paste media URLs in normal product flows.

Presentation files:

portal.skill.presentation accepts optional include_files=true to return visual.files.assets with rendered file URLs.

portal-action.mjs defaults include_files=true for portal.skill.presentation unless explicitly disabled.

Image runs return overlay (boxed image), plus mask / cutout assets when available.

Audio runs normalize data URLs to output.media_files.assets with uploaded file URLs when blob storage is configured.

Runtime Auth Bridge

User-scoped actions use a fixed auth bridge:

1. Resolve runtime API key context (api_key, agent_uid, owner_uid_hint, base_url). 2. GET /agent/me with X-API-Key + x-agent-uid to resolve user_id. 3. POST /user/api-key-login with user_id + api_key to obtain userToken. 4. Execute Portal Action with Authorization: Bearer .

Insufficient Points Recovery

For POINTS_INSUFFICIENT responses:

Keep error.code and error.message unchanged.

Preserve and surface error.details.recharge_url when available.

Diagnostic logs should recommend portal.recharge.create or direct open of recharge_url.

Bundled Files

scripts/execute.mjs (CLI args: [api_key] [capability] [input_payload] [base_url] [agent_uid] [owner_uid_hint])

scripts/poll.mjs (CLI args: [api_key] [base_url] [agent_uid] [owner_uid_hint])

scripts/feedback.mjs (CLI args: [api_key] [payload_json] [base_url] [agent_uid] [owner_uid_hint])

scripts/telemetry.mjs (shared best-effort telemetry helper)

scripts/runtime-auth.mjs (shared auto-bootstrap helper)

scripts/portal-auth.mjs (api-key -> user session bridge)

scripts/portal-action.mjs (CLI args: [api_key] [base_url] [agent_uid] [owner_uid_hint])

scripts/attachment-normalize.mjs (attachment URL/path normalization + upload)

references/capabilities.json

references/openapi.json

SKILL.zh-CN.md

Telemetry and Feedback

Bundled scripts now support best-effort telemetry emit for auth/execute/poll/feedback flows.

Telemetry is non-blocking and does not change runtime exit semantics if telemetry delivery fails.

Optional environment variables:

- SKILL_TELEMETRY_ENABLED (true by default) - SKILL_TELEMETRY_BASE_URL (defaults to runtime base_url) - SKILL_TELEMETRY_TIMEOUT_MS (2000 by default)

Feedback script posts to POST /feedback/submit with runtime auth (X-API-Key) and attaches agent_uid + owner_uid_hint in metadata.

Capability IDs

human_detect

image_tagging

tts_report

embeddings

reranker

asr

tts_low_cost

markdown_convert

face-detect

person-detect

hand-detect

body-keypoints-2d

body-contour-63pt

face-keypoints-106pt

head-pose

face-feature-classification

face-action-classification

face-image-quality

face-emotion-recognition

face-physical-attributes

face-social-attributes

political-figure-recognition

designated-person-recognition

exhibit-image-recognition

person-instance-segmentation

person-semantic-segmentation

concert-cutout

full-body-matting

head-matting

product-cutout

Release Notes

When publishing a new version, add a new section here. Agent update summaries must be generated from this block.

2.4.2 (2026-03-12)

What's New

Added /api/blob/upload-file direct-upload fallback for file_path flows when @vercel/blob/client is unavailable.

Added portal.skill.presentation file rendering (visual.files.assets) for overlay/mask/cutout URLs.

Added audio output normalization to return output.media_files.assets with uploaded file URLs when blob storage is configured.

Breaking/Behavior Changes

None.

Migration Notes

For agent runtimes without @vercel/blob/client, send file_path as before; the runtime now falls back to direct upload.

To receive rendered files, call portal.skill.presentation with include_files=true or rely on the portal default.

2.4.1 (2026-03-12)

What's New

Added server-side portal.skill.execute input normalization for attachment.url (both input.attachment.url and top-level attachment.url).

Added explicit media URL precedence guard (image_url/audio_url/file_url take priority over attachment.url when both are present).

Added end-to-end tests for upload-first execution payload compatibility and precedence behavior.

Clarified fallback guidance for runtimes missing @vercel/blob/client to use backend pre-upload URLs.

Breaking/Behavior Changes

None.

Migration Notes

Existing portal-action.mjs workflows remain compatible.

For local file workflows in constrained agent runtimes, prefer backend pre-upload then pass attachment.url or explicit media URL.

2.4.0 (2026-03-12)

What's New

Added Portal Actions contract for single-skill user closure flows (portal.me, balance/ledger/usage, execute/poll/presentation, voucher and recharge actions).

Added local double-confirm write gate: portal.voucher.redeem and portal.recharge.create require confirm=true.

Added runtime auth bridge script (portal-auth.mjs) for api_key -> user session.

Added action runner (portal-action.mjs) and attachment normalization script (attachment-normalize.mjs) with attachment.url and file_path support.

Standardized insufficient-points diagnostics to preserve recharge_url in passthrough envelopes.

Breaking/Behavior Changes

Write actions now fail fast locally when confirm=true is absent.

Migration Notes

Existing execute.mjs and poll.mjs workflows remain available.

Portal users should call portal-action.mjs for user closure actions.

2.3.4 (2026-03-11)

What's New

Added best-effort telemetry emit in runtime scripts for auth/execute/poll flows.

Added scripts/feedback.mjs to submit structured feedback via runtime auth (X-API-Key).

Added shared telemetry helper with optional env controls (SKILL_TELEMETRY_*).

Breaking/Behavior Changes

None.

Migration Notes

Existing execute/poll calls remain unchanged.

If you run scripts in constrained environments, allow optional telemetry calls to /agent/telemetry/ingest and /telemetry/ingest.

2.3.3 (2026-03-11)

What's New

Standardized user-facing guidance around upload-based flows: do not expose manual URL/JSON fields for media/document inputs.

Updated capability reference examples and wording to match upload-first product UX.

Renamed CLI argument label from input_json to input_payload for consistency with structured payload semantics.

Breaking/Behavior Changes

None.

Migration Notes

Existing runtime API calls remain unchanged.

If your integration shows custom input forms, prefer file/attachment inputs instead of manual URL/JSON text fields.