بناء Plugins الواجهة الخلفية للـ CLI

تتيح Plugins الخلفية الخاصة بـ CLI لـ OpenClaw استدعاء CLI محلي للذكاء الاصطناعي بوصفه خلفية استدلال نصي backend. تظهر الخلفية كبادئة موفر في مراجع النماذج:

acme-cli/acme-large

استخدم خلفية CLI عندما يكون التكامل العلوي مكشوفًا بالفعل كأمر محلي، أو عندما يمتلك 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", "--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 وتحليل مخرجاته:

فضّل أصغر إعداد ثابت يطابق CLI. أضف استدعاءات راجعة لـ Plugin فقط للسلوك الذي ينتمي فعلًا إلى الخلفية.

# خطافات الخلفية المتقدمة

يمكن لـ CliBackendPlugin أيضًا تعريف:

أبق هذه الخطافات مملوكة للموفر. لا تضف فروعًا خاصة بـ CLI إلى النواة عندما يمكن لخطاف خلفية التعبير عن السلوك.

# جسر أدوات 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 من الفشل مغلقًا عندما يتطلب المستدعي عدم وجود أدوات أصلية.

# إعداد المستخدم

يمكن للمستخدمين تجاوز أي افتراضي للخلفية:

{
  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"],
      },
    },
  },
}

وثّق الحد الأدنى من التجاوزات التي سيحتاجها المستخدمون غالبًا. عادةً يكون ذلك command فقط عندما يكون الثنائي خارج PATH.

# التحقق

بالنسبة إلى Plugins المضمّنة، أضف اختبارًا مركزًا حول الباني وتسجيل الإعداد، ثم شغّل مسار الاختبار المستهدف الخاص بـ Plugin:

pnpm test extensions/acme-cli

بالنسبة إلى Plugins المحلية أو المثبتة، تحقق من الاكتشاف ومن تشغيل نموذج حقيقي واحد:

openclaw plugins inspect acme-cli --runtime --json
openclaw 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: