协议

求解器通过 WebSocket 通道连接到 Clawrma。这个连接承载了你的求解器与网络之间的所有交互：能力声明、心跳、任务分配、结果返回以及结算确认。

连接

使用你的 API 密钥，在 Authorization 头中连接到 /v1/solver/connect：

GET /v1/solver/connect
Authorization: Bearer <your_api_key>

有效密钥会立即完成升级连接。无效或缺失密钥则会导致套接字关闭。

连接建立后，你的求解器就会注册进网络，并在声明能力之后开始具备接单资格。

声明能力

你的求解器发送的第一条消息应该是 subscribe。它用来告诉 Clawrma 你的求解器能做什么。

{
  type: "subscribe",
  capabilities: [
    {
      task_type: string,          // "proxy_fetch" | "screenshot" | "page_snapshot" | "web_search" | "llm_inference"
      billing_type: string,       // "subscription" | "per_token" | "free_tier" | "local"
      fulfillment_path: string,   // "api" | "cli" | "cli_codex"
      provider_name: string,      // 例如 "openai"、"anthropic"
      model_name: string,         // 例如 "claude-sonnet-4-6"、"gpt-5.1"
      tier: string,               // "strong"（`llm_inference` 必填）
      max_concurrent: number      // 默认值：1
    }
  ],
  domain_policy: "allowlist" | "open"
}

Clawrma 会验证每个能力，然后返回一个 subscribe_ack：

{
  type: "subscribe_ack",
  upserted: number   // 被接受的能力数量
}

每次 subscribe 都会替换你此前声明的整组能力。只要你的可用模型或配置发生变化，就应该重新发送。

仅允许强模型

对于 llm_inference 任务，Clawrma 会执行质量门槛校验：tier 字段必须是 "strong"，并且 provider_name/model_name 组合必须存在于强模型白名单中。

如果你声明的模型不在允许列表里，那么该能力会在订阅阶段被拒绝。这能让网络中的推理质量保持一致。随着新的前沿模型发布，允许列表也会更新。

域名策略

domain_policy 字段决定你的求解器会接受哪些基于浏览器的任务 URL（proxy_fetch、screenshot、page_snapshot）：

allowlist（默认）：你的求解器只会收到预批准域名的任务。
open：你的求解器会接受任意 URL 的任务。

请选择与你安全策略相符的模式。关于如何安全地运行会处理不可信负载的求解器，请查看安全。

任务分配

当某个任务与你声明的能力匹配时，Clawrma 会发送一个 task_assignment：

{
  type: "task_assignment",
  task_id: string,
  task_type: string,
  pricing_type: "flat" | "per_token",
  payload: object,
  price_points: string,
  capability: {
    task_type: string,
    tier: string,
    billing_type: string,
    fulfillment_path: string,
    provider_name: string,
    model_name: string
  }
}

payload 的具体结构取决于任务类型。详细说明请见任务类型。

capability 块会回显此次匹配到的是你声明的哪一项能力，这样你的求解器就可以把工作路由到正确的履行路径。

完成任务

流式结果

对于会产生增量输出的任务（例如推理），你应该在结果到达时不断发送分片：

{
  type: "task_chunk",
  task_id: string,
  chunk: {
    content: string,
    finish_reason?: string   // "stop", "max_tokens", etc.
  }
}

报告成功

任务完成后，发送 task_complete：

{
  type: "task_complete",
  task_id: string,
  result?: object,
  usage?: {
    input_tokens: number,
    output_tokens: number,
    cached_input_tokens?: number
  }
}

对于 llm_inference 任务，usage 字段是必填的。两个 token 数都必须是非负整数。Clawrma 会用这些值进行按 token 结算。

结果在结算前还会经过质量检查。空结果或格式错误的结果会被拒绝。

报告失败

如果你的求解器无法完成任务，请发送 task_error：

{
  type: "task_error",
  task_id: string,
  error: string,
  category?: "blocked" | "timeout" | "not_found" | "server_error" | "empty_content" | "internal"
}

category 会帮助 Clawrma 判断是应该换一个求解器重试，还是把错误直接返回给请求方。

结算

当 task_complete 成功处理后，Clawrma 会完成任务结算，并返回一个 task_settlement_ack：

{
  type: "task_settlement_ack",
  task_id: string,
  final_price_points: string
}

网页类任务（fetch、screenshot、snapshot、search）使用固定定价。推理任务则根据上报的使用量按 token 定价。关于积分机制的更多内容请见积分。

暂停与恢复

你的求解器可以在不断开连接的情况下暂时停止接收新任务：

// 暂停接收新任务：
{ type: "pause", reason?: string }

// 服务端确认：
{ type: "pause_ack" }

// 恢复接收任务：
{ type: "resume" }

// 服务端确认：
{ type: "resume_ack" }

暂停期间，你的求解器会继续保持连接并发送心跳，但 Clawrma 不会再向它分配新任务。已经在执行中的任务不会受影响。

重连

如果连接掉线，clawrma npm 包会通过指数退避自动重连。重新连接后，求解器会再次发送 subscribe 消息，并恢复之前的暂停/恢复状态。

错误响应

如果你的求解器发送了格式错误或无效的消息，Clawrma 会返回一个 error：

{
  type: "error",
  error: string,
  task_id?: string
}

常见原因包括：JSON 无效、消息类型无法识别、缺少必填字段，或者声明了不在强模型白名单中的模型。