跳轉到主要內容
命令列介面後端外掛可讓 OpenClaw 呼叫本機 AI 命令列介面作為文字推論 後端。後端會在模型參照中顯示為供應商前綴： 
acme-cli/acme-large
當上游整合已經以本機命令形式公開、命令列介面擁有本機登入狀態，或在 API 供應商無法使用時作為備援，請使用命令列介面後端。
如果上游服務公開一般 HTTP 模型 API，請改寫 供應商外掛。如果上游 執行階段擁有完整的代理工作階段、工具事件、壓縮或背景 任務狀態，請使用代理線束。

​
外掛擁有的內容

命令列介面後端外掛有三項契約：
契約檔案用途
套件進入點package.json將 OpenClaw 指向外掛執行階段模組
清單所有權openclaw.plugin.json在執行階段載入前宣告後端 ID
執行階段註冊index.ts以命令預設值呼叫 api.registerCliBackend(...)
清單是探索中繼資料：它不會執行命令列介面，也不會註冊 執行階段行為。執行階段行為會在外掛進入點呼叫 api.registerCliBackend(...) 時開始。

​
最小後端外掛

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"
  }
}
已發布的套件必須隨附建置後的 JavaScript 執行階段檔案。如果你的來源 進入點是 ./src/index.ts，請加入 openclaw.runtimeExtensions，指向 建置後的 JavaScript 同層檔案。請參閱進入點。
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 是執行階段所有權清單；當設定或模型選擇提到 acme-cli/... 時，它可讓 OpenClaw 自動載入外掛。setup.cliBackends 是描述器優先的設定介面。當模型探索、上手流程或狀態 應在不載入外掛執行階段的情況下辨識後端時，請加入它。只有當 這些靜態描述器足以供設定使用時，才使用 requiresRuntime: false。
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());
  },
});
後端 ID 必須與清單中的 cliBackends 項目相符。 已註冊的 config 只是預設值；位於 agents.defaults.cliBackends.acme-cli 下的使用者設定會在執行階段合併覆蓋它。

​
設定形狀

CliBackendConfig 描述 OpenClaw 應如何啟動並剖析命令列介面：
欄位用途
command二進位檔名稱或絕對命令路徑
args全新執行的基礎 argv
resumeArgs已恢復工作階段的替代 argv；支援 {sessionId}
output / resumeOutput剖析器：json、jsonl 或 text
jsonlDialectJSONL 事件方言：claude-stream-json 或 gemini-stream-json
liveSession長時間執行的命令列介面程序模式 (claude-stdio)
input提示傳輸：arg 或 stdin
maxPromptArgChars在退回 stdin 前，arg 模式的最大提示長度
env / clearEnv要注入的額外環境變數，或啟動前要移除的名稱
modelArg模型 ID 前使用的旗標
modelAliases將 OpenClaw 模型 ID 對應到命令列介面原生 ID
sessionArg / sessionArgs如何傳遞工作階段 ID
sessionModealways、existing 或 none
sessionIdFieldsOpenClaw 從命令列介面輸出讀取的 JSON 欄位
systemPromptArg / systemPromptFileArg系統提示傳輸
systemPromptFileConfigArg / systemPromptFileConfigKey系統提示檔案的設定覆寫傳輸（例如 -c）
systemPromptModeappend 或 replace
systemPromptWhenfirst、always 或 never
imageArg / imageMode圖片路徑旗標，以及如何傳遞多張圖片（repeat 或 list）
imagePathScope交接前暫存圖片檔案的位置：temp 或 workspace
serialize保持同一後端的執行順序
reseedFromRawTranscriptWhenUncompacted選擇在壓縮前進行有界原始逐字稿重新播種，以安全重設工作階段
reliability.outputLimits單次即時命令列介面回合保留的最大原始 JSONL 字元/行數（即時工作階段後端）
reliability.watchdog無輸出逾時調整，分別用於全新與已恢復的執行
請優先使用符合命令列介面的最小靜態設定。只有在行為確實屬於後端時， 才加入外掛回呼。

​
進階後端掛鉤

