API Claw（爪）

智能手表、IoT 设备、聊天插件——它们都希望内置 AI 智能体。但在设备本地运行一个大模型并不可行：算力不足、功耗过高、效果欠佳。

API Claw（爪） 正是为此而生。只需对 Buda 位于 /api/v1 的 REST API 发起几次调用，第三方开发者就能为自己的产品配备一个云端托管的 AI 智能体，它具备对话能力和私有知识库，按需唤醒，闲置时不占用任何资源。

实际上，你接入的并不是一个原始的模型 API，而是一个托管的智能体能力层，它已经包含了模型接入、运行时、知识库、会话管理以及运维扩缩容。

它面向谁

• 智能硬件厂商——希望内置 AI 助手的手表、耳机、IoT 设备
• 软件开发者——希望嵌入 AI 对话的小程序、应用、浏览器扩展
• SaaS 提供商——希望为客户提供「AI 驱动的私有空间」

两类常见的买家

1. 聊天应用、SaaS 工具和第三方软件

如果你已经有一个拥有用户、对话、表单或工作流的产品，API Claw（爪）让你无需自己搭建整套后端就能加入 AI 智能体。

例如：

• 一个聊天应用，希望在每段对话中加入 AI 助手
• 一个客服 SaaS，希望让每个客户都拥有专属的 AI 支持智能体
• 一个浏览器扩展或企业内部工具，需要一个基于云的 AI 工作者

2. 硬件制造商

如果你在打造智能手表、耳机、语音终端或其他联网设备，API Claw（爪）让设备连接到云端的 AI 大脑，而不必试图在本地运行智能。

这意味着：

• 设备负责输入与输出
• 智能体在云端运行
• 升级在服务端完成，而不必依赖持续而复杂的固件更新

工作原理

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

每个终端用户都会获得一个独立的 Chat Session，上下文相互隔离。智能体在空闲时休眠，并在消息到达时自动唤醒。

你无需自己构建什么

使用 API Claw（爪），开发者无需单独构建或运维：

• 模型配置与供应商切换
• 推理机器或 GPU 基础设施
• 智能体运行时与工具沙箱
• 文件摄取与知识库处理
• 会话与上下文管理
• 面向不同用户或客户的租户隔离
• 针对空闲智能体的唤醒/休眠编排

这正是核心价值：你的团队可以专注于产品体验，而 Buda 在背后提供智能体基础设施层。

为什么不直接调用 LLM API？

调用模型 API 给你的是模型输出。API Claw（爪）给你的是一个可运营的 AI 智能体。

如果你是一家产品公司，这个差异比单纯的模型质量更重要。

API Claw（爪）与 OpenClaw 的对比

OpenClaw 是智能体能力与运行时层。API Claw（爪）是产品化的 API 表面，让外部硬件和软件得以接入该能力。

简而言之：

• OpenClaw = 底层的智能体运行时 / 能力模型
• API Claw（爪） = 在其之上构建、面向开发者的集成层

API 总览一览

API Claw（爪）最容易理解为五个相互协作的 API 分组：

API Claw（爪）有自己的托管 iframe 表面。你的后端创建一个短期嵌入 URL：

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

{
  "externalUserId": "customer-123",
  "displayName": "Kelly",
  "ttlSeconds": 3600,
  "mode": "chat"
}

响应中包含：

{
  "embedUrl": "https://buda.im/embed/api-claw/tsk_abc123#token=SHORT_LIVED_TOKEN",
  "sessionId": "tsk_abc123",
  "expiresAt": "2026-05-26T12:00:00.000Z"
}

然后将返回的 embedUrl 放进 iframe：

<iframe
  src="https://buda.im/embed/api-claw/tsk_abc123#token=SHORT_LIVED_TOKEN"
  title="API Claw Agent"
  allow="microphone"
  style="width: 400px; height: 600px; border: 0;"
></iframe>

