ساخت 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());
  },
});

# شکل پیکربندی

CliBackendConfig توضیح می‌دهد OpenClaw چگونه باید CLI را اجرا و خروجی آن را parse کند:

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

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

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

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

# پل ابزار 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 بتواند به‌صورت بسته شکست بخورد.

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

کاربران می‌توانند هر پیش‌فرض بک‌اند را 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ای را مستند کنید که کاربران احتمالاً به آن نیاز دارند. معمولاً وقتی باینری خارج از PATH است، این فقط command خواهد بود.

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

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

pnpm test extensions/acme-cli

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

openclaw plugins inspect acme-cli --runtime --json
openclaw agent --message "reply exactly: backend ok" --model acme-cli/acme-large

اگر بک‌اند از تصاویر یا MCP پشتیبانی می‌کند، یک smoke زنده اضافه کنید که این مسیرها را با CLI واقعی اثبات کند. برای رفتار prompt، تصویر، 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/کشف مدل باید بک‌اند را در حالت سرد ببیند، setup.cliBackends حاضر است OPENCLAW_DOCS_MARKER:calloutClose:

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

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