Membangun Plugin backend CLI

Plugin backend CLI memungkinkan OpenClaw memanggil CLI AI lokal sebagai backend inferensi teks. Backend muncul sebagai prefiks penyedia dalam referensi model:

acme-cli/acme-large

Gunakan backend CLI ketika integrasi upstream sudah diekspos sebagai perintah lokal, ketika CLI memiliki status login lokal, atau ketika CLI berguna sebagai fallback jika penyedia API tidak tersedia.

Jika layanan upstream mengekspos API model HTTP biasa, tulis Plugin penyedia sebagai gantinya. Jika runtime upstream memiliki sesi agen lengkap, peristiwa alat, compaction, atau status tugas latar belakang, gunakan harness agen.

Yang dimiliki Plugin

Plugin backend CLI memiliki tiga kontrak:

Kontrak	File	Tujuan
Entri paket	`package.json`	Mengarahkan OpenClaw ke modul runtime Plugin
Kepemilikan manifest	`openclaw.plugin.json`	Mendeklarasikan id backend sebelum runtime dimuat
Pendaftaran runtime	`index.ts`	Memanggil `api.registerCliBackend(...)` dengan default perintah

Manifest adalah metadata penemuan. Manifest tidak menjalankan CLI dan tidak mendaftarkan perilaku runtime. Perilaku runtime dimulai saat entri Plugin memanggil api.registerCliBackend(...).

Plugin backend minimal

Buat metadata paket

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"
  }
}

Paket yang dipublikasikan harus menyertakan file runtime JavaScript yang sudah dibangun. Jika entri sumber Anda adalah ./src/index.ts, tambahkan openclaw.runtimeExtensions yang menunjuk ke peer JavaScript yang sudah dibangun. Lihat Titik entri.

Deklarasikan kepemilikan backend

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 adalah daftar kepemilikan runtime. Ini memungkinkan OpenClaw memuat Plugin secara otomatis ketika konfigurasi atau pemilihan model menyebut acme-cli/....setup.cliBackends adalah permukaan setup berbasis deskriptor terlebih dahulu. Tambahkan ini ketika penemuan model, onboarding, atau status harus mengenali backend tanpa memuat runtime Plugin. Gunakan requiresRuntime: false hanya ketika deskriptor statis tersebut cukup untuk setup.

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

Id backend harus cocok dengan entri cliBackends manifest. config yang didaftarkan hanya default; konfigurasi pengguna di bawah agents.defaults.cliBackends.acme-cli digabungkan di atasnya saat runtime.

Bentuk konfigurasi

CliBackendConfig menjelaskan bagaimana OpenClaw harus meluncurkan dan mengurai CLI:

Bidang	Penggunaan
`command`	Nama biner atau path perintah absolut
`args`	argv dasar untuk eksekusi baru
`resumeArgs`	argv alternatif untuk sesi yang dilanjutkan; mendukung `{sessionId}`
`output` / `resumeOutput`	Parser: `json`, `jsonl`, atau `text`
`input`	Transport prompt: `arg` atau `stdin`
`modelArg`	Flag yang digunakan sebelum id model
`modelAliases`	Memetakan id model OpenClaw ke id native CLI
`sessionArg` / `sessionArgs`	Cara meneruskan id sesi
`sessionMode`	`always`, `existing`, atau `none`
`sessionIdFields`	Bidang JSON yang dibaca OpenClaw dari output CLI
`systemPromptArg` / `systemPromptFileArg`	Transport prompt sistem
`systemPromptWhen`	`first`, `always`, atau `never`
`imageArg` / `imageMode`	Dukungan path gambar
`serialize`	Menjaga eksekusi backend yang sama tetap berurutan
`reliability.watchdog`	Penyesuaian timeout tanpa output

Pilih konfigurasi statis terkecil yang cocok dengan CLI. Tambahkan callback Plugin hanya untuk perilaku yang benar-benar menjadi milik backend.

Hook backend lanjutan

CliBackendPlugin juga dapat mendefinisikan:

Hook	Penggunaan
`normalizeConfig(config, context)`	Menulis ulang konfigurasi pengguna lama setelah merge
`resolveExecutionArgs(ctx)`	Menambahkan flag berlingkup permintaan seperti effort berpikir
`prepareExecution(ctx)`	Membuat jembatan autentikasi atau konfigurasi sementara sebelum peluncuran
`transformSystemPrompt(ctx)`	Menerapkan transformasi prompt sistem akhir yang spesifik CLI
`textTransforms`	Penggantian prompt/output dua arah
`defaultAuthProfileId`	Memilih profil autentikasi OpenClaw tertentu
`authEpochMode`	Menentukan bagaimana perubahan autentikasi membatalkan sesi CLI tersimpan
`nativeToolMode`	Mendeklarasikan apakah CLI memiliki alat native yang selalu aktif
`bundleMcp` / `bundleMcpMode`	Mengikutsertakan jembatan alat MCP loopback OpenClaw

Jaga agar hook ini tetap dimiliki penyedia. Jangan menambahkan cabang spesifik CLI ke core ketika hook backend dapat mengekspresikan perilaku tersebut.

Jembatan alat MCP

Backend CLI tidak menerima alat OpenClaw secara default. Jika CLI dapat mengonsumsi konfigurasi MCP, ikut sertakan secara eksplisit:

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

Mode jembatan yang didukung adalah:

Mode	Penggunaan
`claude-config-file`	CLI yang menerima file konfigurasi MCP
`codex-config-overrides`	CLI yang menerima override konfigurasi pada argv
`gemini-system-settings`	CLI yang membaca pengaturan MCP dari direktori pengaturan sistemnya

Aktifkan jembatan hanya ketika CLI benar-benar dapat mengonsumsinya. Jika CLI memiliki lapisan alat bawaan sendiri yang tidak dapat dinonaktifkan, tetapkan nativeToolMode: "always-on" agar OpenClaw dapat gagal secara tertutup ketika pemanggil mensyaratkan tidak ada alat native.

Konfigurasi pengguna

Pengguna dapat menimpa default backend apa pun:

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

Dokumentasikan override minimum yang kemungkinan dibutuhkan pengguna. Biasanya itu hanya command ketika biner berada di luar PATH.

Verifikasi

Untuk Plugin yang dibundel, tambahkan pengujian terfokus di sekitar builder dan pendaftaran setup, lalu jalankan lane pengujian tertarget milik Plugin:

pnpm test extensions/acme-cli

Untuk Plugin lokal atau terpasang, verifikasi penemuan dan satu eksekusi model nyata:

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

Jika backend mendukung gambar atau MCP, tambahkan smoke langsung yang membuktikan path tersebut dengan CLI nyata. Jangan mengandalkan inspeksi statis untuk perilaku prompt, gambar, MCP, atau lanjutkan-sesi.

Checklist

package.json memiliki openclaw.extensions dan entri runtime yang sudah dibangun untuk paket yang dipublikasikan

openclaw.plugin.json mendeklarasikan cliBackends dan activation.onStartup yang disengaja

setup.cliBackends hadir ketika setup/penemuan model harus melihat backend dalam keadaan dingin

api.registerCliBackend(...) menggunakan id backend yang sama dengan manifest

Override pengguna di bawah agents.defaults.cliBackends.<id> tetap menang

Pengaturan sesi, prompt sistem, gambar, dan parser output cocok dengan kontrak CLI nyata

Pengujian tertarget dan setidaknya satu smoke CLI langsung membuktikan path backend

Terkait

Backend CLI - konfigurasi pengguna dan perilaku runtime
Membangun Plugin - dasar paket dan manifest
Gambaran umum SDK Plugin - referensi API pendaftaran
Manifest Plugin - cliBackends dan deskriptor setup
Harness agen - runtime agen eksternal penuh

Overview

Plugins

Skills

Automation and tasks

Tools

Agent coordination

Membangun Plugin backend CLI

Yang dimiliki Plugin

Plugin backend minimal

Bentuk konfigurasi

Hook backend lanjutan

Jembatan alat MCP

Konfigurasi pengguna

Verifikasi

Checklist

Terkait

Overview

Plugins

Skills

Automation and tasks

Tools

Agent coordination

Documentation Index

​Yang dimiliki Plugin

​Plugin backend minimal

​Bentuk konfigurasi

​Hook backend lanjutan

​Jembatan alat MCP

​Konfigurasi pengguna

​Verifikasi

​Checklist

​Terkait

Yang dimiliki Plugin

Plugin backend minimal

Bentuk konfigurasi

Hook backend lanjutan

Jembatan alat MCP

Konfigurasi pengguna

Verifikasi

Checklist

Terkait