Xây dựng các plugin backend CLI

Các 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 xuất hiện dưới dạng tiền tố provider trong tham chiếu model:

acme-cli/acme-large

Sử 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 quản lý trạng thái đăng nhập cục bộ hoặc làm phương án dự phòng khi các provider API không khả dụng.

Nếu dịch vụ thượng nguồn cung cấp API model HTTP thông thường, hãy viết một plugin provider thay thế. Nếu runtime thượng nguồn quản lý toàn bộ phiên agent, sự kiện công cụ, compaction hoặc trạng thái tác vụ nền, hãy sử dụng một agent harness.

​

Những gì plugin quản lý

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

Hợp đồng	Tệp	Mục đích
Điểm vào gói	package.json	Trỏ OpenClaw đến mô-đun runtime của plugin
Quyền sở hữu manifest	openclaw.plugin.json	Khai báo id backend trước khi runtime tải
Đăng ký runtime	index.ts	Gọi api.registerCliBackend(...) với các giá trị mặc định của lệnh

Manifest là siêu dữ liệu khám phá: nó không thực thi CLI hoặc đă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

1. Tạo siêu dữ liệu gói

   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"
     }
   }
   

   Các gói đã phát hành phải chứa các tệp runtime JavaScript đã được build. Nếu điểm vào mã nguồn của bạn là ./src/index.ts, hãy thêm openclaw.runtimeExtensions trỏ đến tệp JavaScript đã build tương ứng. Xem Điểm vào.

2. Khai báo quyền sở hữu backend

   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 là danh sách quyền sở hữu runtime; nó cho phép OpenClaw tự động tải plugin khi cấu hình hoặc lựa chọn model đề cập đến acme-cli/....

   setup.cliBackends là bề mặt thiết lập ưu tiên descriptor. Hãy thêm nó khi việc khám phá model, onboarding hoặc trạng thái cần nhận diện backend mà không tải runtime của plugin. Chỉ sử dụng requiresRuntime: false khi các descriptor tĩnh đó đủ cho việc thiết lập.

3. Đăng ký backend

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

   Id backend phải khớp với mục manifest cliBackends. config đã đăng ký chỉ là giá trị mặc định; cấu hình người dùng trong agents.defaults.cliBackends.acme-cli sẽ được hợp nhất và ghi đè lên nó tại runtime.

​

Cấu trúc cấu hình

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

Trường	Công dụng
command	Tên tệp nhị phân hoặc đường dẫn lệnh tuyệt đối
args	argv cơ sở cho các lần chạy mới
resumeArgs	argv thay thế cho các phiên được tiếp tục; hỗ trợ {sessionId}
output / resumeOutput	Trình phân tích: json, jsonl hoặc text
jsonlDialect	Phương ngữ sự kiện JSONL: claude-stream-json hoặc gemini-stream-json
liveSession	Chế độ tiến trình CLI tồn tại lâu (claude-stdio)
input	Phương thức truyền prompt: arg hoặc stdin
maxPromptArgChars	Độ dài prompt tối đa cho chế độ arg trước khi chuyển sang stdin
env / clearEnv	Các biến môi trường bổ sung cần chèn hoặc các tên cần loại bỏ trước khi khởi chạy
modelArg	Cờ được dùng trước id model
modelAliases	Ánh xạ id model OpenClaw sang id gốc của CLI
sessionArg / sessionArgs	Cách truyền id phiên
sessionMode	always, existing hoặc none
sessionIdFields	Các trường JSON mà OpenClaw đọc từ đầu ra CLI
systemPromptArg / systemPromptFileArg	Phương thức truyền prompt hệ thống
systemPromptFileConfigArg / systemPromptFileConfigKey	Phương thức truyền ghi đè cấu hình cho tệp prompt hệ thống (ví dụ -c)
systemPromptMode	append hoặc replace
systemPromptWhen	first, always hoặc never
imageArg / imageMode	Cờ đường dẫn hình ảnh và cách truyền nhiều hình ảnh (repeat hoặc list)
imagePathScope	Nơi lưu các tệp hình ảnh tạm trước khi bàn giao: temp hoặc workspace
serialize	Duy trì thứ tự các lần chạy cùng backend
reseedFromRawTranscriptWhenUncompacted	Cho phép tùy chọn gieo lại bản ghi thô có giới hạn trước compaction để đặt lại phiên an toàn
reliability.watchdog	Tinh chỉnh thời gian chờ khi không có đầu ra, riêng biệt cho lần chạy mới và lần chạy tiếp tục

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

​

Hook backend nâng cao

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

