本页内容
本页内容
构建插件
构建 CLI 后端插件
CLI 后端插件让 OpenClaw 可以将本地 AI CLI 作为文本推理后端来调用。该后端会在模型引用中显示为一个提供方前缀:
当上游集成已公开为本地命令时、当 CLI 拥有本地登录状态时或当 API 提供程序不可用时作为后备时,请使用 CLI 后端。
插件负责什么
一个 CLI 后端插件有三个契约:
| 契约 | 文件 | 用途 |
|---|---|---|
| 包入口 | package.json |
指向 OpenClaw 的插件运行时模块 |
| 清单所有权 | openclaw.plugin.json |
在运行时加载之前声明后端 id |
| 运行时注册 | index.ts |
使用命令默认值调用 api.registerCliBackend(...) |
清单是发现元数据:它不会执行 CLI,也不会注册运行时行为。运行时行为从插件入口调用 api.registerCliBackend(...) 时开始。
最小后端插件
创建包元数据
已发布的包必须包含已构建的 JavaScript 运行时文件。如果你的源入口是 ./src/index.ts,请添加 openclaw.runtimeExtensions,指向构建后的 JavaScript 同级文件。参见 入口点。
声明后端所有权
cliBackends 是运行时所有权列表;当模型选择或 agentRuntime.id 提及 acme-cli 时,它会让 OpenClaw 自动加载该插件。
setup.cliBackends 是仅基于描述符的 setup 接口。若模型发现、引导流程或状态需要在不加载插件运行时的情况下识别该后端,请添加它。仅当这些静态描述符已足够用于 setup 时,才使用 requiresRuntime: false。
注册后台
后端 id 必须与清单中的 cliBackends 条目匹配。注册的适配器是权威的插件代码;OpenClaw 配置选择后端,但不会重写其命令契约。
将 modelProvider 设置为 CLI 执行其模型的规范模型提供者。它可以匹配后端 ID(如上所述)或单独的提供商 ID。省略它或提供空白值会在运行时或仅安装注册期间发出警告:直接 CLI 引用仍然有效,但不会创建提供程序到运行时的绑定。 OpenClaw 不会从 id 推断出该字段。
配置结构
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 |
arg 模式下在回退到 stdin 前允许的最大提示词长度 |
env / clearEnv |
要注入的额外环境变量,或启动前要移除的变量名称 |
modelArg |
模型 id 前使用的标志 |
modelAliases |
将 OpenClaw 模型 id 映射到 CLI-native id |
sessionArgs |
使用 {sessionId} 传递会话 id 的方式 |
sessionMode |
always、existing 或 none |
sessionIdFields |
JSON 字段 OpenClaw 从 CLI 输出读取 |
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。 terminal_reason 为 hook_stopped、stop_hook_prevented、aborted_tools、aborted_streaming、budget_exhausted 或 max_turns 的无应答 result 是记录的转弯停止:OpenClaw向用户报告该原因,并且不会在后备模型上重放回合,因为后端的工具操作可能已经运行。
省略 reliability.watchdog 以继承标准配置文件,包括 cron 的较长恢复运行预算和显式超时。仅当后端有意需要自己的看门狗策略时才设置它。
恢复重试保留在操作员配置的 timeoutMs 内:单调测量经过的时间,因此 NTP 校正或手动时钟更改既不能缩短仍有预算的重试,也不能让挂起的 CLI 超过其超时时间。
freshSessionRecovery 是后端拥有的兼容性合约:
- 将其保留为未定义或将其设置为
"replace-binding"以保留旧的清除和重新设定种子行为。 OpenClaw 清除持久绑定,并在故障符合恢复条件时使用新会话重试。 - 将其设置为
"invalidated-only"以抑制新的替换,除非共享失效检查证明旧会话已死亡。只有session_expired这样做。
从 CLI 或 SDK 会话合约中选择值,而不是从提供商 ID 或广泛错误类中选择。捆绑的Anthropic后端使用"invalidated-only";其本机会话合约不会将未过期失败视为对话无法再恢复的证据。
优先选择与 CLI 匹配的最小静态配置。仅为真正属于后端的行为添加插件回调。
高级后端钩子
CliBackendPlugin 还可以定义:
| 钩子 | 用途 |
|---|---|
normalizeConfig(config, context) |
使用运行时上下文规范化已注册的静态适配器 |
resolveExecutionArgs(ctx) |
添加请求范围的标志,例如思考强度或侧问题隔离 |
prepareExecution(ctx) |
在启动前创建临时身份验证、配置或环境桥接 |
transformSystemPrompt(ctx) |
应用最终的 CLI- 特定系统提示转换 |
textTransforms |
双向 prompt/output 替代品 |
defaultAuthProfileId |
优先使用特定的 OpenClaw 身份验证配置 |
authEpochMode |
决定身份验证变更如何使存储的 CLI 会话失效 |
nativeToolMode |
声明原生工具是不存在、始终启用,还是由宿主选择 |
toolAvailabilityEnforcement |
声明是在 argv 中还是在执行暂存阶段强制执行精确的工具上限 |
projectNativeToolAuthority |
将观察到的本机工具列表映射到 cron 上限的标准 OpenClaw 功能 |
sideQuestionToolMode |
为 /btw 侧问题声明禁用的原生工具 |
bundleMcp / bundleMcpMode |
选择加入 OpenClaw 的回环 MCP 工具桥接 |
ownsNativeCompaction |
后端拥有自己的自动压缩 - OpenClaw defers |
manualCompaction |
原子命令、传输和肯定确认合约 |
subscriptionAuthDispatch |
选择加入的、使用订阅凭据执行的嵌入式运行通过此后端执行 |
runtimeArtifact |
将脚本启动器绑定到其完整的捆绑包树 |
让这些钩子归提供商所有。当后端挂钩可以表达行为时,请勿将 CLI- 特定分支添加到核心。
prepareExecution(ctx) 接收 ctx.contextTokenBudget,即为运行选择的有效代币限制。拥有本机压缩的后端可以将该预算映射到其 CLI- 特定启动合约中。它还接收可选的有效 ctx.thinkingLevel:off、minimal、low、medium、high、xhigh、adaptive 或 max。当所选级别必须通过启动环境或分阶段配置应用时,请使用该字段;对于本机 CLI 标志,相同的字段可用于 resolveExecutionArgs(ctx)。
resolveExecutionArgs(ctx) 还接收可选的 ctx.fastMode,即此调用的有效布尔值。核心在 CLI 后解析自动模式并处理范围准入和后端准备,因此经过的等待计入其截止时间。显式打开和关闭保持不变。该字段遵循会话、代理和模型快速模式设置;后端可以将其映射到其本机参数或忽略它。生成的进程会保留调用的决定;它不接收原始 "auto"。
当后端拥有已安装的 CLI 协议或 SDK 集成时,prepareExecution(ctx) 也可能返回可选的 execute 传输。传输接收准确准备的命令、参数、可选的 argv0、环境、提示、会话和工具可用性;它产生后端现有的结构化流记录。构造 CLI 调用时,在 args 中保留准备好的命令 argv0 和解释器或脚本前缀。 argv0 保留 PATH 填充程序的调用名称。可选的 promptContext.prependContext 和 promptContext.appendContext 是私人提示构建添加和有界保存的会话注释,与普通的 prompt 分开。保存的注释是引用的参考数据,并且可能会在恢复轮次时重复;他们并不断言先前的原生转变消耗了他们。通过本机运行时的私有上下文机制传输它们;切勿将它们记录为操作员编写的输入。 OpenClaw 的策略和观察钩子仍然收到完整的逻辑提示。本机工具操作必须使用提供的运行绑定 requestToolPermission 回调,而不是创建独立的审批权限。 OpenClaw 保留取消、看门狗、会话策略,并且 MCP 授予所有权。配对节点执行和手动压缩继续通过现有的主机管理的进程路径。
可重用传输具有运行绑定 liveSession 功能。在创建初始或替换流程之前,请等待 liveSession.restart(),除非当前流程可重用。这加入了之前的进程退出及其主机拥有的资源清理;仅等待子进程退出是不够的。当调用者被撤销或必须保留确切的实时生成时,主机拒绝重新启动。 register() 保持同步准入检查,并在清理未解决时拒绝替换。
可以接受用户输入已在飞行中的转弯的运行时通过 ctx.registerMessageInjection 提供它。一旦回合准备好接受输入就调用它;然后,主机公开该运行的同转弯转向,而不是将消息作为单独的转弯进行排队。接收器应答 isAvailable() 进行准入,并仅在运行时确认消耗后才解析 queueMessage(text, withCurrent),而不仅仅是在写入 stdin 后。将同步本机写入传递给await withCurrent(submit):主机在调用它之前准备当前源和工具权限。重新检查 submit 内的本机可用性,因此在准备期间完成的回合在写入之前会被拒绝。当输入从未开始时拒绝,因此主机将其作为普通的排队回合重放,而不是丢失它;主机在会话记录中记录开始的输入,因此运行时不得将其写入其中。注册与运行一样长。
对于捆绑或官方插件的双向进程,请使用共享 createOwnedStdioProcess 所有者 以及准备好的命令、参数、argv0 和 exactEnv: true。在POSIX上,terminateOnHostLoss: true在主机丢失变成协议EOF之前停止进程树;显式 stdin 关闭仍然很优雅。这可以防止未应答的权限挂钩在网关被杀死后继续。在发布现场会话注册之前加入 closeOwnedStdioProcess。
runtimeArtifact 是插件拥有的。仅当实时推理生成或重新验证经过验证的设置权限时才会查阅它;正常的 CLI 运行不需要它。没有此声明的后端无法创建经过验证的 CLI 设置权限。 bundled-package-tree 声明指定了确切的 package.json 所有者,并要求包入口点是命令。 OpenClaw 对有界的完整安装包树(包括嵌套依赖项)进行哈希处理,并拒绝重定向符号链接、已声明包外部的启动器、所需的外部依赖项声明、超大树和未知脚本。仅当该树包含完整的推理实现时才声明这一点;可选的工具集成并不能使外部实现图安全。
在 Windows 上,受支持的 JavaScript 入口点通过从 PATH 中选择的经过验证的 Node 可执行文件运行。显式脚本路径不需要 PATHEXT 中的后缀;裸命令查找仍然遵循 PATH 和 PATHEXT。
如果同一后端还提供独立的本机可执行文件,请在 nativeExecutableNames 中列出其标准基本名称。其他本机命令仍未验证。
ctx.executionMode is "agent"对于正常转弯和"side-question"对于短暂的/btw来电。当CLI需要不同的一次性标志,例如禁用本机工具、会话持久性或恢复行为BTW。如果后端通常有nativeToolMode: "always-on"但它的附带问题 argv 可靠地禁用了这些工具,也设置了sideQuestionToolMode: "disabled";否则OpenClaw拒绝运行时BTW无需工具CLI跑步。
仅当后端可以禁用单个运行的每个后端本机工具时,才设置 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 流-JSON,输入是父回合的 system/init.tools 列表,当存在主机选择时与 toolAvailability.native 相交。托管本机设置可以在选择 CLI 参数后删除工具,因此永远不会推断默认值。每个回合都以待定权限开始:MCP 发现仍然可用,但工具调用明显拒绝,直到初始化提供列表。热转弯不能借用前一转弯的快照。仅返回核心词汇表中的标准名称(read、write、edit、apply_patch、exec、process、web_search、web_fetch),每个名称均源自主机通过本机工具强制执行的名称这份合同。核心在更新活动环回授权之前验证结果,并在最终的创建者上限捕获时再次验证结果;任何其他名字都失败。更新快照会使之前缓存的工具投影失效。仅项目等效功能:Claude 的 Glob 定位路径,NotebookEdit 编辑笔记本单元,因此两者都不授予通用 read 或 edit。本机列表包含工具名称,而不是权限规则模式。在 OpenClaw 显式请求 shell 并拒绝托管要求或禁用它的旧托管设置后,Codex 本机代码模式项目 read 和 exec。每次飞行前都会检查有效设置及其来源;对于本机模式,用户本地 shell 禁用被覆盖,而托管拒绝在捕获之前拒绝。它从不推断 write、edit、apply_patch 或 process。固定的 Codex 注册表没有禁用 shell 的模型;禁用其 shell 的自定义模型仍然是不可观察的异常,因为 Codex 不公开该模型功能。
以前保存的空自动化上限仍然受到限制。重新创建作业或从新的授权创建者轮流显式编辑其工具;不能安全地将旧的空帽与故意拒绝区分开来。
parseJsonlEvent:提供方特定的 JSONL 流
当后端输出的逐行 JSON 不符合内置的 Claude、Codex 或 Gemini 方言时,设置 parseJsonlEvent。该钩子接收一行原始内容以及解析后的后端 id 和配置,并返回一个规范化事件、多个事件,或返回 null 以让内置解析器尝试处理该行。
支持的事件包括增量助理文本、增量思维、本机工具 start/result 显示、会话 ID 和终端结果。终端结果可能包括最终文本、用法、错误和后继会话 ID。任一事件形状报告的会话 ID 参与恢复会话和分叉持久性。
生命周期事件有意与此返回联合分开,因此现有插件可以继续详尽地匹配它。请使用 parseJsonlLifecycleEvent 作为后端拥有的生命周期记录。
工具事件描述的是后端已经执行的工作。OpenClaw 会渲染并汇总这些事件,但不会将其视为宿主工具执行、可信诊断、回环关联或消息传递证据。
parseJsonlLifecycleEvent:提供者本机生命周期记录
当后端发出独立于助手文本、工具、会话和终端结果的生命周期状态的 JSONL 记录时,设置 parseJsonlLifecycleEvent。该钩子接收与 parseJsonlEvent 相同的行和上下文,并首先尝试。返回生命周期事件会消耗该行;返回 null 让源兼容的 parseJsonlEvent 挂钩或内置解析器处理它。
当前的生命周期合约支持本机压缩开始和结束记录。最终记录包括 completed,因此通道可以区分成功和不完整的压缩,而无需从后续消息推断结果。
ownsNativeCompaction:选择退出 OpenClaw 压缩
如果您的后端运行压缩其 own 转录本的代理,请设置 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 端点。
如果后端支持就地手动命令,请在所有权标志旁边声明它:
构建器接收可选的 /compact 指令。验证器接收有界的原始过程输出,并且必须要求后端拥有的肯定确认;单独的零出口并不能证明压缩。不要为创建单独会话或需要普通模型转向的命令声明此功能。
MCP 工具桥接
CLI 后端默认不会接收 OpenClaw 工具。如果 CLI 可以消费 MCP 配置,请显式启用:
支持的桥接模式:
| 模式 | 用途 |
|---|---|
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 前缀选择独立后端。可以通过该提供程序模型的 agentRuntime.id 选择声明标准 modelProvider 的后端。适配器机制保留在插件中:
将凭据放入 OpenClaw 身份验证配置文件或插件拥有的配置中。检查注册的命令是否在网关服务的PATH上;需要不同路径或 argv 的部署应更改或包装插件注册。
验证
对于打包插件,请围绕 builder 和 setup 注册添加一个有针对性的测试,然后运行该插件的目标测试任务:
对于本地或已安装的插件,验证发现能力并实际运行一次模型:
如果后端支持图像或 MCP,请添加一个实时冒烟测试,使用真实 CLI 证明这些路径可用。不要依赖静态检查来验证 prompt、图像、MCP 或会话恢复行为。
清单
当 setup/model 发现应该看到后端冷
时,