令牌位于 URL 的哈希片段中，因此它不会作为首次页面请求的一部分被发送到服务器。页面在浏览器中读取该令牌，并仅将其用于 /api/v1/embed/... 的 JSON 调用。令牌过期后，从你的后端创建一个新的嵌入 URL。

应用场景如何组合这些 API

大多数产品都遵循同样的生命周期：创建、注入、运行、读取、学习、更新。

经验法则：

• 把持久的知识放进 Drive。
• 把瞬时的用户输入放进 Chat Session。
• 把客户或设备的隔离放进 Space。
• 把角色、行为和运行时身份放进 API Claw（爪）。主要的开发者流程使用 /api/v1/api-agents/{agentId}/...；当你的后端已经在 Space 上下文中工作时，嵌套的 /api/v1/spaces/{spaceId}/agents/{agentId}/... 端点仍然可用。
• 只有当调用方是无法安全持有主 API 密钥的前端时，才使用 Embed API。

集成步骤

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

{
  "name": "Acme Device Fleet",
  "slug": "acme-device-fleet"
}

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

{
  "name": "Watch Assistant",
  "emoji": "AI",
  "instructions": "You are a smartwatch assistant. Use Drive files as source of truth. Keep replies short enough for a small screen."
}

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": "# Resetting the device\n\nHold the crown for 8 seconds, then confirm on screen."
}

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

{
  "message": "How do I reset my device?",
  "mode": "chat"
}

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

API Claw（爪）的 OpenAPI 端点

这些端点可在 /api/v1/openapi.json 的 OpenAPI JSON 和 /api/v1/doc 的交互式 Swagger UI 中查看。

我应该 iframe 哪个 URL？

对于 API Claw（爪），你的后端应首先调用这个 OpenAPI 端点：

POST /api/v1/spaces/{spaceId}/agents/{agentId}/embed-urls

它返回一个类似这样的 embedUrl：

https://buda.im/embed/api-claw/{sessionId}#token={shortLivedToken}

返回的那个确切 URL 就是 iframe 的 src。

在以下情况使用它：

• 你想要一个现成的、由 Buda 托管的 API Claw（爪）对话界面。
• 你需要一个按计划过期的链接。
• 你要嵌入到网站、后台管理面板、客户门户或合作伙伴控制台中。
• 你的产品后端可以在过期前后刷新该 URL。

不要 iframe /api/v1/embed/...。那些路由是供托管 iframe 页面和原生前端使用的 JSON API。对于微信小程序、移动应用和浏览器扩展，请自行构建对话界面并调用：

POST /api/v1/spaces/{spaceId}/agents/{agentId}/embed-sessions
POST /api/v1/embed/chat-sessions/{sessionId}/messages
GET  /api/v1/embed/chat-sessions/{sessionId}

这样前端就获得了一个作用域受限的短期令牌，而无需暴露你的主 Buda API 密钥。

小程序的嵌入式对话

对于微信小程序、移动应用、浏览器扩展，或任何你无法完全掌控的前端，都不要把你的主 Buda API 密钥下发到客户端。

请改用嵌入流程：

1. 你的后端用真实的 API 密钥调用 Buda，并签发一个短期嵌入令牌。
2. 你的小程序只存储那个短期令牌。
3. 小程序通过 /api/v1/embed/... 发送消息并轮询状态。
4. 令牌过期后，你的后端再签发一个新的。

后端：签发一个嵌入会话

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

{
  "externalUserId": "wechat-openid-oABC123",
  "displayName": "Kelly",
  "ttlSeconds": 3600,
  "mode": "chat",
  "metadata": {
    "miniProgram": "wechat",
    "scene": "device-support"
  }
}

只向小程序返回 token、sessionId 和所需的 API URL。如果要用 iframe，请改为调用 /embed-urls 并返回 embedUrl。

小程序：发送一条消息

POST /api/v1/embed/chat-sessions/{sessionId}/messages
Authorization: Bearer <embed-token>
Content-Type: application/json

{
  "message": "How do I reset my device?",
  "mode": "chat"
}

小程序：轮询回复

