Cloud 快速开始

在可信后端使用服务端 SDK。使用服务端 SDK 2.0.0。将 BEEOS_CLOUD_API_URL 设为 https://api.cloud.beeos.ai/v1（或当前环境的 /v1 URL），将 bsk_ 服务端 Key 存放于 BEEOS_API_KEY，并将已认证产品用户映射到应用内 BEEOS_EXTERNAL_USER_ID。TypeScript 与 Python 均通过 BeeOSClient 提供强类型资源方法和结果。

创建托管实例

从 GET /v1/instance-templates 选择已发布的 variant_id，设置 BEEOS_VARIANT_ID。OpenClaw 或 Hermes 使用 BYOK llm.providers 和 llm.models：每个模型引用 provider ID，且恰好一个模型为 default、order 为 0。provider 协议为 openai 或 anthropic，需使用对应 base URL 和自己的 provider Key。本例使用 OpenAI 协议。

AgentBay 和 BeeOS 浏览器/移动端 variant 不需要 Cloud 注入模型：这些无模型框架应省略整个 llm 块。不要发送已废弃的 model_primary 或 model_credential 字段。provider Key 只保存在后端配置中，不得记录 BYOK 请求体。

Python 安装：pip install beeos-cloud-sdk==2.0.0。

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: process.env.BEEOS_CLOUD_API_URL!, // https://api.cloud.beeos.ai/v1
  apiKey: process.env.BEEOS_API_KEY!, // bsk_…, backend only
}).withExternalUser(process.env.BEEOS_EXTERNAL_USER_ID!);

const created = await cloud.instances.create({
  name: "assistant-prod",
  variant_id: process.env.BEEOS_VARIANT_ID!,
  llm: {
    providers: [{
      id: "my-provider",
      protocol: "openai",
      base_url: process.env.BEEOS_MODEL_PROVIDER_URL!,
      api_key: process.env.BEEOS_MODEL_PROVIDER_API_KEY!,
    }],
    models: [{
      provider_id: "my-provider",
      model: process.env.BEEOS_MODEL_ID!,
      role: "default",
      order: 0,
    }],
  },
}, crypto.randomUUID());
console.log(created.data.id);

就绪后发送工作

创建返回 202、data.id 和 operation，并不表示实例已就绪。使用 cloud.instances.getStatus(created.data.id)（Python：cloud.instances.get_status(created["data"]["id"])）等待实例 running，再用 cloud.harnesses.list() 选择该实例的就绪 harness。SDK 自动发送外部用户请求头，harness 路径为 /uhp/v1/harnesses。将该 harness ID 设置为 BEEOS_HARNESS_ID；它与实例 ID 不同。将供应和就绪失败明确反馈给产品后端。

下面代码继续使用上文已限定用户范围的 cloud 客户端：

const response = await cloud.responses.create({
  input: "Hello",
  metadata: { harness_id: process.env.BEEOS_HARNESS_ID! },
}, crypto.randomUUID());
console.log(response.id, response.status, response.output);

Response 有独立 ID、状态和输出。继续下一回合时传 previous_response_id；后台工作设置 background: true，再用 cloud.responses.get(response.id)（Python：cloud.responses.get(response["id"])）查询进度。Harness SDK 在运行进程内部处理工作。

通过产品后端及其认证用户通道返回面向用户的结果。前端不得接收服务端 Key 或 provider Key；参阅产品前端集成。