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 INLINECODE0
• asynchronous long-running jobs through INLINECODE1
• 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.

• - 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.

• - 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:

• - INLINECODE16
• INLINECODE17
• INLINECODE18
• INLINECODE19
• INLINECODE20
• INLINECODE21
• INLINECODE22

Runtime expectations:

• - python3 is available in INLINECODE24
• INLINECODE25 defaults to INLINECODE26
• INLINECODE27 must be a bare origin, not a URL ending in INLINECODE28

First Run

For a new user, the shortest safe path is:

1. 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:

• - INLINECODE36
• INLINECODE37
• INLINECODE38

Registration session states:

• - INLINECODE39
• INLINECODE40
• INLINECODE41

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

Executions

Native execution uses:

• - INLINECODE42

Execution requests may include:

• - INLINECODE43
• INLINECODE44
• INLINECODE45
• INLINECODE46
• INLINECODE47
• INLINECODE48
• INLINECODE49
• INLINECODE50
• INLINECODE51
• INLINECODE52

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:

• - INLINECODE64
• INLINECODE65

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

Task requests use:

• - INLINECODE67
• INLINECODE68 required
• INLINECODE69 optional
• INLINECODE70 optional
• INLINECODE71 optional
• INLINECODE72 optional
• INLINECODE73 optional

Task requests do not accept:

• - INLINECODE74
• INLINECODE75
• INLINECODE76
• INLINECODE77
• INLINECODE78

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 INLINECODE82

Task states:

• - INLINECODE83
• INLINECODE84
• INLINECODE85
• INLINECODE86

Billing

Billing and recovery flows use:

• - INLINECODE87
• INLINECODE88
• INLINECODE89
• INLINECODE90
• INLINECODE91

Structured balance failures may return:

• - INLINECODE92
• INLINECODE93
• INLINECODE94
• INLINECODE95
• INLINECODE96

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

Common Commands

Registration

Create a registration session:

CODEBLOCK0

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

CODEBLOCK1

Check or poll a registration session:

CODEBLOCK2

Bootstrap and store the first API key:

CODEBLOCK3

Executions

List currently available exact models:

CODEBLOCK4

Let the server choose model and provider automatically:

CODEBLOCK5

Use an exact model ref with automatic provider routing:

CODEBLOCK6

Use an explicit provider override:

CODEBLOCK7

Send a dry run:

CODEBLOCK8

Use streaming execution:

CODEBLOCK9

Tasks

Submit a long-running job:

CODEBLOCK10

Fetch the current task state:

CODEBLOCK11

Poll until the task succeeds or fails:

CODEBLOCK12

Billing

Explain a structured 402 response:

CODEBLOCK13

Create a top-up session from the 402 shortfall:

CODEBLOCK14

Check top-up progress:

CODEBLOCK15

Show current balance:

CODEBLOCK16

Show recent billing activity:

CODEBLOCK17

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

CODEBLOCK18

Operational Guidance

Routing Failures

Translate common routing errors into plain language:

• - provider_unavailable: the selected provider is not currently connected
• INLINECODE101: 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

• - 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 INLINECODE116

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