Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Plugin แบ็กเอนด์ CLI ช่วยให้ OpenClaw เรียก CLI AI ภายในเครื่องเป็นแบ็กเอนด์การอนุมานข้อความได้ แบ็กเอนด์จะแสดงเป็นคำนำหน้าผู้ให้บริการใน refs ของโมเดล: 
acme-cli/acme-large
ใช้แบ็กเอนด์ CLI เมื่อการผสาน upstream ถูกเปิดเผยเป็นคำสั่งภายในเครื่องอยู่แล้ว เมื่อ CLI เป็นเจ้าของสถานะการเข้าสู่ระบบภายในเครื่อง หรือเมื่อ CLI เป็นตัวเลือกสำรองที่มีประโยชน์หากผู้ให้บริการ API ไม่พร้อมใช้งาน
หากบริการ upstream เปิดเผย API โมเดล HTTP ปกติ ให้เขียน Plugin ผู้ให้บริการ แทน หาก runtime ของ upstream เป็นเจ้าของเซสชันเอเจนต์ทั้งหมด เหตุการณ์เครื่องมือ Compaction หรือสถานะงานเบื้องหลัง ให้ใช้ ชุดควบคุมเอเจนต์

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

Plugin แบ็กเอนด์ CLI มีสัญญาสามส่วน:
สัญญาไฟล์วัตถุประสงค์
จุดเข้าแพ็กเกจpackage.jsonชี้ OpenClaw ไปยังโมดูล runtime ของ Plugin
ความเป็นเจ้าของ manifestopenclaw.plugin.jsonประกาศรหัสแบ็กเอนด์ก่อนโหลด runtime
การลงทะเบียน runtimeindex.tsเรียก api.registerCliBackend(...) พร้อมค่าเริ่มต้นของคำสั่ง
manifest เป็นเมทาดาทาสำหรับการค้นพบ มันไม่ได้เรียกใช้ CLI และไม่ได้ลงทะเบียนพฤติกรรม runtime พฤติกรรม runtime เริ่มเมื่อจุดเข้า Plugin เรียก api.registerCliBackend(...)

​
Plugin แบ็กเอนด์ขั้นต่ำ

1

สร้างเมทาดาทาแพ็กเกจ

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"
  }
}
แพ็กเกจที่เผยแพร่ต้องจัดส่งไฟล์ runtime JavaScript ที่ build แล้ว หากจุดเข้าซอร์สของคุณคือ ./src/index.ts ให้เพิ่ม openclaw.runtimeExtensions ที่ชี้ไปยังไฟล์ JavaScript ที่ build แล้วคู่กัน ดู จุดเข้า
2

ประกาศความเป็นเจ้าของแบ็กเอนด์

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 คือรายการความเป็นเจ้าของ runtime ซึ่งช่วยให้ OpenClaw โหลด Plugin อัตโนมัติเมื่อ config หรือการเลือกโมเดลกล่าวถึง acme-cli/...setup.cliBackends คือพื้นผิวการตั้งค่าแบบ descriptor-first เพิ่มเมื่อการค้นพบโมเดล การเริ่มใช้งาน หรือสถานะควรรู้จักแบ็กเอนด์โดยไม่ต้องโหลด runtime ของ Plugin ใช้ requiresRuntime: false เฉพาะเมื่อ descriptor แบบสแตติกเหล่านั้นเพียงพอสำหรับการตั้งค่า
3

ลงทะเบียนแบ็กเอนด์

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());
  },
});
รหัสแบ็กเอนด์ต้องตรงกับรายการ cliBackends ใน manifest ส่วน config ที่ลงทะเบียนเป็นเพียงค่าเริ่มต้นเท่านั้น config ของผู้ใช้ภายใต้ agents.defaults.cliBackends.acme-cli จะถูก merge ทับใน runtime

​
รูปแบบ config

CliBackendConfig อธิบายว่า OpenClaw ควรเรียกใช้และแยกวิเคราะห์ CLI อย่างไร:
ฟิลด์การใช้งาน
commandชื่อไบนารีหรือพาธคำสั่งแบบสมบูรณ์
argsargv พื้นฐานสำหรับการรันใหม่
resumeArgsargv ทางเลือกสำหรับเซสชันที่ดำเนินต่อ รองรับ {sessionId}
output / resumeOutputตัวแยกวิเคราะห์: json, jsonl หรือ text
inputการส่งพรอมป์: arg หรือ stdin
modelArgแฟล็กที่ใช้ก่อนรหัสโมเดล
modelAliasesแมปรหัสโมเดล OpenClaw ไปยังรหัสแบบเนทีฟของ CLI
sessionArg / sessionArgsวิธีส่งรหัสเซสชัน
sessionModealways, existing หรือ none
sessionIdFieldsฟิลด์ JSON ที่ OpenClaw อ่านจากเอาต์พุต CLI
systemPromptArg / systemPromptFileArgการส่งพรอมป์ระบบ
systemPromptWhenfirst, always หรือ never
imageArg / imageModeการรองรับพาธรูปภาพ
serializeรักษาลำดับการรันของแบ็กเอนด์เดียวกัน
reliability.watchdogการปรับแต่ง timeout เมื่อไม่มีเอาต์พุต
เลือกใช้ config แบบสแตติกที่เล็กที่สุดซึ่งตรงกับ CLI เพิ่ม callback ของ Plugin เฉพาะสำหรับพฤติกรรมที่เป็นของแบ็กเอนด์จริง ๆ

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

CliBackendPlugin ยังสามารถกำหนด:
Hookการใช้งาน
normalizeConfig(config, context)เขียน config ผู้ใช้แบบเก่าใหม่หลัง merge
resolveExecutionArgs(ctx)เพิ่มแฟล็กตามขอบเขตคำขอ เช่น ระดับความพยายามในการคิด
prepareExecution(ctx)สร้างสะพาน auth หรือ config ชั่วคราวก่อนเริ่มทำงาน
transformSystemPrompt(ctx)ใช้การแปลงพรอมป์ระบบขั้นสุดท้ายที่เจาะจงกับ CLI
textTransformsการแทนที่พรอมป์/เอาต์พุตแบบสองทิศทาง
defaultAuthProfileIdเลือกใช้โปรไฟล์ auth ของ OpenClaw ที่เจาะจง
authEpochModeตัดสินว่าการเปลี่ยน auth ทำให้เซสชัน CLI ที่จัดเก็บไว้หมดอายุอย่างไร
nativeToolModeประกาศว่า CLI มีเครื่องมือเนทีฟที่เปิดตลอดหรือไม่
bundleMcp / bundleMcpModeเลือกใช้สะพานเครื่องมือ MCP ผ่าน loopback ของ OpenClaw
ให้ 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",
  },
};
โหมดสะพานที่รองรับคือ:
โหมดการใช้งาน
claude-config-fileCLI ที่ยอมรับไฟล์ config MCP
codex-config-overridesCLI ที่ยอมรับการ override config บน argv
gemini-system-settingsCLI ที่อ่านการตั้งค่า MCP จากไดเรกทอรีการตั้งค่าระบบของตัวเอง
เปิดใช้สะพานเฉพาะเมื่อ 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 หรือการดำเนินเซสชันต่อ

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

package.json มี openclaw.extensions และจุดเข้า runtime ที่ build แล้วสำหรับแพ็กเกจที่เผยแพร่
openclaw.plugin.json ประกาศ cliBackends และ activation.onStartup ตามเจตนา
setup.cliBackends มีอยู่เมื่อการตั้งค่า/การค้นพบโมเดลควรมองเห็นแบ็กเอนด์แบบเย็น
api.registerCliBackend(...) ใช้รหัสแบ็กเอนด์เดียวกับ manifest
override ของผู้ใช้ภายใต้ agents.defaults.cliBackends.<id> ยังคงชนะ
การตั้งค่าเซสชัน พรอมป์ระบบ รูปภาพ และตัวแยกวิเคราะห์เอาต์พุตตรงกับสัญญาจริงของ CLI
การทดสอบเป้าหมายและ live CLI smoke อย่างน้อยหนึ่งรายการพิสูจน์เส้นทางแบ็กเอนด์

​
ที่เกี่ยวข้อง