AI智能体>服务端 API>OpenClaw 实例管理

OpenClaw 实例管理

编辑文档 更新于

OpenClaw 是 BRTC 对接的第三方实时音视频 AI 引擎。通过 OpenClaw 实例管理接口，您可以创建、查询、释放 OpenClaw 实例，并在创建 AI 智能体时通过 external_agent_config 绑定使用。

创建 OpenClaw 实例

创建新的 OpenClaw 实例。创建为异步过程，接口返回后实例状态为 CREATING，系统后台自动完成资源分配后状态更新为 RUNNING。

接口请求地址

  • 请求方式：POST/JSON
  • 传输协议：HTTPS
  • 请求 URL：
https://brtc-api.baijiayun.com/vcs/aiagent/v1/openclaw/create

请求参数

名称 位置 类型 必选 中文名 说明
body body object 否 none
» app_id body string 是 应用 ID
» name body string 是 实例名称，同一 app_id 下唯一，最长64字符
» trace_id body string 是 追踪 ID，用于日志排查，建议使用 UUID

请求参数 json 模板

{
  "app_id": "456",
  "name": "test-openclaw-instance",
  "trace_id": "trace-test-001"
}

返回参数

返回数据结构

名称 类型 必选 约束 中文名 说明
» code integer true none none
» data object true none none
»» app_id integer true none 应用 ID
»» name string true none 实例名称
»» trace_id string true none 追踪 ID
»» status string true none 当前状态，固定为 CREATING
» msg string true none none

返回示例

200 Response

{
  "code": 200,
  "data": {
    "app_id": 456,
    "name": "test-openclaw-instance",
    "trace_id": "trace-test-001",
    "status": "CREATING"
  },
  "msg": "succeed"
}

查询 OpenClaw 实例列表

查询当前应用下的 OpenClaw 实例列表，支持按状态、绑定状态等条件过滤。

接口请求地址

  • 请求方式：GET
  • 传输协议：HTTPS
  • 请求 URL：
https://brtc-api.baijiayun.com/vcs/aiagent/v1/openclaw/list

请求参数

名称 位置 类型 必选 中文名 说明
app_id query string 是 应用 ID
openclaw_id query string 否 OpenClaw 实例 ID，按 ID 精确过滤
agent_id query string 否 绑定的智能体 ID，按绑定的智能体过滤
name query string 否 实例名称，精确过滤
status query integer 否 实例状态过滤：
- 0: CREATING（创建中）
- 1: RUNNING（运行中，默认）
- -1: STOPPED（已删除）
不传时默认查询 status >= 0 的实例
is_bound query boolean 否 绑定状态过滤：
- true: 已绑定的实例
- false: 未绑定的实例
- 不传: 全部
limit query integer 否 返回结果数量，默认20，最大100
offset query integer 否 分页偏移量，默认0

请求参数示例

app_id=456&limit=20&offset=0&status=1

返回参数

返回数据结构

名称 类型 必选 约束 中文名 说明
» code integer true none none
» data object true none none
»» total integer true none 总数
»» list [object] true none 实例列表
»»» id integer true none 记录 ID
»»» partner_id integer true none 合作方 ID
»»» app_id integer true none 应用 ID
»»» name string true none 实例名称
»»» trace_id string true none 追踪 ID
»»» room_id string true none 绑定的房间 ID
»»» agent_id string true none 绑定的智能体 ID
»»» openclaw_id string true none OpenClaw 平台实例 ID
»»» url string true none 接口访问地址
»»» token string true none 接口访问令牌
»»» device_id string true none 设备 ID
»»» private_key_pem string true none 设备私钥
»»» device_token string true none 设备令牌
»»» status string true none 实例状态：
- CREATING: 创建中
- RUNNING: 运行中
- STOPPED: 已删除
»»» error_msg string true none 错误信息
»»» is_bound boolean true none 是否已绑定智能体
»»» created_at string true none 创建时间
»»» updated_at string true none 更新时间
» msg string true none none

返回示例

200 Response

{
  "code": 200,
  "data": {
    "total": 1,
    "list": [
      {
        "id": 1,
        "partner_id": 123,
        "app_id": 456,
        "name": "test-openclaw-instance",
        "trace_id": "trace-test-001",
        "room_id": "",
        "agent_id": "",
        "openclaw_id": "openclaw-838d70918dfc",
        "url": "ws://10.233.96.107:18789",
        "token": "c0a6f395410260b18191f4b3b83f2fc0be9513e2b5096d1d802cc5a299a59718",
        "device_id": "",
        "private_key_pem": "",
        "device_token": "",
        "status": "RUNNING",
        "error_msg": "",
        "is_bound": false,
        "created_at": "2025-08-13 10:21:38",
        "updated_at": "2025-08-13 10:21:38"
      }
    ]
  },
  "msg": "succeed"
}

