SDK Aplikasi OpenClaw adalah API klien publik untuk aplikasi di luar proses OpenClaw. GunakanDocumentation Index
Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
@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:
| Permukaan | Status | Fungsinya |
|---|---|---|
OpenClaw | Siap | Titik masuk klien utama. Memiliki transport, koneksi, permintaan, dan peristiwa. |
GatewayClientTransport | Siap | Transport WebSocket yang didukung oleh klien Gateway. |
oc.agents | Siap | Mencantumkan, membuat, memperbarui, menghapus, dan mengambil handle agen. |
Agent.run() | Siap | Memulai run Gateway agent dan mengembalikan Run. |
oc.runs | Siap | Membuat, mengambil, menunggu, membatalkan, dan melakukan streaming run. |
Run.events() | Siap | Melakukan streaming peristiwa per-run yang dinormalisasi dengan replay untuk run cepat. |
Run.wait() | Siap | Memanggil agent.wait dan mengembalikan RunResult yang stabil. |
Run.cancel() | Siap | Memanggil sessions.abort berdasarkan id run, dengan kunci sesi jika tersedia. |
oc.sessions | Siap | Membuat, menyelesaikan, mengirim ke, menambal, memadatkan, dan mengambil handle sesi. |
Session.send() | Siap | Memanggil sessions.send dan mengembalikan Run. |
oc.tasks | Siap | Mencantumkan, membaca, dan membatalkan entri ledger tugas Gateway. |
oc.models | Siap | Memanggil models.list dan RPC status models.authStatus saat ini. |
oc.tools | Siap | Mencantumkan, menentukan cakupan, dan menjalankan tool Gateway melalui pipeline kebijakan. |
oc.artifacts | Siap | Mencantumkan, mengambil, dan mengunduh artefak transkrip Gateway. |
oc.approvals | Siap | Mencantumkan dan menyelesaikan approval eksekusi melalui RPC approval Gateway. |
oc.environments | Sebagian | Mencantumkan kandidat lingkungan lokal-Gateway dan node; create/delete belum tersambung. |
oc.rawEvents() | Siap | Mengekspos peristiwa mentah Gateway untuk konsumen tingkat lanjut. |
normalizeGatewayEvent() | Siap | Mengonversi peristiwa mentah Gateway ke bentuk peristiwa SDK yang stabil. |
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.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:
Menjalankan agen
Gunakanoc.agents.get(id) saat aplikasi membutuhkan handle agen, lalu panggil
agent.run().
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.Session.send() memanggil sessions.send dan mengembalikan Run. Handle sesi
juga mendukung:
Streaming peristiwa
SDK menormalisasi peristiwa mentah Gateway ke dalam envelopeOpenClawEvent
yang stabil:
| Tipe peristiwa | Peristiwa Gateway sumber |
|---|---|
run.started | Awal siklus hidup agent |
run.completed | Akhir siklus hidup agent |
run.failed | Error siklus hidup agent |
run.cancelled | Akhir siklus hidup yang dibatalkan paksa/dibatalkan |
run.timed_out | Akhir siklus hidup timeout |
assistant.delta | Delta streaming asisten |
assistant.message | Pesan asisten |
thinking.delta | Aliran berpikir atau rencana |
tool.call.started | Awal tool/item/perintah |
tool.call.delta | Pembaruan tool/item/perintah |
tool.call.completed | Penyelesaian tool/item/perintah |
tool.call.failed | Kegagalan tool/item/perintah atau status diblokir |
approval.requested | Permintaan approval eksekusi atau plugin |
approval.resolved | Penyelesaian approval eksekusi atau plugin |
session.created | Pembuatan sessions.changed |
session.updated | Pembaruan sessions.changed |
session.compacted | Compaction sessions.changed |
task.updated | Peristiwa pembaruan tugas |
artifact.updated | Peristiwa aliran patch |
raw | Peristiwa 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:
oc.events(). Untuk frame Gateway mentah,
gunakan oc.rawEvents().
Model, tool, artefak, dan approval
Helper model memetakan ke metode Gateway saat ini:oc.tools.invoke() mengembalikan envelope bertipe
alih-alih melempar untuk penolakan kebijakan atau approval.
sessionKey, runId,
atau taskId:
openclaw tasks:
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: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
- plugin provider
- plugin channel
- hook tool atau siklus hidup
- plugin harness agen
- helper runtime tepercaya
@openclaw/sdk. Kode Plugin harus
mengimpor dari subpath openclaw/plugin-sdk/* yang terdokumentasi. Jangan
mencampur kedua kontrak tersebut.