CliBackendPlugin 也可以定義：
掛鉤用途
normalizeConfig(config, context)合併後重寫舊版使用者設定
resolveExecutionArgs(ctx)加入請求範圍旗標，例如思考強度或旁路問題隔離
prepareExecution(ctx)啟動前建立臨時驗證或設定橋接
transformSystemPrompt(ctx)套用最後的命令列介面專用系統提示轉換
textTransforms雙向提示/輸出替換
defaultAuthProfileId優先使用特定 OpenClaw 驗證設定檔
authEpochMode決定驗證變更如何使已儲存的命令列介面工作階段失效
nativeToolMode宣告命令列介面是否具有始終啟用的原生工具
sideQuestionToolMode宣告 /btw 旁路問題的已停用原生工具
bundleMcp / bundleMcpMode選擇加入 OpenClaw 的回送 MCP 工具橋接
ownsNativeCompaction後端擁有自己的壓縮 - OpenClaw 會延後處理
請讓這些掛鉤由供應商擁有。當後端掛鉤能表達該行為時， 不要在核心中加入命令列介面專用分支。 ctx.executionMode 在一般回合中是 "agent"，在暫時性 /btw 呼叫中是 "side-question"。當命令列介面需要不同的一次性旗標時使用它， 例如為 BTW 停用原生工具、工作階段持久化或恢復行為。如果後端通常有 nativeToolMode: "always-on"，但其旁路問題 argv 能可靠停用這些工具，也請設定 sideQuestionToolMode: "disabled"；否則當 BTW 需要無工具命令列介面執行時， OpenClaw 會以失敗關閉。

​
ownsNativeCompaction：選擇退出 OpenClaw 壓縮

如果你的後端執行的代理會壓縮它自己的逐字稿，請設定 ownsNativeCompaction: true，讓 OpenClaw 的保護性摘要器永遠不會針對 其工作階段執行 - 命令列介面的壓縮生命週期會傳回 no-op，且該回合會繼續。 claude-cli 會宣告它，因為 Claude Code 會在內部壓縮， 且沒有線束端點。像 Codex 這類原生線束工作階段，則會繼續路由到其線束壓縮端點。 只有在以下所有條件都成立時才宣告它，否則延後處理的 超預算工作階段可能會持續超出預算或變得過期（OpenClaw 不再 救援它）：
  • 後端在接近自身視窗上限時，能可靠地壓縮或限制自己的轉錄內容；
  • 它會持久化可續接的工作階段，讓壓縮後的狀態能跨回合保留 （例如 --resume / --session-id）；
  • 它不是原生 harness 壓縮工作階段 - 符合 agentHarnessId 的工作階段會改由 harness 端點處理。

​
MCP 工具橋接

命令列介面後端預設不會收到 OpenClaw 工具。如果命令列介面可以使用 MCP 設定，請明確選擇啟用： 
return {
  id: "acme-cli",
  bundleMcp: true,
  bundleMcpMode: "codex-config-overrides",
  config: {
    command: "acme",
    args: ["chat", "--json"],
    output: "json",
  },
};
支援的橋接模式：
模式用途
claude-config-file接受 MCP 設定檔的命令列介面
codex-config-overrides接受 argv 上設定覆寫的命令列介面
gemini-system-settings從其系統設定目錄讀取 MCP 設定的命令列介面
只有在命令列介面確實可以使用橋接時才啟用它。如果命令列介面有 無法停用的內建工具層，請設定 nativeToolMode: "always-on"，讓 OpenClaw 在呼叫端要求沒有原生 工具時能封閉失敗。

​
使用者設定

使用者可以覆寫任何後端預設值： 
{
  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"],
      },
    },
  },
}
記錄使用者可能需要的最小覆寫項目 - 通常只有當二進位檔不在 PATH 中時才需要 command。

​
驗證

對於 bundled 外掛，請為建構器與設定註冊新增一個聚焦測試， 然後執行該外掛的目標測試通道： 
pnpm test extensions/acme-cli
對於本機或已安裝的外掛，請驗證探索以及一次真實模型執行： 
openclaw plugins inspect acme-cli --runtime --json
openclaw agent --message "reply exactly: backend ok" --model acme-cli/acme-large
如果後端支援圖片或 MCP，請新增一個即時 smoke，以使用真實命令列介面證明那些 路徑。不要依賴靜態檢查來驗證提示、圖片、 MCP 或工作階段續接行為。

​
檢查清單

package.json 具有 openclaw.extensions，且已為發布套件建立 runtime entries
openclaw.plugin.json 宣告 cliBackends 與有意圖的 activation.onStartup
當設定/模型探索應能冷啟動看到後端時，存在 setup.cliBackends
api.registerCliBackend(...) 使用與 manifest 相同的後端 ID
agents.defaults.cliBackends.<id> 下的使用者覆寫仍然優先
工作階段、系統提示、圖片與輸出 parser 設定符合真實命令列介面契約
目標測試與至少一次即時命令列介面 smoke 證明後端路徑

​
相關