OpenMarlin#

Use this skill when a user explicitly wants to use OpenMarlin from inside OpenClaw.

This skill covers four main jobs:

• account registration and API key bootstrap
• native execution requests through /v1/executions
• asynchronous long-running jobs through /v1/tasks
• billing, balance, and 402 Payment Required recovery

When To Activate#

Activate this skill for requests such as:

• "use openmarlin to answer this"
• "ask openmarlin to summarize this page"
• "use openmarlin to find today's USD/CNY exchange rate"
• "use openmarlin to execute this task"
• "use openmarlin to generate a video"
• "use openmarlin to submit an async video task"
• "register OpenMarlin"
• "check OpenMarlin balance"

When routing the request:

• treat "use openmarlin ..." as an OpenMarlin intent, not generic chat
• prefer /v1/executions for normal tasks such as answering, searching, summarizing, extracting, or translating
• prefer /v1/tasks for video generation and other artifact-oriented jobs even when the user did not explicitly say "async"
• treat requests mentioning video, rendering, long-running generation, or background execution as /v1/tasks by default unless the user explicitly asks for synchronous execution
• do not reject activation just because the user did not provide an exact model ref in the first sentence

Core Constraints#

• Keep the flow OpenClaw-first by default.
• Do not collect passwords, magic links, MFA secrets, or raw credentials in chat.
• Prefer the device auth flow unless the deployment specifically requires workos_callback.
• Treat browser use as a narrow external step for identity or Stripe checkout, not the main control plane.
• After browser handoff begins, keep polling the registration session in OpenClaw until it becomes completed or expired.
• Treat browser callback or landing pages as user-facing only. Machine-readable registration state must come from the registration session.
• Treat OPENMARLIN_SERVER_URL as the only trusted API origin and keep it as a bare origin without /v1.
• Do not use https://openmarlin.ai as OPENMARLIN_SERVER_URL; that is the browser-facing website. Use https://api.openmarlin.ai unless the user is targeting a custom deployment.
• Use server-provided handoff.authorization_url directly. Do not reconstruct WorkOS or browser URLs locally.
• Store platform API keys in OpenClaw auth-profile storage when available, not in ordinary skill config.
• Treat OPENMARLIN_PLATFORM_API_KEY as a temporary override for debugging, not the preferred steady-state storage path.
• If no platform key is available yet, start registration/bootstrap instead of telling the user to manually provide an API key.
• When balance information is incomplete, label local billing state as last-known or estimated instead of pretending it is authoritative.

Installation#

This skill is distributed as a directory, not as a standalone Markdown file. If you install it manually, copy both SKILL.md and the sibling scripts/ directory.

Required files:

• SKILL.md
• scripts/registration_session.py
• scripts/platform_request.py
• scripts/billing.py
• scripts/openclaw_billing_state.py
• scripts/openclaw_platform_auth.py
• scripts/openclaw_skill_config.py

Runtime expectations:

• python3 is available in PATH
• OPENMARLIN_SERVER_URL defaults to https://api.openmarlin.ai
• OPENMARLIN_SERVER_URL must be a bare origin, not a URL ending in /v1

First Run#

For a new user, the shortest safe path is:

1. Confirm OPENMARLIN_SERVER_URL if you need to override the default.
2. Start registration with python3 scripts/registration_session.py create.
3. Complete external auth in the browser if the server returns a handoff URL.
4. Poll the registration session with watch until it becomes completed.
5. Bootstrap and store the first workspace API key with bootstrap --store.
6. Optionally call python3 scripts/platform_request.py models.
7. Send the first execution request.

After setup, the most common next actions are:

• send a routed execution request
• submit a long-running task and poll for completion
• inspect available models
• recover from a 402 Payment Required response
• inspect balance or recent billing activity
• fetch the caller's referral code and invite link

Request Model#

Registration#

Registration flows are built on:

• POST /v1/registration/sessions
• GET /v1/registration/sessions/:sessionId
• POST /v1/registration/sessions/:sessionId/api-keys

Registration session states:

• pending_external_auth
• completed
• expired

When a session completes, OpenClaw should continue from the machine-readable registration session state, not from browser callback output.

Executions#

Native execution uses:

• POST /v1/executions

Execution requests may include:

• instruction
• kind = agent_run
• stream
• provider_id
• labels
• agent_id
• session_key
• timeout_ms
• model
• metadata

Execution routing rules:

• with neither model nor provider_id, let the server choose both
• with only model, use an exact full ref and let the server choose a provider
• with only provider_id, let the server choose an eligible model on that provider
• with both model and provider_id, the server enforces both constraints

If model is provided, it must be an exact full ref such as openai-codex/gpt-5.4.

If you provide both provider_id and model, first confirm from python3 scripts/platform_request.py models that the provider advertises that same exact model ref.

Tasks#

Long-running jobs use:

• POST /v1/tasks
• GET /v1/tasks/:taskId

Task requests do not use the same routing shape as /v1/executions.

Task requests use:

• kind = video
• input.prompt required
• input.media_urls optional
• input.media_ids optional
• input.duration_ms optional
• input.aspect_ratio optional
• metadata optional

Task requests do not accept:

• instruction
• provider_id
• labels
• model
• stream

Prefer /v1/tasks when:

• generation may take many minutes
• stream output is absent or not useful
• the real result is expected to arrive later as artifact metadata such as an artifact_url
• the request is for video generation, unless the user explicitly insists on a synchronous execution path
• when using /v1/tasks from inside OpenClaw, default to submitting with watch-and-wait behavior instead of stopping after returning a task_id

Task states:

• queued
• running
• succeeded
• failed

Billing#

Billing and recovery flows use:

• GET /v1/balance
• GET /v1/usage-events
• GET /v1/ledger
• POST /v1/topup/sessions
• GET /v1/topup/sessions/:sessionId

Structured balance failures may return:

• error_code = insufficient_balance
• message
• workspace_id
• current_balance.amount / unit
• required_balance.amount / unit

Treat that 402 shape as workflow input, not a generic transport failure.

Common Commands#

Registration#

Create a registration session:

bash

python3 scripts/registration_session.py create

Create a callback-style session when the deployment requires it:

bash

python3 scripts/registration_session.py create --auth-flow workos_callback

Check or poll a registration session:

bash

python3 scripts/registration_session.py status --session-id <session-id>
python3 scripts/registration_session.py watch --session-id <session-id>

Bootstrap and store the first API key:

bash

python3 scripts/registration_session.py bootstrap \
  --session-id <session-id> \
  --store

Executions#

List currently available exact models:

bash

python3 scripts/platform_request.py models

Let the server choose model and provider automatically:

bash

python3 scripts/platform_request.py executions \
  --body-json '{"instruction":"say hello"}'

Use an exact model ref with automatic provider routing:

bash

python3 scripts/platform_request.py executions \
  --body-json '{"instruction":"say hello","model":"openai-codex/gpt-5.4"}'

Use an explicit provider override:

bash

python3 scripts/platform_request.py executions \
  --provider node-a \
  --body-json '{"instruction":"say hello"}'

Send a dry run:

bash

python3 scripts/platform_request.py executions \
  --dry-run \
  --server-url https://your-server.example.com \
  --api-key claw_wsk_placeholder \
  --body-json '{"instruction":"say hello"}'

Use streaming execution:

bash

python3 scripts/platform_request.py executions \
  --body-json '{"instruction":"say hello","stream":true}'

Tasks#

Submit a long-running job:

bash

python3 scripts/platform_request.py tasks-submit \
  --watch \
  --body-json '{"kind":"video","input":{"prompt":"Generate a short plane video."}}'

Fetch the current task state:

bash

python3 scripts/platform_request.py tasks-status --task-id <task-id>

