حزمة SDK لتطبيقات OpenClaw هي واجهة API العامة للعميل للتطبيقات خارج عملية OpenClaw. استخدم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.
@openclaw/sdk عندما يريد سكربت أو لوحة معلومات أو مهمة CI أو
إضافة IDE أو أي تطبيق خارجي آخر الاتصال بـ Gateway أو بدء تشغيلات الوكلاء أو
بث الأحداث أو انتظار النتائج أو إلغاء العمل أو فحص موارد Gateway.
تختلف حزمة SDK للتطبيقات عن Plugin SDK.
يتحدث
@openclaw/sdk مع Gateway من خارج OpenClaw.
openclaw/plugin-sdk/* مخصص فقط للـ plugins التي تعمل داخل OpenClaw
وتسجل مزودي الخدمة أو القنوات أو الأدوات أو الخطافات أو بيئات التشغيل الموثوقة.ما الذي يتوفر اليوم
تأتي@openclaw/sdk مع:
| الواجهة | الحالة | ما الذي تفعله |
|---|---|---|
OpenClaw | جاهز | نقطة دخول العميل الرئيسية. تدير النقل والاتصال والطلبات والأحداث. |
GatewayClientTransport | جاهز | نقل WebSocket مدعوم بعميل Gateway. |
oc.agents | جاهز | تسرد مقابض الوكلاء وتنشئها وتحدثها وتحذفها وتحصل عليها. |
Agent.run() | جاهز | تبدأ تشغيل agent عبر Gateway وتعيد Run. |
oc.runs | جاهز | تنشئ التشغيلات وتحصل عليها وتنتظرها وتلغيها وتبثها. |
Run.events() | جاهز | تبث أحداثا موحدة لكل تشغيل مع إعادة تشغيل للتشغيلات السريعة. |
Run.wait() | جاهز | تستدعي agent.wait وتعيد RunResult مستقرة. |
Run.cancel() | جاهز | تستدعي sessions.abort حسب معرف التشغيل، مع مفتاح الجلسة عند توفره. |
oc.sessions | جاهز | تنشئ مقابض الجلسات وتحلها وترسل إليها وترقعها وتضغطها وتحصل عليها. |
Session.send() | جاهز | تستدعي sessions.send وتعيد Run. |
oc.models | جاهز | تستدعي models.list وRPC الحالية لحالة models.authStatus. |
oc.tools | جزئي | تسرد كتالوج الأدوات والأدوات الفعالة؛ استدعاء الأدوات المباشر غير موصل. |
oc.approvals | جاهز | تسرد موافقات التنفيذ وتحلها عبر RPCs موافقات Gateway. |
oc.rawEvents() | جاهز | تكشف أحداث Gateway الخام للمستهلكين المتقدمين. |
normalizeGatewayEvent() | جاهز | تحول أحداث Gateway الخام إلى شكل حدث SDK المستقر. |
AgentRunParams, RunResult, RunStatus, OpenClawEvent,
OpenClawEventType, GatewayEvent, OpenClawTransport,
GatewayRequestOptions, SessionCreateParams, SessionSendParams,
RuntimeSelection, EnvironmentSelection, WorkspaceSelection,
ApprovalMode, وأنواع النتائج ذات الصلة.
الاتصال بـ Gateway
أنشئ عميلا باستخدام عنوان URL صريح لـ Gateway، أو احقن نقلا مخصصا للاختبارات وبيئات تشغيل التطبيقات المضمنة.new OpenClaw({ gateway: "ws://..." }) مكافئ لـ url. يقبل المنشئ خيار
gateway: "auto"، لكن اكتشاف Gateway التلقائي ليس ميزة SDK منفصلة بعد؛ مرر
url عندما لا يعرف التطبيق بالفعل كيفية اكتشاف Gateway.
للاختبارات، مرر كائنا ينفذ OpenClawTransport:
تشغيل وكيل
استخدمoc.agents.get(id) عندما يريد التطبيق مقبض وكيل، ثم استدع
agent.run().
openai/gpt-5.5 إلى تجاوزات
provider وmodel في Gateway. تبقى timeoutMs بالميلي ثانية في SDK
وتحول إلى ثواني مهلة Gateway من أجل RPC الخاصة بـ agent.
يستخدم run.wait() RPC الخاصة بـ Gateway وهي agent.wait. مهلة انتظار تنتهي
بينما لا يزال التشغيل نشطا تعيد status: "accepted" بدلا من الادعاء بأن
التشغيل نفسه انتهت مهلته. يتم توحيد مهل وقت التشغيل والتشغيلات المجهضة
والتشغيلات الملغاة إلى timed_out أو cancelled.
إنشاء الجلسات وإعادة استخدامها
استخدم الجلسات عندما يريد التطبيق حالة نص محادثة دائمة.Session.send() الدالة sessions.send ويعيد Run. تدعم مقابض الجلسات أيضا:
بث الأحداث
توحد SDK أحداث Gateway الخام في غلافOpenClawEvent مستقر:
| نوع الحدث | حدث Gateway المصدر |
|---|---|
run.started | بدء دورة حياة agent |
run.completed | انتهاء دورة حياة agent |
run.failed | خطأ دورة حياة agent |
run.cancelled | انتهاء دورة حياة مجهضة/ملغاة |
run.timed_out | انتهاء دورة حياة بسبب المهلة |
assistant.delta | فرق بث المساعد |
assistant.message | رسالة المساعد |
thinking.delta | بث التفكير أو الخطة |
tool.call.started | بدء أداة/عنصر/أمر |
tool.call.delta | تحديث أداة/عنصر/أمر |
tool.call.completed | اكتمال أداة/عنصر/أمر |
tool.call.failed | فشل أداة/عنصر/أمر أو حالة محظورة |
approval.requested | طلب موافقة تنفيذ أو plugin |
approval.resolved | حل موافقة تنفيذ أو plugin |
session.created | إنشاء sessions.changed |
session.updated | تحديث sessions.changed |
session.compacted | ضغط sessions.changed |
task.updated | أحداث تحديث المهمة |
artifact.updated | أحداث بث الرقع |
raw | أي حدث بلا ربط SDK مستقر بعد |
Run.events() الأحداث إلى معرف تشغيل واحد ويعيد تشغيل الأحداث التي شوهدت
بالفعل للتشغيلات السريعة. هذا يعني أن التدفق الموثق آمن:
oc.events(). لإطارات Gateway الخام، استخدم
oc.rawEvents().
النماذج والأدوات والموافقات
تتطابق مساعدات النماذج مع طرق Gateway الحالية:غير مدعوم صراحة اليوم
تتضمن SDK أسماء لنموذج المنتج الذي نريده، لكنها لا تتظاهر بصمت بأن RPCs Gateway موجودة. ترمي هذه الاستدعاءات حاليا أخطاء صريحة بأنها غير مدعومة:workspace وruntime وenvironment وapprovals لكل تشغيل مطبوعة
كشكل مستقبلي، لكن Gateway الحالية لا تدعم هذه التجاوزات على RPC الخاصة بـ
agent. إذا مررها المستدعون، ترمي SDK قبل إرسال التشغيل حتى لا ينفذ العمل
بالخطأ بسلوك مساحة العمل أو وقت التشغيل أو البيئة أو الموافقات الافتراضي.
App SDK مقابل Plugin SDK
استخدم App SDK عندما يعيش الكود خارج OpenClaw:- سكربتات Node التي تبدأ تشغيلات الوكلاء أو تراقبها
- مهام CI التي تستدعي Gateway
- لوحات المعلومات ولوحات الإدارة
- إضافات IDE
- الجسور الخارجية التي لا تحتاج إلى أن تصبح plugins قنوات
- اختبارات التكامل مع عمليات نقل Gateway مزيفة أو حقيقية
- plugins مزودي الخدمة
- plugins القنوات
- خطافات الأدوات أو دورة الحياة
- plugins أحزمة الوكلاء
- مساعدات وقت التشغيل الموثوقة
@openclaw/sdk. وينبغي لكود Plugin الاستيراد من
المسارات الفرعية الموثقة openclaw/plugin-sdk/*. لا تخلط بين العقدين.