Buda AI - API Claw — 智能硬件 & 第三方开发者接入

通过 Buda OpenAPI，让你的硬件或软件产品拥有云端 AI Agent 能力，无需自建推理基础设施

智能手表、IoT 设备、聊天插件……这些产品都想内置 AI Agent，但在设备端跑大模型不现实：算力不够、功耗太高、效果太差。

API Claw 就是为这个场景设计的：通过 Buda 的 OpenAPI，第三方开发者可以用几个 API 调用，给自己的产品接入一个云端 OpenClaw 🦞 AI Agent，拥有对话能力和专属知识库，按需唤醒、不用时零消耗。

更准确地说，你接入的不是一个裸模型 API，而是一层已经托管好的 Agent 能力层，里面已经包括模型、运行时、知识库、会话管理和弹性扩缩容。

适合谁

智能硬件开发商 — 手表、耳机、IoT 设备，想内置 AI 助手
软件开发商 — 微信小程序、App、浏览器插件，想嵌入 AI 对话
SaaS 服务商 — 想给自己的客户提供"带 AI 的私有空间"

两类最典型的接入方

1. 聊天软件、SaaS 工具、第三方软件服务商

如果你已经有自己的产品，有用户、有聊天窗口、有表单或工作流，API Claw 可以让你在不重做整套后端 AI 基础设施的前提下，把 AI Agent 直接嵌入进去。

例如：

一个聊天软件，希望每个聊天窗口都能接一个 AI 助手
一个客服 SaaS，希望每个客户都有自己的私有 AI 客服
一个浏览器插件或企业内部系统，需要一个云端 AI Worker

2. 智能硬件厂商

如果你在做智能手表、耳机、语音终端或其他联网设备，API Claw 可以让设备直接连接一个云端 AI 大脑，而不是在设备本地硬跑复杂智能能力。

也就是说：

设备端负责输入输出
Agent 在云端运行
能力升级在服务端完成，不必把复杂度都压到固件里

工作原理

你的产品（硬件/软件）
        ↓  API 调用
  Buda OpenAPI
        ↓
  Space（租户空间）
        ↓
  Agent（AI 助手）+ Drive（知识库）
        ↓
  Chat Session（对话）

每个终端用户对应一个独立的 Chat Session，上下文隔离。Agent 睡眠时不消耗资源，收到消息时自动唤醒。

你不需要自己做的部分

接入 API Claw 之后，开发者不需要再单独建设或维护下面这些基础设施：

模型配置和供应商切换
推理机器或 GPU 基础设施
Agent 运行时和工具沙箱
文件知识库处理
会话与上下文管理
不同用户 / 客户之间的租户隔离
空闲 Agent 的唤醒与休眠调度

这正是 API Claw 的价值所在：你的团队专注产品本身，Buda 提供背后的 Agent 基础设施层。

	裸模型 API	API Claw
返回内容	文本或结构化结果	带上下文的 Agent 回复
会话	你自己管理	内建 Session 模型
知识库	你自己做检索	自带 Drive 知识库
运行时	你自己编排	托管 Agent Runtime
多租户	你自己设计	内建 Space 隔离
运维	你自己扛	Buda 托管

API Claw 和 OpenClaw 的关系

OpenClaw 是底层的 Agent 能力和运行时模型，API Claw 则是把这层能力产品化、API 化之后给外部开发者接入的方式。

简单说：

OpenClaw = 底层 Agent runtime / capability layer
API Claw = 面向开发者的接入层

API 路由命名

API Claw 是营销和产品名；实际 OpenAPI 资源名建议交给 API Agents。公开 REST 路由统一使用 /api/v1 作为版本前缀，资源使用复数、kebab-case：

/api/v1/api-agents

我不建议用 /apiagents：它没有版本前缀，单词边界不清楚，也容易和 Buda 内部 Agent 管理接口混淆。/api/v1/api-agents 更适合作为实际功能 API；API Claws 则保留在营销、导航和文档标题里。主流程优先使用 /api/v1/api-agents/{agentId}/...；已经明确知道 spaceId 和 agentId 的系统，也可以继续使用嵌套资源路由。

API 组	主要路由	控制什么
Space API	`/api/v1/spaces`	客户、设备、团队或账号的租户边界
API Agents API	`/api/v1/api-agents`	API Claws 产品对应的实际 OpenAPI 资源
Agent API	`/api/v1/spaces/{spaceId}/agents`	某个 Space 内的托管 Agent
Drive API	`/api/v1/api-agents/{agentId}/drive/files`	Agent 的长期知识库、手册、策略和记忆
Chat Session API	`/api/v1/spaces/{spaceId}/agents/{agentId}/chat-sessions`	用户会话、异步 Agent 运行和消息
Embed API	`/api/v1/spaces/{spaceId}/agents/{agentId}/embed-urls`	短期 iframe URL 或前端安全访问

接入流程

注册开发者账号，获取 API Key

在 Buda 注册一个开发者账号，进入设置获取 API Key。这个 Key 用于后续所有 OpenAPI 调用的鉴权。

创建 Space（租户空间）

每个你的客户（或每台设备）对应一个 Space。

POST /api/v1/spaces
Authorization: Bearer <your-api-key>
Content-Type: application/json

{
  "name": "用户的设备空间",
  "slug": "device-space"
}

返回 spaceId，保存下来。

在 Space 内创建 Agent

你可以使用顶层产品资源创建 API Claw：

POST /api/v1/api-agents
Authorization: Bearer <your-api-key>
Content-Type: application/json

{
  "spaceId": "{spaceId}",
  "name": "我的 AI 助手",
  "emoji": "AI",
  "instructions": "你是一个智能手表助手，帮助用户管理日程、回答健康问题。"
}

返回 agentId 和 driveId。如果你已经在代码里明确维护 Space 下的 Agent，也可以使用等价的嵌套路由 POST /api/v1/spaces/{spaceId}/agents。

（可选）写入知识库文件到 Drive

如果你的 Agent 需要基于特定文档回答问题（产品手册、FAQ 等），可以把文件写入 Drive：

PUT /api/v1/api-agents/{agentId}/drive/files
Authorization: Bearer <your-api-key>
Content-Type: application/json

{
  "path": "manuals/reset-device.md",
  "mimeType": "text/markdown",
  "content": "# 重置设备\n\n长按表冠 8 秒，然后在屏幕上确认。"
}

等价的 Space-scoped 路由 /api/v1/spaces/{spaceId}/agents/{agentId}/drive/files 仍然保留，适合你的后端本来就以 Space 为租户边界工作的场景。

发起对话

POST /api/v1/spaces/{spaceId}/agents/{agentId}/chat-sessions
Authorization: Bearer <your-api-key>
Content-Type: application/json

{
  "message": "我该怎么重置设备？",
  "mode": "chat"
}

Buda 会返回 session.id，并异步启动 Agent 运行。如果你想继续同一个终端用户的上下文，保存这个 session.id，后续请求里带上它。

读取会话结果

GET /api/v1/api-agents/{agentId}/sessions/{sessionId}
Authorization: Bearer <your-api-key>

返回里包含会话状态和消息。轮询到状态变成 completed、waiting_for_input、failed 或 cancelled 即可。

API Claw OpenAPI 端点

这些端点会出现在 /api/v1/openapi.json，也可以在 /api/v1/doc 的 Swagger UI 中查看。

