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

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

acme-cli/acme-large

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

Plugin مالک چه چیزهایی است

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

manifest فراداده کشف است. CLI را اجرا نمی‌کند و رفتار runtime را ثبت نمی‌کند. رفتار runtime زمانی شروع می‌شود که ورودی 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", "--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());  },});

شکل config

CliBackendConfig توصیف می‌کند OpenClaw چگونه باید CLI را اجرا و parse کند:

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

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

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

این hookها را در مالکیت ارائه‌دهنده نگه دارید. وقتی یک hook بک‌اند می‌تواند رفتار را بیان کند، شاخه‌های ویژه CLI به core اضافه نکنید.

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

ownsNativeCompaction: خروج از Compaction OpenClaw

اگر بک‌اند شما عاملی را اجرا می‌کند که transcript خود را compact می‌کند، ownsNativeCompaction: true را تنظیم کنید تا summarizer محافظ OpenClaw هرگز روی نشست‌های آن اجرا نشود - چرخه عمر Compaction در CLI یک no-op برمی‌گرداند و turn ادامه پیدا می‌کند. claude-cli آن را اعلام می‌کند چون Claude Code به‌صورت داخلی compact می‌کند و endpoint هارنس ندارد. نشست‌های native-harness مانند Codex در عوض همچنان به endpoint Compaction هارنس خودشان route می‌شوند.

فقط زمانی آن را اعلام کنید که همه موارد زیر برقرار باشند، وگرنه یک نشست deferred over-budget می‌تواند همچنان over budget بماند / stale شود (OpenClaw دیگر آن را نجات نمی‌دهد):

• بک‌اند با اطمینان transcript خودش را وقتی به window نزدیک می‌شود compact یا محدود می‌کند؛
• یک نشست قابل resume را persist می‌کند تا وضعیت compactشده بین turnها باقی بماند (مثلاً --resume / --session-id);
• یک نشست Compaction از نوع native-harness نیست - نشست‌های منطبق با agentHarnessId در عوض به endpoint هارنس route می‌شوند.

bridge ابزار MCP

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

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

حالت‌های bridge پشتیبانی‌شده عبارت‌اند از:

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

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

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

{  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.5",        fallbacks: ["acme-cli/large"],      },    },  },}

حداقل override موردنیاز کاربران را مستند کنید. معمولاً این فقط 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 پشتیبانی می‌کند، یک آزمون smoke زنده اضافه کنید که آن مسیرها را با CLI واقعی اثبات کند. برای رفتار پرامپت، تصویر، MCP یا ازسرگیری نشست، به بازرسی ایستا تکیه نکنید.

چک‌لیست

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json برای بسته‌های منتشرشده دارای openclaw.extensions و ورودی‌های runtime ساخته‌شده است 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(...) از همان شناسه بک‌اند موجود در manifest استفاده می‌کند OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s بازنویسی‌های کاربر زیر agents.defaults.cliBackends.<id> همچنان اولویت دارند OPENCLAW_DOCS_MARKER:calloutClose: