حزمة تطوير تطبيقات OpenClaw

يُعد OpenClaw App SDK واجهة API العامة للعميل للتطبيقات خارج عملية OpenClaw. استخدم @openclaw/sdk عندما يريد سكربت أو لوحة معلومات أو مهمة CI أو إضافة IDE أو تطبيق خارجي آخر الاتصال بـ Gateway، أو بدء تشغيلات الوكيل، أو بث الأحداث، أو انتظار النتائج، أو إلغاء العمل، أو فحص موارد Gateway.

ما يتوفر اليوم

يأتي @openclaw/sdk مع:

يصدر 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، أو مرر نقلا مخصصا للاختبارات وبيئات تشغيل التطبيقات المضمنة.

 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. يقبل المنشئ الخيار gateway: "auto"، لكن اكتشاف Gateway التلقائي ليس ميزة SDK مستقلة بعد؛ مرر url عندما لا يعرف التطبيق مسبقا كيفية اكتشاف Gateway.

للاختبارات، مرر كائنا ينفذ OpenClawTransport:

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

تشغيل وكيل

استخدم oc.agents.get(id) عندما يريد التطبيق مقبض وكيل، ثم استدع agent.run().

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 إلى تجاوزات Gateway provider وmodel. يبقى timeoutMs بالمللي ثانية في SDK ويُحول إلى ثواني مهلة Gateway من أجل RPC الخاص بـ agent.

يستخدم run.wait() استدعاء RPC الخاص بـ Gateway agent.wait. عندما تنتهي مهلة انتظار بينما لا يزال التشغيل نشطا، يعيد status: "accepted" بدلا من الادعاء بأن التشغيل نفسه انتهت مهلته. تُوحد مهل التشغيل، والتشغيلات التي أُجهضت، والتشغيلات الملغاة إلى timed_out أو cancelled.

إنشاء الجلسات وإعادة استخدامها

استخدم الجلسات عندما يريد التطبيق حالة نصية دائمة.

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 ويعيد Run. تدعم مقابض الجلسات أيضا:

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

بث الأحداث

يوحد SDK أحداث Gateway الخام في غلاف OpenClawEvent مستقر:

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

تشمل أنواع الأحداث الشائعة:

يرشح Run.events() الأحداث إلى معرف تشغيل واحد ويعيد تشغيل الأحداث التي شوهدت بالفعل للتشغيلات السريعة. هذا يعني أن التدفق الموثق آمن:

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

للبث على مستوى التطبيق، استخدم oc.events(). ولإطارات Gateway الخام، استخدم oc.rawEvents().

النماذج والأدوات والعناصر والموافقات

تتطابق مساعدات النماذج مع طرق Gateway الحالية:

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

تعرض مساعدات الأدوات كتالوج Gateway، وعرض الأدوات الفعال، والاستدعاء المباشر لأدوات Gateway. يعيد oc.tools.invoke() غلافا مكتوبا بدلا من الرمي عند رفض السياسة أو الموافقة.

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

تعرض مساعدات العناصر إسقاط عناصر Gateway لسياق الجلسة أو التشغيل أو المهمة. يتطلب كل استدعاء نطاقا صريحا واحدا من sessionKey أو runId أو taskId:

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

تستخدم مساعدات الموافقة استدعاءات RPC الخاصة بموافقات exec:

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

تستخدم مساعدات المهام سجل المهام الدائم الذي يدعم أيضا openclaw tasks:

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

تعرض مساعدات البيئة اكتشاف Gateway المحلي وnode للقراءة فقط:

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

غير مدعوم صراحة اليوم

يتضمن SDK أسماء لنموذج المنتج الذي نريده، لكنه لا يتظاهر بصمت بأن استدعاءات RPC الخاصة بـ Gateway موجودة. ترمي هذه الاستدعاءات حاليا أخطاء صريحة لعدم الدعم:

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

حقول كل تشغيل workspace وruntime وenvironment وapprovals مكتوبة كشكل مستقبلي، لكن Gateway الحالي لا يدعم تلك التجاوزات على RPC الخاص بـ agent. إذا مررها المستدعون، يرمي SDK قبل إرسال التشغيل حتى لا ينفذ العمل بالخطأ بسلوك مساحة العمل أو وقت التشغيل أو البيئة أو الموافقة الافتراضي.

App SDK مقابل Plugin SDK

استخدم App SDK عندما يعيش الكود خارج OpenClaw:

• سكربتات Node التي تبدأ تشغيلات الوكلاء أو تراقبها
• مهام CI التي تستدعي Gateway
• لوحات المعلومات ولوحات الإدارة
• إضافات IDE
• الجسور الخارجية التي لا تحتاج إلى أن تصبح plugins قنوات
• اختبارات التكامل مع نقل Gateway وهمي أو حقيقي

استخدم Plugin SDK عندما يعمل الكود داخل OpenClaw:

• plugins المزودين
• plugins القنوات
• خطافات الأدوات أو دورة الحياة
• plugins حاضنة الوكيل
• مساعدات وقت التشغيل الموثوقة

ينبغي لكود App SDK الاستيراد من @openclaw/sdk. وينبغي لكود Plugin الاستيراد من مسارات openclaw/plugin-sdk/* الفرعية الموثقة. لا تخلط بين العقدين.

ذات صلة

• تصميم API لـ OpenClaw App SDK
• مرجع RPC لـ Gateway
• حلقة الوكيل
• بيئات تشغيل الوكيل
• الجلسات
• مهام الخلفية
• وكلاء ACP
• نظرة عامة على Plugin SDK