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

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

acme-cli/acme-large

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

สิ่งที่ Plugin รับผิดชอบ

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

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

รูปแบบการกำหนดค่า

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

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

ฮุกแบ็กเอนด์ขั้นสูง

CliBackendPlugin ยังสามารถกำหนดรายการต่อไปนี้ได้:

เก็บฮุกเหล่านี้ไว้ภายใต้ความรับผิดชอบของผู้ให้บริการ อย่าเพิ่มแขนงเฉพาะ CLI ลงในแกนกลางเมื่อฮุกของแบ็กเอนด์สามารถอธิบายพฤติกรรมนั้นได้

runtimeArtifact เป็นความรับผิดชอบของ Plugin และผู้ใช้ไม่สามารถแทนค่าได้ ระบบจะตรวจสอบค่านี้เฉพาะเมื่อรอบการอนุมานสดสร้างหรือตรวจสอบสิทธิ์การตั้งค่าที่ผ่านการยืนยันอีกครั้ง การทำงาน CLI ปกติไม่จำเป็นต้องใช้ค่านี้ แบ็กเอนด์ที่ไม่มีการประกาศนี้ไม่สามารถสร้างสิทธิ์การตั้งค่า CLI ที่ผ่านการยืนยันได้ การประกาศ bundled-package-tree จะระบุเจ้าของ package.json ที่แน่นอนและกำหนดให้จุดเข้าของแพ็กเกจเป็นคำสั่ง OpenClaw จะแฮชโครงสร้างแพ็กเกจที่ติดตั้งทั้งหมดภายในขอบเขต รวมถึงการขึ้นต่อกันแบบซ้อน และจะหยุดการทำงานอย่างปลอดภัยเมื่อพบลิงก์สัญลักษณ์ที่เปลี่ยนเส้นทาง ตัวเรียกใช้นอกแพ็กเกจที่ประกาศ การประกาศการขึ้นต่อกันภายนอกที่จำเป็น โครงสร้างที่มีขนาดใหญ่เกินไป และสคริปต์ที่ไม่รู้จัก ให้ประกาศค่านี้เฉพาะเมื่อโครงสร้างดังกล่าวมีการใช้งานการอนุมานที่สมบูรณ์ การผสานรวมเครื่องมือเสริมไม่ได้ทำให้กราฟการใช้งานภายนอกมีความปลอดภัย

หากแบ็กเอนด์เดียวกันมีไฟล์ปฏิบัติการเนทีฟที่ทำงานได้ในตัว ให้ระบุชื่อฐานมาตรฐานของไฟล์เหล่านั้นใน nativeExecutableNames คำสั่งเนทีฟอื่น ๆ จะยังคงไม่ได้รับการยืนยัน แม้ว่าผู้ใช้จะแทนที่คำสั่งของแบ็กเอนด์ก็ตาม

ctx.executionMode มีค่าเป็น "agent" สำหรับรอบการทำงานปกติ และ "side-question" สำหรับการเรียก /btw แบบชั่วคราว ใช้ค่านี้เมื่อ CLI ต้องใช้แฟล็กแบบครั้งเดียวที่แตกต่างกัน เช่น การปิดใช้งานเครื่องมือเนทีฟ การคงอยู่ของเซสชัน หรือลักษณะการทำงานของการทำต่อสำหรับ BTW หากโดยปกติแบ็กเอนด์มี nativeToolMode: "always-on" แต่อาร์กิวเมนต์ argv สำหรับคำถามแทรกของแบ็กเอนด์สามารถปิดใช้งานเครื่องมือเหล่านั้นได้อย่างน่าเชื่อถือ ให้ตั้งค่า sideQuestionToolMode: "disabled" ด้วย มิฉะนั้น OpenClaw จะหยุดทำงานแบบปิดเพื่อความปลอดภัยเมื่อ BTW ต้องเรียกใช้ CLI โดยไม่มีเครื่องมือ

ตั้งค่า nativeToolMode: "selectable" เฉพาะเมื่อ resolveExecutionArgs สามารถปิดใช้งานเครื่องมือเนทีฟของแบ็กเอนด์ทุกตัวสำหรับการทำงานแต่ละครั้งได้ สำหรับการทำงานที่ถูกจำกัดเหล่านั้น ctx.toolAvailability.native จะเป็นทูเพิลว่าง และ ctx.toolAvailability.mcp จะเป็นรายการอนุญาต MCP ที่แยกจากโฮสต์อย่างเคร่งครัด ฮุกต้องแทนที่แฟล็กเครื่องมือที่ขัดแย้งกันและส่งคืน argv ที่บังคับใช้ค่าทั้งสอง OpenClaw จะเรียกฮุกนี้หนึ่งครั้งด้วย argv สุดท้ายสำหรับการเริ่มใหม่หรือการทำต่อ และจะหยุดทำงานแบบปิดเพื่อความปลอดภัยเมื่อแบ็กเอนด์ไม่สามารถบังคับใช้ข้อจำกัดได้ ชื่อ MCP ในบริบทนี้สามารถอนุมัติโดยอัตโนมัติได้อย่างปลอดภัย เนื่องจากโฮสต์ได้จำกัดการกำหนดค่า MCP ที่สร้างขึ้นไว้เฉพาะเซิร์ฟเวอร์และเครื่องมือเหล่านั้นแล้ว

ownsNativeCompaction: การเลือกไม่ใช้ Compaction ของ OpenClaw

หากแบ็กเอนด์ของคุณเรียกใช้เอเจนต์ที่ทำ Compaction ทรานสคริปต์ของตนเอง ให้ตั้งค่า ownsNativeCompaction: true เพื่อให้ตัวสรุปเพื่อป้องกันของ OpenClaw ไม่ทำงานกับเซสชันของแบ็กเอนด์ วงจร Compaction ของ CLI จะไม่ดำเนินการใด ๆ และรอบการทำงานจะดำเนินต่อไป claude-cli ประกาศค่านี้เนื่องจาก Claude Code ทำ Compaction ภายในโดยไม่มีเอนด์พอยต์ของฮาร์เนส ส่วนเซสชันฮาร์เนสเนทีฟ เช่น Codex จะยังคงถูกส่งต่อไปยังเอนด์พอยต์ Compaction ของฮาร์เนสแทน

ประกาศค่านี้เฉพาะเมื่อเป็นไปตามเงื่อนไขทั้งหมดต่อไปนี้ มิฉะนั้นเซสชันที่เกินงบประมาณและถูกเลื่อนการประมวลผลอาจยังคงเกินงบประมาณหรือล้าสมัยได้ (OpenClaw จะไม่เข้าช่วยเหลืออีกต่อไป):

• แบ็กเอนด์ทำ Compaction หรือจำกัดขนาดทรานสคริปต์ของตนเองอย่างน่าเชื่อถือเมื่อใกล้ถึงขีดจำกัดหน้าต่าง;
• แบ็กเอนด์คงเซสชันที่สามารถทำต่อได้ เพื่อให้สถานะที่ผ่าน Compaction ยังคงอยู่ข้ามรอบการทำงาน (ตัวอย่างเช่น --resume / --session-id);
• เซสชันนั้นไม่ใช่เซสชัน Compaction ของฮาร์เนสเนทีฟ โดยเซสชันที่ตรงกับ agentHarnessId จะถูกส่งต่อไปยังเอนด์พอยต์ของฮาร์เนสแทน

บริดจ์เครื่องมือ MCP

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

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

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

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

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

การตรวจสอบยืนยัน

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

pnpm test extensions/acme-cli

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

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

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

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

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

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s ค่าทับของผู้ใช้ภายใต้ agents.defaults.cliBackends.<id> ยังคงมีผลเหนือกว่า OPENCLAW_DOCS_MARKER:calloutClose: