การสร้าง Plugin แบ็กเอนด์ CLI

Plugin แบ็กเอนด์ CLI ช่วยให้ OpenClaw เรียก CLI AI ภายในเครื่องเป็นแบ็กเอนด์การอนุมานข้อความได้ แบ็กเอนด์จะแสดงเป็นคำนำหน้าผู้ให้บริการใน refs ของโมเดล:

acme-cli/acme-large

ใช้แบ็กเอนด์ CLI เมื่อการผสาน upstream ถูกเปิดเผยเป็นคำสั่งภายในเครื่องอยู่แล้ว เมื่อ CLI เป็นเจ้าของสถานะการเข้าสู่ระบบภายในเครื่อง หรือเมื่อ CLI เป็นตัวเลือกสำรองที่มีประโยชน์หากผู้ให้บริการ API ไม่พร้อมใช้งาน

# สิ่งที่ Plugin เป็นเจ้าของ

Plugin แบ็กเอนด์ CLI มีสัญญาสามส่วน:

manifest เป็นเมทาดาทาสำหรับการค้นพบ มันไม่ได้เรียกใช้ CLI และไม่ได้ลงทะเบียนพฤติกรรม runtime พฤติกรรม runtime เริ่มเมื่อจุดเข้า 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());
  },
});

# รูปแบบ config

CliBackendConfig อธิบายว่า OpenClaw ควรเรียกใช้และแยกวิเคราะห์ CLI อย่างไร:

เลือกใช้ config แบบสแตติกที่เล็กที่สุดซึ่งตรงกับ CLI เพิ่ม callback ของ Plugin เฉพาะสำหรับพฤติกรรมที่เป็นของแบ็กเอนด์จริง ๆ

# hook แบ็กเอนด์ขั้นสูง

CliBackendPlugin ยังสามารถกำหนด:

ให้ hook เหล่านี้เป็นของผู้ให้บริการ อย่าเพิ่ม branch ที่เจาะจง CLI ลงใน core เมื่อ hook แบ็กเอนด์สามารถแสดงพฤติกรรมได้

# สะพานเครื่องมือ MCP

แบ็กเอนด์ CLI จะไม่ได้รับเครื่องมือ OpenClaw โดยค่าเริ่มต้น หาก CLI สามารถใช้ config 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 ปิดกั้นอย่างปลอดภัยเมื่อผู้เรียกต้องการไม่มีเครื่องมือเนทีฟ

# การกำหนดค่าของผู้ใช้

ผู้ใช้สามารถ override ค่าเริ่มต้นของแบ็กเอนด์ใดก็ได้:

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

บันทึก override ขั้นต่ำที่ผู้ใช้น่าจะต้องใช้ โดยทั่วไปคือเฉพาะ command เมื่อไบนารีอยู่นอก PATH

# การตรวจสอบ

สำหรับ Plugin ที่รวมมาในชุด ให้เพิ่มการทดสอบแบบเฉพาะจุดรอบ builder และการลงทะเบียน setup จากนั้นรัน lane ทดสอบเป้าหมายของ Plugin:

pnpm test extensions/acme-cli

สำหรับ Plugin ภายในเครื่องหรือที่ติดตั้งแล้ว ให้ตรวจสอบการค้นพบและการรันโมเดลจริงหนึ่งครั้ง:

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

หากแบ็กเอนด์รองรับรูปภาพหรือ MCP ให้เพิ่ม live smoke ที่พิสูจน์เส้นทางเหล่านั้นด้วย CLI จริง อย่าพึ่งพาการตรวจสอบแบบสแตติกสำหรับพฤติกรรมพรอมป์ รูปภาพ MCP หรือการดำเนินเซสชันต่อ

# รายการตรวจสอบ

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json มี openclaw.extensions และจุดเข้า runtime ที่ build แล้วสำหรับแพ็กเกจที่เผยแพร่ 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(...) ใช้รหัสแบ็กเอนด์เดียวกับ manifest OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s override ของผู้ใช้ภายใต้ agents.defaults.cliBackends.<id> ยังคงชนะ OPENCLAW_DOCS_MARKER:calloutClose: