CLI arka uç Pluginleri oluşturma

CLI arka uç pluginleri, OpenClaw'ın metin çıkarımı arka ucu olarak yerel bir yapay zekâ CLI'ını çağırmasını sağlar. Arka uç, model referanslarında bir sağlayıcı öneki olarak görünür:

acme-cli/acme-large

Üst sistem entegrasyonu zaten yerel bir komut olarak sunuluyorsa, CLI yerel oturum açma durumunu yönetiyorsa veya API sağlayıcıları kullanılamadığında yedek olarak bir CLI arka ucu kullanın.

Pluginin yönettiği alanlar

Bir CLI arka uç plugininin üç sözleşmesi vardır:

Manifest, keşif meta verisidir: CLI'ı çalıştırmaz veya çalışma zamanı davranışını kaydetmez. Çalışma zamanı davranışı, plugin giriş noktası api.registerCliBackend(...) çağrısı yaptığında başlar.

En küçük arka uç plugini

{  "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());  },});

Yapılandırma biçimi

CliBackendConfig, OpenClaw'ın CLI'ı nasıl başlatıp ayrıştırması gerektiğini açıklar:

CLI ile eşleşen en küçük statik yapılandırmayı tercih edin. Plugin geri çağrılarını yalnızca gerçekten arka uca ait davranışlar için ekleyin.

Gelişmiş arka uç kancaları

CliBackendPlugin ayrıca şunları tanımlayabilir:

Bu kancaları sağlayıcının yönetiminde tutun. Davranış bir arka uç kancasıyla ifade edilebiliyorsa çekirdeğe CLI'a özgü dallar eklemeyin.

runtimeArtifact plugin tarafından yönetilir ve kullanıcı tarafından geçersiz kılınamaz. Yalnızca canlı bir çıkarım turu doğrulanmış kurulum yetkisi oluşturduğunda veya bunu yeniden doğruladığında kullanılır; normal CLI çalıştırmaları bunu gerektirmez. Bu bildirime sahip olmayan bir arka uç, doğrulanmış CLI kurulum yetkisi oluşturamaz. Bir bundled-package-tree bildirimi, tam package.json sahibini adlandırır ve paket giriş noktasının komut olmasını gerektirir. OpenClaw, iç içe bağımlılıklar dâhil olmak üzere sınırlandırılmış eksiksiz kurulu paket ağacının karmasını hesaplar ve başka yere yönlendiren sembolik bağlantılar, bildirilen paketin dışındaki başlatıcılar, gerekli harici bağımlılık bildirimleri, aşırı büyük ağaçlar ve bilinmeyen betikler için güvenli biçimde işlemi reddeder. Bunu yalnızca söz konusu ağaç eksiksiz çıkarım uygulamasını içeriyorsa bildirin; isteğe bağlı araç entegrasyonları harici bir uygulama grafiğini güvenli hâle getirmez.

Aynı arka uç kendi kendine yeterli yerel bir yürütülebilir dosya da sağlıyorsa bunun standart temel adlarını nativeExecutableNames içinde listeleyin. Kullanıcı arka uç komutunu geçersiz kılsa bile diğer yerel komutlar doğrulanmamış olarak kalır.

ctx.executionMode, normal turlar için "agent", geçici /btw çağrıları için "side-question" değeridir. CLI, BTW için yerel araçları, oturum kalıcılığını veya sürdürme davranışını devre dışı bırakmak gibi farklı tek seferlik bayraklara ihtiyaç duyduğunda bunu kullanın. Bir arka uç normalde nativeToolMode: "always-on" değerine sahipse ancak yan soru argv'si bu araçları güvenilir biçimde devre dışı bırakıyorsa sideQuestionToolMode: "disabled" değerini de ayarlayın; aksi takdirde BTW araçsız bir CLI çalıştırması gerektirdiğinde OpenClaw güvenli biçimde başarısız olur.

nativeToolMode: "selectable" değerini yalnızca resolveExecutionArgs, tek bir çalıştırma için arka uca özgü tüm araçları devre dışı bırakabiliyorsa ayarlayın. Bu kısıtlı çalıştırmalarda ctx.toolAvailability.native boş bir demettir ve ctx.toolAvailability.mcp, ana bilgisayar tarafından yalıtılmış tam MCP izin listesidir. Kanca, çakışan araç bayraklarını değiştirmeli ve her iki değeri de uygulayan argv'yi döndürmelidir; OpenClaw bunu son yeni veya sürdürme argv'siyle bir kez çağırır ve arka uç kısıtlamayı uygulayamadığında güvenli biçimde başarısız olur. Bu bağlamdaki MCP adlarının otomatik olarak onaylanması yalnızca ana bilgisayarın oluşturulan MCP yapılandırmasını zaten bu sunucular ve araçlarla sınırlandırmış olması nedeniyle güvenlidir.

ownsNativeCompaction: OpenClaw Compaction özelliğini devre dışı bırakma

Arka ucunuz kendi dökümünü sıkıştıran bir ajan çalıştırıyorsa OpenClaw'ın koruyucu özetleyicisinin bu oturumlarda hiçbir zaman çalışmaması için ownsNativeCompaction: true değerini ayarlayın; CLI Compaction yaşam döngüsü işlem yapmadan döner ve tur devam eder. claude-cli, Claude Code herhangi bir çalıştırma düzeneği uç noktası olmadan dahili olarak sıkıştırma yaptığı için bunu bildirir. Codex gibi yerel çalıştırma düzeneği oturumları ise bunun yerine çalıştırma düzeneklerinin Compaction uç noktasına yönlendirilmeye devam eder.

Bunu yalnızca aşağıdakilerin tümü geçerliyse bildirin; aksi takdirde ertelenmiş ve bütçeyi aşmış bir oturum bütçeyi aşmaya devam edebilir veya eskimeye başlayabilir (OpenClaw artık onu kurtarmaz):

• arka uç, penceresine yaklaştıkça kendi dökümünü güvenilir biçimde sıkıştırır veya sınırlar;
• sıkıştırılmış durumun turlar arasında korunması için sürdürülebilir bir oturumu kalıcılaştırır (örneğin --resume / --session-id);
• yerel çalıştırma düzeneği Compaction oturumu değildir; eşleşen agentHarnessId oturumları bunun yerine çalıştırma düzeneği uç noktasına yönlendirilir.

MCP araç köprüsü

CLI arka uçları varsayılan olarak OpenClaw araçlarını almaz. CLI bir MCP yapılandırmasını kullanabiliyorsa bunu açıkça etkinleştirin:

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

Desteklenen köprü modları:

Köprüyü yalnızca CLI gerçekten kullanabiliyorsa etkinleştirin. CLI'ın devre dışı bırakılamayan kendi yerleşik araç katmanı varsa OpenClaw'ın bir çağıran yerel araçların bulunmamasını gerektirdiğinde güvenli biçimde başarısız olabilmesi için nativeToolMode: "always-on" değerini ayarlayın. Her yerel aracı çalıştırma başına devre dışı bırakabiliyorsa yukarıdaki resolveExecutionArgs sözleşmesiyle "selectable" değerini kullanın.

Kullanıcı yapılandırması

Kullanıcılar herhangi bir arka uç varsayılanını geçersiz kılabilir:

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

Kullanıcıların ihtiyaç duyma olasılığı bulunan asgari geçersiz kılmayı belgeleyin; ikili dosya PATH dışında olduğunda bu genellikle yalnızca command olur.

Doğrulama

Paketle gelen pluginler için oluşturucu ve kurulum kaydı çevresine odaklanmış bir test ekleyin, ardından pluginin hedeflenmiş test hattını çalıştırın:

pnpm test extensions/acme-cli

Yerel veya kurulu pluginler için keşfi ve gerçek bir model çalıştırmasını doğrulayın:

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

Arka uç görüntüleri veya MCP'yi destekliyorsa bu yolları gerçek CLI ile kanıtlayan canlı bir duman testi ekleyin. İstem, görüntü, MCP veya oturum sürdürme davranışı için statik incelemeye güvenmeyin.

Kontrol listesi

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json, yayımlanan paketler için openclaw.extensions ve derlenmiş çalışma zamanı girdileri içeriyor OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s openclaw.plugin.json, cliBackends ve bilinçli olarak seçilmiş activation.onStartup değerini bildiriyor OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Kurulum/model keşfinin arka ucu soğuk durumda görmesi gerekiyorsa setup.cliBackends mevcut OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s api.registerCliBackend(...), manifest ile aynı arka uç kimliğini kullanıyor OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s agents.defaults.cliBackends.<id> altındaki kullanıcı geçersiz kılmaları hâlâ öncelikli OPENCLAW_DOCS_MARKER:calloutClose: