Xây dựng các Plugin phần phụ trợ CLI

Plugin backend CLI cho phép OpenClaw gọi một CLI AI cục bộ làm backend suy luận văn bản. Backend này xuất hiện như một tiền tố nhà cung cấp trong tham chiếu mô hình:

acme-cli/acme-large

Dùng backend CLI khi tích hợp thượng nguồn đã được cung cấp dưới dạng lệnh cục bộ, khi CLI sở hữu trạng thái đăng nhập cục bộ, hoặc khi CLI là phương án dự phòng hữu ích nếu các nhà cung cấp API không khả dụng.

# Plugin sở hữu những gì

Một Plugin backend CLI có ba hợp đồng:

Manifest là siêu dữ liệu khám phá. Nó không thực thi CLI và không đăng ký hành vi runtime. Hành vi runtime bắt đầu khi điểm vào Plugin gọi api.registerCliBackend(...).

# Plugin backend tối thiểu

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

# Hình dạng cấu hình

CliBackendConfig mô tả cách OpenClaw nên khởi chạy và phân tích CLI:

Ưu tiên cấu hình tĩnh nhỏ nhất khớp với CLI. Chỉ thêm callback của Plugin cho hành vi thật sự thuộc về backend.

# Hook backend nâng cao

CliBackendPlugin cũng có thể định nghĩa:

Giữ các hook này thuộc sở hữu của nhà cung cấp. Không thêm nhánh dành riêng cho CLI vào core khi hook backend có thể biểu đạt hành vi đó.

# Cầu nối công cụ MCP

Backend CLI mặc định không nhận công cụ OpenClaw. Nếu CLI có thể tiêu thụ cấu hình MCP, hãy chọn tham gia rõ ràng:

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

Các chế độ cầu nối được hỗ trợ là:

Chỉ bật cầu nối khi CLI thật sự có thể tiêu thụ nó. Nếu CLI có lớp công cụ tích hợp riêng không thể tắt, hãy đặt nativeToolMode: "always-on" để OpenClaw có thể fail closed khi bên gọi yêu cầu không có công cụ gốc.

# Cấu hình người dùng

Người dùng có thể ghi đè bất kỳ mặc định backend nào:

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

Ghi tài liệu về ghi đè tối thiểu mà người dùng nhiều khả năng cần. Thường đó chỉ là command khi binary nằm ngoài PATH.

# Xác minh

Đối với Plugin đi kèm, hãy thêm một kiểm thử tập trung quanh builder và đăng ký thiết lập, rồi chạy lane kiểm thử mục tiêu của Plugin:

pnpm test extensions/acme-cli

Đối với Plugin cục bộ hoặc đã cài đặt, hãy xác minh khám phá và một lượt chạy mô hình thật:

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

Nếu backend hỗ trợ ảnh hoặc MCP, hãy thêm smoke live chứng minh các đường dẫn đó với CLI thật. Không dựa vào kiểm tra tĩnh cho hành vi prompt, ảnh, MCP, hoặc tiếp tục phiên.

# Danh sách kiểm tra

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json có openclaw.extensions và các điểm vào runtime đã build cho gói phát hành OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s openclaw.plugin.json khai báo cliBackends và activation.onStartup có chủ đích OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s setup.cliBackends có mặt khi thiết lập/khám phá mô hình cần thấy backend ở trạng thái lạnh OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s api.registerCliBackend(...) dùng cùng id backend với manifest OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Ghi đè người dùng dưới agents.defaults.cliBackends.<id> vẫn thắng OPENCLAW_DOCS_MARKER:calloutClose: