الانتقال إلى المحتوى الرئيسي
تتيح Plugins الخلفيات الخاصة بـ CLI لـ OpenClaw استدعاء CLI محلي للذكاء الاصطناعي كخلفية لاستدلال النصوص. تظهر الخلفية كبادئة موفّر في مراجع النماذج: 
acme-cli/acme-large
استخدم خلفية CLI عندما يكون التكامل العلوي متاحًا بالفعل كأمر محلي، أو عندما يمتلك CLI حالة تسجيل الدخول المحلية، أو عندما يكون CLI بديلًا مفيدًا إذا لم تكن موفّرات API متاحة.
إذا كانت الخدمة العلوية تعرض API نماذج HTTP عادية، فاكتب provider plugin بدلًا من ذلك. إذا كان وقت التشغيل العلوي يمتلك جلسات الوكيل الكاملة، أو أحداث الأدوات، أو Compaction، أو حالة المهام الخلفية، فاستخدم agent harness.

​
ما يملكه Plugin

يمتلك Plugin خلفية CLI ثلاثة عقود:
العقدالملفالغرض
مدخل الحزمةpackage.jsonيوجّه OpenClaw إلى وحدة وقت تشغيل Plugin
ملكية البيانopenclaw.plugin.jsonيعلن معرّف الخلفية قبل تحميل وقت التشغيل
تسجيل وقت التشغيلindex.tsيستدعي api.registerCliBackend(...) مع افتراضيات الأمر
البيان هو بيانات وصفية للاكتشاف. لا ينفّذ CLI ولا يسجّل سلوك وقت التشغيل. يبدأ سلوك وقت التشغيل عندما يستدعي مدخل Plugin api.registerCliBackend(...).

​
Plugin خلفية بسيط بالحد الأدنى

1

Create package metadata

package.json
{
  "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"
  }
}
يجب أن تشحن الحزم المنشورة ملفات وقت تشغيل JavaScript مبنية. إذا كان مدخل المصدر لديك هو ./src/index.ts، فأضف openclaw.runtimeExtensions يشير إلى نظير JavaScript المبني. راجع Entry points.
2

Declare backend ownership

openclaw.plugin.json
{
  "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
  }
}
cliBackends هي قائمة ملكية وقت التشغيل. تسمح لـ OpenClaw بتحميل Plugin تلقائيًا عندما يذكر الإعداد أو اختيار النموذج acme-cli/....setup.cliBackends هو سطح الإعداد المعتمد على الواصفات أولًا. أضفه عندما ينبغي لاكتشاف النماذج، أو الإعداد الأولي، أو الحالة أن يتعرّف على الخلفية من دون تحميل وقت تشغيل Plugin. استخدم requiresRuntime: false فقط عندما تكون هذه الواصفات الثابتة كافية للإعداد.
3

Register the backend

index.ts
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());
  },
});
يجب أن يطابق معرّف الخلفية إدخال cliBackends في البيان. config المسجّل هو الافتراضي فقط؛ ويُدمج إعداد المستخدم ضمن agents.defaults.cliBackends.acme-cli فوقه في وقت التشغيل.

​
شكل الإعداد

يصف CliBackendConfig كيف ينبغي لـ OpenClaw تشغيل CLI وتحليل مخرجاته:
الحقلالاستخدام
commandاسم الملف الثنائي أو مسار الأمر المطلق
argsargv الأساسية لعمليات التشغيل الجديدة
resumeArgsargv بديلة للجلسات المستأنفة؛ تدعم {sessionId}
output / resumeOutputالمحلّل: json أو jsonl أو text
inputنقل الموجّه: arg أو stdin
modelArgالعلم المستخدم قبل معرّف النموذج
modelAliasesيربط معرّفات نماذج OpenClaw بمعرّفات CLI الأصلية
sessionArg / sessionArgsكيفية تمرير معرّف الجلسة
sessionModealways أو existing أو none
sessionIdFieldsحقول JSON التي يقرأها OpenClaw من مخرجات CLI
systemPromptArg / systemPromptFileArgنقل موجّه النظام
systemPromptWhenfirst أو always أو never
imageArg / imageModeدعم مسار الصورة
serializeإبقاء عمليات تشغيل الخلفية نفسها مرتبة
reliability.watchdogضبط مهلة عدم وجود مخرجات
فضّل أصغر إعداد ثابت يطابق CLI. أضف استدعاءات Plugin الراجعة فقط للسلوك الذي ينتمي فعلًا إلى الخلفية.

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

يمكن لـ CliBackendPlugin أيضًا تعريف:
الخطافالاستخدام
normalizeConfig(config, context)يعيد كتابة إعدادات المستخدم القديمة بعد الدمج
resolveExecutionArgs(ctx)يضيف أعلامًا مقيّدة بالطلب مثل جهد التفكير أو عزل السؤال الجانبي
prepareExecution(ctx)ينشئ جسور مصادقة أو إعداد مؤقتة قبل التشغيل
transformSystemPrompt(ctx)يطبّق تحويلًا نهائيًا خاصًا بـ CLI لموجّه النظام
textTransformsاستبدالات ثنائية الاتجاه للموجّه/المخرجات
defaultAuthProfileIdيفضّل ملف تعريف مصادقة محددًا في OpenClaw
authEpochModeيقرر كيف تؤدي تغييرات المصادقة إلى إبطال جلسات CLI المخزنة
nativeToolModeيعلن ما إذا كان CLI يملك أدوات أصلية مفعّلة دائمًا
sideQuestionToolModeيعلن الأدوات الأصلية المعطلة لأسئلة /btw الجانبية
bundleMcp / bundleMcpModeيختار استخدام جسر أدوات MCP المحلي من OpenClaw
ownsNativeCompactionالخلفية تمتلك Compaction الخاصة بها - يؤجل OpenClaw
أبقِ هذه الخطافات مملوكة للموفّر. لا تضف فروعًا خاصة بـ CLI إلى النواة عندما يستطيع خطاف خلفية التعبير عن السلوك. ctx.executionMode تكون "agent" للدورات العادية و"side-question" لاستدعاءات /btw المؤقتة. استخدمها عندما يحتاج CLI إلى أعلام مختلفة لمرة واحدة، مثل تعطيل الأدوات الأصلية، أو استمرارية الجلسة، أو سلوك الاستئناف لـ BTW. إذا كانت الخلفية عادة تحتوي على nativeToolMode: "always-on" لكن argv الخاصة بالسؤال الجانبي لديها تعطل تلك الأدوات بشكل موثوق، فعيّن أيضًا sideQuestionToolMode: "disabled"؛ وإلا يفشل OpenClaw مغلقًا عندما يتطلب BTW تشغيل CLI بلا أدوات.

​
ownsNativeCompaction: إلغاء استخدام Compaction في OpenClaw

إذا كانت خلفيتك تشغّل وكيلًا يضغط سجلّه الخاص، فعيّن ownsNativeCompaction: true حتى لا يعمل ملخّص الحماية في OpenClaw أبدًا على جلساته - تعيد دورة حياة Compaction في CLI عملية بلا تأثير وتستمر الدورة. يعلن claude-cli ذلك لأن Claude Code يجري Compaction داخليًا بلا نقطة نهاية harness. أما جلسات native-harness مثل Codex فتستمر في التوجيه إلى نقطة نهاية Compaction الخاصة بـ harness بدلًا من ذلك. لا تعلن ذلك إلا عندما تنطبق كل الشروط التالية، وإلا يمكن لجلسة مؤجلة متجاوزة للميزانية أن تبقى فوق الميزانية / تصبح قديمة (لن ينقذها OpenClaw بعد الآن):
  • تضغط الخلفية سجلّها أو تحدّه بشكل موثوق عندما يقترب من نافذته؛
  • تحتفظ بجلسة قابلة للاستئناف حتى تبقى الحالة المضغوطة عبر الدورات (مثل --resume / --session-id)؛
  • ليست جلسة Compaction من native-harness - فالجلسات المطابقة لـ agentHarnessId تُوجّه إلى نقطة نهاية harness بدلًا من ذلك.

​
جسر أدوات MCP

لا تتلقى خلفيات CLI أدوات OpenClaw افتراضيًا. إذا كان CLI يستطيع استهلاك إعداد MCP، فاختر ذلك صراحة: 
return {
  id: "acme-cli",
  bundleMcp: true,
  bundleMcpMode: "codex-config-overrides",
  config: {
    command: "acme",
    args: ["chat", "--json"],
    output: "json",
  },
};
أوضاع الجسر المدعومة هي:
الوضعالاستخدام
claude-config-fileأدوات CLI التي تقبل ملف إعداد MCP
codex-config-overridesأدوات CLI التي تقبل تجاوزات الإعداد على argv
gemini-system-settingsأدوات CLI التي تقرأ إعدادات MCP من دليل إعدادات النظام الخاص بها
فعّل الجسر فقط عندما يستطيع 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 أو استئناف الجلسة.

​
قائمة التحقق

يحتوي package.json على openclaw.extensions ومدخلات وقت تشغيل مبنية للحزم المنشورة
يعلن openclaw.plugin.json عن cliBackends وactivation.onStartup المقصود
يكون setup.cliBackends موجودًا عندما ينبغي للإعداد/اكتشاف النماذج رؤية الخلفية وهي باردة
يستخدم api.registerCliBackend(...) معرّف الخلفية نفسه الموجود في البيان
تظل تجاوزات المستخدم ضمن agents.defaults.cliBackends.<id> هي الغالبة
تطابق إعدادات الجلسة وموجّه النظام والصورة ومحلّل الإخراج عقد CLI الحقيقي
تثبت الاختبارات المستهدفة واختبار دخان CLI حي واحد على الأقل مسار الخلفية

​
ذو صلة