OpenMarlin

当用户明确要求在 OpenClaw 内使用 OpenMarlin 时，请使用此技能。

该技能涵盖四项主要任务：

• 账户注册与 API 密钥初始化
• 通过 /v1/executions 发起原生执行请求
• 通过 /v1/tasks 处理异步长运行任务
• 计费、余额查询及 402 Payment Required 错误恢复

触发时机

在以下请求中激活该技能：

• “使用 OpenMarlin 回答这个问题”
• “让 OpenMarlin 总结这个页面”
• “使用 OpenMarlin 查询今天的 USD/CNY 汇率”
• “使用 OpenMarlin 执行这个任务”
• “使用 OpenMarlin 生成视频”
• “使用 OpenMarlin 提交一个异步视频任务”
• “注册 OpenMarlin”
• “检查 OpenMarlin 余额”

路由请求时应遵循：

• 将“使用 OpenMarlin ...”视为 OpenMarlin 专属意图，而非通用对话
• 对于常规任务（如回答、搜索、摘要、提取、翻译），优先使用 /v1/executions
• 对于视频生成等以产出物为导向的任务，即使用户未明确说明“异步”，也优先使用 /v1/tasks
• 当请求涉及视频、渲染、长时间生成或后台执行时，默认使用 /v1/tasks，除非用户明确要求同步执行
• 不因用户未在首句提供确切模型标识而拒绝激活

核心约束

• 默认保持 OpenClaw 优先的流程设计
• 不在聊天中收集密码、魔法链接、MFA 秘密或原始凭证
• 除非部署有特殊要求，否则优先使用 device 认证流程
• 将浏览器操作视为身份验证或 Stripe 结算的有限外部步骤，而非主控平面
• 浏览器跳转开始后，需持续轮询 OpenClaw 中的注册会话，直至其状态变为 completed 或 expired
• 浏览器回调或落地页仅面向用户，机器可读的注册状态必须来自注册会话本身
• 将 OPENMARLIN_SERVER_URL 视为唯一可信的 API 来源，且必须为裸域名，不带 /v1
• 不得使用 https://openmarlin.ai 作为 OPENMARLIN_SERVER_URL；这是面向浏览器的网站。应使用 https://api.openmarlin.ai，除非用户指向自定义部署
• 直接使用服务器提供的 handoff.authorization_url，不得本地重建 WorkOS 或浏览器 URL
• 当可用时，将平台 API 密钥存储在 OpenClaw 的 auth-profile 存储中，而非普通技能配置中
• 将 OPENMARLIN_PLATFORM_API_KEY 视为调试用的临时覆盖项，非推荐的长期存储路径
• 当余额信息不完整时，将本地计费状态标记为“最后已知”或“估算值”，而非假装其具有权威性

安装

该技能以目录形式分发，非独立 Markdown 文件。若手动安装，请复制 SKILL.md 及同级的 scripts/ 目录。

所需文件：

• 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

运行时要求：

• python3 必须在 PATH 中可用
• OPENMARLIN_SERVER_URL 默认值为 https://api.openmarlin.ai
• OPENMARLIN_SERVER_URL 必须为裸域名，不能以 /v1 结尾

首次运行

对新用户而言，最安全快捷的路径如下：

1. 如需覆盖默认值，请确认 OPENMARLIN_SERVER_URL
2. 使用 python3 scripts/registration_session.py create 启动注册流程
3. 若服务器返回跳转 URL，则在浏览器中完成外部认证
4. 使用 watch 命令轮询注册会话，直到状态变为 completed
5. 使用 bootstrap --store 自动化并存储首个工作区 API 密钥
6. 可选：调用 python3 scripts/platform_request.py models 查看可用模型
7. 发送首个执行请求

设置完成后，最常见的后续操作包括：

• 发送已路由的执行请求
• 提交长运行任务并轮询其完成状态
• 检查可用模型列表
• 从 402 Payment Required 响应中恢复
• 检查余额或近期计费活动
• 获取调用者的推荐码和邀请链接

请求模型

注册

注册流程基于以下接口：

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

注册会话状态：

• pending_external_auth
• completed
• expired

会话完成后，OpenClaw 应继续依赖机器可读的注册会话状态，而非浏览器回调输出。

执行

原生执行使用：

• POST /v1/executions

执行请求可包含：

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

执行路由规则：

• 若未提供 model 和 provider_id，由服务器自行决定两者
• 仅提供 model 时，使用完整的精确模型引用，由服务器选择适配的提供方
• 仅提供 provider_id 时，由服务器在该提供方下选择符合条件的模型
• 同时提供 model 和 provider_id 时，服务器强制执行双重约束

若提供 model，必须是完整的精确引用，例如 openai-codex/gpt-5.4