Endpoint	用途
`GET /api/v1/spaces`	列出 API Key 用户可访问的 Spaces
`POST /api/v1/spaces`	创建租户 Space
`GET /api/v1/api-agents`	列出当前 API Key 可访问的 API Agents
`POST /api/v1/api-agents`	在某个 Space 下创建 API Agent
`GET /api/v1/spaces/{spaceId}/agents`	列出某个 Space 内的 Claw Agents
`POST /api/v1/spaces/{spaceId}/agents`	创建带独立 Drive 的托管 Claw Agent
`GET /api/v1/api-agents/{agentId}/drive/files`	用 API Agents 路由浏览 Agent Drive 文件
`PUT /api/v1/api-agents/{agentId}/drive/files`	用 API Agents 路由创建或覆盖 Drive 文件
`GET /api/v1/spaces/{spaceId}/agents/{agentId}/drive/files`	用 Space-scoped 路由浏览同一个 Agent Drive
`PUT /api/v1/spaces/{spaceId}/agents/{agentId}/drive/files`	用 Space-scoped 路由创建或覆盖同一个 Drive 文件
`POST /api/v1/spaces/{spaceId}/agents/{agentId}/chat-sessions`	发送消息并启动或继续 Agent 会话
`GET /api/v1/api-agents/{agentId}/sessions`	列出某个 API Agent 的会话
`POST /api/v1/api-agents/{agentId}/sessions`	创建某个 API Agent 的会话
`GET /api/v1/api-agents/{agentId}/sessions/{sessionId}`	读取会话状态和消息
`POST /api/v1/api-agents/{agentId}/sessions/{sessionId}/messages`	向已有会话发送消息
`DELETE /api/v1/api-agents/{agentId}/sessions/{sessionId}/run`	停止正在运行的会话
`POST /api/v1/api-agents/{agentId}/sessions/{sessionId}/attachments`	为聊天附件申请上传 URL
`GET /api/v1/api-agents/{agentId}/sessions/{sessionId}/stream`	恢复活跃会话流
`POST /api/v1/api-agents/{agentId}/sessions/{sessionId}/chat`	使用 AI SDK 消息协议进行流式聊天
`POST /api/v1/spaces/{spaceId}/agents/{agentId}/embed-urls`	创建短期 iframe URL
`POST /api/v1/embed/chat-sessions/{sessionId}/messages`	使用短期 embed token 从前端发送消息

计费模式

Buda 按 Space 收费，不按终端用户数量收费。你作为开发者购买 Space，如何向你的终端用户收费由你自己决定。

典型模式：

你向 Buda 购买 Space（批量可议价）
你向你的终端用户收订阅费（手表激活费、月费等）
差价即为你的利润

为什么硬件团队会特别在意这个能力

对硬件团队来说，这会直接改变成本结构：

不需要为了 AI 能力把设备做得足够重
不需要让用户自己的电脑或手机长期充当主运行环境
不需要额外养一支复杂的 AI 后端团队，只为支撑某一条设备产品线

你的硬件可以保持轻量，而 AI 能力持续在云端升级。

与 ChatGPT / OpenAI 的类比

	OpenAI	Buda
面向消费者的产品	ChatGPT	Buda App
面向开发者的 API	OpenAI API	Buda OpenAPI
开发者用 API 构建	自己的 AI 产品	带 Agent + Drive 的完整 AI 空间

区别在于：Buda OpenAPI 不只是模型调用，而是提供了完整的 Agent 运行环境，包括知识库、会话管理、工具调用能力。

为什么不用 OpenClaw？

OpenClaw 是一个优秀的开源 AI Agent 项目，适合个人用户在自己的机器上自托管运行。但对于需要规模化接入的硬件或软件开发商，它并不是合适的选择。

完整对比参见：Buda vs OpenClaw 深度对比

	OpenClaw	Buda
定位	开源个人助手，自托管	商业企业级平台，托管服务
基础设施	运行在用户本地机器	自研 Kubernetes 集群（Claw Computer），弹性伸缩
网关架构	重量级 Gateway，单机瓶颈	无传统 Gateway，轻量 API 层，天然横向扩展
多租户	不支持，每个实例独立	原生多租户，一个 API Key 管理百万 Space
Token 管理	依赖用户自行配置模型	商业化 Token 管理，成本可控可预测
隔离性	共享宿主机 OS	每个 Agent 独立沙箱，容器级隔离
SLA & 支持	社区支持，无 SLA	企业级 SLA，商业支持
适合场景	个人极客、开发者自用	硬件量产、SaaS 集成、规模化商业部署

一句话总结：OpenClaw 是给个人用的工具，Buda 是给开发者卖给用户的基础设施。

如果你要给 10 万台手表每台配一个 AI 助手，你需要的是 Buda，而不是在每台设备背后跑一个 OpenClaw 实例。

常见问题

终端用户需要注册 Buda 账号吗？ 不需要。终端用户完全不感知 Buda 的存在，你的产品通过 API 代理所有交互。

Agent 不用时会一直消耗资源吗？ 不会。Agent 在没有对话时处于休眠状态，只有收到消息时才被唤醒处理。

我能给不同用户配置不同的 Agent 指令吗？ 可以。每个 Space 可以有独立的 Agent 配置，你可以按需为不同用户创建不同的 Space 和 Agent。

API Claw — 智能硬件 & 第三方开发者接入

适合谁