OpenClawDocs

Search...K

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

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": "เรียกใช้ CLI AI ภายในเครื่องของ Acme ผ่าน 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: "เรียกใช้ CLI AI ภายในเครื่องของ Acme ผ่าน OpenClaw",  register(api) {    api.registerCliBackend(buildAcmeCliBackend());  },});

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

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

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

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

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

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

prepareExecution(ctx) รับ ctx.contextTokenBudget ซึ่งเป็นขีดจำกัดโทเค็นที่มีผล ซึ่งเลือกไว้สำหรับการเรียกใช้ แบ็กเอนด์ที่จัดการ Compaction แบบเนทีฟเองสามารถจับคู่ งบประมาณดังกล่าวกับสัญญาการเรียกใช้เฉพาะ CLI ของตนได้

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

หากแบ็กเอนด์เดียวกันมีไฟล์ปฏิบัติการเนทีฟที่ทำงานได้ด้วยตนเองด้วย ให้ระบุ ชื่อฐานมาตรฐานของไฟล์เหล่านั้นใน 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 ปฏิเสธโดยปริยายได้เมื่อผู้เรียกต้องการไม่ใช้เครื่องมือเนทีฟ หากสามารถปิดใช้งานเครื่องมือเนทีฟทั้งหมดสำหรับการเรียกใช้แต่ละครั้งได้ ให้ใช้ "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 "ตอบให้ตรงตามนี้: 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(...) ใช้ ID แบ็กเอนด์เดียวกับแมนิเฟสต์ OPENCLAW_DOCS_MARKER:calloutClose:

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

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

• แบ็กเอนด์ CLI - การกำหนดค่าของผู้ใช้และพฤติกรรมรันไทม์
• การสร้าง Plugin - ข้อมูลพื้นฐานเกี่ยวกับแพ็กเกจและแมนิเฟสต์
• ภาพรวม SDK ของ Plugin - เอกสารอ้างอิง API การลงทะเบียน
• แมนิเฟสต์ของ Plugin - cliBackends และตัวอธิบายการตั้งค่า
• ฮาร์เนสเอเจนต์ - รันไทม์เอเจนต์ภายนอกเต็มรูปแบบ

Install OpenClawSet up TelegramFix GatewayBuild a plugin

Ask Molty

Ask Molty

Molty

Responses are generated using AI and may contain mistakes.