Hook	Công dụng
normalizeConfig(config, context)	Viết lại cấu hình người dùng cũ sau khi hợp nhất
resolveExecutionArgs(ctx)	Thêm các cờ theo phạm vi yêu cầu, chẳng hạn như mức độ suy luận hoặc cô lập câu hỏi phụ
prepareExecution(ctx)	Tạo cầu nối xác thực, cấu hình hoặc môi trường tạm thời trước khi khởi chạy
transformSystemPrompt(ctx)	Áp dụng phép biến đổi prompt hệ thống cuối cùng dành riêng cho CLI
textTransforms	Các phép thay thế prompt/đầu ra hai chiều
defaultAuthProfileId	Ưu tiên một hồ sơ xác thực OpenClaw cụ thể
authEpochMode	Quyết định cách thay đổi xác thực làm mất hiệu lực các phiên CLI đã lưu
nativeToolMode	Khai báo công cụ gốc không tồn tại, luôn bật hoặc có thể được host lựa chọn
sideQuestionToolMode	Khai báo các công cụ gốc bị vô hiệu hóa cho câu hỏi phụ /btw
bundleMcp / bundleMcpMode	Cho phép sử dụng cầu nối công cụ MCP loopback của OpenClaw
ownsNativeCompaction	Backend tự quản lý compaction — OpenClaw trì hoãn
subscriptionAuthDispatch	Các lần chạy nhúng đã chọn tham gia bằng thông tin xác thực thuê bao được thực thi qua backend này
runtimeArtifact	Giới hạn trình khởi chạy script trong toàn bộ cây gói đi kèm của nó

Giữ các hook này thuộc quyền quản lý của provider. Không thêm các nhánh dành riêng cho CLI vào lõi khi một hook backend có thể biểu đạt hành vi đó.

prepareExecution(ctx) nhận ctx.contextTokenBudget, giới hạn token hiệu dụng được chọn cho lần chạy. Các backend tự quản lý compaction gốc có thể ánh xạ ngân sách đó vào hợp đồng khởi chạy dành riêng cho CLI của chúng.

runtimeArtifact thuộc quyền sở hữu của plugin và người dùng không thể ghi đè. Giá trị này chỉ được tham chiếu khi một lượt suy luận trực tiếp tạo mới hoặc xác thực lại quyền thiết lập đã xác minh; các lần chạy CLI thông thường không yêu cầu giá trị này. Backend không có khai báo này không thể tạo quyền thiết lập CLI đã xác minh. Khai báo bundled-package-tree chỉ định chính xác chủ sở hữu package.json và yêu cầu entrypoint của gói phải là lệnh đó. OpenClaw băm toàn bộ cây gói đã cài đặt trong giới hạn, bao gồm các phần phụ thuộc lồng nhau, và dừng an toàn đối với symlink chuyển hướng, trình khởi chạy nằm ngoài gói đã khai báo, các khai báo phần phụ thuộc bên ngoài bắt buộc, cây quá lớn và tập lệnh không xác định. Chỉ khai báo giá trị này khi cây đó chứa toàn bộ phần triển khai suy luận; các tích hợp công cụ tùy chọn không khiến biểu đồ triển khai bên ngoài trở nên an toàn.

Nếu cùng backend đó cũng cung cấp một tệp thực thi gốc độc lập, hãy liệt kê các basename chuẩn của tệp trong nativeExecutableNames. Các lệnh gốc khác vẫn không được xác minh ngay cả khi người dùng ghi đè lệnh backend.

ctx.executionMode là "agent" cho các lượt thông thường và "side-question" cho các lệnh gọi /btw tạm thời. Sử dụng giá trị này khi CLI cần các cờ dùng một lần khác, chẳng hạn như tắt công cụ gốc, khả năng duy trì phiên hoặc hành vi tiếp tục cho BTW. Nếu backend thường có nativeToolMode: "always-on" nhưng argv cho câu hỏi phụ của backend tắt các công cụ đó một cách đáng tin cậy, hãy đặt thêm sideQuestionToolMode: "disabled"; nếu không, OpenClaw sẽ dừng an toàn khi BTW yêu cầu một lần chạy CLI không có công cụ.

Chỉ đặt nativeToolMode: "selectable" khi resolveExecutionArgs có thể tắt mọi công cụ gốc của backend cho từng lần chạy riêng lẻ. Đối với các lần chạy bị hạn chế đó, ctx.toolAvailability.native là một tuple rỗng và ctx.toolAvailability.mcp là danh sách cho phép MCP chính xác được cô lập bởi máy chủ. Hook phải thay thế các cờ công cụ xung đột và trả về argv thực thi cả hai giá trị; OpenClaw gọi hook này một lần với argv cuối cùng cho lượt mới hoặc tiếp tục và dừng an toàn khi backend không thể thực thi hạn chế. Tên MCP trong ngữ cảnh này chỉ an toàn để tự động phê duyệt vì máy chủ đã giới hạn cấu hình MCP được tạo ở các máy chủ và công cụ đó.

​

ownsNativeCompaction: chọn không sử dụng Compaction của OpenClaw

Nếu backend của bạn chạy một tác nhân tự Compaction bản chép lời của chính nó, hãy đặt ownsNativeCompaction: true để trình tóm tắt bảo vệ của OpenClaw không bao giờ chạy trên các phiên của tác nhân đó — vòng đời Compaction CLI trả về trạng thái không làm gì và lượt tiếp tục. claude-cli khai báo giá trị này vì Claude Code thực hiện Compaction nội bộ mà không có endpoint harness. Thay vào đó, các phiên harness gốc như Codex tiếp tục được định tuyến đến endpoint Compaction của harness.

Chỉ khai báo giá trị này khi đáp ứng tất cả các điều kiện sau, nếu không một phiên vượt ngân sách bị hoãn có thể tiếp tục vượt ngân sách hoặc trở nên lỗi thời (OpenClaw không còn khắc phục phiên đó):

• backend thực hiện Compaction hoặc giới hạn bản chép lời của chính nó một cách đáng tin cậy khi gần đạt giới hạn cửa sổ;
• backend duy trì một phiên có thể tiếp tục để trạng thái đã Compaction tồn tại qua các lượt (ví dụ: --resume / --session-id);
• đây không phải là phiên Compaction bằng harness gốc — các phiên khớp với agentHarnessId được định tuyến đến endpoint harness thay thế.

​

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

Các backend CLI không nhận công cụ OpenClaw theo mặc định. Nếu CLI có thể sử dụng cấu hình MCP, hãy chọn tham gia một cách 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ợ:

Chế độ	Cách sử dụng
claude-config-file	CLI chấp nhận tệp cấu hình MCP
codex-config-overrides	CLI chấp nhận các giá trị ghi đè cấu hình trong argv
gemini-system-settings	CLI đọc cài đặt MCP từ thư mục cài đặt hệ thống của chúng

Chỉ bật cầu nối khi CLI thực sự có thể sử dụng 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ể dừng an toàn khi bên gọi yêu cầu không có công cụ gốc. Nếu CLI có thể tắt mọi công cụ gốc theo từng lần chạy, hãy sử dụng "selectable" với hợp đồng resolveExecutionArgs ở trên.

​

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

Người dùng có thể ghi đè mọi giá trị mặc định của backend:

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

Ghi lại giá trị ghi đè tối thiểu mà người dùng có thể cần — thường chỉ là command khi tệp nhị phân nằm ngoài PATH.

​

Xác minh

Đối với các plugin đi kèm, hãy thêm một kiểm thử tập trung cho trình dựng và việc đăng ký thiết lập, sau đó chạy lane kiểm thử mục tiêu của plugin:

pnpm test extensions/acme-cli

Đối với các plugin cục bộ hoặc đã cài đặt, hãy xác minh khả năng khám phá và một lần chạy mô hình thực:

openclaw plugins inspect acme-cli --runtime --json
openclaw agent --message "chỉ trả lời chính xác: backend ok" --model acme-cli/acme-large

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

​

Danh sách kiểm tra

package.json có openclaw.extensions và các mục runtime đã dựng cho những gói được phát hành

openclaw.plugin.json khai báo cliBackends và activation.onStartup có chủ đích

setup.cliBackends hiện diện khi quá trình thiết lập/khám phá mô hình cần thấy backend ở trạng thái nguội

api.registerCliBackend(...) sử dụng cùng id backend với manifest

Các giá trị ghi đè của người dùng trong agents.defaults.cliBackends.<id> vẫn được ưu tiên

Cài đặt phiên, prompt hệ thống, hình ảnh và trình phân tích cú pháp đầu ra khớp với hợp đồng CLI thực

Các kiểm thử mục tiêu và ít nhất một smoke test CLI trực tiếp chứng minh đường dẫn backend

​

Liên quan

• Backend CLI — cấu hình người dùng và hành vi runtime
• Xây dựng plugin — kiến thức cơ bản về gói và manifest
• Tổng quan SDK Plugin — tài liệu tham khảo API đăng ký
• Manifest plugin — cliBackends và các bộ mô tả thiết lập
• Harness tác nhân — các runtime tác nhân bên ngoài đầy đủ