查询 OpenClaw 实例状态

根据 app_id 和 name 查询单个 OpenClaw 实例的详细信息。

接口请求地址

  • 请求方式：GET
  • 传输协议：HTTPS
  • 请求 URL：
https://brtc-api.baijiayun.com/vcs/aiagent/v1/openclaw/status

请求参数

名称 位置 类型 必选 中文名 说明
app_id query string 是 应用 ID
name query string 是 实例名称

请求参数示例

app_id=456&name=test-openclaw-instance

返回参数

返回数据结构与列表接口的 OpenclawItem 结构一致。

名称 类型 必选 约束 中文名 说明
» code integer true none none
» data object true none none
»» id integer true none 记录 ID
»» partner_id integer true none 合作方 ID
»» app_id integer true none 应用 ID
»» name string true none 实例名称
»» trace_id string true none 追踪 ID
»» room_id string true none 绑定的房间 ID
»» agent_id string true none 绑定的智能体 ID
»» openclaw_id string true none OpenClaw 平台实例 ID
»» url string true none 接口访问地址
»» token string true none 接口访问令牌
»» device_id string true none 设备 ID
»» private_key_pem string true none 设备私钥
»» device_token string true none 设备令牌
»» status string true none 实例状态
»» error_msg string true none 错误信息
»» is_bound boolean true none 是否已绑定智能体
»» created_at string true none 创建时间
»» updated_at string true none 更新时间
» msg string true none none

返回示例

200 Response

{
  "code": 200,
  "data": {
    "id": 1,
    "partner_id": 123,
    "app_id": 456,
    "name": "test-openclaw-instance",
    "trace_id": "trace-test-001",
    "room_id": "",
    "agent_id": "",
    "openclaw_id": "openclaw-838d70918dfc",
    "url": "ws://10.233.96.107:18789",
    "token": "c0a6f395410260b18191f4b3b83f2fc0be9513e2b5096d1d802cc5a299a59718",
    "device_id": "",
    "private_key_pem": "",
    "device_token": "",
    "status": "RUNNING",
    "error_msg": "",
    "is_bound": false,
    "created_at": "2025-08-13 10:21:38",
    "updated_at": "2025-08-13 10:21:38"
  },
  "msg": "succeed"
}

释放 OpenClaw 实例

释放指定的 OpenClaw 实例。释放后实例状态变为 STOPPED，将无法再被 AI 智能体绑定使用。

接口请求地址

  • 请求方式：POST/JSON
  • 传输协议：HTTPS
  • 请求 URL：
https://brtc-api.baijiayun.com/vcs/aiagent/v1/openclaw/release

请求参数

名称 位置 类型 必选 中文名 说明
body body object 否 none
» app_id body string 是 应用 ID
» openclaw_id body string 是 OpenClaw 实例 ID

请求参数 json 模板

{
  "app_id": "456",
  "openclaw_id": "openclaw-838d70918dfc"
}

返回参数

返回数据结构

名称 类型 必选 约束 中文名 说明
» code integer true none none
» data object true none none
»» openclaw_id string true none OpenClaw 实例 ID
»» success boolean true none 是否释放成功
» msg string true none none

返回示例

200 Response

{
  "code": 200,
  "data": {
    "openclaw_id": "openclaw-838d70918dfc",
    "success": true
  },
  "msg": "succeed"
}

实例状态说明

状态 值 说明
CREATING 0 创建中，系统后台正在分配资源，请等待
RUNNING 1 运行中，实例可用，可被 AI 智能体绑定
STOPPED -1 已删除/已释放，不可用

与 AI 智能体的关系

  1. 通过 OpenClaw 管理接口创建 OpenClaw 实例，获取 openclaw_id。
  2. 在创建 AI 智能体时，设置 external_agent_enable: true，并在 external_agent_config 中指定 type: "openclaw" 和 openclaw_id。
  3. AI 智能体停止时，系统会自动解绑关联的 OpenClaw 实例（实例变为未绑定状态，可供下次使用）。
  4. 不再需要时，通过释放接口释放 OpenClaw 实例。
{{allComment[version]}} ×
  • 暂无评论
  • {{comment.author}}
    {{ comment.createdAt | date: 'yyyy-MM-dd HH:mm:ss '}}
    {{comment.content}}
您需要 后才能评论