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

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

acme-cli/acme-large

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

مسئولیت‌های Plugin

یک Plugin مربوط به backend در CLI سه قرارداد دارد:

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

حداقل Plugin مربوط به backend

{  "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", "--json"],      output: "json",      input: "stdin",      modelArg: "--model",      sessionArg: "--session",      sessionMode: "existing",      sessionIdFields: ["session_id", "conversation_id"],      systemPromptFileArg: "--system-file",      systemPromptWhen: "first",      imageArg: "--image",      imageMode: "repeat",      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 را توصیف می‌کند:

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

hookهای پیشرفته backend

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

مالکیت این hookها را در اختیار provider نگه دارید. زمانی که یک hook مربوط به backend می‌تواند رفتار را بیان کند، شاخه‌های مختص CLI را به هسته اضافه نکنید.

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

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

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

nativeToolMode: "selectable" را فقط زمانی تنظیم کنید که resolveExecutionArgs بتواند تمام ابزارهای بومی بک‌اند را برای یک اجرای منفرد غیرفعال کند. در چنین اجراهای محدودی، ctx.toolAvailability.native یک تاپل خالی و ctx.toolAvailability.mcp فهرست مجاز دقیق MCP با جداسازی میزبان است. هوک باید پرچم‌های ابزاری متعارض را جایگزین کند و argvای برگرداند که هر دو مقدار را اعمال کند؛ OpenClaw آن را یک بار با argv نهایی اجرای تازه یا ازسرگیری فراخوانی می‌کند و اگر بک‌اند نتواند محدودیت را اعمال کند، با رویکرد بسته و ایمن متوقف می‌شود. تأیید خودکار نام‌های MCP در این زمینه فقط به این دلیل ایمن است که میزبان از قبل پیکربندی MCP تولیدشده را به همان سرورها و ابزارها محدود کرده است.

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 بتواند با رویکرد بسته و ایمن متوقف شود. اگر CLI می‌تواند همهٔ ابزارهای بومی را برای هر اجرا غیرفعال کند، از "selectable" به‌همراه قرارداد resolveExecutionArgs بالا استفاده کنید.

پیکربندی کاربر

کاربران می‌توانند هر پیش‌فرض بک‌اند را بازنویسی کنند:

{  agents: {    defaults: {      cliBackends: {        "acme-cli": {          command: "/opt/acme/bin/acme",          args: ["chat", "--json", "--profile", "work"],          modelAliases: {            large: "acme-large-2026",          },        },      },      model: {        primary: "openai/gpt-5.6-sol",        fallbacks: ["acme-cli/large"],      },    },  },}

حداقل بازنویسی‌ای را که احتمالاً کاربران نیاز خواهند داشت مستند کنید؛ معمولاً فقط command، زمانی که فایل اجرایی خارج از PATH قرار دارد.

راستی‌آزمایی

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

pnpm test extensions/acme-cli

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

openclaw plugins inspect acme-cli --runtime --jsonopenclaw agent --message "reply exactly: 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 بازنویسی‌های کاربر در agents.defaults.cliBackends.<id> همچنان اولویت دارند OPENCLAW_DOCS_MARKER:calloutClose: