ساخت Pluginهای بک‌اند CLI

Pluginهای بک‌اند CLI به OpenClaw امکان می‌دهند یک CLI هوش مصنوعی محلی را به‌عنوان بک‌اند استنتاج متن فراخوانی کند. بک‌اند در ارجاع‌های مدل به‌صورت پیشوند ارائه‌دهنده ظاهر می‌شود:

acme-cli/acme-large

زمانی از بک‌اند CLI استفاده کنید که یکپارچه‌سازی بالادستی از قبل به‌شکل یک فرمان محلی ارائه شده باشد، CLI وضعیت ورود محلی را مدیریت کند، یا هنگامی که ارائه‌دهندگان API در دسترس نیستند به یک گزینه پشتیبان نیاز باشد.

موارد تحت مالکیت Plugin

یک Plugin بک‌اند CLI سه قرارداد دارد:

مانیفست، فراداده اکتشاف است: CLI را اجرا یا رفتار زمان‌اجرا را ثبت نمی‌کند. رفتار زمان‌اجرا زمانی آغاز می‌شود که ورودی Plugin، api.registerCliBackend(...) را فراخوانی کند.

Plugin حداقلی بک‌اند

{  "name": "@acme/openclaw-acme-cli",  "version": "1.0.0",  "type": "module",  "openclaw": {    "extensions": ["./index.ts"],    "compat": {      "pluginApi": ">=2026.3.24-beta.2",      "minGatewayVersion": "2026.3.24-beta.2"    },    "build": {      "openclawVersion": "2026.3.24-beta.2",      "pluginSdkVersion": "2026.3.24-beta.2"    }  },  "dependencies": {    "openclaw": "^2026.3.24"  },  "devDependencies": {    "typescript": "^5.9.0"  }}

{  "id": "acme-cli",  "name": "Acme CLI",  "description": "Run Acme's local AI CLI through OpenClaw",  "cliBackends": ["acme-cli"],  "setup": {    "cliBackends": ["acme-cli"],    "requiresRuntime": false  },  "activation": {    "onStartup": false  },  "configSchema": {    "type": "object",    "additionalProperties": false  }}

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";import {  CLI_FRESH_WATCHDOG_DEFAULTS,  CLI_RESUME_WATCHDOG_DEFAULTS,  type CliBackendPlugin,} from "openclaw/plugin-sdk/cli-backend"; function buildAcmeCliBackend(): CliBackendPlugin {  return {    id: "acme-cli",    liveTest: {      defaultModelRef: "acme-cli/acme-large",      defaultImageProbe: false,      defaultMcpProbe: false,      docker: {        npmPackage: "@acme/acme-cli",        binaryName: "acme",      },    },    config: {      command: "acme",      args: ["chat", "--output-format", "stream-json", "--prompt", "{prompt}"],      resumeArgs: [        "chat",        "--resume",        "{sessionId}",        "--output-format",        "stream-json",        "--prompt",        "{prompt}",      ],      output: "jsonl",      resumeOutput: "jsonl",      jsonlDialect: "gemini-stream-json",      input: "arg",      modelArg: "--model",      modelAliases: {        large: "acme-large-2026",        fast: "acme-fast-2026",      },      sessionArgs: ["--session", "{sessionId}"],      sessionMode: "existing",      sessionIdFields: ["session_id", "conversation_id"],      systemPromptFileArg: "--system-file",      systemPromptWhen: "first",      imageArg: "--image",      imageMode: "repeat",      imagePathScope: "workspace",      reliability: {        watchdog: {          fresh: { ...CLI_FRESH_WATCHDOG_DEFAULTS },          resume: { ...CLI_RESUME_WATCHDOG_DEFAULTS },        },      },      serialize: true,    },  };} export default definePluginEntry({  id: "acme-cli",  name: "Acme CLI",  description: "Run Acme's local AI CLI through OpenClaw",  register(api) {    api.registerCliBackend(buildAcmeCliBackend());  },});

شکل پیکربندی

