OpenClaw 플러그인: 코어를 포크하지 않고 에이전트 확장하기

에이전트 플랫폼을 망치는 가장 빠른 방법은 모든 커스텀 통합(custom integration) 기능을 코어(core)에 직접 집어넣는 것입니다. 처음 일주일 동안은 효율적으로 느껴질 것입니다. 하지만 첫 번째 고객이 프라이빗 도구를 요청하고, 두 번째 팀이 다른 모델 제공업체(model provider)를 원하며, 세 번째 워크플로우가 아무도 사용하지 않는 채널을 필요로 하게 되면 상황이 달라집니다. 갑자기 모든 업그레이드는 병합 충돌(merge conflict)이 되고, 모든 운영자 특화 아이디어는 플랫폼의 리스크가 됩니다.

OpenClaw의 플러그인 시스템은 그런 일이 발생하지 않도록 하기 위해 존재합니다. 플러그인은 SDK 등록 API를 통해 채널(channels), 모델 제공업체(model providers), 음성 제공업체(speech providers), 이미지 생성(image generation), 웹 검색(web search), 에이전트 도구(agent tools), 커스텀 명령(custom commands), 훅(hooks), HTTP 경로(HTTP routes), 게이트웨이 메서드(Gateway methods), CLI 서브커맨드(CLI subcommands), 서비스(services), 메모리 어댑터(memory adapters) 및 기타 런타임 동작을 추가할 수 있습니다. 핵심은 타입이 지정된 경계(typed boundary)입니다. OpenClaw는 이 경계를 중심으로 탐색, 검증, 테스트, 비활성화 및 업그레이드를 수행할 수 있습니다.

이것은 단순한 개발자 편의 기능이 아니라 수익 창출을 위한 기능입니다. 만약 에이전트가 구독 이벤트를 확인하거나, 지원 티켓을 분류하거나, 영업 통화를 요약하거나, 니치(niche)한 내부 시스템과 통신해야 한다면, 저는 매니페스트(manifest), 좁은 진입점(entry point), 테스트 표면(test surface), 그리고 깔끔한 삭제 경로를 가진 작은 패키지를 원합니다.

코드가 아닌 경계부터 시작하기

첫 번째 설계 질문은 간단합니다: 이 플러그인이 무엇을 소유해야 하는가? OpenClaw 문서는 기능 모델(capability model)을 명확하게 나누고 있습니다. 채널 플러그인은 메시징 플랫폼을 위한 계정 확인(account resolution), 설정(setup), 보안 정책(security policy), 페어링(pairing), 아웃바운드 전달(outbound delivery) 및 스레딩(threading)을 소유합니다. 코어는 여전히 공유된 message 도구, 프롬프트 와이어링(prompt wiring), 세션 장부 관리(session bookkeeping) 및 디스패치(dispatch)를 소유합니다. 제공업체(provider) 플러그인은 모델 인증(model auth), 카탈로그 확인(catalog resolution) 및 제공업체 런타임 동작을 소유합니다. 도구(tool) 또는 훅(hook) 플러그인은 전체 채널이나 모델 백엔드인 척하지 않고 더 작은 운영자 동작을 소유합니다.

그러한 경계는 에이전트의 건전성을 유지해 줍니다. 수익(revenue) 플러그인이 대시보드 지표를 얻기 위해 세션 저장소(session store)를 패치해서는 안 됩니다. 채널(channel) 플러그인은 코어(core)가 이미 공유 메시지 도구(message tool)를 통해 아웃바운드 메시징을 라우팅하고 있는데, 자체적인 중복 전송 도구를 만들어내서는 안 됩니다. 프로바이더(provider) 플러그인은 프로바이더 인증(auth)과 매니페스트(manifest) 메타데이터가 이미 존재함에도 불구하고 프롬프트(prompt)를 통해 비밀 정보를 몰래 전달해서는 안 됩니다. 좋은 플러그인 설계는 작업에 부합하는 가장 작은 기능(capability)을 선택하는 것에서 시작됩니다.

관련된 경계에 대해서는 MCP 가이드와 훅(hooks) 가이드를 읽어보세요. 플러그인은 네이티브 확장 경로이며, MCP는 런타임 통합(runtime integration)을 소유하지 않고 외부 도구를 사용하는 용도입니다.

모든 네이티브 플러그인에는 매니페스트가 필요합니다

네이티브 매니페스트는 openclaw.plugin.json이며, 문서는 이에 대해 단호하게 명시하고 있습니다: 모든 네이티브 OpenClaw 플러그인은 플러그인 루트에 반드시 이를 포함해야 합니다. OpenClaw는 플러그인 코드를 로드하기 전에 이 파일을 읽습니다. 매니페스트가 누락되거나 유효하지 않으면 플러그인 오류로 간주되며 구성 검증(config validation)이 차단됩니다.

매니페스트는 비용이 저렴하고 정적인 사실들을 위한 것입니다: 플러그인 식별(identity), 구성 검증(config validation), 인증(auth) 및 온보딩(onboarding) 메타데이터, UI 힌트, 정적 기능 소유권 스냅샷, 그리고 플러그인이 해당 인터페이스를 소유할 때의 channels, providers, cliBackends, skills, contracts와 같은 필드들이 이에 해당합니다. 런타임 동작(runtime behavior)은 플러그인 코드에 속합니다. 엔트리 파일(entry files)과 설치 메타데이터는 package.json에 속합니다.

지루해 보이는 configSchema는 선택 사항이 아닙니다. 구성(config)이 없는 플러그인이라 할지라도 JSON 스키마(JSON Schema)가 필요하며, 빈 엄격한 객체 스키마(empty strict object schema)도 허용됩니다. 스키마는 게이트웨이(Gateway)가 이미 고장 난 런타임을 로드하는 중간 단계에 도달하기 전, 구성의 읽기 및 쓰기 시점에 검증됩니다.

이것이 운영에서 중요한 이유

설정 검증 (Config validation)은 플러그인 규율이 빛을 발하는 지점입니다. 매니페스트 (manifest) 문서에 따르면, 채널 ID가 플러그인 매니페스트에 의해 선언되지 않은 한 알 수 없는 channels.* 키는 오류로 간주됩니다. plugins.entries.<id>, plugins.allow, plugins.deny, 그리고 plugins.slots.*는 반드시 탐색 가능한 플러그인 ID를 참조해야 합니다. 플러그인이 설치되었지만 매니페스트나 스키마 (schema)가 손상되었거나 누락된 경우, 검증이 실패하고 Doctor가 해당 플러그인 오류를 보고합니다. 만약 플러그인 설정이 존재하지만 플러그인이 비활성화된 상태라면, OpenClaw는 설정을 유지하면서 경고를 표시합니다.

이러한 동작은 운영자 (operators)에게 정확히 필요한 기능입니다. 런타임 (runtime)이 실수를 조용히 삼켜버렸는지 추측할 필요 없이, 플러그인을 제거하거나, 비활성화하거나, 인증 문제를 조사할 수 있습니다. 매니페스트는 OpenClaw에 "이 ID는 알 수 없습니다", "이 설정 형태는 잘못되었습니다", 또는 "이 비활성화된 플러그인에 여전히 설정이 남아 있습니다"라고 말할 수 있는 충분한 정보를 제공합니다.

만약 당신이 OpenClaw를 데모 봇이 아닌 실제 운영 도구로 만들고자 한다면, 확장 경계 (extension boundary)가 중요합니다. 전체 운영 가이드를 확인하려면 Get ClawKit을 이용하세요.

집중된 SDK 임포트 (SDK imports) 사용하기

SDK 개요에는 법처럼 지켜야 할 하나의 임포트 규칙이 있습니다. 바로 특정 openclaw/plugin-sdk/<subpath> 경로에서 임포트하는 것입니다. definePluginEntry를 위해서는 openclaw/plugin-sdk/plugin-entry를 사용하세요. defineChannelPluginEntry, defineSetupPluginEntry, 그리고 공유 채널 헬퍼 (helpers)를 위해서는 openclaw/plugin-sdk/core를 사용하세요. 런타임 (runtime), 프로바이더 (provider), 채널 (channel), 인증 (auth), 그리고 테스트 (testing) 서브패스 (subpaths)는 실제로 필요한 인터페이스에 대해서만 사용하십시오.

그 이유는 실무적입니다. 좁은 서브패스는 시작 속도를 빠르게 유지하고 순환 참조 (circular dependency) 문제를 방지하는 데 도움이 됩니다. 또한 문서는 프로덕션 코드에서 SDK 경로를 통해 자신의 플러그인을 임포트하는 것을 경고합니다. 플러그인 내부에서는 api.ts, runtime-api.ts, index.ts, setup-entry.ts와 같은 로컬 모듈을 사용하십시오. 저장소 내의 린트 (lint) 규칙은 거대한 루트 임포트 (monolithic root imports), 직접적인 src/ 임포트, 그리고 SDK 자기 참조 임포트 (SDK self-imports)를 거부합니다.

많은 수익 워크플로우에는 작은 도구 플러그인만으로도 충분합니다

모든 통합(integration)이 채널(channel)이나 프로바이더(provider)일 필요는 없습니다. 에이전트에게 타입이 지정된 액션(typed action)만 필요하다면 도구(tool)를 등록하세요. 문서는 도구를 LLM이 호출할 수 있는 타입이 지정된 함수(typed functions)로 설명합니다. 도구는 필수(required)이거나 { optional: true }를 통해 선택 사항(optional)으로 설정할 수 있습니다. 부수 효과(side effects)나 추가적인 바이너리 요구 사항이 있는 경우 선택적 도구를 사용하고, 운영자가 tools.allow를 통해 직접 참여(opt in)하도록 하세요.

이러한 도구는 여전히 지루할 정도로 엄격해야 합니다. 명확한 이름, 좁은 파라미터 스키마(parameter schema), 그리고 에이전트가 이해할 수 있는 결과 형식(result format)을 부여하세요. "빠른 내부 도구"가 마법 같은 백도어(backdoor)가 되도록 방치하지 마세요. 만약 도구가 메시지를 보내거나, 결제(billing)를 건드리거나, 데이터를 변경하거나, 외부 시스템을 호출한다면, 이를 선택 사항으로 만들고 운영자가 어떻게 활성화하는지 문서화하세요.

시작하기(getting-started) 문서에는 제가 좋아하는 두 가지 가드레일(guardrails)이 추가되어 있습니다. 첫째, 도구 이름은 코어 도구(core tools)와 충돌해서는 안 되며, 둘째, 사용자는 tools.allow에 플러그인 ID를 추가함으로써 플러그인의 모든 도구를 활성화할 수 있습니다. 이는 깔끔한 채택 경로(adoption path)를 제공합니다. 하나의 선택적 도구로 시작하여 테스트한 다음, 팀이 전체 번들(bundle)을 신뢰할 때 플러그인을 선택하도록 하세요.

채널에는 설정 경로(setup lane)가 필요합니다

채널 플러그인(Channel plugins)은 OpenClaw와 사람 사이의 경계에 위치하기 때문에 더 무겁습니다. 채널 가이드에 따르면 채널 플러그인은 설정(config), 보안(security), 페어링(pairing), 아웃바운드 메시징(outbound messaging), 그리고 스레딩(threading)을 담당합니다. 설정 문서에는 채널 플러그인을 위한 패키지 메타데이터가 나와 있습니다: openclaw.extensions, 선택 사항인 setupEntry, 그리고 id, label, blurb 및 선택 사항인 설정 메타데이터를 포함하는 openclaw.channel 블록입니다.

전체 채널 엔트리(channel entry)에는 defineChannelPluginEntry를 사용하고, 경량 설정 파일에는 defineSetupPluginEntry를 사용하세요. 엔트리포인트(entrypoint) 문서는 이 분리에 대해 설명합니다: defineChannelPluginEntry는 채널을 자동으로 등록하고 등록 모드(registration mode)에서 registerFull을 제어합니다. defineSetupPluginEntry는 런타임(runtime)이나 CLI 배선(wiring) 없이, 설정 전용 로딩을 위한 플러그인만을 반환합니다.

그러한 분리는 설정 흐름(setup flows)이 무거운 런타임 의존성(runtime dependencies)을 끌어들이는 것을 방지합니다. 설정 문서에 따르면, 채널이 비활성화되어 있지만 설정 인터페이스(setup surfaces)가 필요한 경우, 활성화되어 있지만 구성되지 않은 경우, 또는 지연 로딩(deferred loading)이 활성화된 경우에 이 경량 엔트리(lightweight entry)가 사용됩니다. 설정 엔트리(Setup entries)에는 채널 플러그인 객체와 필요한 스타트업 설정 인터페이스가 포함되어야 하며, 백그라운드 서비스, 무거운 SDK 임포트(imports), 또는 CLI 등록(registrations)은 포함해서는 안 됩니다.

등록 모드(registration mode) 준수

엔트리포인트(entrypoint) 문서에는 세 가지 등록 모드가 정의되어 있습니다: full, setup-only, 그리고 setup-runtime입니다. full은 스타트업 시 모든 것을 등록합니다. setup-only는 채널 설정 인터페이스를 등록합니다. setup-runtime은 설정과 경량 런타임을 함께 제공합니다. 만약 defineChannelPluginEntry를 사용한다면, 헬퍼(helper)가 이 분리 작업을 대신 처리해 줍니다. 만약 definePluginEntry 내부에서 채널을 직접 등록한다면, api.registrationMode를 직접 확인하고 모드가 full이 아닐 경우 무거운 런타임 등록을 수행하기 전에 반환(return)해야 합니다.

이 지점이 많은 자체 제작 확장 기능(homemade extensions)들이 불안정해지는 원인입니다. 개발자의 로컬 환경에서는 잘 작동하다가, 온보딩(onboarding) 과정에서 설정 경로가 거대한 클라이언트 라이브러리를 임포트하거나 토큰이 존재한다고 가정하기 때문에 실패하곤 합니다. 등록 모드를 준수하는 플러그인은 설정 상태를 표시하고, 비밀 정보(secrets)를 노출하지 않으면서 계정을 검사할 수 있으며, 무거운 런타임 코드가 필요하기 전에 Gateway가 깔끔하게 시작될 수 있도록 합니다.

호스트 내부 기능 대신 런타임 헬퍼(runtime helpers) 사용

런타임 헬퍼 문서에서는 api.runtime을 코어 헬퍼(core helpers)를 위한 주입된 인터페이스(injected interface)로 설명합니다. 플러그인은 해당 객체를 통해 에이전트 디렉토리 및 워크스페이스 경로를 확인하고, ID(identity) 기본값을 검사하며, 세션 스토어(session-store) 헬퍼를 사용하고, 관리되는 서브에이전트(subagents)를 실행하며, TTS를 호출하고, 미디어 이해(media understanding)를 사용하며, 기타 런타임 네임스페이스(namespaces)에 접근할 수 있습니다. 이 설계는 의도적인 것입니다: OpenClaw 내부의 프라이빗 임포트(private imports)를 사용하지 말고, 주입된 런타임을 사용하십시오.

그것은 플러그인을 이식 가능(portable)하게 유지해 줍니다. 만약 운영자(operator)가 ClawHub나 npm에서 귀하의 패키지를 설치한다면, 플러그인은 OpenClaw 저장소 내의 프라이빗 파일 경로(private file path)에 의존해서는 안 됩니다. 또한 문서에서는 플러그인이 실행하는 하위 에이전트(subagents)를 위한 모델 오버라이드(model overrides)를 사용하려면 플러그인 설정(plugin config)을 통해 운영자의 명시적인 옵트인(opt-in)이 필요하다고 명시하고 있습니다. 이것이 올바른 기본값입니다. 신뢰할 수 없는 플러그인은 작업을 요청할 수는 있지만, 임의의 모델 오버라이드를 조용히 선택해서는 안 됩니다.

프로바이더 플러그인은 런타임을 부팅하지 않고도 인증을 노출해야 합니다

프로바이더(Provider) 플러그인도 동일한 패턴을 따릅니다. 프로바이더 가이드에는 providers, providerAuthEnvVars, providerAuthChoices가 포함된 매니페스트(manifest)가 표시되어 있습니다. 이를 통해 OpenClaw는 프로바이더 런타임(provider runtime)이 로드되기 전에 자격 증명(credentials)을 감지하고 인증 선택지(auth choices)를 제시할 수 있습니다. 그런 다음 프로바이더 엔트리(provider entry)는 ID, 레이블(label), 문서 경로(docs path), 환경 변수(env vars), 인증 방법(auth methods), 그리고 카탈로그(catalog)를 사용하여 프로바이더를 등록합니다.

운영자에게 이는 모델 프로바이더(model providers)를 관리 가능하게 만들어 줍니다. 매니페스트는 어떤 환경 변수가 자격 증명의 존재를 증명하는지 명시할 수 있습니다. 런타임은 API 키를 사용할 수 있을 때만 카탈로그를 해결(resolve)할 수 있습니다. 사용자는 프로바이더가 설치 및 구성된 후에 acme-ai/acme-large와 같은 모델 참조(model refs)를 선택할 수 있습니다. 포크(fork), 프롬프트 수준의 비밀 정보 처리(prompt-level secret handling), 또는 정체불명의 로컬 패치(local patch)가 필요 없습니다.

해피 패스(happy path)뿐만 아니라 계약(contract)을 테스트하십시오

플러그인 테스트 문서는 타겟 해결(target resolution), 채널 피드백(channel feedback), 플러그인 API 모킹(API mocks), 런타임 계약(runtime contracts), 프로바이더 HTTP 모킹(HTTP mocks), 픽스처(fixtures) 등을 위한 집중적인 헬퍼(helpers)들을 설명합니다. 또한 채널 계정 해결(channel account resolution), 프로바이더 모델 해결(provider model resolution), 런타임 스토어 모킹(runtime-store mocking)을 위한 일반적인 Vitest 패턴도 보여줍니다. 번들형 플러그인(bundled plugins)의 경우, 계약 테스트(contract tests)를 통해 어떤 플러그인이 어떤 프로바이더를 등록하는지, 어떤 음성 프로바이더(speech providers)를 소유하는지, 등록 형태(registration shape)의 정확성, 그리고 런타임 준수 여부(runtime compliance)를 검증합니다.

OpenClaw 저장소 내부에서 빌드하고 있다면, 스코프 지정 플러그인 테스트(scoped plugin tests)와 pnpm check를 실행하세요. 외부에서 배포하는 경우라면, 저장소 전용 린트 규칙(lint rules)이 적용되지 않더라도 동일한 규율을 유지해야 합니다. 비밀 정보(secrets)를 실체화하지 않고 테스트 계정을 검사하세요. 테스트 대상의 해석 실패(target resolution failures)를 테스트하세요. 키가 있는 경우와 없는 경우의 프로바이더 카탈로그(provider catalogs)를 테스트하세요. 비활성화되었거나 구성되지 않은 설정 경로가 인터넷의 절반을 임포트(import)하지 않는지 테스트하세요.

패치(patch)가 아닌 패키지(package)로 배포하기

설정 문서에 따르면 외부 플러그인은 ClawHub 또는 npm에 배포할 수 있으며, 그 후 openclaw plugins install <package-name> 명령어로 설치할 수 있습니다. OpenClaw는 먼저 ClawHub를 시도하고, 실패할 경우 npm으로 전환(fallback)합니다. 또한 clawhub: 또는 npm:을 사용하여 소스를 강제할 수도 있습니다. 저장소 내부의 플러그인은 extensions/ 아래에 위치하며 빌드 중에 발견됩니다.

설치 시 주의해야 할 세부 사항이 하나 있습니다. npm 소스 설치의 경우, 설정 문서에 따르면 openclaw plugins install 실행 시 npm install --ignore-scripts가 실행됩니다. 네이티브 빌드 단계(native build steps)와 패키지 매니저 허용 목록(package-manager allowlists)을 문서화하지 않는 한, 의존성 트리(dependency trees)를 순수 JavaScript 또는 TypeScript로 유지하세요.

운영자 체크리스트