Langsung ke konten utama

Documentation Index

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

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

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.
SDK Aplikasi berbeda dari Plugin SDK. @openclaw/sdk berkomunikasi 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. Memiliki transport, koneksi, permintaan, dan peristiwa.
GatewayClientTransportSiapTransport WebSocket yang didukung oleh klien Gateway.
oc.agentsSiapMencantumkan, membuat, memperbarui, menghapus, dan mengambil handle agen.
Agent.run()SiapMemulai run Gateway agent dan mengembalikan Run.
oc.runsSiapMembuat, mengambil, menunggu, membatalkan, dan melakukan streaming run.
Run.events()SiapMelakukan streaming peristiwa 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 tersedia.
oc.sessionsSiapMembuat, menyelesaikan, mengirim ke, menambal, memadatkan, dan mengambil handle sesi.
Session.send()SiapMemanggil sessions.send dan mengembalikan Run.
oc.tasksSiapMencantumkan, membaca, dan membatalkan entri ledger tugas Gateway.
oc.modelsSiapMemanggil models.list dan RPC status models.authStatus saat ini.
oc.toolsSiapMencantumkan, menentukan cakupan, dan menjalankan tool Gateway melalui pipeline kebijakan.
oc.artifactsSiapMencantumkan, mengambil, dan mengunduh artefak transkrip Gateway.
oc.approvalsSiapMencantumkan dan menyelesaikan approval eksekusi melalui RPC approval Gateway.
oc.environmentsSebagianMencantumkan kandidat lingkungan lokal-Gateway dan node; create/delete belum tersambung.
oc.rawEvents()SiapMengekspos peristiwa mentah Gateway untuk konsumen tingkat lanjut.
normalizeGatewayEvent()SiapMengonversi peristiwa mentah Gateway ke bentuk peristiwa SDK yang stabil.
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.
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://..." }) 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:
Tipe peristiwaPeristiwa Gateway sumber
run.startedAwal siklus hidup agent
run.completedAkhir siklus hidup agent
run.failedError siklus hidup agent
run.cancelledAkhir siklus hidup yang dibatalkan paksa/dibatalkan
run.timed_outAkhir siklus hidup timeout
assistant.deltaDelta streaming asisten
assistant.messagePesan asisten
thinking.deltaAliran berpikir atau rencana
tool.call.startedAwal tool/item/perintah
tool.call.deltaPembaruan tool/item/perintah
tool.call.completedPenyelesaian tool/item/perintah
tool.call.failedKegagalan tool/item/perintah atau status diblokir
approval.requestedPermintaan approval eksekusi atau plugin
approval.resolvedPenyelesaian approval eksekusi atau plugin
session.createdPembuatan sessions.changed
session.updatedPembaruan sessions.changed
session.compactedCompaction sessions.changed
task.updatedPeristiwa pembaruan tugas
artifact.updatedPeristiwa aliran patch
rawPeristiwa apa pun yang belum memiliki pemetaan SDK stabil
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