CliBackendConfig نحوه راه‌اندازی و تجزیه CLI توسط OpenClaw را توصیف می‌کند. مثال کامل بالا عمداً همان فیلدهای فرمان، ازسرگیری، JSONL، نام مستعار مدل، نشست، تصویر و پایشگر آداپتور همراه google-gemini-cli را به‌کار می‌گیرد:

کوچک‌ترین پیکربندی ایستایی را ترجیح دهید که با CLI مطابقت دارد. فراخوان‌های برگشتی Plugin را تنها برای رفتاری اضافه کنید که واقعاً به بک‌اند تعلق دارد.

هوک‌های پیشرفته بک‌اند

CliBackendPlugin می‌تواند موارد زیر را نیز تعریف کند:

این هوک‌ها را تحت مالکیت ارائه‌دهنده نگه دارید. وقتی یک هوک بک‌اند می‌تواند رفتار را بیان کند، شاخه‌های مخصوص CLI را به هسته اضافه نکنید.

prepareExecution(ctx) مقدار ctx.contextTokenBudget، یعنی محدودیت مؤثر توکن انتخاب‌شده برای اجرا را دریافت می‌کند. بک‌اندهایی که مالک Compaction بومی هستند، می‌توانند این بودجه را به قرارداد راه‌اندازی ویژهٔ CLI خود نگاشت کنند.

runtimeArtifact تحت مالکیت Plugin است. این مورد فقط زمانی بررسی می‌شود که یک نوبت استنتاج زنده، اختیار تأییدشدهٔ راه‌اندازی را ایجاد یا دوباره اعتبارسنجی کند؛ اجراهای عادی CLI به آن نیاز ندارند. بک‌اندی بدون این اعلان نمی‌تواند اختیار تأییدشدهٔ راه‌اندازی CLI ایجاد کند. اعلان bundled-package-tree مالک دقیق package.json را نام می‌برد و ایجاب می‌کند نقطهٔ ورود بسته همان فرمان باشد. OpenClaw از درخت کامل و کران‌دار بستهٔ نصب‌شده، شامل وابستگی‌های تو‌در‌تو، هش می‌گیرد و در برابر پیوندهای نمادین تغییرمسیر‌دهنده، راه‌اندازهای خارج از بستهٔ اعلان‌شده، اعلان‌های الزامی وابستگی خارجی، درخت‌های بیش‌ازحد بزرگ و اسکریپت‌های ناشناخته به‌صورت بسته شکست می‌خورد. این مورد را فقط زمانی اعلان کنید که آن درخت شامل پیاده‌سازی کامل استنتاج باشد؛ یکپارچه‌سازی‌های اختیاری ابزار، گراف پیاده‌سازی خارجی را ایمن نمی‌کنند.

اگر همان بک‌اند یک فایل اجرایی بومی خودبسنده نیز ارائه می‌کند، نام‌های پایهٔ متعارف آن را در nativeExecutableNames فهرست کنید. سایر فرمان‌های بومی تأییدنشده باقی می‌مانند.

ctx.executionMode برای نوبت‌های عادی "agent" و برای فراخوانی‌های موقتی /btw برابر با "side-question" است. زمانی از آن استفاده کنید که CLI برای BTW به پرچم‌های یک‌بارهٔ متفاوتی نیاز دارد، مانند غیرفعال‌کردن ابزارهای بومی، ماندگاری نشست یا رفتار ازسرگیری. اگر یک بک‌اند معمولاً nativeToolMode: "always-on" دارد اما argv پرسش جانبی آن، آن ابزارها را به‌طور قابل‌اعتماد غیرفعال می‌کند، sideQuestionToolMode: "disabled" را نیز تنظیم کنید؛ در غیر این صورت، هنگامی که BTW به اجرای CLI بدون ابزار نیاز دارد، OpenClaw به‌صورت بسته شکست می‌خورد.

