يُعد OpenClaw App SDK واجهة API العامة للعميل للتطبيقات خارج عملية OpenClaw. استخدمDocumentation 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 عندما يريد سكربت أو لوحة معلومات أو مهمة CI أو إضافة IDE
أو تطبيق خارجي آخر الاتصال بـ Gateway، أو بدء تشغيلات الوكيل، أو بث الأحداث، أو انتظار النتائج، أو إلغاء العمل، أو فحص موارد Gateway.
يختلف App SDK عن Plugin SDK.
يتواصل
@openclaw/sdk مع Gateway من خارج OpenClaw.
أما openclaw/plugin-sdk/* فهو مخصص فقط للـ plugins التي تعمل داخل OpenClaw
وتسجل المزودين أو القنوات أو الأدوات أو الخطافات أو بيئات التشغيل الموثوقة.ما يتوفر اليوم
يأتي@openclaw/sdk مع:
| السطح | الحالة | ما يفعله |
|---|---|---|
OpenClaw | جاهز | نقطة الدخول الرئيسية للعميل. يمتلك النقل والاتصال والطلبات والأحداث. |
GatewayClientTransport | جاهز | نقل WebSocket مدعوم بعميل Gateway. |
oc.agents | جاهز | يسرد مقابض الوكلاء وينشئها ويحدثها ويحذفها ويحصل عليها. |
Agent.run() | جاهز | يبدأ تشغيل Gateway من نوع agent ويعيد Run. |
oc.runs | جاهز | ينشئ التشغيلات ويحصل عليها وينتظرها ويلغيها ويبثها. |
Run.events() | جاهز | يبث أحداثا موحدة لكل تشغيل مع إعادة تشغيل للتشغيلات السريعة. |
Run.wait() | جاهز | يستدعي agent.wait ويعيد RunResult مستقرا. |
Run.cancel() | جاهز | يستدعي sessions.abort بواسطة معرف التشغيل، مع مفتاح الجلسة عند توفره. |
oc.sessions | جاهز | ينشئ مقابض الجلسات ويحلها ويرسل إليها ويرقعها ويضغطها ويحصل عليها. |
Session.send() | جاهز | يستدعي sessions.send ويعيد Run. |
oc.tasks | جاهز | يسرد إدخالات سجل مهام Gateway ويقرأها ويلغيها. |
oc.models | جاهز | يستدعي models.list وRPC الحالة الحالي models.authStatus. |
oc.tools | جاهز | يسرد أدوات Gateway ويحدد نطاقها ويستدعيها عبر مسار السياسة. |
oc.artifacts | جاهز | يسرد عناصر Gateway النصية ويحصل عليها وينزلها. |
oc.approvals | جاهز | يسرد موافقات exec ويحلها عبر استدعاءات RPC الخاصة بموافقات Gateway. |
oc.environments | جزئي | يسرد مرشحي البيئات المحلية لـ Gateway وnode؛ الإنشاء/الحذف غير موصولين. |
oc.rawEvents() | جاهز | يتيح أحداث Gateway الخام للمستهلكين المتقدمين. |
normalizeGatewayEvent() | جاهز | يحول أحداث Gateway الخام إلى شكل حدث SDK المستقر. |
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، وأنواع النتائج ذات الصلة.
الاتصال بـ 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 إلى تجاوزات Gateway
provider وmodel. يبقى 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 | طلب موافقة exec أو plugin |
approval.resolved | حل موافقة exec أو 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 الحالية:oc.tools.invoke() غلافا مكتوبا بدلا من الرمي عند
رفض السياسة أو الموافقة.
sessionKey أو runId أو
taskId:
openclaw tasks:
غير مدعوم صراحة اليوم
يتضمن SDK أسماء لنموذج المنتج الذي نريده، لكنه لا يتظاهر بصمت بأن استدعاءات RPC الخاصة بـ 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/* الفرعية الموثقة. لا تخلط بين العقدين.