CLI 백엔드 Plugin 빌드하기

패키지 메타데이터 만들기

{
  "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라면 빌드된 JavaScript 피어를 가리키는 openclaw.runtimeExtensions를 추가하세요. 진입점을 참조하세요.

백엔드 소유권 선언하기

{
  "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는 런타임 소유권 목록입니다. config 또는 모델 선택에서 acme-cli/...가 언급될 때 OpenClaw가 Plugin을 자동 로드할 수 있게 합니다.

setup.cliBackends는 descriptor-first 설정 표면입니다. 모델 검색, 온보딩 또는 상태가 Plugin 런타임을 로드하지 않고 백엔드를 인식해야 할 때 추가하세요. 해당 정적 descriptor만으로 설정에 충분한 경우에만 requiresRuntime: false를 사용하세요.

백엔드 등록하기

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 아래의 사용자 config는 런타임에 그 위로 병합됩니다.