OpenMarlin

Use OpenMarlin from OpenClaw to answer questions, run tasks, and manage OpenMarlin account setup and billing flows.

Security Scan

The skill's code, instructions, and requested resources are coherent with its stated purpose (managing OpenMarlin registration, executions, tasks, and billing), but it will read/write OpenClaw state and store API keys locally and the source is unverified so exercise normal caution.

Purpose & Capability

Name and description (OpenMarlin account setup, executions, tasks, billing) match the included scripts and SKILL.md. Required binary (python3) is appropriate. No unexplained credentials or unrelated binaries are requested.

Instruction Scope

Runtime instructions direct the agent/operator to run the included Python helper scripts, perform browser handoffs for external auth, poll registration sessions, bootstrap workspace API keys, submit executions/tasks, and handle 402 recovery. These steps are within the stated purpose, but the scripts explicitly read and write OpenClaw state (e.g., ~/.openclaw/openclaw.json, agent auth-profiles.json) and may open the system browser for handoff — this is expected for an account/billing skill but is more invasive than a pure query-only skill.

Install Mechanism

No remote install/download steps; code is distributed alongside SKILL.md. The skill requires copying the scripts directory and running them locally with python3. No URLs or archive extraction are used by the skill itself.

Credentials

The skill does not require env vars at install time, but optionally uses OPENMARLIN_SERVER_URL and OPENMARLIN_PLATFORM_API_KEY and resolves credentials from OpenClaw auth-profiles. It reads/writes OpenClaw config and auth profile files (e.g., ~/.openclaw/openclaw.json, ~/.openclaw/agents/<agent>/agent/auth-profiles.json) to store platform API keys and state — this is proportionate to account/bootstrap and billing tasks but does grant access to shared OpenClaw agent state.

Persistence & Privilege

The skill persists state under OpenClaw's agent directories (billing-state.json, task-state.json, auth-profiles.json) and may store platform API keys in OpenClaw auth-profile storage. always is false and the skill does not request elevated system-wide privileges. Writing its own agent data and auth entries is consistent with its purpose.

Assessment

This skill appears to do what it says: it helps register an OpenMarlin account, bootstrap/store workspace API keys, submit executions and long-running tasks, and manage billing. Before installing: (1) Note that it will read and write OpenClaw state under ~/.openclaw (openclaw.json, agent auth-profiles.json, billing-state/task-state) and may store API keys there — review those file writes if you care about scoped storage. (2) The scripts will contact whatever OPENMARLIN_SERVER_URL is configured (defaults to https://api.openmarlin.ai); only set that to servers you trust. (3) The skill will open the browser for external auth handoffs; don’t paste passwords or secret tokens into chat. (4) Source and homepage are not provided in the registry metadata — if you need a higher assurance, review the included Python files locally or run the scripts in a sandbox before giving them access to your OpenClaw profile. If you are comfortable with these behaviors, the skill is internally coherent with its purpose.

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:

python3 scripts/registration_session.py create

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

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

Check or poll a registration session:

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:

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

Executions

List currently available exact models:

python3 scripts/platform_request.py models

Let the server choose model and provider automatically:

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

Use an exact model ref with automatic provider routing:

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

Use an explicit provider override:

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

Send a dry run:

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:

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

Tasks

Submit a long-running job:

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

Fetch the current task state:

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

Poll until the task succeeds or fails:

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

Billing

Explain a structured 402 response:

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:

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:

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

Show current balance:

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

Show recent billing activity:

python3 scripts/billing.py activity

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

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