Harness 管理

Cloud SDK 只通过 UHP harness 管理实例内的智能体。harnesses 资源将调用发送到当前 Cloud host 上的 /uhp/v1，不再提供通用运行时方法调用。

TypeScript 方法	HTTP 路由	用途
harnesses.create(input)	POST /uhp/v1/harnesses	创建智能体；必须提供 BeeOS 扩展字段 instance_id 和 name
harnesses.update(id, input)	PUT /uhp/v1/harnesses/{harness_id}	修改技能或应用模板
harnesses.get(id) / list()	GET /uhp/v1/harnesses[/{harness_id}]	读取当前配置
harnesses.listModels(id)	GET /uhp/v1/harnesses/{harness_id}/models	harness 可用的模型

Python 使用同名 snake case 方法（list_models）；Go 使用 Create、Update、Get、List、ListModels 与 UHPHarnessCreate。discovery 能力 harness_management 目前仍为 false，但这些调用按本文描述工作。

const harness = await cloud.harnesses.create({
  base: 'openclaw', name: 'support', instance_id: instanceId,
  default_model: 'openai/gpt-4.1',
});
await cloud.harnesses.update(harness.id, {
  base: 'openclaw',
  template_id: templateId,
  skills: [{ name: 'triage', blob: 'file_abc', sha256: bundleSha256, size_bytes: '18342' }],
});

配置

• 创建：必须提供 instance_id 和 name，base 必须是实例的运行时。default_model 只在创建时生效。创建时不接受技能，请创建后用 update 添加。
• 更新规则：未出现的字段保持不变，base 不可修改。请求中出现 skills 时，与已安装技能比较：
  • 列出且带 files[]（内联文件，受 4 MiB 请求体限制）、content 或 blob（Cloud Files file_... ID，附 sha256 与 size_bytes）的技能会被安装；
  • 未列出的、来自目录（catalog）安装的技能会被卸载；
  • 列出但未安装、且没有 files、content 或 blob 的技能返回 422；
  • 正在安装的技能带 enabled: false 返回 422；请先启用安装，再禁用。
• 模板：BeeOS 扩展字段 template_id 应用智能体模板。
• 模型：单个回合选择模型时传 Responses 的 model 字段。

BeeOS Cloud 暂不支持（均返回 422）：

请求	错误码
harnesses.delete(id)	beeos_harness_delete_not_supported
非空 mcp_servers	beeos_mcp_not_supported
update 时 default_model 与当前值不同（且未带 template_id）	beeos_field_not_supported
修改名称，system_prompt、disabled_tools、environment、max_step、timeout_seconds、plugins	beeos_field_not_supported

同步写入

create、update 是同步调用。OpenAPI 文档中这些操作的说明写明，Cloud 提交运行时工作后最多等待 45 秒再响应，因此这些调用的 HTTP 超时应不少于 60 秒。

状态	含义	处理方式
200	所有变更已生效	使用返回的 harness
422	校验失败或请求暂不支持，未提交任何工作	修正请求
409 beeos_harness_busy	该 harness 有另一个写入正在进行	等待 Retry-After 后重试
502 harness_error	部分条目失败；error.detail.operations[] 逐项给出 kind、name、status	成功项已生效；修正后重发请求以重试其余项
503 harness_unavailable	实例未运行或操作日志暂不可用	稍后重试
504 beeos_harness_update_in_progress	工作仍在进行	等待 Retry-After 后重发完全相同的请求

504 后重发相同请求会挂回在途工作，而不会重新开始。不支持 ETag / If-Match，也没有技能文件端点。

全部操作及其字段见 harnesses domain。