Poll until the task succeeds or fails:

bash

python3 scripts/platform_request.py tasks-watch --task-id <task-id>

Billing#

Explain a structured 402 response:

bash

python3 scripts/billing.py explain-402 \
  --response-json '{"error_code":"insufficient_balance","message":"Workspace balance is insufficient for this request.","workspace_id":"ws_123","current_balance":{"amount":0,"unit":"credits"},"required_balance":{"amount":1,"unit":"credits"}}'

Create a top-up session from the 402 shortfall:

bash

python3 scripts/billing.py create-topup \
  --response-json '{"error_code":"insufficient_balance","message":"Workspace balance is insufficient for this request.","workspace_id":"ws_123","current_balance":{"amount":0,"unit":"credits"},"required_balance":{"amount":1,"unit":"credits"}}'

Check top-up progress:

bash

python3 scripts/billing.py status --session-id <topup-session-id>
python3 scripts/billing.py watch --session-id <topup-session-id>

Show current balance:

bash

python3 scripts/billing.py balance --workspace-id <workspace-id>

Show recent billing activity:

bash

python3 scripts/billing.py activity

Fetch the caller's referral code, invite link, and attribution summary:

bash

python3 scripts/billing.py referral-link

Operational Guidance#

Routing Failures#

Translate common routing errors into plain language:

• provider_unavailable: the selected provider is not currently connected
• provider_label_mismatch: the selected provider does not satisfy the requested routing hints
• execution_provider_not_found: no eligible execution provider matched the current request
• execution_provider_ambiguous: more than one execution provider matched and the server needs narrower labels or an explicit provider override
• execution_kind_not_available: the selected provider does not support the requested execution kind
• task_executor_not_found: no configured task executor matched the current long-running task request
• invalid_routing_labels: labels were malformed

When these happen:

• restate the provider and labels you actually sent
• suggest retrying with different labels, a different provider, or automatic routing
• do not invent hidden labels or undocumented routing fields

For /v1/tasks specifically:

• do not suggest provider overrides, labels, or model routing as a recovery path
• suggest validating kind = video and the input payload shape instead

For long-running jobs:

• prefer tasks-submit --watch over asking the user to manually follow up with tasks-watch
• for video-generation requests, treat tasks-submit --watch as the default completion path unless the user explicitly asks for fire-and-forget behavior
• when repeating the exact same video submission shortly after a task was already attempted, prefer reusing the recent idempotency_key so the server returns the original task instead of creating a second /v1/tasks request
• keep refreshing local task state while watching so long-running tasks remain inside that short reuse window
• acknowledge acceptance as soon as a task_id is returned
• keep polling until the task reaches a terminal state or times out; do not require the user to ask again just to continue watching the same task
• surface final output and metadata when the task reaches succeeded

Balance And Recovery#

When the server returns a structured 402 insufficient_balance response:

• show the current balance, required balance, and shortfall explicitly
• explain that this is a recoverable billing state
• keep the recovery flow inside OpenClaw until the required Stripe checkout step
• prefer authoritative GET /v1/balance reads when available
• keep local billing snapshots only as supporting context

When guiding a top-up flow:

• create the top-up session inside OpenClaw
• show the difference between pending_payment, credit_applied, and payment_failed
• tell the user that opening the Stripe checkout_url is the only required external billing step
• refresh balance after credit lands

Credential Handling#

The returned secret from API key bootstrap is the steady-state platform credential for OpenClaw.

• prefer OpenClaw auth profiles over plain repo files or ordinary config
• store the key in the default OpenClaw auth profile when --store is used
• avoid echoing raw secrets unless the active command explicitly returns them
• when reporting success, show where the key was stored or loaded from
• never ask the user to paste a platform API key into chat as the normal registration path
• if openmarlin.ai appears blocked by browser or Cloudflare protection, verify that helpers are targeting https://api.openmarlin.ai before suggesting manual browser actions