OpenClaw Uygulama SDK API tasarımı

Bu sayfa, herkese açık OpenClaw App SDK için ayrıntılı API referansı tasarımıdır. Bilinçli olarak Plugin SDK bölümünden ayrı tutulmuştur.

Herkese açık app SDK iki katmanda oluşturulmalıdır:

1. Düşük seviyeli, üretilmiş bir Gateway istemcisi.
2. OpenClaw, Agent, Session, Run, Task, Artifact, Approval ve Environment nesnelerine sahip, yüksek seviyeli ergonomik bir sarmalayıcı.

Ad alanı tasarımı

Düşük seviyeli ad alanları Gateway kaynaklarını yakından izlemelidir:

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

Yüksek seviyeli sarmalayıcılar, yaygın akışları kullanışlı hale getiren nesneler döndürmelidir:

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

Olay sözleşmesi

Herkese açık SDK, sürümlü, yeniden oynatılabilir ve normalize edilmiş olaylar sunmalıdır.

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 bir yeniden oynatma imlecidir. Tüketiciler events({ after: id }) ile yeniden bağlanabilmeli ve saklama izin verdiğinde kaçırılan olayları alabilmelidir.

Önerilen normalize edilmiş olay aileleri:

Runtime'a özgü yükler raw üzerinden kullanılabilir olmalıdır, ancak uygulamaların normal UI için raw ayrıştırması gerekmemelidir.

Sonuç sözleşmesi

Run.wait() kararlı bir sonuç zarfı döndürmelidir:

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

Sonuç sade ve kararlı olmalıdır. Zaman damgası değerleri Gateway şeklini korur; bu nedenle mevcut lifecycle destekli run'lar genellikle epoch milisaniye sayıları bildirirken adapter'lar hâlâ ISO dizgileri gösterebilir. Zengin UI, tool izleri ve runtime'a özgü ayrıntılar olaylara ve artifact'lara aittir.

accepted terminal olmayan bir bekleme sonucudur: Gateway bekleme son tarihinin, run bir lifecycle bitişi/hatası üretmeden önce dolduğu anlamına gelir. timed_out olarak ele alınmamalıdır; timed_out, kendi runtime zaman aşımını aşan bir run için ayrılmıştır.

Onaylar ve sorular

Kodlama agent'ları sürekli güvenlik sınırlarını geçtiği için onaylar birinci sınıf olmalıdır.

run.onApproval(async (request) => {  if (request.kind === "tool" && request.toolName === "exec") {    return request.approveOnce({ reason: "CI command allowed by policy" });  }   return request.askUser();});

Onay olayları şunları taşımalıdır:

• onay id'si
• run id'si ve oturum id'si
• istek türü
• istenen eylem özeti
• tool adı veya ortam eylemi
• risk seviyesi
• kullanılabilir kararlar
• süre sonu
• kararın yeniden kullanılıp kullanılamayacağı

Sorular onaylardan ayrıdır. Bir soru, kullanıcıdan veya host uygulamadan bilgi ister. Bir onay, bir eylemi gerçekleştirmek için izin ister.

ToolSpace modeli

Uygulamaların, Plugin iç bileşenlerini içe aktarmadan tool yüzeyini anlaması gerekir.

const tools = await run.toolSpace(); for (const tool of tools.list()) {  console.log(tool.name, tool.source, tool.requiresApproval);}

SDK şunları sunmalıdır:

• normalize edilmiş tool metadata'sı
• kaynak: OpenClaw, MCP, Plugin, channel, runtime veya app
• şema özeti
• onay politikası
• runtime uyumluluğu
• bir tool'un gizli, readonly, yazma yetenekli veya host yetenekli olup olmadığı

SDK üzerinden tool çağırma açık ve kapsamlı olmalıdır. Çoğu uygulama agent çalıştırmalı, rastgele tool'ları doğrudan çağırmamalıdır.

Artifact modeli

Artifact'lar dosyalardan daha fazlasını kapsamalıdır.

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

Yaygın örnekler:

• dosya düzenlemeleri ve üretilen dosyalar
• patch paketleri
• VCS diff'leri
• ekran görüntüleri ve medya çıktıları
• log'lar ve iz paketleri
• pull request bağlantıları
• runtime yörüngeleri
• yönetilen ortam workspace snapshot'ları

Artifact erişimi, her artifact'ın normal bir yerel dosya olduğunu varsaymadan redaction, saklama ve indirme URL'lerini desteklemelidir.

Güvenlik modeli

App SDK yetki konusunda açık olmalıdır.

Önerilen token kapsamları:

Varsayılanlar:

• varsayılan olarak gizli bilgi iletimi yok
• sınırsız ortam değişkeni aktarımı yok
• gizli değerler yerine gizli referansları
• açık sandbox ve ağ politikası
• açık uzak ortam saklama politikası
• politika aksini kanıtlamadıkça host yürütmesi için onaylar
• raw runtime olayları, çağıranın daha güçlü bir tanılama kapsamı yoksa Gateway'den ayrılmadan önce redacted edilir

Yönetilen ortam sağlayıcısı

Yönetilen agent'lar ortam sağlayıcıları olarak uygulanmalıdır.

type EnvironmentProvider = {  id: string;  capabilities: {    checkout?: boolean;    sandbox?: boolean;    networkPolicy?: boolean;    secrets?: boolean;    artifacts?: boolean;    logs?: boolean;    pullRequests?: boolean;    longRunning?: boolean;  };};

İlk uygulamanın hosted SaaS olması gerekmez. Mevcut node host'larını, geçici workspace'leri, CI tarzı runner'ları veya Testbox tarzı ortamları hedefleyebilir. Önemli sözleşme şudur:

1. workspace hazırla
2. güvenli ortamı ve gizli bilgileri bağla
3. run başlat
4. olay akışı sağla
5. artifact'ları topla
6. politikaya göre temizle veya sakla

Bu kararlı hale geldiğinde hosted cloud hizmeti aynı sağlayıcı sözleşmesini uygulayabilir.

Paket yapısı

Önerilen paketler:

Depoda Plugin'ler için zaten openclaw/plugin-sdk/* bulunur. Plugin yazarları ile app geliştiricilerini karıştırmamak için bu ad alanını ayrı tutun.

Üretilmiş istemci stratejisi

Düşük seviyeli istemci, sürümlü Gateway protokol şemalarından üretilmeli, ardından elle yazılmış ergonomik sınıflarla sarmalanmalıdır.

Katmanlama:

1. Gateway şeması için tek doğruluk kaynağı.
2. Oluşturulmuş düşük düzey TypeScript istemcisi.
3. Dış girdiler ve olay yükleri için çalışma zamanı doğrulayıcıları.
4. Üst düzey OpenClaw, Agent, Session, Run, Task ve Artifact sarmalayıcıları.
5. Tarif örnekleri ve entegrasyon testleri.

Faydalar:

• protokol sapması görünür olur
• testler, oluşturulan yöntemleri Gateway dışa aktarımlarıyla karşılaştırabilir
• App SDK, Plugin SDK iç bileşenlerinden bağımsız kalır
• düşük düzey tüketiciler hâlâ protokole tam erişime sahiptir
• üst düzey tüketiciler küçük ürün API'sini alır

İlgili

• OpenClaw App SDK
• Gateway RPC başvurusu
• Agent döngüsü
• Agent çalışma zamanları
• Arka plan görevleri
• ACP agent'ları
• Plugin SDK genel bakışı