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。

相關內容