Langsung ke konten utama

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.

OpenClaw App SDK adalah API klien publik untuk aplikasi di luar proses OpenClaw. Gunakan @openclaw/sdk ketika skrip, dasbor, pekerjaan CI, ekstensi IDE, atau aplikasi eksternal lain ingin terhubung ke Gateway, memulai run agen, mengalirkan event, menunggu hasil, membatalkan pekerjaan, atau memeriksa resource Gateway.
App SDK berbeda dari Plugin SDK. @openclaw/sdk berbicara dengan Gateway dari luar OpenClaw. openclaw/plugin-sdk/* hanya untuk plugin yang berjalan di dalam OpenClaw dan mendaftarkan provider, channel, tool, hook, atau runtime tepercaya.

​
Yang Tersedia Saat Ini

@openclaw/sdk tersedia dengan:
PermukaanStatusFungsinya
OpenClawSiapTitik masuk klien utama. Mengelola transport, koneksi, request, dan event.
GatewayClientTransportSiapTransport WebSocket yang didukung oleh klien Gateway.
oc.agentsSiapMencantumkan, membuat, memperbarui, menghapus, dan mengambil handle agen.
Agent.run()SiapMemulai run agent Gateway dan mengembalikan Run.
oc.runsSiapMembuat, mengambil, menunggu, membatalkan, dan mengalirkan run.
Run.events()SiapMengalirkan event per-run yang dinormalisasi dengan replay untuk run cepat.
Run.wait()SiapMemanggil agent.wait dan mengembalikan RunResult yang stabil.
Run.cancel()SiapMemanggil sessions.abort berdasarkan id run, dengan kunci sesi jika ada.
oc.sessionsSiapMembuat, me-resolve, mengirim ke, menambal, memadatkan, dan mengambil handle sesi.
Session.send()SiapMemanggil sessions.send dan mengembalikan Run.
oc.modelsSiapMemanggil models.list dan RPC status models.authStatus saat ini.
oc.toolsSebagianMencantumkan katalog tool dan tool efektif; pemanggilan tool langsung belum tersambung.
oc.approvalsSiapMencantumkan dan me-resolve persetujuan exec melalui RPC persetujuan Gateway.
oc.rawEvents()SiapMengekspos event Gateway mentah untuk konsumen tingkat lanjut.
normalizeGatewayEvent()SiapMengubah event Gateway mentah menjadi bentuk event SDK yang stabil.
SDK juga mengekspor tipe inti yang digunakan oleh permukaan tersebut: AgentRunParams, RunResult, RunStatus, OpenClawEvent, OpenClawEventType, GatewayEvent, OpenClawTransport, GatewayRequestOptions, SessionCreateParams, SessionSendParams, RuntimeSelection, EnvironmentSelection, WorkspaceSelection, ApprovalMode, dan tipe hasil terkait.

​
Terhubung Ke Gateway

Buat klien dengan URL Gateway eksplisit, atau injeksikan transport kustom untuk pengujian dan runtime aplikasi tertanam. 
import { OpenClaw } from "@openclaw/sdk";

const oc = new OpenClaw({
  url: "ws://127.0.0.1:14565",
  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 terpisah; teruskan url ketika 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) ketika aplikasi menginginkan 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 dipecah 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 agent.wait Gateway. Tenggat tunggu yang kedaluwarsa saat run masih aktif mengembalikan status: "accepted" alih-alih berpura-pura run itu sendiri mengalami timeout. Timeout runtime, run yang dibatalkan, dan run yang dicancel dinormalisasi menjadi timed_out atau cancelled.

​
Membuat Dan Menggunakan Ulang Sesi

Gunakan sesi ketika aplikasi menginginkan status transkrip yang persisten. 
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 });

​
Mengalirkan Event

SDK menormalisasi event Gateway mentah menjadi amplop 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;
};
Jenis event umum meliputi:
Jenis eventEvent Gateway sumber
run.startedAwal siklus hidup agent
run.completedAkhir siklus hidup agent
run.failedError siklus hidup agent
run.cancelledAkhir siklus hidup yang diabort/dicancel
run.timed_outAkhir siklus hidup timeout
assistant.deltaDelta streaming asisten
assistant.messagePesan asisten
thinking.deltaAliran pemikiran atau rencana
tool.call.startedAwal tool/item/perintah
tool.call.deltaPembaruan tool/item/perintah
tool.call.completedPenyelesaian tool/item/perintah
tool.call.failedKegagalan atau status diblokir tool/item/perintah
approval.requestedRequest persetujuan exec atau plugin
approval.resolvedResolusi persetujuan exec atau plugin
session.createdPembuatan sessions.changed
session.updatedPembaruan sessions.changed
session.compactedCompaction sessions.changed
task.updatedEvent pembaruan tugas
artifact.updatedEvent aliran patch
rawEvent apa pun yang belum memiliki pemetaan SDK stabil
Run.events() memfilter event ke satu id run dan me-replay event yang sudah terlihat untuk run cepat. Artinya alur yang didokumentasikan aman: 
const run = await agent.run("Summarize the latest session.");

for await (const event of run.events()) {
  if (event.type === "run.completed") {
    break;
  }
}
Untuk aliran seluruh aplikasi, gunakan oc.events(). Untuk frame Gateway mentah, gunakan oc.rawEvents().

​
Model, Tool, Dan Persetujuan

Helper model dipetakan ke metode Gateway saat ini: 
await oc.models.list();
await oc.models.status({ probe: false }); // calls models.authStatus
Helper tool mengekspos katalog Gateway dan tampilan tool efektif: 
await oc.tools.list();
await oc.tools.effective({ sessionKey: "main" });
Helper persetujuan menggunakan RPC persetujuan exec: 
const approvals = await oc.approvals.list();
await oc.approvals.respond("approval-id", { decision: "approve" });

​
Yang Secara Eksplisit Belum Didukung Saat Ini

SDK menyertakan nama untuk model produk yang kami inginkan, tetapi tidak diam-diam berpura-pura RPC Gateway sudah ada. Panggilan ini saat ini melempar error tidak didukung yang eksplisit: 
await oc.tasks.list();
await oc.tasks.get("task-id");
await oc.tasks.cancel("task-id");

await oc.tools.invoke("tool-name", {});

await oc.artifacts.list();
await oc.artifacts.get("artifact-id");
await oc.artifacts.download("artifact-id");

await oc.environments.list();
await oc.environments.create({});
await oc.environments.status("environment-id");
await oc.environments.delete("environment-id");
Field per-run workspace, runtime, environment, dan approvals diketik sebagai bentuk mendatang, 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 dieksekusi dengan perilaku workspace, runtime, environment, atau persetujuan default.

​
App SDK Dibanding Plugin SDK

Gunakan App SDK ketika 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 ketika kode berjalan di dalam OpenClaw:
  • plugin provider
  • plugin channel
  • hook tool atau siklus hidup
  • plugin harness agen
  • helper runtime tepercaya
Kode App SDK harus mengimpor dari @openclaw/sdk. Kode Plugin harus mengimpor dari subpath openclaw/plugin-sdk/* yang didokumentasikan. Jangan campur kedua kontrak.

​
Dokumen Terkait