Building plugins
建置命令列介面後端外掛
CLI 後端外掛可讓 OpenClaw 呼叫本機 AI 命令列介面，作為文字推論 後端。此後端會在模型參照中顯示為提供者前綴：
acme-cli/acme-large當上游整合已透過本機命令提供、命令列介面管理本機登入狀態，或在 API 提供者無法使用時作為備援，可使用 CLI 後端。
外掛負責的項目
CLI 後端外掛包含三項合約：
| 合約 | 檔案 | 用途 |
|---|---|---|
| 套件進入點 | package.json |
將 OpenClaw 指向外掛執行階段模組 |
| 資訊清單所有權 | openclaw.plugin.json |
在載入執行階段前宣告後端 ID |
| 執行階段註冊 | index.ts |
使用命令預設值呼叫 api.registerCliBackend(...) |
資訊清單是探索中繼資料：它不會執行命令列介面或註冊
執行階段行為。外掛進入點呼叫
api.registerCliBackend(...) 時，執行階段行為才會開始。
最小後端外掛
建立套件中繼資料
{ "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，請新增指向
建置完成之對應 JavaScript 檔案的 openclaw.runtimeExtensions。請參閱進入點。
宣告後端所有權
{ "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 是執行階段所有權清單；當模型選擇或 agentRuntime.id 提及 acme-cli 時，
它可讓 OpenClaw 自動載入
外掛。
setup.cliBackends 是描述元優先的設定介面。當
模型探索、初始設定或狀態應在不載入外掛執行階段的情況下辨識後端時，請新增此介面。
只有當這些靜態描述元足以完成設定時，才使用 requiresRuntime: 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", "--output-format", "stream-json", "--prompt", "{prompt}"], resumeArgs: [ "chat", "--resume", "{sessionId}", "--output-format", "stream-json", "--prompt", "{prompt}", ], output: "jsonl", resumeOutput: "jsonl", jsonlDialect: "gemini-stream-json", input: "arg", modelArg: "--model", modelAliases: { large: "acme-large-2026", fast: "acme-fast-2026", }, sessionArgs: ["--session", "{sessionId}"], sessionMode: "existing", sessionIdFields: ["session_id", "conversation_id"], systemPromptFileArg: "--system-file", systemPromptWhen: "first", imageArg: "--image", imageMode: "repeat", imagePathScope: "workspace", 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 項目。已註冊的
轉接器是具權威性的外掛程式碼；OpenClaw 設定會選擇後端，
但不會改寫其命令合約。
設定結構
CliBackendConfig 說明 OpenClaw 應如何啟動及剖析命令列介面。上述
完整範例刻意使用與內建
google-gemini-cli 轉接器相同的命令、恢復、JSONL、
模型別名、工作階段、影像及監控程序欄位：
| 欄位 | 用途 |
|---|---|
command |
二進位檔名稱或命令的絕對路徑 |
args |
全新執行的基礎 argv |
resumeArgs |
已恢復工作階段的替代 argv；支援 {sessionId} |
output / resumeOutput |
剖析器：json、jsonl 或 text |
jsonlDialect |
JSONL 事件方言：claude-stream-json 或 gemini-stream-json |
liveSession |
長時間執行的 CLI 處理程序模式（claude-stdio） |
input |
提示詞傳輸方式：arg 或 stdin |
maxPromptArgChars |
arg 模式在改用標準輸入前允許的提示詞長度上限 |
env / clearEnv |
要注入的額外環境變數，或啟動前要移除的名稱 |
modelArg |
模型 ID 前使用的旗標 |
modelAliases |
將 OpenClaw 模型 ID 對應至 CLI 原生 ID |
sessionArgs |
如何使用 {sessionId} 傳遞工作階段 ID |
sessionMode |
always、existing 或 none |
sessionIdFields |
OpenClaw 從 CLI 輸出讀取的 JSON 欄位 |
systemPromptArg / systemPromptFileArg |
系統提示詞傳輸方式 |
systemPromptFileConfigArg / systemPromptFileConfigKey |
系統提示詞檔案的設定覆寫傳輸方式（例如 -c） |
systemPromptMode |
append 或 replace |
systemPromptWhen |
first、always 或 never |
imageArg / imageMode |
影像路徑旗標，以及如何傳遞多張影像（repeat 或 list） |
imagePathScope |
交接前暫存影像檔案的所在位置：temp 或 workspace |
serialize |
讓相同後端的執行保持依序進行 |
reseedFromRawTranscriptWhenUncompacted |
選擇啟用在壓縮前對原始逐字稿進行有界限的重新植入，以安全重設工作階段 |
reliability.watchdog |
無輸出逾時調整，分別設定全新與已恢復的執行 |
應優先使用符合命令列介面的最小靜態設定。僅針對確實屬於後端的行為 新增外掛回呼。
進階後端掛鉤
CliBackendPlugin 也可定義：
| 掛鉤 | 用途 |
|---|---|
normalizeConfig(config, context) |
使用執行階段內容正規化已註冊的靜態轉接器 |
resolveExecutionArgs(ctx) |
新增要求範圍的旗標，例如思考強度或旁支問題隔離 |
prepareExecution(ctx) |
在啟動前建立暫時的驗證、設定或環境橋接 |
transformSystemPrompt(ctx) |
套用最終的 CLI 特定系統提示詞轉換 |
textTransforms |
雙向提示詞／輸出替換 |
defaultAuthProfileId |
優先使用特定的 OpenClaw 驗證設定檔 |
authEpochMode |
決定驗證變更使已儲存 CLI 工作階段失效的方式 |
nativeToolMode |
宣告原生工具是不存在、永遠開啟，或可由主機選擇 |
toolAvailabilityEnforcement |
宣告確切的工具上限是在 argv 或執行暫存階段中強制執行 |
sideQuestionToolMode |
宣告 /btw 旁支問題所停用的原生工具 |
bundleMcp / bundleMcpMode |
選擇啟用 OpenClaw 的迴送 MCP 工具橋接 |
ownsNativeCompaction |
後端自行管理壓縮 — OpenClaw 會延後處理 |
subscriptionAuthDispatch |
已選擇啟用、使用訂閱認證資訊的嵌入式執行會透過此後端執行 |
runtimeArtifact |
將指令碼啟動器限定於其完整的內建套件樹狀結構 |
這些掛鉤應由提供者負責。如果後端掛鉤可表達該行為， 請勿在核心中新增 CLI 特定分支。
prepareExecution(ctx) 會接收 ctx.contextTokenBudget，也就是為該次執行選定的有效權杖
限制。自行處理原生壓縮的後端，可將此
預算對應至其命令列介面專用的啟動合約。
runtimeArtifact 由外掛擁有。僅在即時推論回合
建立或重新驗證已確認的設定授權時才會查詢；
一般命令列介面執行不需要它。沒有此宣告的後端無法
建立已驗證的命令列介面設定授權。bundled-package-tree 宣告會指定
確切的 package.json 擁有者，並要求套件進入點必須是該
命令。OpenClaw 會對有界且完整的已安裝套件樹狀結構進行雜湊，包括
巢狀相依套件；若遇到重新導向的符號連結、
宣告套件外的啟動器、必要的外部相依性
宣告、過大的樹狀結構或未知指令碼，則會採取失敗關閉。僅當該
樹狀結構包含完整的推論實作時才宣告此項；選用的工具整合
不會讓外部實作圖變得安全。
如果同一後端也隨附獨立完備的原生可執行檔，請在
nativeExecutableNames 中列出其標準基底名稱。其他原生命令仍為
未驗證狀態。
一般回合的 ctx.executionMode 為 "agent"，暫時性
/btw 呼叫則為 "side-question"。當命令列介面需要不同的一次性旗標時使用它，
例如針對 BTW 停用原生工具、工作階段持久化或恢復行為。
如果後端通常具有 nativeToolMode: "always-on"，但其
附帶問題的 argv 能可靠地停用這些工具，也請設定
sideQuestionToolMode: "disabled"；否則，當 BTW
要求執行無工具的命令列介面時，OpenClaw 會採取失敗關閉。
僅當後端能針對單次執行停用所有
後端原生工具時，才設定 nativeToolMode: "selectable"。受限制的執行會收到標準
合約：ctx.toolAvailability.native 是確切的後端原生清單，而
ctx.toolAvailability.openClaw 是確切的 OpenClaw 工具名稱清單。
主機會獨立將產生的 MCP 設定與授權限制於該
OpenClaw 清單；外掛不得在核心中轉換此清單，也不得加入傳輸前綴。
請宣告後端如何強制執行該合約：
toolAvailabilityEnforcement: "execution-args"要求resolveExecutionArgs。此掛鉤必須取代互相衝突的工具旗標、停用 可能在所選工具範圍外執行的自訂介面，並 為全新與恢復的執行傳回可強制執行的 argv。toolAvailabilityEnforcement: "prepare-execution"要求prepareExecution。此掛鉤必須暫存精確的單次執行原則，並傳回toolAvailabilityEnforced: true；缺少確認時會採取失敗關閉，而且 OpenClaw 會在啟動前清理暫存的資源。
在建立此合約前，OpenClaw 會將排程 toolsAllow 等執行階段上限
正規化並展開群組。原生工具會停用，而
缺少完整已宣告強制執行路徑的後端會在執行前失敗。
針對 v2026.7.2-beta.1 至 v2026.7.2-beta.3 建置的外掛，仍可
讀取已淘汰的 ctx.toolAvailability.mcp 傳輸名稱投影；當可選取的後端實作
resolveExecutionArgs 時，也可省略 toolAvailabilityEnforcement。
OpenClaw 會根據外掛套件必要的 openclaw.build.openclawVersion 中繼資料
辨識這條已發布的 beta 路徑，並將其保留至
2026.8.x 系列。新的與更新後的外掛應使用標準
ctx.toolAvailability.openClaw 名稱，並明確宣告
toolAvailabilityEnforcement: "execution-args"；beta
相容路徑預定在該期限結束後移除。
ownsNativeCompaction：選擇不使用 OpenClaw 壓縮
如果你的後端執行的代理程式會壓縮其自身對話記錄，請設定
ownsNativeCompaction: true，使 OpenClaw 的防護摘要器永遠不會對
其工作階段執行；命令列介面的壓縮生命週期會直接略過，而
回合會繼續進行。claude-cli 會宣告此項，因為 Claude Code 會
在內部進行壓縮，且沒有控制框架端點。Codex 等原生控制框架工作階段
則會繼續路由至其控制框架壓縮端點。
僅在以下條件全部成立時才宣告此項，否則延後處理且 超出預算的工作階段可能持續超出預算或變成過期狀態（OpenClaw 將不再 挽救它）：
- 後端會在接近其 視窗上限時，可靠地壓縮或限制自己的對話記錄；
- 後端會持久保存可恢復的工作階段，使壓縮後的狀態能跨回合保留
（例如
--resume/--session-id）； - 它不是原生控制框架壓縮工作階段；符合
agentHarnessId的 工作階段會改為路由至控制框架端點。
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 能採取失敗關閉。如果它能針對每次執行停用所有原生工具，請搭配上述
resolveExecutionArgs 合約使用 "selectable"。
選取後端
使用者透過模型參照前綴選取獨立後端。宣告了標準
modelProvider 的後端，則可改為透過該
供應商模型的 agentRuntime.id 選取。轉接器機制仍保留在外掛中：
{ agents: { defaults: { model: { primary: "openai/gpt-5.6-sol", fallbacks: ["acme-cli/large"], }, }, },}請將認證資訊放在 OpenClaw 驗證設定檔或外掛擁有的設定中。請確保
已註冊的命令位於閘道服務的 PATH 中；需要不同
路徑或 argv 的部署應變更或包裝外掛註冊。
驗證
對於隨附的外掛，請為建構器與設定 註冊新增聚焦測試，然後執行該外掛的目標測試通道：
pnpm test extensions/acme-cli對於本機或已安裝的外掛，請驗證探索功能並執行一次真實模型：
openclaw plugins inspect acme-cli --runtime --jsonopenclaw agent --message "完全照以下內容回覆：後端正常" --model acme-cli/acme-large如果後端支援圖片或 MCP，請新增即時冒煙測試，以真實 命令列介面證明這些路徑可運作。請勿僅依賴靜態檢查來驗證提示詞、圖片、 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
後端模型前綴或模型範圍的 agentRuntime.id 會選取該註冊
OPENCLAW_DOCS_MARKER:calloutClose:
