Skip to main content
CLI 后端插件让 OpenClaw 能够将本地 AI CLI 作为文本推理 后端调用。该后端会在模型引用中显示为提供商前缀： 
acme-cli/acme-large
当上游集成已经以本地命令形式暴露、CLI 拥有本地登录状态，或 API 提供商不可用时作为回退方案，可以使用 CLI 后端。
如果上游服务暴露普通的 HTTP 模型 API，请改写 提供商插件。如果上游 运行时拥有完整的智能体会话、工具事件、压缩或后台 任务状态，请使用 agent harness。

​
插件拥有的内容

CLI 后端插件有三个合约：
合约文件用途
包入口package.json将 OpenClaw 指向插件运行时模块
清单所有权openclaw.plugin.json在运行时加载前声明后端 id
运行时注册index.ts使用命令默认值调用 api.registerCliBackend(...)
清单是设备发现元数据：它不会执行 CLI 或注册 运行时行为。运行时行为从插件入口调用 api.registerCliBackend(...) 时开始。

​
最小后端插件

1

Create package metadata

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

Declare backend ownership

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

Register the backend

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 应该如何启动和解析 CLI：
字段用途
command二进制名称或绝对命令路径
args全新运行的基础 argv
resumeArgs恢复会话的替代 argv；支持 {sessionId}
output / resumeOutput解析器：json、jsonl 或 text
jsonlDialectJSONL 事件方言：claude-stream-json 或 gemini-stream-json
liveSession长生命周期 CLI 进程模式（claude-stdio）
input提示传输：arg 或 stdin
maxPromptArgCharsarg 模式下回退到 stdin 前的最大提示长度
env / clearEnv要注入的额外环境变量，或启动前要剥离的名称
modelArg模型 id 前使用的标志
modelAliases将 OpenClaw 模型 id 映射到 CLI 原生 id
sessionArg / sessionArgs如何传递会话 id
sessionModealways、existing 或 none
sessionIdFieldsOpenClaw 从 CLI 输出读取的 JSON 字段
systemPromptArg / systemPromptFileArg系统提示传输
systemPromptFileConfigArg / systemPromptFileConfigKey系统提示文件的配置覆盖传输（例如 -c）
systemPromptModeappend 或 replace
systemPromptWhenfirst、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 --json
openclaw agent --message "reply exactly: backend ok" --model acme-cli/acme-large
如果后端支持图片或 MCP，请添加一个实时冒烟测试，用真实 CLI 证明这些路径。不要依赖静态检查来验证提示词、图片、 MCP 或会话恢复行为。

​
清单

package.json 有 openclaw.extensions，并且发布包有已构建的运行时条目
openclaw.plugin.json 声明 cliBackends 和有意设置的 activation.onStartup
当设置/模型发现需要在冷启动时看到该后端时，存在 setup.cliBackends
api.registerCliBackend(...) 使用与清单相同的后端 id
agents.defaults.cliBackends.<id> 下的用户覆盖仍然优先
会话、系统提示词、图片和输出解析器设置与真实 CLI 契约匹配
目标测试和至少一次实时 CLI 冒烟测试证明后端路径

​
相关