跳轉到主要內容

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

The OpenClaw App SDK 是供 OpenClaw 程序外部應用程式使用的公開用戶端 API。當腳本、儀表板、CI 作業、IDE 擴充功能或其他外部應用程式想要連線到 Gateway、啟動代理執行、串流事件、等待結果、取消工作，或檢查 Gateway 資源時，請使用 @openclaw/sdk。
App SDK 與 Plugin SDK 不同。 @openclaw/sdk 會從 OpenClaw 外部與 Gateway 通訊。 openclaw/plugin-sdk/* 僅供在 OpenClaw 內部執行，並註冊提供者、通道、工具、hook 或受信任執行階段的 plugins 使用。

​
目前提供的內容

@openclaw/sdk 提供：
Surface狀態功能
OpenClaw就緒主要用戶端進入點。負責傳輸、連線、請求與事件。
GatewayClientTransport就緒由 Gateway 用戶端支援的 WebSocket 傳輸。
oc.agents就緒列出、建立、更新、刪除並取得代理控制代碼。
Agent.run()就緒啟動 Gateway agent 執行並回傳 Run。
oc.runs就緒建立、取得、等待、取消並串流執行。
Run.events()就緒串流標準化的逐執行事件，並為快速執行提供重播。
Run.wait()就緒呼叫 agent.wait 並回傳穩定的 RunResult。
Run.cancel()就緒依執行 id 呼叫 sessions.abort，可用時包含 session key。
oc.sessions就緒建立、解析、傳送至、修補、壓縮並取得 session 控制代碼。
Session.send()就緒呼叫 sessions.send 並回傳 Run。
oc.tasks就緒列出、讀取並取消 Gateway 任務帳本項目。
oc.models就緒呼叫 models.list 與目前的 models.authStatus 狀態 RPC。
oc.tools就緒透過政策管線列出、限定範圍並叫用 Gateway 工具。
oc.artifacts就緒列出、取得並下載 Gateway transcript artifacts。
oc.approvals就緒透過 Gateway approval RPC 列出並解析 exec approvals。
oc.environments部分列出 Gateway-local 與 node 環境候選項目；尚未接上建立/刪除。
oc.rawEvents()就緒為進階消費者公開原始 Gateway 事件。
normalizeGatewayEvent()就緒將原始 Gateway 事件轉換為穩定的 SDK 事件形狀。
SDK 也會匯出這些介面使用的核心型別： AgentRunParams, RunResult, RunStatus, OpenClawEvent, OpenClawEventType, GatewayEvent, OpenClawTransport, GatewayRequestOptions, SessionCreateParams, SessionSendParams, ArtifactSummary, ArtifactQuery, ArtifactsListResult, ArtifactsGetResult, ArtifactsDownloadResult, TaskSummary, TaskStatus, TasksListParams, TasksListResult, TasksGetResult, TasksCancelResult, RuntimeSelection, EnvironmentSelection, WorkspaceSelection, ApprovalMode，以及相關的結果型別。

​
連線到 Gateway

使用明確的 Gateway URL 建立用戶端，或為測試與嵌入式應用程式執行階段注入自訂傳輸。 
import { OpenClaw } from "@openclaw/sdk";

const oc = new OpenClaw({
  url: "ws://127.0.0.1:18789",
  token: process.env.OPENCLAW_GATEWAY_TOKEN,
  requestTimeoutMs: 30_000,
});

await oc.connect();
new OpenClaw({ gateway: "ws://..." }) 等同於 url。建構函式接受 gateway: "auto" 選項，但自動 Gateway 探索尚不是獨立的 SDK 功能；當應用程式尚不知道如何探索 Gateway 時，請傳入 url。 測試時，傳入實作 OpenClawTransport 的物件： 
const oc = new OpenClaw({
  transport: {
    async request(method, params) {
      return { method, params };
    },
    async *events() {},
  },
});

​
執行代理

當應用程式需要代理控制代碼時，使用 oc.agents.get(id)，然後呼叫 agent.run()。 
const agent = await oc.agents.get("main");

const run = await agent.run({
  input: "Review this pull request and suggest the smallest safe fix.",
  model: "openai/gpt-5.5",
  sessionKey: "main",
  timeoutMs: 30_000,
});

for await (const event of run.events()) {
  const data = event.data as { delta?: unknown };
  if (event.type === "assistant.delta" && typeof data.delta === "string") {
    process.stdout.write(data.delta);
  }
}

const result = await run.wait({ timeoutMs: 120_000 });
console.log(result.status);
像 openai/gpt-5.5 這樣的提供者限定模型參照會拆分為 Gateway provider 與 model 覆寫。timeoutMs 在 SDK 中維持毫秒，並會針對 agent RPC 轉換為 Gateway timeout 秒數。 run.wait() 使用 Gateway agent.wait RPC。如果等待期限到期時執行仍在進行中，會回傳 status: "accepted"，而不是假裝執行本身已逾時。執行階段逾時、中止的執行與取消的執行會標準化為 timed_out 或 cancelled。

​
建立並重用 sessions

當應用程式需要持久的 transcript 狀態時，請使用 sessions。 
const session = await oc.sessions.create({
  agentId: "main",
  label: "release-review",
});

const run = await session.send("Prepare release notes from the current diff.");
await run.wait();
Session.send() 會呼叫 sessions.send 並回傳 Run。Session 控制代碼也支援： 
await session.abort(run.id);
await session.patch({ label: "renamed-session" });
await session.compact({ maxLines: 200 });

​
串流事件

SDK 會將原始 Gateway 事件標準化為穩定的 OpenClawEvent envelope： 
type OpenClawEvent = {
  version: 1;
  id: string;
  ts: number;
  type: OpenClawEventType;
  runId?: string;
  sessionId?: string;
  sessionKey?: string;
  taskId?: string;
  agentId?: string;
  data: unknown;
  raw?: GatewayEvent;
};
常見事件類型包含：
事件類型來源 Gateway 事件
run.startedagent 生命週期開始
run.completedagent 生命週期結束
run.failedagent 生命週期錯誤
run.cancelled已中止/取消的生命週期結束
run.timed_out逾時生命週期結束
assistant.delta助手串流 delta
assistant.message助手訊息
thinking.deltaThinking 或計畫串流
tool.call.started工具/項目/命令開始
tool.call.delta工具/項目/命令更新
tool.call.completed工具/項目/命令完成
tool.call.failed工具/項目/命令失敗或遭封鎖狀態
approval.requestedExec 或 plugin approval request
approval.resolvedExec 或 plugin approval resolution
session.createdsessions.changed 建立
session.updatedsessions.changed 更新
session.compactedsessions.changed compaction
task.updated任務更新事件
artifact.updatedPatch 串流事件
raw尚無穩定 SDK 對應的任何事件
Run.events() 會將事件篩選到單一執行 id，並為快速執行重播已看過的事件。這表示文件中的流程是安全的： 
const run = await agent.run("Summarize the latest session.");

for await (const event of run.events()) {
  if (event.type === "run.completed") {
    break;
  }
}
若要使用應用程式範圍的串流，請使用 oc.events()。若要使用原始 Gateway frames，請使用 oc.rawEvents()。

​
模型、工具、artifacts 與 approvals

模型輔助工具會對應到目前的 Gateway 方法： 
await oc.models.list();
await oc.models.status({ probe: false }); // calls models.authStatus
工具輔助工具會公開 Gateway 目錄、有效工具視圖與直接 Gateway 工具叫用。oc.tools.invoke() 會回傳具型別的 envelope，而不是因政策或 approval 拒絕而拋出。 
await oc.tools.list();
await oc.tools.effective({ sessionKey: "main" });
await oc.tools.invoke("tool-name", {
  args: { input: "value" },
  sessionKey: "main",
  confirm: false,
  idempotencyKey: "tool-call-1",
});
Artifact 輔助工具會為 session、run 或 task context 公開 Gateway artifact projection。每次呼叫都需要一個明確的 sessionKey、runId 或 taskId 範圍： 
const { artifacts } = await oc.artifacts.list({ sessionKey: "main" });
const first = artifacts[0];

if (first) {
  const { artifact } = await oc.artifacts.get(first.id, { sessionKey: "main" });
  const download = await oc.artifacts.download(artifact.id, { sessionKey: "main" });
  console.log(download.encoding, download.url);
}
Approval 輔助工具使用 exec approval RPC： 
const approvals = await oc.approvals.list();
await oc.approvals.respond("approval-id", { decision: "approve" });
任務輔助工具使用同時支援 openclaw tasks 的持久任務帳本： 
const tasks = await oc.tasks.list({ status: "running", sessionKey: "agent:main:main" });
const task = await oc.tasks.get(tasks.tasks[0].id);
await oc.tasks.cancel(task.task.id, { reason: "user stopped task" });
環境輔助工具公開唯讀的 Gateway-local 與 node 探索： 
const { environments } = await oc.environments.list();
await oc.environments.status(environments[0].id);

​
目前明確不支援

SDK 包含我們想要的產品模型名稱，但不會默默假裝 Gateway RPC 存在。這些呼叫目前會拋出明確的不支援錯誤： 
await oc.environments.create({});
await oc.environments.delete("environment-id");
逐執行的 workspace、runtime、environment 與 approvals 欄位已型別化為未來形狀，但目前的 Gateway 不支援在 agent RPC 上使用這些覆寫。如果呼叫端傳入它們，SDK 會在提交執行前拋出，避免工作意外以預設 workspace、runtime、environment 或 approval 行為執行。

​
App SDK 與 Plugin SDK

當程式碼位於 OpenClaw 外部時，請使用 App SDK：
  • 啟動或觀察代理執行的 Node 腳本
  • 呼叫 Gateway 的 CI 作業
  • 儀表板與管理面板
  • IDE 擴充功能
  • 不需要成為通道 plugins 的外部橋接
  • 使用假或真實 Gateway 傳輸的整合測試
當程式碼在 OpenClaw 內部執行時，請使用 Plugin SDK：
  • 提供者 plugins
  • 通道 plugins
  • 工具或生命週期 hooks
  • 代理 harness plugins
  • 受信任的 runtime helpers
App SDK 程式碼應從 @openclaw/sdk 匯入。Plugin 程式碼應從已文件化的 openclaw/plugin-sdk/* 子路徑匯入。不要混用這兩份合約。

​
相關