Plugin internals

기준일: 2026-07-26
공식 기준: Plugin internals

Plugin internals 문서는 OpenClaw 공식 문서(plugins/architecture)를 한국어로 정리한 가이드입니다. Plugin internals: capability model, ownership, contracts, load pipeline, and runtime helpers 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Plugin internals: capability model, ownership, contracts, load pipeline, and runtime helpers

한국어 가이드 범위: plugins/architecture 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• Public capability model
• External compatibility stance
• Plugin shapes
• Compatibility signals
• Architecture overview
• Plugin metadata snapshot and lookup table
• Activation planning
• Channel plugins and the shared message tool
• Capability ownership model
• Capability layering
• Multi-capability company plugin example
• Capability example: video understanding
• Contracts and enforcement
• What belongs in a contract
• Execution model
• Export boundary
• Internals and reference
• 관련 문서

상세 내용

본문

This is the deep architecture reference for the OpenClaw plugin system. For practical guides, start with one of the focused pages below.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Public capability model

Capabilities are the public native plugin model inside OpenClaw. Every native OpenClaw plugin registers against one or more capability types:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Capability	Registration method	Example plugins
Text inference	api.registerProvider(...)	anthropic, openai
CLI inference backend	api.registerCliBackend(...)	anthropic, openai
Embeddings	api.registerEmbeddingProvider(...)	Provider-owned vector plugins
Speech	api.registerSpeechProvider(...)	elevenlabs, microsoft
Realtime transcription	api.registerRealtimeTranscriptionProvider(...)	openai
Realtime voice	api.registerRealtimeVoiceProvider(...)	google, openai
Media understanding	api.registerMediaUnderstandingProvider(...)	google, openai
Transcripts source	api.registerTranscriptSourceProvider(...)	discord, google-meet, teams-meetings, zoom-meetings
Image generation	api.registerImageGenerationProvider(...)	fal, google, openai
Music generation	api.registerMusicGenerationProvider(...)	fal, google, minimax
Video generation	api.registerVideoGenerationProvider(...)	fal, google, qwen
Web fetch	api.registerWebFetchProvider(...)	firecrawl
Web search	api.registerWebSearchProvider(...)	brave, firecrawl, google
Channel / messaging	api.registerChannel(...)	matrix, msteams
Gateway discovery	api.registerGatewayDiscoveryService(...)	bonjour

External compatibility stance

The capability model is landed in core and used by bundled/native plugins today, but external plugin compatibility still needs a tighter bar than "it is exported, therefore it is frozen."

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Plugin situation	Guidance
Existing external plugins	Keep hook-based integrations working; this is the compatibility baseline.
New bundled/native plugins	Prefer explicit capability registration over vendor-specific reach-ins or new hook-only designs.
External plugins adopting capability registration	Allowed, but treat capability-specific helper surfaces as evolving unless docs mark them stable.

Plugin shapes

OpenClaw classifies every loaded plugin into a shape based on its actual registration behavior (not just static metadata):

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Compatibility signals

openclaw doctor, openclaw plugins inspect , openclaw status --all, and openclaw plugins doctor surface these compatibility notices:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Signal	Meaning
config valid	Config parses fine and plugins resolve
hook-only (info)	Plugin registers only hooks; a supported path, but not migrated to capability registration yet
deprecated memory-embedding API (warn)	Non-bundled plugin uses the old memory-specific embedding provider API instead of registerEmbeddingProvider
hard error	Config is invalid or plugin failed to load

Architecture overview

OpenClaw's plugin system has four layers:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• parse-time metadata comes from registerCli(..., { descriptors: [...] })
• the real plugin CLI module can stay lazy and register on first invocation
• manifest/config validation should work from manifest/schema metadata without executing plugin code
• native capability discovery may load trusted plugin entry code to build a non-activating registry snapshot
• native runtime behavior comes from the plugin module's register(api) path with api.registrationMode === "full"

Plugin metadata snapshot and lookup table

Gateway startup builds one PluginMetadataSnapshot for the current config snapshot. The snapshot is metadata-only: it stores the installed plugin index, manifest registry, manifest diagnostics, owner maps, a plugin id normalizer, and manifest records. It does not hold loaded plugin modules, provider SDKs, package contents, or runtime exports.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• channel ownership
• deferred channel startup
• startup plugin ids
• provider and CLI backend ownership
• setup provider, command alias, model catalog provider, and manifest contract ownership
• plugin config schema and channel config schema validation
• startup auto-enable decisions

Activation planning

Activation planning is part of the control plane. Callers can ask which plugins are relevant to a concrete command, provider, channel, route, agent harness, or capability before loading broader runtime registries.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• activation.* fields are explicit planner hints
• providers, channels, commandAliases, setup.providers, contracts.tools, and hooks remain manifest ownership fallback
• the ids-only planner API stays available for existing callers
• the plan API reports reason labels so diagnostics can distinguish explicit hints from ownership fallback

Channel plugins and the shared message tool

Channel plugins do not need to register a separate send/edit/react tool for normal chat actions. OpenClaw keeps one shared message tool in core, and channel plugins own the channel-specific discovery and execution behind it.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• core owns the shared message tool host, prompt wiring, session/thread bookkeeping, and execution dispatch
• channel plugins own scoped action discovery, capability discovery, and any channel-specific schema fragments
• channel plugins own provider-specific session conversation grammar, such as how conversation ids encode thread ids or inherit from parent conversations
• channel plugins execute the final action through their action adapter
• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• trusted inbound requesterSenderId
• outbound.sendPoll is the shared baseline for channels that fit the common poll model
• actions.handleAction("poll") is the preferred path for channel-specific poll semantics or extra poll parameters

Capability ownership model

OpenClaw treats a native plugin as the ownership boundary for a company or a feature, not as a grab bag of unrelated integrations.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• a company plugin should usually own all of that company's OpenClaw-facing surfaces
• a feature plugin should usually own the full feature surface it introduces
• channels should consume shared core capabilities instead of re-implementing provider behavior ad hoc
• a vendor's OpenClaw-facing surface lives in one plugin even if it spans text models, speech, images, and video
• other vendors can do the same for their own surface area
• channels do not care which vendor plugin owns the provider; they consume the shared capability contract exposed by core
• plugin = ownership boundary
• capability = core contract that multiple plugins can implement or consume

Capability layering

Use this mental model when deciding where code belongs:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• core owns reply-time TTS policy, fallback order, prefs, and channel delivery
• elevenlabs, google, microsoft, and openai own synthesis implementations
• voice-call consumes the telephony TTS runtime helper

Multi-capability company plugin example

A company plugin should feel cohesive from the outside. If OpenClaw has shared contracts for models, speech, realtime transcription, realtime voice, media understanding, image generation, video generation, web fetch, and web search, a vendor can own all of its surfaces in one place:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• one plugin owns the vendor surface
• core still owns the capability contracts
• provider request translation and HTTP helpers stay in the vendor plugin
• channels and feature plugins consume api.runtime.* helpers, not vendor code
• contract tests can assert that the plugin registered the capabilities it claims to own

id: "exampleai",
  name: "ExampleAI",
  description: "ExampleAI models and media capabilities.",
  register(api) {
    api.registerProvider({
      id: "exampleai",
      // auth/model catalog/runtime hooks
    });

    api.registerSpeechProvider({
      id: "exampleai",
      // vendor speech config — implement the SpeechProviderPlugin interface directly
    });

    api.registerMediaUnderstandingProvider({
      id: "exampleai",
      capabilities: ["image", "audio", "video"],
      describeImage: (req) => exampleAiMedia.describeImage(req),
      transcribeAudio: (req) => exampleAiMedia.transcribeAudio(req),
      describeVideo: (req) => exampleAiMedia.describeVideo(req),
    });

    api.registerWebSearchProvider({
      id: "exampleai-search",
      createTool() {
        // Return the vendor-owned web search tool.
      },
    });
  },
});

Capability example: video understanding

OpenClaw already treats image/audio/video understanding as one shared capability. The same ownership model applies there:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Contracts and enforcement

The plugin API surface is intentionally typed and centralized in OpenClawPluginApi. That contract defines the supported registration points and the runtime helpers a plugin may rely on.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• plugin authors get one stable internal standard
• core can reject duplicate ownership such as two plugins registering the same provider id
• startup can surface actionable diagnostics for malformed registration
• contract tests can enforce bundled-plugin ownership and prevent silent drift

What belongs in a contract

When in doubt, raise the abstraction level: define the capability first, then let plugins plug into it.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• typed
• small
• capability-specific
• owned by core
• reusable by multiple plugins
• consumable by channels/features without vendor knowledge
• vendor-specific policy hidden in core
• one-off plugin escape hatches that bypass the registry
• channel code reaching straight into a vendor implementation
• ad hoc runtime objects that are not part of OpenClawPluginApi or api.runtime

Execution model

Native OpenClaw plugins run in-process with the Gateway. They are not sandboxed. A loaded native plugin has the same process-level trust boundary as core code.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Export boundary

OpenClaw exports capabilities, not implementation convenience.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• bundled-plugin-specific helper subpaths
• runtime plumbing subpaths not intended as public API
• vendor-specific convenience helpers
• setup/onboarding helpers that are implementation details

Internals and reference

For the load pipeline, registry model, provider runtime hooks, Gateway HTTP routes, message tool schemas, channel target resolution, provider catalogs, context engine plugins, and the guide to adding a new capability, see Plugin architecture internals.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

관련 문서

주요 항목:

• Building plugins
• Plugin manifest
• Plugin SDK setup

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/plugins/architecture
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

id: "exampleai",
  name: "ExampleAI",
  description: "ExampleAI models and media capabilities.",
  register(api) {
    api.registerProvider({
      id: "exampleai",
      // auth/model catalog/runtime hooks
    });

    api.registerSpeechProvider({
      id: "exampleai",
      // vendor speech config — implement the SpeechProviderPlugin interface directly
    });

    api.registerMediaUnderstandingProvider({
      id: "exampleai",
      capabilities: ["image", "audio", "video"],
      describeImage: (req) => exampleAiMedia.describeImage(req),
      transcribeAudio: (req) => exampleAiMedia.transcribeAudio(req),
      describeVideo: (req) => exampleAiMedia.describeVideo(req),
    });

    api.registerWebSearchProvider({
      id: "exampleai-search",
      createTool() {
        // Return the vendor-owned web search tool.
      },
    });
  },
});

관련 링크

• 공식 원문: plugins/architecture
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.