Plugin SDK 개요

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Import 규칙

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";

​

Subpath 참조

​

Registration API

​

Capability 등록

​

Tool 및 command

​

Infrastructure

​

Workflow Plugin용 host hook

• api.session.state.registerSessionExtension(...)
• api.session.workflow.enqueueNextTurnInjection(...)
• api.session.workflow.registerSessionSchedulerJob(...)
• api.session.workflow.sendSessionAttachment(...)
• api.session.workflow.scheduleSessionTurn(...)
• api.session.workflow.unscheduleSessionTurnsByTag(...)
• api.session.controls.registerSessionAction(...)
• api.session.controls.registerControlUiDescriptor(...)
• api.agent.events.registerAgentEventSubscription(...)
• api.agent.events.emitAgentEvent(...)
• api.runContext.setRunContext(...) / getRunContext(...) / clearRunContext(...)
• api.lifecycle.registerRuntimeLifecycle(...)

• 외부 Plugin은 세션 확장, UI 설명자, 명령, 도구 메타데이터, 다음 턴 주입, 일반 훅을 소유할 수 있습니다.
• 신뢰할 수 있는 도구 정책은 일반 before_tool_call 훅보다 먼저 실행되며, 호스트 안전 정책에 참여하므로 번들 전용입니다.
• 예약된 명령 소유권은 번들 전용입니다. 외부 Plugin은 자체 명령 이름이나 별칭을 사용해야 합니다.
• allowPromptInjection=false는 agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, 레거시 before_agent_start의 프롬프트 필드, enqueueNextTurnInjection을 포함한 프롬프트 변경 훅을 비활성화합니다.

​

Gateway 디스커버리 등록

api.registerGatewayDiscoveryService({
  id: "my-discovery",
  async advertise(ctx) {
    const handle = await startMyAdvertiser({
      gatewayPort: ctx.gatewayPort,
      tls: ctx.gatewayTlsEnabled,
      displayName: ctx.machineDisplayName,
    });
    return { stop: () => handle.stop() };
  },
});

​

CLI 등록 메타데이터

• commands: 등록자가 소유한 명시적 명령 이름
• descriptors: CLI 도움말, 라우팅, 지연 Plugin CLI 등록에 사용되는 파싱 시점 명령 설명자
• parentPath: ["nodes"] 같은 중첩 명령 그룹의 선택적 부모 명령 경로

api.registerCli(
  async ({ program }) => {
    const { registerMatrixCli } = await import("./src/cli.js");
    registerMatrixCli({ program });
  },
  {
    descriptors: [
      {
        name: "matrix",
        description: "Manage Matrix accounts, verification, devices, and profile state",
        hasSubcommands: true,
      },
    ],
  },
);

api.registerCli(
  async ({ program }) => {
    const { registerNodesCanvasCommands } = await import("./src/cli.js");
    registerNodesCanvasCommands(program);
  },
  {
    parentPath: ["nodes"],
    descriptors: [
      {
        name: "canvas",
        description: "Capture or render canvas content from a paired node",
        hasSubcommands: true,
      },
    ],
  },
);

​

CLI 백엔드 등록

• 백엔드 id는 codex-cli/gpt-5 같은 모델 참조에서 제공자 접두사가 됩니다.
• 백엔드 config는 agents.defaults.cliBackends.<id>와 같은 형태를 사용합니다.
• 사용자 구성이 여전히 우선합니다. OpenClaw는 CLI를 실행하기 전에 agents.defaults.cliBackends.<id>를 Plugin 기본값 위에 병합합니다.
• 백엔드가 병합 후 호환성 재작성(예: 이전 플래그 형태 정규화)을 필요로 할 때는 normalizeConfig를 사용하세요.
• OpenClaw 사고 수준을 네이티브 effort 플래그에 매핑하는 것처럼 CLI 방언에 속한 요청 범위 argv 재작성에는 resolveExecutionArgs를 사용하세요.

​

배타적 슬롯

​

메모리 임베딩 어댑터

• registerMemoryCapability는 권장되는 배타적 메모리 Plugin API입니다.
• registerMemoryCapability는 컴패니언 Plugin이 특정 메모리 Plugin의 비공개 레이아웃에 접근하는 대신 openclaw/plugin-sdk/memory-host-core를 통해 내보낸 메모리 아티팩트를 소비할 수 있도록 publicArtifacts.listArtifacts(...)도 노출할 수 있습니다.
• registerMemoryPromptSection, registerMemoryFlushPlan, registerMemoryRuntime은 레거시 호환 배타적 메모리 Plugin API입니다.
• MemoryFlushPlan.model은 활성 폴백 체인을 상속하지 않고 플러시 턴을 ollama/qwen3:8b 같은 정확한 provider/model 참조에 고정할 수 있습니다.
• registerMemoryEmbeddingProvider를 사용하면 활성 메모리 Plugin이 하나 이상의 임베딩 어댑터 ID(예: openai, gemini 또는 사용자 지정 Plugin 정의 ID)를 등록할 수 있습니다.
• agents.defaults.memorySearch.provider와 agents.defaults.memorySearch.fallback 같은 사용자 구성은 등록된 해당 어댑터 ID에 대해 해석됩니다.

​

이벤트 및 수명 주기

​

훅 결정 의미론

• before_tool_call: { block: true } 반환은 종료 조건입니다. 어떤 핸들러든 이를 설정하면 더 낮은 우선순위의 핸들러는 건너뜁니다.
• before_tool_call: { block: false } 반환은 재정의가 아니라 결정 없음(block 생략과 동일)으로 처리됩니다.
• before_install: { block: true } 반환은 종료 조건입니다. 어떤 핸들러든 이를 설정하면 더 낮은 우선순위의 핸들러는 건너뜁니다.
• before_install: { block: false } 반환은 재정의가 아니라 결정 없음(block 생략과 동일)으로 처리됩니다.
• reply_dispatch: { handled: true, ... } 반환은 종료 조건입니다. 어떤 핸들러든 디스패치를 처리했다고 선언하면 더 낮은 우선순위의 핸들러와 기본 모델 디스패치 경로는 건너뜁니다.
• message_sending: { cancel: true } 반환은 종료 조건입니다. 어떤 핸들러든 이를 설정하면 더 낮은 우선순위의 핸들러는 건너뜁니다.
• message_sending: { cancel: false } 반환은 재정의가 아니라 결정 없음(cancel 생략과 동일)으로 처리됩니다.
• message_received: 인바운드 스레드/토픽 라우팅이 필요할 때는 타입 지정 threadId 필드를 사용하세요. 채널별 추가 정보에는 metadata를 유지하세요.
• message_sending: 채널별 metadata로 폴백하기 전에 타입 지정 replyToId / threadId 라우팅 필드를 사용하세요.
• gateway_start: 내부 gateway:startup 훅에 의존하는 대신 Gateway 소유 시작 상태에는 ctx.config, ctx.workspaceDir, ctx.getCron?.()을 사용하세요.
• cron_changed: Gateway 소유 Cron 수명 주기 변경을 관찰합니다. 외부 깨우기 스케줄러를 동기화할 때는 event.job?.state?.nextRunAtMs와 ctx.getCron?.()을 사용하고, 만료 확인과 실행의 진실 공급원은 OpenClaw로 유지하세요.

​

API 객체 필드

​

내부 모듈 규칙

my-plugin/
  api.ts            # Public exports for external consumers
  runtime-api.ts    # Internal-only runtime exports
  index.ts          # Plugin entry point
  setup-entry.ts    # Lightweight setup-only entry (optional)

• Anthropic: Claude 베타 헤더 및 service_tier 스트림 헬퍼를 위한 공개 api.ts / contract-api.ts 이음매.
• @openclaw/openai-provider: api.ts는 Provider 빌더, 기본 모델 헬퍼, 실시간 Provider 빌더를 내보냅니다.
• @openclaw/openrouter-provider: api.ts는 온보딩/구성 헬퍼와 함께 Provider 빌더를 내보냅니다.

​

관련 항목