核心用法
OpenMarlin 是 OpenClaw 生态中的 AI 任务执行平台，通过 /v1/executions 提供即时问答、搜索、摘要、翻译等同步任务，通过 /v1/tasks 支持视频生成等耗时较长的异步作业。用户需先完成设备授权注册，获取 API Key 后方可调用。
注册流程：创建注册会话 → 浏览器完成外部身份验证 → 轮询会话状态至完成 → 引导并存储首个工作区 API Key。
执行任务：
- 即时任务（/v1/executions）：适合问答、数据分析等，支持流式输出与模型/供应商路由
- 异步任务（/v1/tasks）：专用于视频生成等长时作业，需轮询任务状态直至完成
计费管理：内置 402 Payment Required 恢复机制，支持余额查询、充值会话创建与 Stripe 支付集成。
显著优点
1. OpenClaw 原生集成：深度融入 OpenClaw 工作流，支持 auth-profile 安全存储 API Key
2. 灵活路由策略：支持自动路由、指定模型、指定供应商或组合约束，适配多供应商场景
3. 完整的计费闭环：结构化余额不足响应 + 自动充值流程，避免任务中断
4. 安全设计：设备流优先、不在聊天中收集密码/MFA、浏览器步骤隔离为窄外部环节
5. 脚本化运维：提供完整的 Python CLI 工具链，支持注册、执行、任务、计费的自动化操作
潜在缺点与局限性
- 外部依赖重：必须配合浏览器完成身份验证和 Stripe 支付，无法纯 CLI 闭环
- Python 运行时依赖：需本地
python3环境及多个脚本文件，非独立二进制分发 - 任务类型受限：视频生成仅支持特定参数（prompt、media_urls、aspect_ratio 等），不支持通用
instruction模式 - 供应商可见性有限：模型列表需手动查询，无实时供应商健康状态暴露
- 异步任务无流式：长任务必须轮询，无法实时进度推送
适合人群
- OpenClaw 生态用户，需扩展 AI 执行能力
- 开发者构建自动化工作流（CI/CD、批量内容生成）
- 需要视频生成等长时异步任务的场景
- 多供应商 AI 路由策略的运维团队
常规风险
| 风险类型 | 说明 | 缓解建议 |
|---------|------|---------|
| 凭证泄露 | API Key 在脚本调试时可能意外回显 | 使用 `--store` 存入 auth-profile，避免手动复制 |
| 中间人攻击 | `OPENMARLIN_SERVER_URL` 配置错误指向恶意节点 | 严格校验为裸 origin，禁用非 HTTPS 端点 |
| 计费失控 | 视频任务耗时未知，可能产生意外费用 | 任务提交前检查余额，设置合理超时 |
| 会话过期 | 注册或充值会话有有效期，浏览器步骤中断导致失败 | 实现 `watch` 轮询，及时提示用户完成外部步骤 |
| 供应商单点故障 | 显式指定 provider_id 时可能遭遇不可用 | 优先使用自动路由，故障时降级处理 |