若同时提供 provider_id 和 model，请先通过 python3 scripts/platform_request.py models 确认该提供方是否公开了相同的模型引用。

任务

长运行任务使用：

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

任务请求的结构与 /v1/executions 不同。

任务请求使用：

• kind = video
• input.prompt（必需）
• input.media_urls（可选）
• input.media_ids（可选）
• input.duration_ms（可选）
• input.aspect_ratio（可选）
• metadata（可选）

任务请求不接受：

• instruction
• provider_id
• labels
• model
• stream

建议在以下情况使用 /v1/tasks：

• 生成可能需要数分钟时间
• 流式输出不存在或无实际用途
• 实际结果预计稍后以附件元数据形式返回，例如 artifact_url
• 请求为视频生成任务，除非用户明确要求同步执行路径
• 在 OpenClaw 内部使用 /v1/tasks 时，默认采用“等待并监控”行为，而非返回 task_id 后立即停止

任务状态：

• queued：已排队
• running：正在运行
• succeeded：成功
• failed：失败

计费

计费与恢复流程使用以下接口：

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

结构化余额不足错误可能返回：

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

将此 402 响应视为工作流输入，而非通用传输失败。

常用命令

注册

创建注册会话：

python3 scripts/registration_session.py create

当部署需要回调模式时，创建回调式会话：

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

检查或轮询注册会话状态：

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

引导并存储首个 API 密钥：

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

执行

列出当前可用的精确模型：

python3 scripts/platform_request.py models

由服务器自动选择模型和提供商：

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

使用精确模型引用，并启用自动提供商路由：

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

使用显式提供商覆盖：

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

发送一次预演请求：

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"}'

使用流式执行：

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

任务

提交一个长时间运行的任务：

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

获取当前任务状态：

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

轮询直到任务成功或失败：

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

计费

解释结构化的 402 响应：

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"}}'

根据 402 差额创建充值会话：

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"}}'

检查充值进度：

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

查看当前余额：

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

查看最近的计费活动：

python3 scripts/billing.py activity

获取调用方的推荐码、邀请链接和归属信息摘要：

python3 scripts/billing.py referral-link

运维指引

路由失败

将常见的路由错误翻译为通俗语言：

• provider_unavailable：所选提供商当前未连接
• provider_label_mismatch：所选提供商不满足请求的路由提示
• execution_provider_not_found：没有符合条件的执行提供商匹配当前请求
• execution_provider_ambiguous：多个执行提供商匹配，服务器需要更窄的标签或显式提供商覆盖
• execution_kind_not_available：所选提供商不支持请求的执行类型
• task_executor_not_found：没有配置的任务执行器匹配当前长任务请求
• invalid_routing_labels：标签格式错误

遇到此类情况时：

• 重述你实际发送的提供商和标签
• 建议尝试使用不同的标签、不同提供商，或启用自动路由
• 不要虚构隐藏标签或未经文档说明的路由字段

针对 /v1/tasks 特别说明：

• 不建议通过提供商覆盖、标签或模型路由作为恢复路径
• 建议验证 kind = video 和 input 数据结构是否正确

对于长时间运行的任务：

• 优先使用 tasks-submit --watch，而非让用户手动调用 tasks-watch
• 对于视频生成请求，除非用户明确要求“发送即忘”，否则默认使用 tasks-submit --watch 作为完成路径
• 一旦返回 task_id 即可确认接收
• 持续轮询直至任务达到终止状态或超时；不要要求用户再次询问才能继续监控同一任务
• 当任务状态变为 succeeded 时，展示最终的 output 和 metadata

• 明确显示当前余额、所需余额及差额
• 说明此为可恢复的计费状态
• 将恢复流程保留在 OpenClaw 内，直至完成所需的 Stripe 结账步骤
• 在可用时优先使用权威的 GET /v1/balance 请求获取数据
• 本地仅保留计费快照作为辅助上下文信息

在引导充值流程时：

• 在 OpenClaw 内创建充值会话
• 展示 pending_payment、credit_applied 和 payment_failed 之间的区别
• 告知用户打开 Stripe 的 checkout_url 是唯一必需的外部计费操作
• 在信用额度到账后刷新余额

凭据处理

API 密钥初始化返回的 secret 是 OpenClaw 的持久化平台凭据。

• 优先使用 OpenClaw 认证配置文件，而非普通的仓库文件或常规配置
• 当使用 --store 选项时，将密钥存储到默认的 OpenClaw 认证配置文件中
• 除非命令明确返回，否则避免直接输出原始密钥
• 报告成功时，应显示密钥的存储位置或加载来源
• 永远不要要求用户通过聊天输入平台 API 密钥作为常规注册路径
• 若 openmarlin.ai 被浏览器或 Cloudflare 阻挡，请确认助手目标地址为 https://api.openmarlin.ai 后再建议手动浏览器操作