OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Building plugins

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:

text
acme-cli/acme-large

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

Yang dikelola plugin

Plugin backend CLI memiliki tiga kontrak:

Kontrak File Tujuan
Entri paket package.json Mengarahkan OpenClaw ke modul runtime plugin
Kepemilikan manifes openclaw.plugin.json Mendeklarasikan ID backend sebelum runtime dimuat
Pendaftaran runtime index.ts Memanggil api.registerCliBackend(...) dengan nilai baku perintah

Manifes merupakan metadata penemuan: manifes tidak menjalankan CLI atau mendaftarkan perilaku runtime. Perilaku runtime dimulai ketika entri plugin memanggil api.registerCliBackend(...).

Plugin backend minimal

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

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

  • 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 adalah daftar kepemilikan runtime; daftar ini memungkinkan OpenClaw memuat otomatis plugin ketika konfigurasi atau pemilihan model menyebutkan acme-cli/....

    setup.cliBackends adalah permukaan penyiapan yang mengutamakan deskriptor. Tambahkan ini ketika penemuan model, orientasi awal, atau status harus mengenali backend tanpa memuat runtime plugin. Gunakan requiresRuntime: false hanya ketika deskriptor statis tersebut sudah mencukupi untuk penyiapan.

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

    ID backend harus cocok dengan entri cliBackends dalam manifes. config yang didaftarkan hanyalah nilai baku; konfigurasi pengguna di bawah agents.defaults.cliBackends.acme-cli digabungkan menimpanya saat runtime.

    • Bentuk konfigurasi

    CliBackendConfig menjelaskan cara OpenClaw harus meluncurkan dan mengurai CLI:

    Bidang Penggunaan
    command Nama biner atau jalur perintah absolut
    args Argumen argv dasar untuk eksekusi baru
    resumeArgs Argumen argv alternatif untuk sesi yang dilanjutkan; mendukung {sessionId}
    output / resumeOutput Pengurai: json, jsonl, atau text
    jsonlDialect Dialek peristiwa JSONL: claude-stream-json atau gemini-stream-json
    liveSession Mode proses CLI berumur panjang (claude-stdio)
    input Transportasi prompt: arg atau stdin
    maxPromptArgChars Panjang maksimum prompt untuk mode arg sebelum beralih ke stdin
    env / clearEnv Variabel lingkungan tambahan yang disuntikkan, atau nama yang dihapus sebelum peluncuran
    modelArg Flag yang digunakan sebelum ID model
    modelAliases Memetakan ID model OpenClaw ke ID asli CLI
    sessionArg / sessionArgs Cara meneruskan ID sesi
    sessionMode always, existing, atau none
    sessionIdFields Bidang JSON yang dibaca OpenClaw dari keluaran CLI
    systemPromptArg / systemPromptFileArg Transportasi prompt sistem
    systemPromptFileConfigArg / systemPromptFileConfigKey Transportasi penggantian konfigurasi untuk file prompt sistem (misalnya -c)
    systemPromptMode append atau replace
    systemPromptWhen first, always, atau never
    imageArg / imageMode Flag jalur gambar dan cara meneruskan beberapa gambar (repeat atau list)
    imagePathScope Lokasi file gambar yang disiapkan sebelum diserahkan: temp atau workspace
    serialize Menjaga urutan eksekusi pada backend yang sama
    reseedFromRawTranscriptWhenUncompacted Mengaktifkan pengisian ulang terbatas dari transkrip mentah sebelum Compaction untuk pengaturan ulang sesi yang aman
    reliability.outputLimits Jumlah maksimum karakter/baris JSONL mentah yang dipertahankan untuk satu giliran CLI langsung (backend sesi langsung)
    reliability.watchdog Penyesuaian batas waktu tanpa keluaran, terpisah untuk eksekusi baru dan lanjutan

    Utamakan konfigurasi statis terkecil yang sesuai dengan CLI. Tambahkan callback plugin hanya untuk perilaku yang benar-benar menjadi tanggung jawab backend.

    Hook backend lanjutan

    CliBackendPlugin juga dapat mendefinisikan:

    Hook Penggunaan
    normalizeConfig(config, context) Menulis ulang konfigurasi pengguna lama setelah penggabungan
    resolveExecutionArgs(ctx) Menambahkan flag dalam cakupan permintaan, seperti tingkat pemikiran atau isolasi pertanyaan sampingan
    prepareExecution(ctx) Membuat jembatan autentikasi atau konfigurasi sementara sebelum peluncuran
    transformSystemPrompt(ctx) Menerapkan transformasi akhir prompt sistem khusus CLI
    textTransforms Penggantian prompt/keluaran dua arah
    defaultAuthProfileId Mengutamakan profil autentikasi OpenClaw tertentu
    authEpochMode Menentukan bagaimana perubahan autentikasi membatalkan sesi CLI tersimpan
    nativeToolMode Mendeklarasikan apakah alat asli tidak tersedia, selalu aktif, atau dapat dipilih host
    sideQuestionToolMode Mendeklarasikan alat asli yang dinonaktifkan untuk pertanyaan sampingan /btw
    bundleMcp / bundleMcpMode Mengaktifkan jembatan alat MCP local loopback milik OpenClaw
    ownsNativeCompaction Backend mengelola Compaction-nya sendiri - OpenClaw menangguhkannya
    runtimeArtifact Membatasi peluncur skrip pada seluruh pohon paket bundelnya

    Pertahankan kepemilikan hook ini pada penyedia. Jangan menambahkan cabang khusus CLI ke inti ketika hook backend dapat mengekspresikan perilaku tersebut.

    runtimeArtifact dimiliki plugin dan tidak dapat ditimpa oleh pengguna. Nilai ini diperiksa hanya ketika satu giliran inferensi langsung membuat atau memvalidasi ulang otoritas penyiapan terverifikasi; eksekusi CLI normal tidak memerlukannya. Backend tanpa deklarasi ini tidak dapat membuat otoritas penyiapan CLI terverifikasi. Deklarasi bundled-package-tree menyebutkan pemilik package.json yang tepat dan mewajibkan titik entri paket menjadi perintahnya. OpenClaw melakukan hash terhadap seluruh pohon paket terpasang yang dibatasi, termasuk dependensi bertingkat, dan menolak secara tertutup symlink yang mengalihkan, peluncur di luar paket yang dideklarasikan, deklarasi dependensi eksternal yang diwajibkan, pohon yang terlalu besar, dan skrip yang tidak dikenal. Deklarasikan ini hanya ketika pohon tersebut memuat implementasi inferensi lengkap; integrasi alat opsional tidak membuat graf implementasi eksternal menjadi aman.

    Jika backend yang sama juga menyertakan executable asli mandiri, cantumkan nama dasar kanonisnya dalam nativeExecutableNames. Perintah asli lainnya tetap tidak terverifikasi meskipun pengguna menimpa perintah backend.

    ctx.executionMode bernilai "agent" untuk giliran normal dan "side-question" untuk panggilan /btw sementara. Gunakan ini ketika CLI memerlukan flag sekali jalan yang berbeda, seperti menonaktifkan alat native, persistensi sesi, atau perilaku melanjutkan sesi untuk BTW. Jika backend biasanya memiliki nativeToolMode: "always-on" tetapi argv pertanyaan sampingnya secara andal menonaktifkan alat tersebut, tetapkan juga sideQuestionToolMode: "disabled"; jika tidak, OpenClaw akan gagal secara tertutup ketika BTW memerlukan eksekusi CLI tanpa alat.

    Tetapkan nativeToolMode: "selectable" hanya jika resolveExecutionArgs dapat menonaktifkan setiap alat native backend untuk satu eksekusi. Untuk eksekusi terbatas tersebut, ctx.toolAvailability.native adalah tuple kosong dan ctx.toolAvailability.mcp adalah daftar izin MCP terisolasi host yang persis. Hook tersebut harus mengganti flag alat yang berkonflik dan mengembalikan argv yang memberlakukan kedua nilai; OpenClaw memanggilnya sekali dengan argv baru atau lanjutan final dan gagal secara tertutup ketika backend tidak dapat memberlakukan pembatasan. Nama MCP dalam konteks ini aman untuk disetujui otomatis hanya karena host telah membatasi konfigurasi MCP yang dihasilkan ke server dan alat tersebut.

    ownsNativeCompaction: tidak menggunakan Compaction OpenClaw

    Jika backend Anda menjalankan agen yang memadatkan transkripnya sendiri, tetapkan ownsNativeCompaction: true agar peringkas pengaman OpenClaw tidak pernah dijalankan terhadap sesinya—siklus hidup Compaction CLI tidak melakukan apa pun dan giliran berlanjut. claude-cli mendeklarasikannya karena Claude Code melakukan Compaction secara internal tanpa endpoint harness. Sesi harness native seperti Codex tetap diarahkan ke endpoint Compaction harness masing-masing.

    Deklarasikan hanya jika semua hal berikut terpenuhi, atau sesi tertunda yang melebihi anggaran dapat tetap melebihi anggaran atau menjadi kedaluwarsa (OpenClaw tidak lagi menyelamatkannya):

    • backend secara andal melakukan Compaction atau membatasi transkripnya sendiri saat mendekati jendelanya;
    • backend mempertahankan sesi yang dapat dilanjutkan agar status hasil Compaction bertahan antar-giliran (misalnya --resume / --session-id);
    • sesi tersebut bukan sesi Compaction harness native—sesi dengan agentHarnessId yang cocok diarahkan ke endpoint harness.

    Jembatan alat MCP

    Backend CLI tidak menerima alat OpenClaw secara default. Jika CLI dapat menggunakan konfigurasi MCP, aktifkan secara eksplisit:

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

    Mode jembatan yang didukung:

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

    Aktifkan jembatan hanya jika CLI benar-benar dapat menggunakannya. Jika CLI memiliki lapisan alat bawaan sendiri yang tidak dapat dinonaktifkan, tetapkan nativeToolMode: "always-on" agar OpenClaw dapat gagal secara tertutup ketika pemanggil mengharuskan tidak adanya alat native. Jika CLI dapat menonaktifkan setiap alat native per eksekusi, gunakan "selectable" dengan kontrak resolveExecutionArgs di atas.

    Konfigurasi pengguna

    Pengguna dapat mengganti default backend apa pun:

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

    Dokumentasikan penggantian minimum yang kemungkinan diperlukan pengguna—biasanya hanya command ketika biner berada di luar PATH.

    Verifikasi

    Untuk Plugin yang dibundel, tambahkan pengujian terfokus pada builder dan registrasi penyiapan, lalu jalankan jalur pengujian tertarget Plugin tersebut:

    bash
    pnpm test extensions/acme-cli

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

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

    Jika backend mendukung gambar atau MCP, tambahkan uji asap langsung yang membuktikan jalur tersebut dengan CLI nyata. Jangan mengandalkan pemeriksaan statis untuk perilaku prompt, gambar, MCP, atau pelanjutan sesi.

    Daftar periksa

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json memiliki openclaw.extensions dan entri runtime hasil build untuk paket yang dipublikasikan OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s openclaw.plugin.json mendeklarasikan cliBackends dan activation.onStartup yang disengaja OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s setup.cliBackends tersedia ketika penyiapan/penemuan model harus dapat melihat backend dalam keadaan dingin OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s api.registerCliBackend(...) menggunakan id backend yang sama dengan manifes OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Penggantian pengguna di bawah agents.defaults.cliBackends.<id> tetap diutamakan OPENCLAW_DOCS_MARKER:calloutClose:

    Was this useful?
    On this page

    On this page