SDK Aplikasi OpenClaw

SDK Aplikasi OpenClaw adalah API klien publik untuk aplikasi di luar proses OpenClaw. Gunakan @openclaw/sdk saat skrip, dasbor, pekerjaan CI, ekstensi IDE, atau aplikasi eksternal lain ingin terhubung ke Gateway, memulai run agen, melakukan streaming peristiwa, menunggu hasil, membatalkan pekerjaan, atau memeriksa sumber daya Gateway.

Yang tersedia saat ini

@openclaw/sdk tersedia dengan:

SDK juga mengekspor tipe inti yang digunakan oleh permukaan tersebut: 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, dan tipe hasil terkait.

Terhubung ke Gateway

Buat klien dengan URL Gateway eksplisit, atau injeksikan transport khusus untuk pengujian dan runtime aplikasi tersemat.

 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://..." }) setara dengan url. Opsi gateway: "auto" diterima oleh konstruktor, tetapi penemuan Gateway otomatis belum menjadi fitur SDK tersendiri; teruskan url saat aplikasi belum tahu cara menemukan Gateway.

Untuk pengujian, teruskan objek yang mengimplementasikan OpenClawTransport:

const oc = new OpenClaw({  transport: {    async request(method, params) {      return { method, params };    },    async *events() {},  },});

Menjalankan agen

Gunakan oc.agents.get(id) saat aplikasi membutuhkan handle agen, lalu panggil 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);

Ref model berkualifikasi provider seperti openai/gpt-5.5 dipisahkan menjadi override provider dan model Gateway. timeoutMs tetap dalam milidetik di SDK dan dikonversi menjadi detik timeout Gateway untuk RPC agent.

run.wait() menggunakan RPC Gateway agent.wait. Deadline tunggu yang berakhir saat run masih aktif mengembalikan status: "accepted" alih-alih seolah-olah run itu sendiri kehabisan waktu. Timeout runtime, run yang dibatalkan paksa, dan run yang dibatalkan dinormalisasi menjadi timed_out atau cancelled.

Membuat dan menggunakan ulang sesi

Gunakan sesi saat aplikasi membutuhkan state transkrip yang tahan lama.

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() memanggil sessions.send dan mengembalikan Run. Handle sesi juga mendukung:

await session.abort(run.id);await session.patch({ label: "renamed-session" });await session.compact({ maxLines: 200 });

Streaming peristiwa

SDK menormalisasi peristiwa mentah Gateway ke dalam envelope OpenClawEvent yang stabil:

type OpenClawEvent = {  version: 1;  id: string;  ts: number;  type: OpenClawEventType;  runId?: string;  sessionId?: string;  sessionKey?: string;  taskId?: string;  agentId?: string;  data: unknown;  raw?: GatewayEvent;};

Tipe peristiwa umum mencakup:

Run.events() memfilter peristiwa ke satu id run dan memutar ulang peristiwa yang sudah terlihat untuk run cepat. Artinya alur terdokumentasi ini aman:

const run = await agent.run("Summarize the latest session."); for await (const event of run.events()) {  if (event.type === "run.completed") {    break;  }}

Untuk stream seluruh aplikasi, gunakan oc.events(). Untuk frame Gateway mentah, gunakan oc.rawEvents().

Model, tool, artefak, dan approval

Helper model memetakan ke metode Gateway saat ini:

await oc.models.list();await oc.models.status({ probe: false }); // calls models.authStatus

Helper tool mengekspos katalog Gateway, tampilan tool efektif, dan pemanggilan tool Gateway langsung. oc.tools.invoke() mengembalikan envelope bertipe alih-alih melempar untuk penolakan kebijakan atau 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",});

Helper artefak mengekspos proyeksi artefak Gateway untuk konteks sesi, run, atau tugas. Setiap panggilan memerlukan satu cakupan eksplisit sessionKey, runId, atau 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);}

Helper approval menggunakan RPC approval eksekusi:

const approvals = await oc.approvals.list();await oc.approvals.respond("approval-id", { decision: "approve" });

Helper tugas menggunakan ledger tugas tahan lama yang juga mendukung 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" });

Helper lingkungan mengekspos penemuan lokal-Gateway dan node yang hanya-baca:

const { environments } = await oc.environments.list();await oc.environments.status(environments[0].id);

Yang secara eksplisit belum didukung saat ini

SDK menyertakan nama untuk model produk yang kami inginkan, tetapi tidak diam-diam berpura-pura bahwa RPC Gateway sudah ada. Panggilan ini saat ini melempar error tidak didukung yang eksplisit:

await oc.environments.create({});await oc.environments.delete("environment-id");

Field workspace, runtime, environment, dan approvals per-run diberi tipe sebagai bentuk masa depan, tetapi Gateway saat ini tidak mendukung override tersebut pada RPC agent. Jika pemanggil meneruskannya, SDK melempar sebelum mengirimkan run agar pekerjaan tidak secara tidak sengaja dijalankan dengan perilaku workspace, runtime, environment, atau approval default.

App SDK vs Plugin SDK

Gunakan SDK Aplikasi saat kode berada di luar OpenClaw:

• Skrip Node yang memulai atau mengamati run agen
• Pekerjaan CI yang memanggil Gateway
• dasbor dan panel admin
• ekstensi IDE
• bridge eksternal yang tidak perlu menjadi plugin channel
• pengujian integrasi dengan transport Gateway palsu atau nyata

Gunakan Plugin SDK saat kode berjalan di dalam OpenClaw:

• plugin provider
• plugin channel
• hook tool atau siklus hidup
• plugin harness agen
• helper runtime tepercaya

Kode SDK Aplikasi harus mengimpor dari @openclaw/sdk. Kode Plugin harus mengimpor dari subpath openclaw/plugin-sdk/* yang terdokumentasi. Jangan mencampur kedua kontrak tersebut.

Terkait

• Desain API OpenClaw App SDK
• Referensi RPC Gateway
• Loop agen
• Runtime agen
• Sesi
• Tugas latar belakang
• Agen ACP
• Ikhtisar Plugin SDK