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ğindeDocumentation 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 kullanın.
App SDK, Plugin SDK’den farklıdır.
@openclaw/sdk, OpenClaw dışından Gateway ile konuşur.
openclaw/plugin-sdk/* yalnızca OpenClaw içinde çalışan ve
sağlayıcılar, kanallar, araçlar, hook’lar veya güvenilen çalışma zamanları kaydeden Plugin’ler içindir.Bugün neler sunulur
@openclaw/sdk şunlarla birlikte gelir:
| Yüzey | Durum | Ne yapar |
|---|---|---|
OpenClaw | Hazır | Ana istemci giriş noktası. Aktarım, bağlantı, istekler ve olayları yönetir. |
GatewayClientTransport | Hazır | Gateway istemcisi tarafından desteklenen WebSocket aktarımı. |
oc.agents | Hazır | Agent tutamaçlarını listeler, oluşturur, günceller, siler ve getirir. |
Agent.run() | Hazır | Bir Gateway agent çalıştırması başlatır ve bir Run döndürür. |
oc.runs | Hazır | Çalıştırmaları oluşturur, getirir, bekler, iptal eder ve yayınlar. |
Run.events() | Hazır | Hızlı çalıştırmalar için yeniden oynatmayla normalize edilmiş çalıştırma başına olayları yayınlar. |
Run.wait() | Hazır | agent.wait çağrısı yapar ve kararlı bir RunResult döndürür. |
Run.cancel() | Hazır | Varsa oturum anahtarıyla, çalıştırma id’sine göre sessions.abort çağırır. |
oc.sessions | Hazır | Oturum tutamaçlarını oluşturur, çözümler, gönderir, yamalar, compaction uygular ve getirir. |
Session.send() | Hazır | sessions.send çağrısı yapar ve bir Run döndürür. |
oc.tasks | Hazır | Gateway görev defteri girdilerini listeler, okur ve iptal eder. |
oc.models | Hazır | models.list ve geçerli models.authStatus durum RPC’sini çağırır. |
oc.tools | Hazır | Gateway araçlarını ilke hattı üzerinden listeler, kapsamlandırır ve çağırır. |
oc.artifacts | Hazır | Gateway transcript artifact’lerini listeler, getirir ve indirir. |
oc.approvals | Hazır | Exec onaylarını Gateway onay RPC’leri üzerinden listeler ve çözümler. |
oc.environments | Kısmi | Gateway yerel ve node ortam adaylarını listeler; oluşturma/silme bağlı değildir. |
oc.rawEvents() | Hazır | Gelişmiş tüketiciler için ham Gateway olaylarını açığa çıkarır. |
normalizeGatewayEvent() | Hazır | Ham Gateway olaylarını kararlı SDK olay biçimine dönüştürü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.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:
Bir agent çalıştırma
Uygulama bir agent tutamacı istediğindeoc.agents.get(id) kullanın, ardından
agent.run() çağırın.
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.Session.send(), sessions.send çağrısı yapar ve bir Run döndürür. Oturum tutamaçları ayrıca
şunları destekler:
Olayları yayınlama
SDK, ham Gateway olaylarını kararlı birOpenClawEvent zarfına normalize eder:
| Olay türü | Kaynak Gateway olayı |
|---|---|
run.started | agent yaşam döngüsü başlangıcı |
run.completed | agent yaşam döngüsü sonu |
run.failed | agent yaşam döngüsü hatası |
run.cancelled | Durdurulmuş/iptal edilmiş yaşam döngüsü sonu |
run.timed_out | Zaman aşımı yaşam döngüsü sonu |
assistant.delta | Assistant yayın deltası |
assistant.message | Assistant mesajı |
thinking.delta | Düşünme veya plan akışı |
tool.call.started | Araç/öğe/komut başlangıcı |
tool.call.delta | Araç/öğe/komut güncellemesi |
tool.call.completed | Araç/öğe/komut tamamlanması |
tool.call.failed | Araç/öğe/komut hatası veya engellenmiş durum |
approval.requested | Exec veya Plugin onay isteği |
approval.resolved | Exec veya Plugin onay çözümü |
session.created | sessions.changed oluşturma |
session.updated | sessions.changed güncelleme |
session.compacted | sessions.changed compaction |
task.updated | Görev güncelleme olayları |
artifact.updated | Yama akışı olayları |
raw | Henüz kararlı SDK eşlemesi olmayan herhangi bir olay |
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:
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:oc.tools.invoke(), ilke veya onay retlerinde
hata fırlatmak yerine türlenmiş bir zarf döndürür.
sessionKey, runId veya
taskId kapsamı gerektirir:
openclaw tasks için de temel oluşturan kalıcı görev defterini kullanır:
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: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
- 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ı
@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.