nativeToolMode: "selectable" را فقط زمانی تنظیم کنید که بک‌اند بتواند همهٔ ابزارهای بومی بک‌اند را برای یک اجرای منفرد غیرفعال کند. اجراهای محدودشده یک قرارداد متعارف دریافت می‌کنند: ctx.toolAvailability.native فهرست دقیق ابزارهای بومی بک‌اند و ctx.toolAvailability.openClaw فهرست دقیق نام ابزارهای OpenClaw است. میزبان به‌طور مستقل پیکربندی و مجوز تولیدشدهٔ MCP را به همان فهرست OpenClaw محدود می‌کند؛ Pluginها نباید آن را در هسته ترجمه کنند یا پیشوندهای انتقالی بیفزایند.

نحوهٔ اعمال این قرارداد توسط بک‌اند را اعلان کنید:

• toolAvailabilityEnforcement: "execution-args" به resolveExecutionArgs نیاز دارد. هوک باید پرچم‌های ابزار متعارض را جایگزین کند، سطوح سفارشی‌سازی‌ای را که می‌توانند خارج از ابزارهای انتخاب‌شده اجرا شوند غیرفعال کند و argv اعمال‌کننده را هم برای اجراهای تازه و هم ازسرگرفته‌شده بازگرداند.
• toolAvailabilityEnforcement: "prepare-execution" به prepareExecution نیاز دارد. هوک باید یک خط‌مشی دقیق مختص هر اجرا را آماده کند و toolAvailabilityEnforced: true را بازگرداند؛ نبود تأیید دریافت باعث شکست بسته می‌شود و OpenClaw منابع آماده‌شده را پیش از راه‌اندازی پاک‌سازی می‌کند.

محدودیت‌های زمان اجرا مانند toolsAllow مربوط به Cron، پیش از ساخته‌شدن این قرارداد توسط OpenClaw عادی‌سازی و بر اساس گروه گسترش داده می‌شوند. ابزارهای بومی غیرفعال می‌شوند و بک‌اندی بدون مسیر اعمال کامل و اعلان‌شده، پیش از اجرا شکست می‌خورد.

Pluginهایی که بر اساس v2026.7.2-beta.1 تا v2026.7.2-beta.3 ساخته شده‌اند، ممکن است همچنان تصویر منسوخ‌شدهٔ نام انتقالی ctx.toolAvailability.mcp را بخوانند و وقتی یک بک‌اند قابل‌انتخاب resolveExecutionArgs را پیاده‌سازی می‌کند، ممکن است toolAvailabilityEnforcement را حذف کنند. OpenClaw آن مسیر بتای منتشرشده را از فرادادهٔ الزامی openclaw.build.openclawVersion بستهٔ Plugin تشخیص می‌دهد و آن را در سراسر خط 2026.8.x حفظ می‌کند. Pluginهای جدید و به‌روزشده باید از نام‌های متعارف ctx.toolAvailability.openClaw استفاده کنند و toolAvailabilityEnforcement: "execution-args" را صریحاً اعلان کنند؛ مسیر سازگاری بتا قرار است پس از آن بازه حذف شود.

ownsNativeCompaction: انصراف از Compaction در OpenClaw

اگر بک‌اند شما عاملی را اجرا می‌کند که رونوشت خودش را فشرده می‌کند، ownsNativeCompaction: true را تنظیم کنید تا خلاصه‌ساز حفاظتی OpenClaw هرگز برای نشست‌های آن اجرا نشود؛ چرخهٔ عمر Compaction در CLI بدون انجام کاری بازمی‌گردد و نوبت ادامه می‌یابد. claude-cli این مورد را اعلان می‌کند، زیرا Claude Code به‌صورت داخلی و بدون نقطهٔ پایانی مهار، Compaction را انجام می‌دهد. نشست‌های مهار بومی مانند Codex در عوض همچنان به نقطهٔ پایانی Compaction مهار خود هدایت می‌شوند.

فقط زمانی آن را اعلان کنید که همهٔ شرایط زیر برقرار باشند؛ در غیر این صورت، یک نشست معوق بیش‌ازبودجه می‌تواند بیش‌ازبودجه یا منقضی باقی بماند (OpenClaw دیگر آن را نجات نمی‌دهد):

