Desain API SDK Aplikasi OpenClaw

Halaman ini adalah desain referensi API terperinci untuk SDK Aplikasi OpenClaw publik. Ini sengaja dipisahkan dari SDK Plugin.

SDK aplikasi publik harus dibangun dalam dua lapisan:

1. Klien Gateway tingkat rendah yang dihasilkan.
2. Wrapper ergonomis tingkat tinggi dengan objek OpenClaw, Agent, Session, Run, Task, Artifact, Approval, dan Environment.

Desain namespace

Namespace tingkat rendah harus mengikuti resource Gateway dengan cermat:

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({ status: "running" });oc.tasks.get(taskId);oc.tasks.cancel(taskId, { reason });oc.tasks.events(taskId, { after }); // future API oc.models.list();oc.models.status(); // Gateway models.authStatus oc.tools.list();oc.tools.invoke("tool-name", { sessionKey, idempotencyKey }); oc.artifacts.list({ runId });oc.artifacts.get(artifactId, { runId });oc.artifacts.download(artifactId, { runId }); oc.approvals.list();oc.approvals.respond(approvalId, ...); oc.environments.list();oc.environments.create(...); // future API: current SDK throws unsupportedoc.environments.status(environmentId);oc.environments.delete(environmentId); // future API: current SDK throws unsupported

Wrapper tingkat tinggi harus 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 harus mengekspos peristiwa berversi, dapat diputar ulang, dan ternormalisasi.

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 harus dapat terhubung kembali dengan events({ after: id }) dan menerima peristiwa yang terlewat ketika retensi memungkinkan.

Kelompok peristiwa ternormalisasi yang direkomendasikan:

Payload bawaan runtime harus tersedia melalui raw, tetapi aplikasi tidak perlu mem-parse raw untuk UI normal.

Kontrak hasil

Run.wait() harus mengembalikan envelope 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 harus sederhana dan stabil. Nilai timestamp mempertahankan bentuk Gateway, sehingga run berbasis lifecycle saat ini biasanya melaporkan angka milidetik epoch sementara adapter masih dapat menampilkan string ISO. UI kaya, trace tool, dan detail bawaan runtime berada di peristiwa dan artifact.

accepted adalah hasil tunggu non-terminal: artinya tenggat tunggu Gateway kedaluwarsa sebelum run menghasilkan akhir/kesalahan lifecycle. Ini tidak boleh diperlakukan sebagai timed_out; timed_out dicadangkan untuk run yang melampaui batas waktu runtime-nya sendiri.

Persetujuan dan pertanyaan

Persetujuan harus menjadi warga kelas satu karena agen pemrograman 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 harus 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 kepada pengguna atau aplikasi host. Persetujuan meminta izin untuk melakukan suatu 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 harus mengekspos:

• metadata tool ternormalisasi
• source: OpenClaw, MCP, Plugin, channel, runtime, atau app
• ringkasan skema
• kebijakan persetujuan
• kompatibilitas runtime
• apakah tool tersembunyi, readonly, mampu menulis, atau mampu host

Pemanggilan tool melalui SDK harus eksplisit dan terscoped. Sebagian besar aplikasi harus menjalankan agen, bukan memanggil tool sembarang secara langsung.

Model artifact

Artifact harus 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
• trajectory runtime
• snapshot workspace lingkungan terkelola

Akses artifact harus mendukung redaksi, retensi, dan URL unduhan tanpa berasumsi bahwa setiap artifact adalah file lokal normal.

Model keamanan

SDK aplikasi harus eksplisit tentang otoritas.

Scope token yang direkomendasikan:

Default:

• tidak ada penerusan rahasia secara default
• tidak ada pass-through variabel lingkungan tanpa batas
• referensi rahasia, bukan nilai rahasia
• kebijakan sandbox dan jaringan yang eksplisit
• retensi lingkungan jarak jauh yang eksplisit
• persetujuan untuk eksekusi host kecuali kebijakan membuktikan sebaliknya
• peristiwa runtime mentah direduksi sebelum keluar dari Gateway kecuali pemanggil memiliki scope diagnostik yang lebih kuat

Penyedia lingkungan terkelola

Agen terkelola harus 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 ter-hosting. Ia dapat menargetkan host node yang ada, workspace sementara, runner bergaya CI, atau lingkungan bergaya Testbox. Kontrak pentingnya adalah:

1. menyiapkan workspace
2. mengikat lingkungan dan rahasia yang aman
3. memulai run
4. mengalirkan peristiwa
5. mengumpulkan artifact
6. membersihkan atau mempertahankan sesuai kebijakan

Setelah ini stabil, layanan cloud ter-hosting dapat mengimplementasikan kontrak penyedia yang sama.

Struktur paket

Paket yang direkomendasikan:

Repo sudah memiliki openclaw/plugin-sdk/* untuk Plugin. Jaga namespace itu terpisah agar tidak membingungkan 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 manual.

Pelapisan:

1. Sumber kebenaran skema Gateway.
2. Klien TypeScript tingkat rendah yang dihasilkan.
3. Validator runtime untuk input eksternal dan payload peristiwa.
4. Wrapper tingkat tinggi OpenClaw, Agent, Session, Run, Task, dan Artifact.
5. Contoh cookbook dan tes integrasi.

Manfaat:

• penyimpangan protokol terlihat
• tes dapat membandingkan metode yang dihasilkan dengan ekspor Gateway
• App SDK tetap independen dari internal Plugin SDK
• konsumen tingkat rendah tetap memiliki akses penuh ke protokol
• konsumen tingkat tinggi mendapatkan API produk yang kecil

Terkait

• OpenClaw App SDK
• Referensi RPC Gateway
• Loop agent
• Runtime agent
• Tugas latar belakang
• Agent ACP
• Ikhtisar Plugin SDK