快速开始
构建 CLI 后端插件
CLI 后端插件让 OpenClaw 能够将本地 AI CLI 作为文本推理 后端调用。该后端会在模型引用中显示为提供商前缀：
acme-cli/acme-large当上游集成已经以本地命令形式暴露、CLI 拥有本地登录状态，或 API 提供商不可用时作为回退方案，可以使用 CLI 后端。
插件拥有的内容
CLI 后端插件有三个合约：
| 合约 | 文件 | 用途 |
|---|---|---|
| 包入口 | package.json |
将 OpenClaw 指向插件运行时模块 |
| 清单所有权 | openclaw.plugin.json |
在运行时加载前声明后端 id |
| 运行时注册 | index.ts |
使用命令默认值调用 api.registerCliBackend(...) |
清单是设备发现元数据：它不会执行 CLI 或注册
运行时行为。运行时行为从插件入口调用
api.registerCliBackend(...) 时开始。
最小后端插件
Create package metadata
{ "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 对等文件。参见 入口点。
Declare backend ownership
{ "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。
Register the backend
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 应该如何启动和解析 CLI：
| 字段 | 用途 |
|---|---|
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 模式下回退到 stdin 前的最大提示长度 |
env / clearEnv |
要注入的额外环境变量，或启动前要剥离的名称 |
modelArg |
模型 id 前使用的标志 |
modelAliases |
将 OpenClaw 模型 id 映射到 CLI 原生 id |
sessionArg / sessionArgs |
如何传递会话 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.outputLimits |
单个实时 CLI 轮次保留的最大原始 JSONL 字符数/行数（实时会话后端） |
reliability.watchdog |
无输出超时调优，区分全新运行和恢复运行 |
优先使用与 CLI 匹配的最小静态配置。只有在行为确实属于该后端时， 才添加插件回调。
高级后端钩子
CliBackendPlugin 还可以定义：
| 钩子 | 用途 |
|---|---|
normalizeConfig(config, context) |
合并后重写旧版用户配置 |
resolveExecutionArgs(ctx) |
添加请求范围的标志，例如思考强度或旁支问题隔离 |
prepareExecution(ctx) |
启动前创建临时认证或配置桥接 |
transformSystemPrompt(ctx) |
应用最终的 CLI 特定系统提示转换 |
textTransforms |
双向提示/输出替换 |
defaultAuthProfileId |
优先使用特定的 OpenClaw 认证配置文件 |
authEpochMode |
决定认证变更如何使已存储的 CLI 会话失效 |
nativeToolMode |
声明 CLI 是否有始终开启的原生工具 |
sideQuestionToolMode |
声明用于 /btw 旁支问题的已禁用原生工具 |
bundleMcp / bundleMcpMode |
选择启用 OpenClaw 的 loopback MCP 工具桥接 |
ownsNativeCompaction |
后端拥有自己的压缩 - OpenClaw 会延后处理 |
保持这些钩子由提供商拥有。当后端钩子可以表达行为时，不要向核心添加 CLI 特定分支。
ctx.executionMode 对普通轮次是 "agent"，对临时 /btw 调用是
"side-question"。当 CLI 需要不同的一次性标志时使用它，
例如为 BTW 禁用原生工具、会话持久化或恢复行为。如果某个后端通常有
nativeToolMode: "always-on"，但它的旁支问题 argv 能可靠地禁用这些工具，
也请设置 sideQuestionToolMode: "disabled"；否则当 BTW
需要无工具 CLI 运行时，OpenClaw 会失败关闭。
ownsNativeCompaction：选择退出 OpenClaw 压缩
如果你的后端运行的智能体会压缩它自己的转录，请设置
ownsNativeCompaction: true，这样 OpenClaw 的防护摘要器就绝不会针对
它的会话运行 - CLI 压缩生命周期会返回 no-op，并继续该
轮次。claude-cli 会声明它，因为 Claude Code 会在内部压缩，
且没有 harness 端点。Codex 等原生 harness 会话则会继续
路由到它们的 harness 压缩端点。
只有在以下所有条件都成立时才声明它，否则被延后的 超预算会话可能继续超预算或变陈旧（OpenClaw 不再 救援它）：
- 后端在接近其窗口时可靠地压缩或限制自己的 transcript；
- 它持久化可恢复的会话，使压缩后的状态能跨轮次保留
（例如
--resume/--session-id）； - 它不是原生 harness 压缩会话 - 匹配
agentHarnessId的会话会改为路由到 harness 端点。
MCP 工具桥接
CLI 后端默认不会接收 OpenClaw 工具。如果 CLI 可以消费 MCP 配置，请显式选择启用：
return { id: "acme-cli", bundleMcp: true, bundleMcpMode: "codex-config-overrides", config: { command: "acme", args: ["chat", "--json"], output: "json", },};支持的桥接模式：
| 模式 | 用途 |
|---|---|
claude-config-file |
接受 MCP 配置文件的 CLI |
codex-config-overrides |
接受 argv 上配置覆盖的 CLI |
gemini-system-settings |
从系统设置目录读取 MCP 设置的 CLI |
只有在 CLI 确实可以消费该桥接时才启用它。如果 CLI 有
无法禁用的内置工具层，请设置 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。
验证
对于内置插件，请围绕构建器和设置注册添加一个聚焦测试， 然后运行该插件的目标测试通道：
pnpm test extensions/acme-cli对于本地或已安装的插件，请验证发现和一次真实模型运行：
openclaw plugins inspect acme-cli --runtime --jsonopenclaw agent --message "reply exactly: 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:
