CLI 后端插件
CLI 后端插件可让 OpenClaw 调用本地 AI CLI 作为文本推理后端。该后端会以提供商前缀的形式出现在模型引用中:
当上游集成已经以本地命令形式暴露、CLI 自身管理本地登录状态,或 API 提供商不可用需要回退时,请使用 CLI 后端。
插件负责的内容¶
CLI 后端插件包含三项契约:
| 契约 | 文件 | 用途 |
|---|---|---|
| 包入口 | package.json |
将 OpenClaw 指向插件运行时模块 |
| 清单所有权 | openclaw.plugin.json |
在运行时加载前声明后端 id |
| 运行时注册 | index.ts |
使用默认命令调用 api.registerCliBackend(...) |
清单是发现元数据:它不会执行 CLI,也不会注册运行时行为。运行时行为从插件入口调用 api.registerCliBackend(...) 时开始。
最小后端插件¶
1. 创建包元数据
```json 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 对应文件。参见 [入口点](sdk-entrypoints.md)。
**2. 声明后端所有权**
```json 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 是运行时所有权列表;当模型选择或 agentRuntime.id 提到 acme-cli 时,它可让 OpenClaw 自动加载该插件。
setup.cliBackends 是描述符优先的设置界面。当模型发现、引导或状态需要在不加载插件运行时的情况下识别该后端时,请添加它。仅当这些静态描述符足以完成设置时,才使用 requiresRuntime: false。
3. 注册后端
```typescript index.ts import { definePluginEntry, type OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
function buildAcmeCliBackend(): Parameters
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 配置会选择后端,但不会重写其命令契约。
## 配置结构 {#config-shape}
`CliBackendConfig` 描述 OpenClaw 应如何启动并解析 CLI。上面的示例有意使用与内置 `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` | 回退到 stdin 之前 `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` | 选择启用压缩前的有界原始转录重播种,以实现安全的会话重置 |
| `freshSessionRecovery` | 可恢复的已恢复会话失败后的全新恢复策略 |
| `reliability.watchdog` | 无输出超时调优,针对全新运行与恢复运行分别设置 |
`claude-stream-json` 不仅仅是一种解析器选择:它声明后端的 `result` 记录承载 Claude Code 的终止语义,包括 `terminal_reason`。一个没有回复的 `result`,如果其 `terminal_reason` 为 `hook_stopped`、`stop_hook_prevented`、`aborted_tools`、`aborted_streaming`、`budget_exhausted` 或 `max_turns`,则是一个已记录的回合停止:OpenClaw 会向用户报告该原因,并且不会在回退模型上重放该回合,因为后端的工具操作可能已经执行。
省略 `reliability.watchdog` 以继承标准配置档,包括用于 cron 和显式超时的更长恢复运行预算。仅当后端有意需要自己的看门狗策略时再设置它。
恢复重试始终保持在操作员配置的 `timeoutMs` 之内:经过时间按单调方式测量,因此 NTP 校正或手动时钟更改既不会缩短仍有预算的重试,也不会让挂起的 CLI 存活超过其超时时间。
`freshSessionRecovery` 是由后端拥有的兼容性契约:
- 将其保留为未定义,或将其设置为 `"replace-binding"`,以保留传统的清除并重播种行为。当失败符合恢复条件时,OpenClaw 会清除已持久化的绑定,并使用全新会话重试。
- 将其设置为 `"invalidated-only"`,以抑制全新替换,除非规范的失效谓词证明旧会话已失效。只有 `session_expired` 会这样做。
请根据 CLI 或 SDK 会话契约选择值,而不是根据提供商 ID 或宽泛的错误类别。内置的 Anthropic 后端使用 `"invalidated-only"`;其原生会话契约不会将非过期失败视为对话无法再恢复的证据。
优先选择与 CLI 匹配的最小静态配置。仅为真正属于后端的行为添加插件回调。
## 高级后端钩子 {#advanced-backend-hooks}
`CliBackendPlugin` 还可以定义:
| 钩子 | 用途 |
| ---------------------------------- | --------------------------------------------------------------------------- |
| `normalizeConfig(config, context)` | 使用运行时上下文规范化已注册的静态适配器 |
| `resolveExecutionArgs(ctx)` | 添加请求作用域的标志,例如思考力度或侧边问题隔离 |
| `prepareExecution(ctx)` | 在启动前创建临时身份验证、配置或环境桥接 |
| `transformSystemPrompt(ctx)` | 应用最终的 CLI 特定系统提示词转换 |
| `textTransforms` | 双向提示词/输出替换 |
| `defaultAuthProfileId` | 优先使用特定的 OpenClaw 身份验证配置档 |
| `authEpochMode` | 决定身份验证更改如何使已存储的 CLI 会话失效 |
| 钩子 | 用途 |
| ---------------------------------- | ---------------------------------------------------------------------------- |
| `nativeToolMode` | 声明原生工具是缺失、始终开启,还是可由宿主选择 |
| `toolAvailabilityEnforcement` | 声明是否在 argv 或执行暂存中强制执行精确的工具上限 |
| `projectNativeToolAuthority` | 将观察到的原生工具列表映射为用于 cron 上限的规范能力 |
| `sideQuestionToolMode` | 声明 `/btw` 侧边问题禁用的原生工具 |
| `bundleMcp` / `bundleMcpMode` | 选择加入 OpenClaw 的环回 MCP 工具桥接 |
| `ownsNativeCompaction` | 后端拥有自己的自动压缩 - OpenClaw 延迟处理 |
| `manualCompaction` | 原子命令、传输和正向确认契约 |
| `subscriptionAuthDispatch` | 选择加入的嵌入式运行在订阅凭据上通过此后端执行 |
| `runtimeArtifact` | 将脚本启动器绑定到其完整的捆绑包树 |
保持这些钩子由提供方拥有。当后端钩子可以表达该行为时,不要向核心添加 CLI 特定分支。
`prepareExecution(ctx)` 接收 `ctx.contextTokenBudget`,即为本次运行选择的有效 Token 限制。拥有原生压缩的后端可以将该预算映射到其 CLI 特定的启动契约中。它还接收可选的有效 `ctx.thinkingLevel`:`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`adaptive` 或 `max`。当所选级别必须通过启动环境或暂存配置应用时,使用该字段;同一字段也可供 `resolveExecutionArgs(ctx)` 用于原生 CLI 标志。
`resolveExecutionArgs(ctx)` 还接收可选的 `ctx.fastMode`,即本次调用的有效布尔值。核心在 CLI 和进程范围准入以及后端准备之后解析自动模式,因此已耗时的等待会计入其截止时间。显式开启和关闭保持不变。该字段遵循会话、代理和模型的快速模式设置;后端可以将其映射到其原生参数或忽略它。派生的进程在本次调用中保持该决定;它不会接收原始 `"auto"`。
`prepareExecution(ctx)` 在后端拥有已安装 CLI 的协议或 SDK 集成时,也可以返回可选的 `execute` 传输。该传输接收精确的已准备命令、参数、可选 `argv0`、环境、Prompt、会话和工具可用性;它返回后端现有的结构化流记录。在构造 CLI 调用时,保留 `args` 中的已准备命令、`argv0` 以及解释器或脚本前缀。`argv0` 保留 PATH 垫片的调用名称。可选的 `promptContext.prependContext` 和 `promptContext.appendContext` 是私有 Prompt 构建附加项和有界的已保存会话笔记,与普通 `prompt` 分开。已保存笔记是引用参考数据,可能在恢复的轮次中重复;它们不断言原生轮次之前已消费它们。通过原生运行时的私有上下文机制传输它们;切勿将它们记录为操作员编写的输入。OpenClaw 的策略和观察钩子仍会接收完整逻辑 Prompt。原生工具操作必须使用提供的、运行绑定的 `requestToolPermission` 回调,而不是创建独立审批权限。OpenClaw 保留取消、看门狗、会话策略和 MCP 授权所有权。配对节点执行和手动压缩继续通过现有的宿主管理进程路径。
可复用传输接收运行绑定的 `liveSession` 能力。在创建初始进程或替换进程之前,除非当前进程可复用,否则等待 `liveSession.restart()`。这会合并前一个进程退出及其宿主拥有的资源清理;仅等待子进程退出是不够的。当调用方被撤销或必须保留精确的实时代际时,宿主拒绝重启。`register()` 仍然是同步准入检查,并在清理未解决时拒绝替换。
`runtimeArtifact` 由插件拥有。仅当实时推理轮次铸造或重新验证已验证的设置权限时才会查询它;正常 CLI 运行不需要它。没有此声明的后端无法铸造已验证的 CLI 设置权限。`bundled-package-tree` 声明指定确切的 `package.json` 所有者,并要求包入口点为命令。OpenClaw 对有限的完整已安装包树进行哈希,包括嵌套依赖,并且对于重定向符号链接、声明包之外的启动器、必需的外部依赖声明、过大的树和未知脚本采取失败关闭。仅当该树包含完整推理实现时才声明此项;可选工具集成不会使外部实现图安全。
在 Windows 上,受支持的 JavaScript 入口点通过从 `PATH` 选择的已验证 Node 可执行文件运行。显式脚本路径不需要其后缀在 `PATHEXT` 中;裸命令查找仍遵循 `PATH` 和 `PATHEXT`。
如果同一后端还附带自包含的原生可执行文件,请在 `nativeExecutableNames` 中列出其规范基本名称。其他原生命令保持未验证。
`ctx.executionMode` 对于正常轮次为 `"agent"`,对于临时 `/btw` 调用为 `"side-question"`。当 CLI 需要不同的一次性标志时,请使用它,例如为 BTW 禁用原生工具、会话持久性或恢复行为。如果后端通常具有 `nativeToolMode: "always-on"`,但其侧边问题 argv 可靠地禁用了这些工具,也请设置 `sideQuestionToolMode: "disabled"`;否则,当 BTW 需要无工具 CLI 运行时,OpenClaw 会失败关闭。
仅当后端可以为单个运行禁用所有后端原生工具时,才设置 `nativeToolMode: "selectable"`。受限运行接收规范契约:`ctx.toolAvailability.native` 是精确的后端原生列表,`ctx.toolAvailability.openClaw` 是精确的 OpenClaw 工具名称列表。宿主独立地将生成的 MCP 配置和授权限制为该 OpenClaw 列表;插件不得在核心中转换它或添加传输前缀。
声明后端如何强制实施该契约:
- `toolAvailabilityEnforcement: "execution-args"` 要求
`resolveExecutionArgs`。钩子必须替换冲突的工具标志,禁用可在所选工具之外执行的自定义界面,并
为全新运行和恢复运行返回强制 argv。
- `toolAvailabilityEnforcement: "prepare-execution"` 要求
`prepareExecution`。钩子必须暂存精确的每次运行策略,并返回
`toolAvailabilityEnforced: true`;缺少确认会失败关闭,并且
OpenClaw 会在启动前清理已暂存的资源。
运行时限制(例如 cron 的 `toolsAllow`)会在此契约构建前由
OpenClaw 规范化并展开组。原生工具会被禁用,且未声明完整强制路径的后端会在执行前失败。
如果后端的原生工具可被模型调用,它可以声明
`projectNativeToolAuthority(nativeTools)`,以便从其会话创建的自动化保留创建者的原生能力。对于 Claude stream-JSON,
输入是父回合的 `system/init.tools` 列表,并在存在宿主选择时与
`toolAvailability.native` 求交集。托管原生设置
可以在 CLI 参数选择后移除工具,因此从不推断默认值。
每个回合都以待处理权限开始:MCP 发现仍然可用,但
在初始化提供列表之前,工具调用会被明显拒绝。热回合
不能借用上一回合的快照。仅返回核心词汇表中的规范名称(`read`、`write`、`edit`、`apply_patch`、`exec`、`process`、
`web_search`、`web_fetch`),每个名称都派生自主机通过该契约强制执行的某个原生工具。Core 在更新活动
loopback 授权之前验证结果,并在最终创建者能力捕获时再次验证;任何其他名称都会导致该回合
失败。更新快照会使先前缓存的工具投影失效。
仅投影等效能力:Claude 的 `Glob` 用于定位路径,
`NotebookEdit` 用于编辑 notebook 单元格,因此二者都不授予通用的 `read` 或 `edit`。
原生列表包含工具名称,而不是权限规则模式。
Codex 原生代码模式在 OpenClaw 显式
请求 shell 并拒绝禁用它的托管要求或旧版托管设置后,投影 `read` 和 `exec`。每次预检都会检查有效设置及其来源;用户本地 shell 禁用会在原生模式下被覆盖,而
托管拒绝会在捕获前拒绝。它从不推断 `write`、`edit`、
`apply_patch` 或 `process`。固定的 Codex 注册表没有
禁用 shell 的模型;禁用其 shell 的自定义模型仍然是不可观察的例外,因为 Codex 不公开该模型能力。
先前保存的空自动化限制仍然受限。重新创建任务,或
从新的已授权创建者回合显式编辑其工具;旧的空限制无法安全地与有意拒绝区分开来。
### `parseJsonlEvent`:提供商特定的 JSONL 流 {#parsejsonevent-provider-specific-jsonl-streams}
当后端发出与内置 Claude、Codex 或 Gemini 方言不匹配的行分隔 JSON 时,设置 `parseJsonlEvent`。钩子接收一行原始
行以及已解析的后端 id 和配置,并返回一个规范化事件、
多个事件,或 `null` 以让内置解析器尝试该行。
支持的事件包括增量助手文本、增量思考、原生
工具开始/结果显示、会话 id 和终端结果。终端结果
可包含最终文本、用量、错误和后续会话 id。由任一事件形状报告的会话 id 都会参与恢复会话和 fork
持久化。
生命周期事件有意与此返回联合类型分开,以便现有插件可以继续穷举匹配它。请改用 `parseJsonlLifecycleEvent`
处理后端拥有的生命周期记录。
工具事件描述后端已经执行的工作。OpenClaw 会渲染并
总结它们,但不会将其视为主机工具执行、可信
诊断、loopback 关联或消息投递证据。
### `parseJsonlLifecycleEvent`:提供商原生生命周期记录 {#parsejsonllifecycleevent-provider-native-lifecycle-records}
当后端为独立于助手文本、工具、会话和终端结果的生命周期状态发出 JSONL 记录时,设置 `parseJsonlLifecycleEvent`。钩子接收与 `parseJsonlEvent` 相同的行和上下文,并优先尝试。返回生命周期事件会消费该行;返回 `null`
则让源兼容的 `parseJsonlEvent` 钩子或内置解析器处理它。
当前生命周期契约支持原生压缩开始和结束记录。
结束记录包含 `completed`,以便通道能够区分成功和不完整的压缩,而无需从后续消息推断结果。
### `ownsNativeCompaction`:选择退出 OpenClaw 压缩 {#ownsnativecompaction-opting-out-of-openclaw-compaction}
如果你的后端运行一个会压缩其**自身**转录的 agent,请设置
`ownsNativeCompaction: true`,以便 OpenClaw 的防护摘要器从不针对其会话运行——自动 CLI 压缩会委托给后端,回合继续。`claude-cli` 声明它,因为 Claude Code 内部压缩且没有 harness 端点。它还声明
`manualCompaction`,因此显式的 OpenClaw `/compact` 会恢复绑定的 Claude Code 会话并调用其原生 `/compact` 命令,而不记录对话回合。例如 Codex 这样的原生 harness 会话仍会路由到其 harness 压缩端点。
**仅当以下所有条件都成立时才声明它**,否则延迟的超预算会话可能保持超预算或过期(OpenClaw 不再救援它):
- 后端在其接近窗口时可靠地压缩或限制其自身转录;
- 它持久化可恢复会话,使压缩状态在回合间存活
(例如 `--resume` / `--session-id`);
- 它不是原生 harness 压缩会话——匹配 `agentHarnessId`
的会话会路由到 harness 端点。
如果后端支持就地手动命令,请连同所有权标志一起声明:
```typescript
manualCompaction: {
buildPrompt: (instructions) =>
instructions ? `/compact ${instructions}` : "/compact",
input: "arg",
validateOutput: (rawOutput) =>
rawOutput.includes('"type":"compaction_complete"')
? { ok: true }
: { ok: false, reason: "CLI did not confirm compaction." },
},
构建器会接收可选的 /compact 指令。验证器会接收有界的原始进程输出,并且必须要求后端提供的明确确认;仅有零退出码不能证明压缩已完成。不要为创建独立会话或需要普通模型轮次的命令声明此能力。
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 能够安全失败。如果它可以在每次运行时禁用所有原生工具,请使用 "selectable" 并遵循上述 resolveExecutionArgs 约定。
选择后端¶
用户通过其 model-ref 前缀选择独立后端。声明了规范 modelProvider 的后端,也可以改为通过该提供商模型的 agentRuntime.id 进行选择。适配器机制仍保留在插件中:
{
agents: {
defaults: {
model: {
primary: "openai/gpt-6-astra",
fallbacks: ["acme-cli/large"],
},
},
},
}
将凭据放在 OpenClaw 身份验证配置文件或插件拥有的配置中。确保已注册的命令位于网关服务的 PATH 中;需要不同路径或 argv 的部署应修改或包装插件注册。
验证¶
对于捆绑插件,请围绕 builder 和 setup 注册添加一个聚焦测试,然后运行该插件的目标测试通道:
对于本地或已安装的插件,请验证发现过程以及一次真实模型运行:
openclaw plugins inspect acme-cli --runtime --json
openclaw agent --message "reply exactly: backend ok" --model acme-cli/acme-large
如果后端支持图像或 MCP,请添加一次实时冒烟测试,使用真实 CLI 证明这些路径可用。不要依赖静态检查来验证 Prompt、图像、MCP 或会话恢复行为。
检查清单¶
Success
package.json 包含 openclaw.extensions,并且已发布包具有构建后的运行时条目
Success
openclaw.plugin.json 声明了 cliBackends 以及有意设置的 activation.onStartup
Success
当 setup/模型发现需要在冷启动时看到该后端时,setup.cliBackends 必须存在
Success
api.registerCliBackend(...) 使用的后端 id 与清单中的相同
Success
后端模型前缀或模型范围的 agentRuntime.id 会选择该注册
Success
会话、系统 Prompt、图像和输出解析器设置与真实 CLI 契约一致
Success
目标测试和至少一次实时 CLI 冒烟测试证明后端路径可用
相关¶
- CLI 后端 - 运行时选择和行为
- 构建插件 - 包和清单基础
- 插件 SDK 概览 - 注册 API 参考
- 插件清单 -
cliBackends和 setup 描述符 - Agent 测试框架 - 完整外部 Agent 运行时
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw