Adding capabilities (contributor guide)

기준일: 2026-07-26
공식 기준: Adding capabilities (contributor guide)

Adding capabilities (contributor guide) 문서는 OpenClaw 공식 문서(plugins/adding-capabilities)를 한국어로 정리한 가이드입니다. Contributor guide for adding a new shared capability to the OpenClaw plugin system 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Contributor guide for adding a new shared capability to the OpenClaw plugin system

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

문서 구성

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

• When to create a capability
• The standard sequence
• What goes where
• Provider and harness seams
• File checklist
• Worked example: image generation
• Embedding providers
• Review checklist
• 관련 문서

상세 내용

본문

This is a contributor guide for OpenClaw core developers. If you are building an external plugin, see Building plugins instead. For the deep architecture reference (capability model, ownership, load pipeline, runtime helpers), see Plugin internals.

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

주요 항목:

• plugin = ownership boundary
• capability = shared core contract

When to create a capability

Create a new capability only when all of these are true:

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

The standard sequence

1. Define the typed core contract. 2. Add plugin registration for that contract. 3. Add a shared runtime helper. 4. Wire one real vendor plugin as proof. 5. Move feature/channel consumers onto the runtime helper. 6. Add contract tests. 7. Document the operator-facing config and ownership model.

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

What goes where

Layer	Owns
Core	Request/response types; provider registry and resolution; fallback behavior; config schema with propagated title/description docs metadata on nested object, wildcard, array-item, and composition nodes; runtime helper surface.
Vendor plugin	Vendor API calls, vendor auth handling, vendor-specific request normalization, and registration of the capability implementation.
Feature/channel plugin	Calls api.runtime.* or the matching plugin-sdk/*-runtime helper. Never calls a vendor implementation directly.

Provider and harness seams

Use provider hooks when the behavior belongs to the model provider contract rather than the generic agent loop. Examples include provider-specific request params after transport selection, auth-profile preference, prompt overlays, and follow-up fallback routing after model/profile failover.

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

주요 항목:

• Core owns the retry/fallback policy.
• Provider plugins own provider-specific request/auth/routing hints.
• Harness plugins own runtime-specific attempt classification.
• Third-party plugins return hints, not direct mutations of core state.

File checklist

For a new capability, expect to touch these areas:

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

주요 항목:

• src/<capability>/types.ts
• src/<capability>/...registry/runtime.ts
• src/plugins/types.ts
• src/plugins/registry.ts
• src/plugins/captured-registration.ts
• src/plugins/contracts/registry.ts
• src/plugins/runtime/types-core.ts
• src/plugins/runtime/index.ts
• src/plugin-sdk/<capability>.ts
• src/plugin-sdk/<capability>-runtime.ts
• One or more bundled plugin packages.
• Config, docs, tests.

Worked example: image generation

Image generation follows the standard shape:

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

주요 항목:

• agents.defaults.imageModel analyzes images.
• agents.defaults.mediaModels.image generates images.

Embedding providers

Use registerEmbeddingProvider(...) / contract embeddingProviders for reusable vector embedding providers. This contract is intentionally broader than memory: tools, search, retrieval, importers, or future feature plugins can consume embeddings without depending on the memory engine. Memory search also consumes generic embeddingProviders.

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

Review checklist

Before shipping a new capability, verify:

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

주요 항목:

• No channel/tool imports vendor code directly.
• The runtime helper is the shared path.
• At least one contract test asserts bundled ownership.
• Config docs name the new model/config key.
• Plugin docs explain the ownership boundary.

관련 문서

주요 항목:

• Plugin internals — capability model, ownership, load pipeline, runtime helpers.
• Building plugins — first-plugin tutorial.
• SDK overview — import map and registration API reference.
• Creating skills — companion contributor surface.

실습 체크리스트

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

관련 링크

• 공식 원문: plugins/adding-capabilities
• OpenClaw 문서 홈

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