• بک‌اند با نزدیک‌شدن به پنجرهٔ خود، رونوشتش را به‌طور قابل‌اعتماد فشرده یا محدود می‌کند؛
• نشستی قابل‌ازسرگیری را ماندگار می‌کند تا وضعیت فشرده‌شده بین نوبت‌ها حفظ شود (برای مثال --resume / --session-id)؛
• این نشست از نوع نشست Compaction با مهار بومی نیست؛ نشست‌های منطبق با agentHarnessId در عوض به نقطهٔ پایانی مهار هدایت می‌شوند.

پل ابزار MCP

بک‌اندهای CLI به‌طور پیش‌فرض ابزارهای OpenClaw را دریافت نمی‌کنند. اگر CLI بتواند پیکربندی MCP را مصرف کند، صریحاً فعالش کنید:

return {  id: "acme-cli",  bundleMcp: true,  bundleMcpMode: "codex-config-overrides",  config: {    command: "acme",    args: ["chat", "--json"],    output: "json",  },};

حالت‌های پشتیبانی‌شدهٔ پل:

پل را فقط زمانی فعال کنید که CLI واقعاً بتواند آن را مصرف کند. اگر CLI لایهٔ ابزار داخلی خودش را دارد که نمی‌توان آن را غیرفعال کرد، nativeToolMode: "always-on" را تنظیم کنید تا وقتی فراخواننده‌ای نبود ابزارهای بومی را الزامی می‌کند، OpenClaw بتواند به‌صورت بسته شکست بخورد. اگر می‌تواند همهٔ ابزارهای بومی را در هر اجرا غیرفعال کند، از "selectable" همراه با قرارداد resolveExecutionArgs بالا استفاده کنید.

انتخاب بک‌اند

کاربران یک بک‌اند مستقل را از طریق پیشوند ارجاع مدل آن انتخاب می‌کنند. بک‌اندی که یک modelProvider متعارف اعلان می‌کند، می‌تواند در عوض از طریق agentRuntime.id مدل آن ارائه‌دهنده انتخاب شود. سازوکارهای آداپتور در Plugin باقی می‌مانند:

{  agents: {    defaults: {      model: {        primary: "openai/gpt-5.6-sol",        fallbacks: ["acme-cli/large"],      },    },  },}

اعتبارنامه‌ها را در پروفایل‌های احراز هویت OpenClaw یا پیکربندی تحت مالکیت Plugin قرار دهید. اطمینان حاصل کنید فرمان ثبت‌شده در PATH سرویس Gateway قرار دارد؛ استقرارهایی که به مسیر یا argv متفاوتی نیاز دارند، باید ثبت Plugin را تغییر دهند یا در یک پوشش قرار دهند.

تأیید

برای Pluginهای همراه، یک آزمون متمرکز پیرامون سازنده و ثبت راه‌اندازی اضافه کنید، سپس مسیر آزمون هدفمند Plugin را اجرا کنید:

pnpm test extensions/acme-cli

برای Pluginهای محلی یا نصب‌شده، کشف و یک اجرای واقعی مدل را تأیید کنید:

openclaw plugins inspect acme-cli --runtime --jsonopenclaw agent --message "دقیقاً پاسخ بده: backend ok" --model acme-cli/acme-large

اگر بک‌اند از تصاویر یا MCP پشتیبانی می‌کند، یک آزمون دود زنده اضافه کنید که آن مسیرها را با CLI واقعی اثبات کند. برای رفتار پرامپت، تصویر، MCP یا ازسرگیری نشست، به بازرسی ایستا تکیه نکنید.

چک‌لیست

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json دارای openclaw.extensions و ورودی‌های زمان اجرای ساخته‌شده برای بسته‌های منتشرشده است OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s openclaw.plugin.json، cliBackends و activation.onStartup موردنظر را اعلان می‌کند OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s وقتی راه‌اندازی/کشف مدل باید بک‌اند را در حالت سرد ببیند، setup.cliBackends موجود است OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s api.registerCliBackend(...) از همان شناسهٔ بک‌اند در مانیفست استفاده می‌کند OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s پیشوند مدل بک‌اند یا agentRuntime.id محدود به مدل، ثبت را انتخاب می‌کند OPENCLAW_DOCS_MARKER:calloutClose: