الانتقال إلى المحتوى الرئيسي

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.

حزمة SDK لتطبيقات OpenClaw هي واجهة API العامة للعميل للتطبيقات خارج عملية OpenClaw. استخدم @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 المستقر.
تصدر SDK أيضا الأنواع الأساسية المستخدمة بواسطة هذه الواجهات: AgentRunParams, RunResult, RunStatus, OpenClawEvent, OpenClawEventType, GatewayEvent, OpenClawTransport, GatewayRequestOptions, SessionCreateParams, SessionSendParams, RuntimeSelection, EnvironmentSelection, WorkspaceSelection, ApprovalMode, وأنواع النتائج ذات الصلة.

الاتصال بـ Gateway

أنشئ عميلا باستخدام عنوان URL صريح لـ Gateway، أو احقن نقلا مخصصا للاختبارات وبيئات تشغيل التطبيقات المضمنة.
import { OpenClaw } from "@openclaw/sdk";

const oc = new OpenClaw({
  url: "ws://127.0.0.1:14565",
  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 إلى تجاوزات provider وmodel في Gateway. تبقى 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;
};
تشمل أنواع الأحداث الشائعة:
نوع الحدثحدث 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() الأحداث إلى معرف تشغيل واحد ويعيد تشغيل الأحداث التي شوهدت بالفعل للتشغيلات السريعة. هذا يعني أن التدفق الموثق آمن:
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 وعرض الأدوات الفعالة:
await oc.tools.list();
await oc.tools.effective({ sessionKey: "main" });
تستخدم مساعدات الموافقات RPCs موافقة التنفيذ:
const approvals = await oc.approvals.list();
await oc.approvals.respond("approval-id", { decision: "approve" });

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

تتضمن SDK أسماء لنموذج المنتج الذي نريده، لكنها لا تتظاهر بصمت بأن RPCs Gateway موجودة. ترمي هذه الاستدعاءات حاليا أخطاء صريحة بأنها غير مدعومة:
await oc.tasks.list();
await oc.tasks.get("task-id");
await oc.tasks.cancel("task-id");

await oc.tools.invoke("tool-name", {});

await oc.artifacts.list();
await oc.artifacts.get("artifact-id");
await oc.artifacts.download("artifact-id");

await oc.environments.list();
await oc.environments.create({});
await oc.environments.status("environment-id");
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/*. لا تخلط بين العقدين.

مستندات ذات صلة