Plugin SDK CLI 后端插件

概述

CLI 后端插件让 OpenClaw 将本地 AI CLI 作为文本推理后端调用。后端以 Provider 前缀形式出现在模型引用中，如 acme-cli/acme-large。

适用场景： 上游集成已作为本地命令暴露、CLI 拥有本地登录状态、或 CLI 是 API Provider 不可用时的有用回退。

不适用场景： 上游服务暴露普通 HTTP 模型 API 时用 Provider 插件；上游运行时拥有完整 Agent 会话时用 Agent Harness。

核心 API

注册 CLI 后端

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";
 
api.registerCliBackend(buildAcmeCliBackend());

CliBackendConfig 关键字段

字段	用途
command	二进制名称或绝对命令路径
args	新运行的基础 argv
resumeArgs	恢复会话的备用 argv（支持 {sessionId}）
output / resumeOutput	解析器：json、jsonl 或 text
input	提示传输：arg 或 stdin
modelArg	模型 ID 前的标志
modelAliases	将 OpenClaw 模型 ID 映射到 CLI 原生 ID
sessionArg / sessionMode	会话 ID 传递方式（always/existing/none）
sessionIdFields	OpenClaw 从 CLI 输出读取的 JSON 字段
systemPromptFileArg	系统提示文件传输
imageArg / imageMode	图像路径支持
serialize	保持同后端运行有序
reliability.watchdog	无输出超时调整

高级后端钩子

钩子	用途
normalizeConfig(config, context)	合并后重写旧版用户配置
resolveExecutionArgs(ctx)	添加请求作用域标志（如思考努力）
prepareExecution(ctx)	启动前创建临时认证或配置桥接
transformSystemPrompt(ctx)	应用最终 CLI 特定系统提示转换
textTransforms	双向提示/输出替换
bundleMcp / bundleMcpMode	选择加入 OpenClaw 的回环 MCP 工具桥接

MCP 工具桥接模式

模式	用途
claude-config-file	接受 MCP 配置文件的 CLI
codex-config-overrides	接受 argv 配置覆盖的 CLI
gemini-system-settings	从系统设置目录读取 MCP 设置的 CLI

清单声明

{
  "id": "acme-cli",
  "cliBackends": ["acme-cli"],
  "setup": { "cliBackends": ["acme-cli"], "requiresRuntime": false },
  "activation": { "onStartup": false }
}

使用示例

function buildAcmeCliBackend(): CliBackendPlugin {
  return {
    id: "acme-cli",
    liveTest: { defaultModelRef: "acme-cli/acme-large", defaultImageProbe: false },
    config: {
      command: "acme",
      args: ["chat", "--json"],
      output: "json",
      input: "stdin",
      modelArg: "--model",
      sessionArg: "--session",
      sessionMode: "existing",
      sessionIdFields: ["session_id"],
      systemPromptFileArg: "--system-file",
      systemPromptWhen: "first",
      reliability: { watchdog: { fresh: { ...CLI_FRESH_WATCHDOG_DEFAULTS } } },
      serialize: true,
    },
  };
}

用户配置覆盖

{
  agents: {
    defaults: {
      cliBackends: {
        "acme-cli": {
          command: "/opt/acme/bin/acme",
          modelAliases: { large: "acme-large-2026" },
        },
      },
    },
  },
}

相关页面

• concepts/plugin-sdk-overview — 注册 API 参考
• concepts/plugin-sdk-agent-harness — 完整外部 Agent 运行时
• concepts/plugin-manifest — cliBackends 和 setup 描述符
• concepts/plugin-building — 包和清单基础