OpenClaw Uygulama SDK'sı

OpenClaw App SDK, OpenClaw sürecinin dışındaki uygulamalar için herkese açık istemci API'sidir. Bir betik, pano, CI işi, IDE eklentisi veya başka bir dış uygulama Gateway'e bağlanmak, agent çalıştırmaları başlatmak, olayları yayınlamak, sonuçları beklemek, işleri iptal etmek ya da Gateway kaynaklarını incelemek istediğinde @openclaw/sdk kullanın.

Bugün neler sunulur

@openclaw/sdk şunlarla birlikte gelir:

SDK ayrıca bu yüzeyler tarafından kullanılan çekirdek türleri de dışa aktarır: 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 ve ilgili sonuç türleri.

Bir Gateway'e bağlanma

Açık bir Gateway URL'siyle bir istemci oluşturun veya testler ve gömülü uygulama çalışma zamanları için özel bir aktarım enjekte edin.

 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://..." }), url ile eşdeğerdir. gateway: "auto" seçeneği constructor tarafından kabul edilir, ancak otomatik Gateway keşfi henüz ayrı bir SDK özelliği değildir; uygulama Gateway'i nasıl keşfedeceğini zaten bilmiyorsa url iletin.

Testler için OpenClawTransport uygulayan bir nesne iletin:

const oc = new OpenClaw({  transport: {    async request(method, params) {      return { method, params };    },    async *events() {},  },});

Bir agent çalıştırma

Uygulama bir agent tutamacı istediğinde oc.agents.get(id) kullanın, ardından agent.run() çağırın.

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);

openai/gpt-5.5 gibi sağlayıcı nitelikli model referansları Gateway provider ve model geçersiz kılmalarına ayrılır. timeoutMs SDK'da milisaniye olarak kalır ve agent RPC'si için Gateway zaman aşımı saniyelerine dönüştürülür.

run.wait(), Gateway agent.wait RPC'sini kullanır. Çalıştırma hâlâ etkinken süresi dolan bir bekleme son tarihi, çalıştırmanın kendisinin zaman aşımına uğradığını varsaymak yerine status: "accepted" döndürür. Çalışma zamanı zaman aşımları, durdurulmuş çalıştırmalar ve iptal edilmiş çalıştırmalar timed_out veya cancelled olarak normalize edilir.

Oturum oluşturma ve yeniden kullanma

Uygulama kalıcı transcript durumu istediğinde oturumları kullanın.

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(), sessions.send çağrısı yapar ve bir Run döndürür. Oturum tutamaçları ayrıca şunları destekler:

await session.abort(run.id);await session.patch({ label: "renamed-session" });await session.compact({ maxLines: 200 });

Olayları yayınlama

SDK, ham Gateway olaylarını kararlı bir OpenClawEvent zarfına normalize eder:

type OpenClawEvent = {  version: 1;  id: string;  ts: number;  type: OpenClawEventType;  runId?: string;  sessionId?: string;  sessionKey?: string;  taskId?: string;  agentId?: string;  data: unknown;  raw?: GatewayEvent;};

Yaygın olay türleri şunları içerir:

Run.events(), olayları tek bir çalıştırma id'sine göre filtreler ve hızlı çalıştırmalar için daha önce görülmüş olayları yeniden oynatır. Bu, belgelenen akışın güvenli olduğu anlamına gelir:

const run = await agent.run("Summarize the latest session."); for await (const event of run.events()) {  if (event.type === "run.completed") {    break;  }}

Uygulama genelindeki akışlar için oc.events() kullanın. Ham Gateway çerçeveleri için oc.rawEvents() kullanın.

Modeller, araçlar, artifact'ler ve onaylar

Model yardımcıları geçerli Gateway yöntemleriyle eşleşir:

await oc.models.list();await oc.models.status({ probe: false }); // calls models.authStatus

Araç yardımcıları Gateway kataloğunu, etkin araç görünümünü ve doğrudan Gateway araç çağrısını açığa çıkarır. oc.tools.invoke(), ilke veya onay retlerinde hata fırlatmak yerine türlenmiş bir zarf döndürür.

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",});

Artifact yardımcıları, oturum, çalıştırma veya görev bağlamı için Gateway artifact projeksiyonunu açığa çıkarır. Her çağrı açık bir sessionKey, runId veya taskId kapsamı gerektirir:

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);}

Onay yardımcıları exec onay RPC'lerini kullanır:

const approvals = await oc.approvals.list();await oc.approvals.respond("approval-id", { decision: "approve" });

Görev yardımcıları, openclaw tasks için de temel oluşturan kalıcı görev defterini kullanır:

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" });

Ortam yardımcıları salt okunur Gateway yerel ve node keşfini açığa çıkarır:

const { environments } = await oc.environments.list();await oc.environments.status(environments[0].id);

Bugün açıkça desteklenmeyenler

SDK, istediğimiz ürün modeli için adlar içerir, ancak Gateway RPC'leri varmış gibi sessizce davranmaz. Bu çağrılar şu anda açık desteklenmeyen hata fırlatır:

await oc.environments.create({});await oc.environments.delete("environment-id");

Çalıştırma başına workspace, runtime, environment ve approvals alanları gelecekteki biçim olarak türlenmiştir, ancak geçerli Gateway bu geçersiz kılmaları agent RPC'sinde desteklemez. Çağıranlar bunları iletirse SDK, işin varsayılan workspace, runtime, environment veya approval davranışıyla yanlışlıkla yürütülmemesi için çalıştırmayı göndermeden önce hata fırlatır.

App SDK ve Plugin SDK karşılaştırması

Kod OpenClaw dışında yaşadığında App SDK kullanın:

• Agent çalıştırmaları başlatan veya gözlemleyen Node betikleri
• Bir Gateway çağıran CI işleri
• panolar ve yönetim panelleri
• IDE eklentileri
• kanal Plugin'leri hâline gelmesi gerekmeyen dış köprüler
• sahte veya gerçek Gateway aktarımlarıyla entegrasyon testleri

Kod OpenClaw içinde çalıştığında Plugin SDK kullanın:

• sağlayıcı Plugin'leri
• kanal Plugin'leri
• araç veya yaşam döngüsü hook'ları
• agent harness Plugin'leri
• güvenilen çalışma zamanı yardımcıları

App SDK kodu @openclaw/sdk içinden import etmelidir. Plugin kodu belgelenmiş openclaw/plugin-sdk/* alt yollarından import etmelidir. İki sözleşmeyi karıştırmayın.

İlgili

• OpenClaw Uygulama SDK API tasarımı
• Gateway RPC referansı
• Ajan döngüsü
• Ajan çalışma zamanları
• Oturumlar
• Arka plan görevleri
• ACP ajanları
• Plugin SDK genel bakışı