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.

Halaman ini adalah rancangan referensi API terperinci untuk SDK Aplikasi OpenClaw publik. Ini sengaja dipisahkan dari Plugin SDK.
@openclaw/sdk adalah paket aplikasi/klien eksternal untuk berkomunikasi dengan Gateway. openclaw/plugin-sdk/* adalah kontrak pembuatan plugin dalam proses. Jangan mengimpor subpath Plugin SDK dari aplikasi yang hanya perlu menjalankan agen.
SDK aplikasi publik sebaiknya dibangun dalam dua lapisan:
  1. Klien Gateway tingkat rendah yang dihasilkan.
  2. Pembungkus ergonomis tingkat tinggi dengan objek OpenClaw, Agent, Session, Run, Task, Artifact, Approval, dan Environment.

​
Desain namespace

Namespace tingkat rendah sebaiknya mengikuti resource Gateway dengan ketat: 
oc.agents.list();
oc.agents.get("main");
oc.agents.create(...);
oc.agents.update(...);

oc.sessions.list();
oc.sessions.create(...);
oc.sessions.resolve(...);
oc.sessions.send(...);
oc.sessions.messages(...);
oc.sessions.fork(...);
oc.sessions.compact(...);
oc.sessions.abort(...);

oc.runs.create(...);
oc.runs.get(runId);
oc.runs.events(runId, { after });
oc.runs.wait(runId);
oc.runs.cancel(runId);

oc.tasks.list(); // future API: current SDK throws unsupported
oc.tasks.get(taskId); // future API: current SDK throws unsupported
oc.tasks.cancel(taskId); // future API: current SDK throws unsupported
oc.tasks.events(taskId, { after }); // future API

oc.models.list();
oc.models.status(); // Gateway models.authStatus

oc.tools.list();
oc.tools.invoke(...); // future API: current SDK throws unsupported

oc.artifacts.list({ runId }); // future API: current SDK throws unsupported
oc.artifacts.get(artifactId); // future API: current SDK throws unsupported
oc.artifacts.download(artifactId); // future API: current SDK throws unsupported

oc.approvals.list();
oc.approvals.respond(approvalId, ...);

oc.environments.list(); // future API: current SDK throws unsupported
oc.environments.create(...); // future API: current SDK throws unsupported
oc.environments.status(environmentId); // future API: current SDK throws unsupported
oc.environments.delete(environmentId); // future API: current SDK throws unsupported
Pembungkus tingkat tinggi sebaiknya mengembalikan objek yang membuat alur umum terasa nyaman: 
const run = await agent.run(inputOrParams);
await run.cancel();
await run.wait();

for await (const event of run.events()) {
  // normalized event stream
}

const artifacts = await run.artifacts.list();
const session = await run.session();

​
Kontrak peristiwa

SDK publik sebaiknya mengekspos peristiwa yang berversi, dapat diputar ulang, dan dinormalisasi. 
type OpenClawEvent = {
  version: 1;
  id: string;
  ts: number;
  type: OpenClawEventType;
  runId?: string;
  sessionId?: string;
  sessionKey?: string;
  taskId?: string;
  agentId?: string;
  data: unknown;
  raw?: unknown;
};
id adalah kursor pemutaran ulang. Konsumen sebaiknya dapat terhubung kembali dengan events({ after: id }) dan menerima peristiwa yang terlewat ketika retensi memungkinkan. Keluarga peristiwa ternormalisasi yang direkomendasikan:
PeristiwaMakna
run.createdRun diterima.
run.queuedRun menunggu lane sesi, runtime, atau lingkungan.
run.startedRuntime memulai eksekusi.
run.completedRun selesai dengan sukses.
run.failedRun berakhir dengan error.
run.cancelledRun dibatalkan.
run.timed_outRun melampaui batas waktunya.
assistant.deltaDelta teks asisten.
assistant.messagePesan asisten lengkap atau pengganti.
thinking.deltaDelta penalaran atau rencana, ketika kebijakan mengizinkan paparan.
tool.call.startedPemanggilan tool dimulai.
tool.call.deltaPemanggilan tool mengalirkan progres atau output parsial.
tool.call.completedPemanggilan tool berhasil kembali.
tool.call.failedPemanggilan tool gagal.
approval.requestedRun atau tool membutuhkan persetujuan.
approval.resolvedPersetujuan diberikan, ditolak, kedaluwarsa, atau dibatalkan.
question.requestedRuntime meminta input dari pengguna atau aplikasi host.
question.answeredAplikasi host memberikan jawaban.
artifact.createdArtefak baru tersedia.
artifact.updatedArtefak yang ada berubah.
session.createdSesi dibuat.
session.updatedMetadata sesi berubah.
session.compactedCompaction sesi terjadi.
task.updatedStatus tugas latar belakang berubah.
git.branchRuntime mengamati atau mengubah status branch.
git.diffRuntime menghasilkan atau mengubah diff.
git.prRuntime membuka, memperbarui, atau menautkan pull request.
Payload native runtime sebaiknya tersedia melalui raw, tetapi aplikasi seharusnya tidak perlu mengurai raw untuk UI normal.

​
Kontrak hasil

Run.wait() sebaiknya mengembalikan amplop hasil yang stabil: 
type RunResult = {
  runId: string;
  status: "accepted" | "completed" | "failed" | "cancelled" | "timed_out";
  sessionId?: string;
  sessionKey?: string;
  taskId?: string;
  startedAt?: string | number;
  endedAt?: string | number;
  output?: {
    text?: string;
    messages?: SDKMessage[];
  };
  usage?: {
    inputTokens?: number;
    outputTokens?: number;
    totalTokens?: number;
    costUsd?: number;
  };
  artifacts?: ArtifactSummary[];
  error?: SDKError;
};
Hasil sebaiknya sederhana dan stabil. Nilai timestamp mempertahankan bentuk Gateway, sehingga run saat ini yang didukung lifecycle biasanya melaporkan angka milidetik epoch sementara adapter mungkin masih menampilkan string ISO. UI kaya, trace tool, dan detail native runtime berada di peristiwa dan artefak. accepted adalah hasil tunggu non-terminal: ini berarti tenggat tunggu Gateway kedaluwarsa sebelum run menghasilkan akhir/error lifecycle. Ini tidak boleh diperlakukan sebagai timed_out; timed_out disediakan untuk run yang melampaui batas waktu runtime miliknya sendiri.

​
Persetujuan dan pertanyaan

Persetujuan harus menjadi kelas utama karena agen coding terus-menerus melintasi batas keamanan. 
run.onApproval(async (request) => {
  if (request.kind === "tool" && request.toolName === "exec") {
    return request.approveOnce({ reason: "CI command allowed by policy" });
  }

  return request.askUser();
});
Peristiwa persetujuan sebaiknya memuat:
  • id persetujuan
  • id run dan id sesi
  • jenis permintaan
  • ringkasan tindakan yang diminta
  • nama tool atau tindakan lingkungan
  • tingkat risiko
  • keputusan yang tersedia
  • kedaluwarsa
  • apakah keputusan dapat digunakan kembali
Pertanyaan terpisah dari persetujuan. Pertanyaan meminta informasi dari pengguna atau aplikasi host. Persetujuan meminta izin untuk melakukan tindakan.

​
Model ToolSpace

Aplikasi perlu memahami permukaan tool tanpa mengimpor internal plugin. 
const tools = await run.toolSpace();

for (const tool of tools.list()) {
  console.log(tool.name, tool.source, tool.requiresApproval);
}
SDK sebaiknya mengekspos:
  • metadata tool ternormalisasi
  • sumber: OpenClaw, MCP, plugin, channel, runtime, atau aplikasi
  • ringkasan skema
  • kebijakan persetujuan
  • kompatibilitas runtime
  • apakah tool tersembunyi, readonly, mampu menulis, atau mampu host
Pemanggilan tool melalui SDK sebaiknya eksplisit dan tercakup. Sebagian besar aplikasi sebaiknya menjalankan agen, bukan memanggil tool arbitrer secara langsung.

​
Model artefak

Artefak sebaiknya mencakup lebih dari file. 
type ArtifactSummary = {
  id: string;
  runId?: string;
  sessionId?: string;
  type:
    | "file"
    | "patch"
    | "diff"
    | "log"
    | "media"
    | "screenshot"
    | "trajectory"
    | "pull_request"
    | "workspace";
  title?: string;
  mimeType?: string;
  sizeBytes?: number;
  createdAt: string;
  expiresAt?: string;
};
Contoh umum:
  • edit file dan file yang dihasilkan
  • bundel patch
  • diff VCS
  • screenshot dan output media
  • log dan bundel trace
  • tautan pull request
  • lintasan runtime
  • snapshot workspace lingkungan terkelola
Akses artefak sebaiknya mendukung redaksi, retensi, dan URL unduhan tanpa mengasumsikan setiap artefak adalah file lokal normal.

​
Model keamanan

SDK aplikasi harus eksplisit tentang otoritas. Cakupan token yang direkomendasikan:
CakupanMengizinkan
agent.readMencantumkan dan memeriksa agen.
agent.runMemulai run.
session.readMembaca metadata dan pesan sesi.
session.writeMembuat, mengirim ke, fork, compact, dan membatalkan sesi.
task.readMembaca status tugas latar belakang.
task.writeMembatalkan atau mengubah kebijakan notifikasi tugas.
approval.respondMenyetujui atau menolak permintaan.
tools.invokeMemanggil tool yang diekspos secara langsung.
artifacts.readMencantumkan dan mengunduh artefak.
environment.writeMembuat atau menghancurkan lingkungan terkelola.
adminOperasi administratif.
Default:
  • tidak ada penerusan secret secara default
  • tidak ada pass-through variabel lingkungan tanpa batas
  • referensi secret, bukan nilai secret
  • kebijakan sandbox dan jaringan eksplisit
  • retensi lingkungan jarak jauh eksplisit
  • persetujuan untuk eksekusi host kecuali kebijakan membuktikan sebaliknya
  • peristiwa runtime mentah diredaksi sebelum meninggalkan Gateway kecuali pemanggil memiliki cakupan diagnostik yang lebih kuat

​
Penyedia lingkungan terkelola

Agen terkelola sebaiknya diimplementasikan sebagai penyedia lingkungan. 
type EnvironmentProvider = {
  id: string;
  capabilities: {
    checkout?: boolean;
    sandbox?: boolean;
    networkPolicy?: boolean;
    secrets?: boolean;
    artifacts?: boolean;
    logs?: boolean;
    pullRequests?: boolean;
    longRunning?: boolean;
  };
};
Implementasi pertama tidak perlu berupa SaaS yang di-host. Ini dapat menargetkan host node yang ada, workspace sementara, runner bergaya CI, atau lingkungan bergaya Testbox. Kontrak yang penting adalah:
  1. menyiapkan workspace
  2. mengikat lingkungan dan secret yang aman
  3. memulai run
  4. mengalirkan peristiwa
  5. mengumpulkan artefak
  6. membersihkan atau mempertahankan sesuai kebijakan
Setelah ini stabil, layanan cloud yang di-host dapat mengimplementasikan kontrak penyedia yang sama.

​
Struktur paket

Paket yang direkomendasikan:
PaketTujuan
@openclaw/sdkSDK tingkat tinggi publik dan klien Gateway tingkat rendah yang dihasilkan.
@openclaw/sdk-reactHook React opsional untuk dashboard dan pembuat aplikasi.
@openclaw/sdk-testingHelper pengujian dan server Gateway palsu untuk integrasi aplikasi.
Repo sudah memiliki openclaw/plugin-sdk/* untuk plugin. Pisahkan namespace itu untuk menghindari kebingungan penulis plugin dengan pengembang aplikasi.

​
Strategi klien yang dihasilkan

Klien tingkat rendah harus dihasilkan dari skema protokol Gateway berversi, lalu dibungkus oleh kelas ergonomis yang ditulis tangan. Pelapisan:
  1. Sumber kebenaran skema Gateway.
  2. Klien TypeScript tingkat rendah yang dihasilkan.
  3. Validator runtime untuk input eksternal dan payload peristiwa.
  4. Pembungkus OpenClaw, Agent, Session, Run, Task, dan Artifact tingkat tinggi.
  5. Contoh cookbook dan pengujian integrasi.
Manfaat:
  • pergeseran protokol terlihat
  • pengujian dapat membandingkan metode yang dihasilkan dengan ekspor Gateway
  • SDK Aplikasi tetap independen dari internal Plugin SDK
  • konsumen tingkat rendah tetap memiliki akses protokol penuh
  • konsumen tingkat tinggi mendapatkan API produk yang kecil

​
Dokumen terkait