SDK برنامه OpenClaw

SDK برنامه OpenClaw، API عمومی کلاینت برای برنامه‌های خارج از فرایند OpenClaw است. وقتی یک اسکریپت، داشبورد، کار CI، افزونه IDE یا برنامه خارجی دیگری می‌خواهد به Gateway وصل شود، اجرای agentها را آغاز کند، رویدادها را stream کند، منتظر نتایج بماند، کار را لغو کند، یا منابع Gateway را بررسی کند، از @openclaw/sdk استفاده کنید.

آنچه امروز ارائه می‌شود

@openclaw/sdk شامل این موارد است:

SDK همچنین typeهای اصلی استفاده‌شده توسط این سطح‌ها را export می‌کند: 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 و typeهای نتیجه مرتبط.

اتصال به Gateway

یک کلاینت با URL صریح Gateway ایجاد کنید، یا برای تست‌ها و runtimeهای برنامه embedded یک transport سفارشی تزریق کنید.

 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" توسط constructor پذیرفته می‌شود، اما کشف خودکار Gateway هنوز قابلیت جداگانه‌ای در SDK نیست؛ وقتی برنامه از قبل نمی‌داند Gateway را چطور کشف کند، url را بدهید.

برای تست‌ها، یک شیء بدهید که OpenClawTransport را پیاده‌سازی می‌کند:

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

اجرای یک agent

وقتی برنامه به handle یک agent نیاز دارد، از 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);

ارجاع‌های مدل دارای provider، مانند openai/gpt-5.5، به overrideهای Gateway provider و model تقسیم می‌شوند. timeoutMs در SDK بر حسب میلی‌ثانیه می‌ماند و برای RPC agent به timeout بر حسب ثانیه در Gateway تبدیل می‌شود.

run.wait() از RPC Gateway با نام agent.wait استفاده می‌کند. deadline انتظار که در حالی منقضی شود که اجرا هنوز فعال است، به‌جای اینکه وانمود کند خود اجرا timeout شده، status: "accepted" برمی‌گرداند. timeoutهای runtime، اجراهای abort شده و اجراهای cancel شده به timed_out یا cancelled نرمال می‌شوند.

ایجاد و استفاده دوباره از نشست‌ها

وقتی برنامه به وضعیت transcript پایدار نیاز دارد، از نشست‌ها استفاده کنید.

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 برمی‌گرداند. handleهای نشست همچنین از این موارد پشتیبانی می‌کنند:

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

Stream کردن رویدادها

SDK رویدادهای خام Gateway را به یک envelope پایدار 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() رویدادها را به یک شناسه اجرا filter می‌کند و رویدادهای قبلاً دیده‌شده را برای اجراهای سریع replay می‌کند. یعنی جریان مستندشده امن است:

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

برای streamهای سراسری برنامه، از oc.events() استفاده کنید. برای frameهای خام Gateway، از oc.rawEvents() استفاده کنید.

مدل‌ها، ابزارها، artifactها و تأییدیه‌ها

helperهای مدل به methodهای فعلی Gateway map می‌شوند:

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

helperهای ابزار، catalog Gateway، نمای مؤثر ابزار و invocation مستقیم ابزار Gateway را expose می‌کنند. oc.tools.invoke() به‌جای throw کردن برای رد شدن توسط سیاست یا تأیید، یک envelope typed برمی‌گرداند.

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

helperهای artifact، projection artifact Gateway را برای زمینه نشست، اجرا یا وظیفه expose می‌کنند. هر فراخوانی به یک scope صریح 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);}

helperهای تأیید از RPCهای تأیید exec استفاده می‌کنند:

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

helperهای وظیفه از دفترکل وظیفه پایدار استفاده می‌کنند که پشتوانه 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" });

helperهای environment کشف فقط‌خواندنی محلی Gateway و node را expose می‌کنند:

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

موارد صریحاً پشتیبانی‌نشده امروز

SDK نام‌هایی را برای مدل محصولی که می‌خواهیم شامل می‌شود، اما بی‌صدا وانمود نمی‌کند RPCهای Gateway وجود دارند. این فراخوانی‌ها در حال حاضر خطاهای پشتیبانی‌نشده صریح throw می‌کنند:

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

فیلدهای هر اجرا با نام‌های workspace، runtime، environment و approvals به‌عنوان شکل آینده typed شده‌اند، اما Gateway فعلی از آن overrideها روی RPC agent پشتیبانی نمی‌کند. اگر فراخوان‌ها آن‌ها را بدهند، SDK پیش از ارسال اجرا throw می‌کند تا کار به‌طور تصادفی با رفتار پیش‌فرض workspace، runtime، environment یا approval اجرا نشود.

SDK برنامه در برابر SDK Plugin

وقتی کد خارج از OpenClaw قرار دارد، از SDK برنامه استفاده کنید:

• اسکریپت‌های Node که اجراهای agent را شروع یا مشاهده می‌کنند
• کارهای CI که یک Gateway را فراخوانی می‌کنند
• داشبوردها و پنل‌های مدیریت
• افزونه‌های IDE
• bridgeهای خارجی که لازم نیست به Plugin کانال تبدیل شوند
• تست‌های integration با transportهای Gateway واقعی یا fake

وقتی کد داخل OpenClaw اجرا می‌شود، از SDK Plugin استفاده کنید:

• Pluginهای provider
• Pluginهای کانال
• hookهای ابزار یا lifecycle
• Pluginهای harness مربوط به agent
• helperهای runtime مورد اعتماد

کد SDK برنامه باید از @openclaw/sdk import کند. کد Plugin باید از subpathهای مستندشده openclaw/plugin-sdk/* import کند. این دو قرارداد را با هم مخلوط نکنید.

مرتبط

• طراحی API ‏SDK برنامه OpenClaw
• مرجع RPC ‏Gateway
• حلقه عامل
• زمان‌های اجرای عامل
• نشست‌ها
• وظایف پس‌زمینه
• عامل‌های ACP
• نمای کلی SDK ‏Plugin