GET /api/v1/embed/chat-sessions/{sessionId}
Authorization: Bearer <embed-token>

这为小程序提供了一条干净的原生集成路径，没有 iframe 限制、第三方 Cookie 问题或泄露的服务端凭证。

最小的 Node.js 示例

const API_BASE = "https://buda.im/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.BUDA_API_KEY}`,
  "Content-Type": "application/json",
};

const space = await fetch(`${API_BASE}/spaces`, {
  method: "POST",
  headers,
  body: JSON.stringify({ name: "Acme Device Fleet" }),
}).then((res) => res.json());

const agent = await fetch(`${API_BASE}/spaces/${space.id}/agents`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Watch Assistant",
    instructions: "Answer from Drive first. Keep replies concise.",
  }),
}).then((res) => res.json());

await fetch(`${API_BASE}/spaces/${space.id}/agents/${agent.id}/drive/files`, {
  method: "PUT",
  headers,
  body: JSON.stringify({
    path: "manuals/reset-device.md",
    content: "# Resetting\n\nHold the crown for 8 seconds.",
    mimeType: "text/markdown",
  }),
});

const started = await fetch(`${API_BASE}/spaces/${space.id}/agents/${agent.id}/chat-sessions`, {
  method: "POST",
  headers,
  body: JSON.stringify({ message: "How do I reset my device?", mode: "chat" }),
}).then((res) => res.json());

const status = await fetch(`${API_BASE}/api-agents/${agent.id}/sessions/${started.session.id}`, {
  headers: { Authorization: headers.Authorization },
}).then((res) => res.json());

构建一个持续演进的、基于 Drive 的 Agent

真正有用的模式不是「每次提示词都把所有内容都发过去」。让你的产品把 Drive 当作 Agent 的持久大脑：

• 把产品手册、政策、发布说明和用户特定状态写入 Drive。
• 每段对话以一条小的运行时消息开始，比如用户的问题或最新的设备事件。
• 轮询 Chat Session 的状态和消息。
• 当你的产品学到了某些可持久保留的内容时，把它作为文件写回 Drive。
• 让下一次运行自动继承这份改进后的上下文。

设备或第三方应用正是通过这种方式获得一个随时间不断进步的 Agent：API 调用唤醒 Agent，会话捕捉当下的对话，而 Drive 把持久知识带向未来。

计费模型

典型模型：

• 你从 Buda 购买 Space（提供批量定价）
• 你向终端用户收取订阅费或激活费
• 差价归你

硬件团队为何在意

对硬件公司而言，这改变了成本结构：

• 无需出厂一台算力足以在本地运行完整 AI 栈的设备
• 无需让用户的笔记本或手机充当主要运行时
• 无需仅为支持一条设备线就维护一个独立的 AI 后端团队

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

类比：ChatGPT 与 OpenAI

差别在于：Buda OpenAPI 不只是模型推理——它提供一个完整的 Agent 运行时，包括知识库、会话管理和工具调用能力。

为什么不用 OpenClaw？

OpenClaw 是一个出色的开源 AI 智能体项目，非常适合想在自己机器上自托管助手的个人。但对于需要规模化的硬件或软件开发者来说，它并不是合适的工具。

完整对比请参阅：Buda 对比 OpenClaw

一句话：OpenClaw 是供个人使用的工具。Buda 是开发者卖给自己用户的基础设施。

如果你需要让 10 万只智能手表各自拥有专属的 AI 助手，你需要的是 Buda，而不是在每台设备背后运行一个独立的 OpenClaw 实例。

常见问题

终端用户需要 Buda 账户吗？ 不需要。终端用户对 Buda 毫无感知。你的产品通过 API 代理所有交互。

Agent 在空闲时会消耗资源吗？ 不会。当没有活跃对话时，Agent 会休眠，并在消息到达时自动唤醒。

我可以为不同用户配置不同的 Agent 指令吗？ 可以。每个 Space 都有自己独立的 Agent 配置。按需为每个用户创建各自的 Space 和 Agent。

相关内容