Plugin

Manage Gateway Plugin, 훅 팩 및 호환 번들을 관리합니다.

명령

openclaw plugins listopenclaw plugins list --enabledopenclaw plugins list --verboseopenclaw plugins list --jsonopenclaw plugins search <query>openclaw plugins search <query> --limit 20openclaw plugins search <query> --jsonopenclaw plugins install <path-or-spec>openclaw plugins inspect <id>openclaw plugins inspect <id> --runtimeopenclaw plugins inspect <id> --jsonopenclaw plugins inspect --allopenclaw plugins info <id>openclaw plugins enable <id>openclaw plugins disable <id>openclaw plugins registryopenclaw plugins registry --refreshopenclaw plugins uninstall <id>openclaw plugins doctoropenclaw plugins update <id-or-npm-spec>openclaw plugins update --allopenclaw plugins marketplace entriesopenclaw plugins marketplace entries --offlineopenclaw plugins marketplace entries --jsonopenclaw plugins marketplace list <marketplace>openclaw plugins marketplace list <marketplace> --jsonopenclaw plugins marketplace refreshopenclaw plugins marketplace refresh --feed-profile clawhub-public --jsonopenclaw plugins marketplace refresh --feed-url https://clawhub.ai/v1/feeds/plugins --expected-sha256 <sha256>openclaw plugins init my-tool --name "My Tool"openclaw plugins init my-provider --name "My Provider" --type provideropenclaw plugins init my-provider --name "My Provider" --type provider --directory ./my-provideropenclaw plugins build --entry ./dist/index.jsopenclaw plugins build --entry ./dist/index.js --checkopenclaw plugins validate --entry ./dist/index.js

느린 설치, 검사, 제거 또는 레지스트리 새로 고침을 조사하려면 OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1로 명령을 실행하세요. 추적은 단계별 시간을 stderr에 기록하고 JSON 출력을 파싱 가능하게 유지합니다. 디버깅을 참조하세요.

작성

openclaw plugins init stock-quotes --name "Stock Quotes"cd stock-quotesnpm run plugin:buildnpm run plugin:validate

plugins init은 기본적으로 최소 TypeScript 도구 Plugin을 생성합니다. 첫 번째 인수는 Plugin ID입니다. 표시 이름에는 --name을 전달하세요. OpenClaw는 기본 출력 디렉터리와 패키지 이름 지정에 ID를 사용합니다. 도구 스캐폴드는 defineToolPlugin을 사용합니다. plugins build는 빌드된 엔트리를 가져오고, 정적 도구 메타데이터를 읽고, openclaw.plugin.json을 작성하며, package.json의 openclaw.extensions를 일치된 상태로 유지합니다. plugins validate는 생성된 매니페스트, 패키지 메타데이터 및 현재 엔트리 내보내기가 여전히 일치하는지 확인합니다. 전체 도구 작성 워크플로는 도구 Plugin을 참조하세요.

스캐폴드는 TypeScript 소스를 작성하지만 빌드된 ./dist/index.js 엔트리에서 메타데이터를 생성하므로 게시된 CLI에서도 워크플로가 작동합니다. 엔트리가 기본 패키지 엔트리가 아닌 경우 --entry <path>를 사용하세요. 생성된 메타데이터가 파일을 다시 쓰지 않고 오래된 경우 CI에서 실패하도록 plugins build --check를 사용하세요.

제공자 스캐폴드

openclaw plugins init acme-models --name "Acme Models" --type providercd acme-modelsnpm installnpm run buildnpm testnpm run validate

제공자 스캐폴드는 OpenAI 호환 API 키 연결, clawhub package validate를 위한 내장 npm run validate 스크립트, ClawHub 패키지 메타데이터, GitHub Actions OIDC를 통한 향후 신뢰할 수 있는 게시를 위해 수동으로 디스패치되는 GitHub 워크플로를 갖춘 일반 텍스트/모델 제공자 Plugin을 생성합니다. 제공자 스캐폴드는 skills를 생성하지 않으며 openclaw plugins build 또는 openclaw plugins validate를 사용하지 않습니다. 이러한 명령은 도구 스캐폴드의 생성된 메타데이터 경로용입니다.

게시하기 전에 자리 표시자 API 기본 URL, 모델 카탈로그, 문서 경로, 자격 증명 텍스트 및 README 문구를 실제 제공자 세부 정보로 교체하세요. 최초 ClawHub 게시와 신뢰할 수 있는 게시자 설정에는 생성된 README를 사용하세요.

설치

openclaw plugins search "calendar"                   # search ClawHub pluginsopenclaw plugins install <package>                      # source auto-detectionopenclaw plugins install clawhub:<package>              # ClawHub onlyopenclaw plugins install npm:<package>                  # npm onlyopenclaw plugins install npm-pack:<path.tgz>            # local npm pack through npm install semanticsopenclaw plugins install git:github.com/<owner>/<repo>  # git repoopenclaw plugins install git:github.com/<owner>/<repo>@<ref>openclaw plugins install <package> --force              # overwrite existing installopenclaw plugins install <package> --pin                # pin versionopenclaw plugins install clawhub:<package> --acknowledge-clawhub-riskopenclaw plugins install <package> --dangerously-force-unsafe-installopenclaw plugins install <path>                         # local pathopenclaw plugins install <plugin>@<marketplace>         # marketplaceopenclaw plugins install <plugin> --marketplace <name>  # marketplace (explicit)openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>

관리자가 설정 시점 설치를 테스트할 때는 보호된 환경 변수로 자동 Plugin 설치 소스를 재정의할 수 있습니다. Plugin 설치 재정의를 참조하세요.

plugins search는 설치 가능한 Plugin 패키지를 ClawHub에서 쿼리하고 설치 준비가 된 패키지 이름을 출력합니다. skills가 아니라 코드 Plugin 및 번들 Plugin 패키지를 검색합니다. ClawHub skills에는 openclaw skills search를 사용하세요.

ClawHub 설치는 명시적 clawhub:<package> locator를 사용합니다.

openclaw plugins install clawhub:openclaw-codex-app-serveropenclaw plugins install clawhub:openclaw-codex-app-server@1.2.3

베어 npm 안전 Plugin 사양은 공식 Plugin id와 일치하지 않는 한 출시 전환 기간에는 기본적으로 npm에서 설치됩니다.

openclaw plugins install openclaw-codex-app-server

npm 전용 해석을 명시하려면 npm:을 사용하세요.

openclaw plugins install npm:openclaw-codex-app-serveropenclaw plugins install npm:@openclaw/discord@2026.5.20openclaw plugins install npm:@scope/plugin-name@1.0.1

OpenClaw는 설치 전에 광고된 Plugin API / 최소 gateway 호환성을 확인합니다. 선택한 ClawHub 버전이 ClawPack 아티팩트를 게시하면 OpenClaw는 버전 지정된 npm-pack .tgz를 다운로드하고 ClawHub digest 헤더와 아티팩트 digest를 검증한 다음 일반 아카이브 경로를 통해 설치합니다. ClawPack 메타데이터가 없는 이전 ClawHub 버전은 여전히 레거시 패키지 아카이브 검증 경로를 통해 설치됩니다. 기록된 설치는 이후 업데이트를 위해 ClawHub 소스 메타데이터, 아티팩트 종류, npm integrity, npm shasum, tarball 이름, ClawPack digest 사실을 보존합니다. 버전이 지정되지 않은 ClawHub 설치는 버전 없는 기록 사양을 유지하므로 openclaw plugins update가 더 새로운 ClawHub 릴리스를 따라갈 수 있습니다. clawhub:pkg@1.2.3 및 clawhub:pkg@beta 같은 명시적 버전 또는 태그 선택자는 해당 선택자에 고정된 상태로 유지됩니다.

마켓플레이스 축약형

마켓플레이스 이름이 ~/.claude/plugins/known_marketplaces.json의 Claude 로컬 레지스트리 캐시에 있으면 plugin@marketplace 축약형을 사용하세요.

openclaw plugins marketplace list <marketplace-name>openclaw plugins install <plugin-name>@<marketplace-name>

마켓플레이스 소스를 명시적으로 전달하려면 --marketplace를 사용하세요.

openclaw plugins install <plugin-name> --marketplace <marketplace-name>openclaw plugins install <plugin-name> --marketplace <owner/repo>openclaw plugins install <plugin-name> --marketplace https://github.com/<owner>/<repo>openclaw plugins install <plugin-name> --marketplace ./my-marketplace

로컬 경로와 아카이브의 경우 OpenClaw는 다음을 자동 감지합니다.

• 네이티브 OpenClaw Plugin(openclaw.plugin.json)
• Codex 호환 번들(.codex-plugin/plugin.json)
• Claude 호환 번들(.claude-plugin/plugin.json 또는 기본 Claude 컴포넌트 레이아웃)
• Cursor 호환 번들(.cursor-plugin/plugin.json)

관리되는 로컬 설치는 Plugin 디렉터리 또는 아카이브여야 합니다. 독립형 .js, .mjs, .cjs, .ts Plugin 파일은 plugins install로 관리되는 Plugin 루트에 복사되지 않습니다. 대신 plugins.load.paths에 명시적으로 나열하세요.

목록

openclaw plugins listopenclaw plugins list --enabledopenclaw plugins list --verboseopenclaw plugins list --jsonopenclaw plugins search <query>openclaw plugins search <query> --limit 20openclaw plugins search <query> --json

시작 로그에 plugins.allow is empty; discovered non-bundled plugins may auto-load: ...가 표시되면, openclaw plugins list --enabled --verbose를 실행하거나 나열된 Plugin id로 openclaw plugins inspect <id>를 실행해 Plugin id를 확인하고 신뢰하는 id를 openclaw.json의 plugins.allow에 복사하세요. 경고가 감지된 모든 Plugin을 나열할 수 있으면, 해당 id가 이미 포함된 붙여넣기 가능한 plugins.allow 스니펫을 출력합니다. Plugin이 설치/로드 경로 출처 없이 로드되면 해당 Plugin id를 검사한 다음, 신뢰하는 id를 plugins.allow에 고정하거나 신뢰할 수 있는 소스에서 Plugin을 다시 설치하여 OpenClaw가 설치 출처를 기록하도록 하세요.

plugins search는 원격 ClawHub 카탈로그 조회입니다. 로컬 상태를 검사하거나, config를 변경하거나, 패키지를 설치하거나, Plugin 런타임 코드를 로드하지 않습니다. 검색 결과에는 ClawHub 패키지 이름, family, channel, version, summary 및 openclaw plugins install clawhub:<package> 같은 설치 힌트가 포함됩니다.

패키징된 Docker 이미지 내부에서 번들 Plugin 작업을 할 때는 /app/extensions/synology-chat 같은 일치하는 패키징 소스 경로 위에 Plugin 소스 디렉터리를 bind-mount하세요. OpenClaw는 /app/dist/extensions/synology-chat보다 먼저 해당 마운트된 소스 오버레이를 감지합니다. 단순히 복사된 소스 디렉터리는 비활성 상태로 남으므로 일반 패키징 설치는 계속 컴파일된 dist를 사용합니다.

런타임 hook 디버깅의 경우:

• openclaw plugins inspect <id> --runtime --json은 모듈 로드 검사 패스에서 등록된 hook과 진단을 표시합니다. 런타임 검사는 의존성을 설치하지 않습니다. 레거시 의존성 상태를 정리하거나 config에서 참조하는 누락된 다운로드 가능 Plugin을 복구하려면 openclaw doctor --fix를 사용하세요.
• openclaw gateway status --deep --require-rpc는 도달 가능한 Gateway URL/profile, service/process 힌트, config 경로, RPC 상태를 확인합니다.
• 비번들 대화 hook(llm_input, llm_output, before_model_resolve, before_agent_reply, before_agent_run, before_agent_finalize, agent_end)에는 plugins.entries.<id>.hooks.allowConversationAccess=true가 필요합니다.

로컬 Plugin 디렉터리 복사를 피하려면 --link를 사용하세요(plugins.load.paths에 추가됨).

openclaw plugins install -l ./my-plugin

독립형 Plugin 파일은 plugins install로 설치하거나 ~/.openclaw/extensions 또는 <workspace>/.openclaw/extensions에 직접 배치하는 대신 plugins.load.paths에 나열해야 합니다. 이러한 자동 감지 루트는 Plugin 패키지 또는 번들 디렉터리를 로드하며, 최상위 스크립트 파일은 로컬 헬퍼로 처리되어 건너뜁니다.

Plugin 인덱스

Plugin 설치 메타데이터는 사용자가 설정하는 구성이 아니라 머신이 관리하는 상태입니다. 설치와 업데이트는 활성 OpenClaw 상태 디렉터리 아래의 공유 SQLite 상태 데이터베이스에 이를 기록합니다. installed_plugin_index 행은 손상되었거나 누락된 Plugin 매니페스트의 레코드를 포함한 지속성 있는 installRecords 메타데이터와, openclaw plugins update, 제거, 진단, 콜드 Plugin 레지스트리에서 사용하는 매니페스트 파생 콜드 레지스트리 캐시를 저장합니다.

OpenClaw가 구성에서 배포된 레거시 plugins.installs 레코드를 발견하면, 런타임 읽기는 openclaw.json을 다시 쓰지 않고 이를 호환성 입력으로 처리합니다. 명시적 Plugin 쓰기와 openclaw doctor --fix는 구성 쓰기가 허용될 때 이러한 레코드를 Plugin 인덱스로 옮기고 구성 키를 제거합니다. 둘 중 하나의 쓰기가 실패하면 설치 메타데이터가 손실되지 않도록 구성 레코드를 유지합니다.

제거

openclaw plugins uninstall <id>openclaw plugins uninstall <id> --dry-runopenclaw plugins uninstall <id> --keep-files

uninstall은 해당되는 경우 plugins.entries, 지속 저장된 Plugin 인덱스, Plugin 허용/거부 목록 항목, 링크된 plugins.load.paths 항목에서 Plugin 레코드를 제거합니다. --keep-files가 설정되지 않은 한, 제거는 추적 중인 관리 설치 디렉터리가 OpenClaw의 Plugin 확장 루트 안에 있을 때 해당 디렉터리도 제거합니다. Active Memory Plugin의 경우 메모리 슬롯이 memory-core로 재설정됩니다.

업데이트

openclaw plugins update <id-or-npm-spec>openclaw plugins update --allopenclaw plugins update <id-or-npm-spec> --dry-runopenclaw plugins update @openclaw/voice-callopenclaw plugins update openclaw-codex-app-server --acknowledge-clawhub-riskopenclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install

업데이트는 관리되는 Plugin 인덱스에서 추적 중인 Plugin 설치와 hooks.internal.installs에서 추적 중인 훅 팩 설치에 적용됩니다.

검사

openclaw plugins inspect <id>openclaw plugins inspect <id> --runtimeopenclaw plugins inspect <id> --json

Inspect는 기본적으로 Plugin 런타임을 가져오지 않고 식별자, 로드 상태, 소스, 매니페스트 기능, 정책 플래그, 진단, 설치 메타데이터, 번들 기능, 감지된 MCP 또는 LSP 서버 지원을 표시합니다. JSON 출력에는 contracts.agentToolResultMiddleware 및 contracts.trustedToolPolicies 같은 Plugin 매니페스트 계약이 포함되므로, 운영자는 Plugin을 활성화하거나 다시 시작하기 전에 신뢰 표면 선언을 감사할 수 있습니다. --runtime을 추가하면 Plugin 모듈을 로드하고 등록된 훅, 도구, 명령, 서비스, Gateway 메서드, HTTP 라우트를 포함합니다. 런타임 검사는 누락된 Plugin 의존성을 직접 보고합니다. 설치와 복구는 openclaw plugins install, openclaw plugins update, openclaw doctor --fix에 남아 있습니다.

Plugin 소유 CLI 명령은 보통 루트 openclaw 명령 그룹으로 설치되지만, Plugin은 openclaw nodes 같은 코어 부모 아래에 중첩 명령을 등록할 수도 있습니다. inspect --runtime이 cliCommands 아래에 명령을 표시한 후에는 나열된 경로에서 실행하세요. 예를 들어 demo-git를 등록하는 Plugin은 openclaw demo-git ping으로 검증할 수 있습니다.

각 Plugin은 런타임에 실제로 등록하는 항목에 따라 분류됩니다.

• plain-capability — 하나의 기능 유형(예: provider 전용 Plugin)
• hybrid-capability — 여러 기능 유형(예: 텍스트 + 음성 + 이미지)
• hook-only — 훅만 있고 기능이나 표면 없음
• non-capability — 도구/명령/서비스는 있지만 기능 없음

기능 모델에 대한 자세한 내용은 Plugin 형태를 참조하세요.

Doctor

openclaw plugins doctor

doctor는 Plugin 로드 오류, 매니페스트/검색 진단, 호환성 알림, 누락된 Plugin 슬롯 같은 오래된 Plugin 구성 참조를 보고합니다. 설치 트리와 Plugin 구성이 깨끗하면 No plugin issues detected.를 출력합니다. 오래된 구성이 남아 있지만 설치 트리가 그 외에는 정상인 경우, 요약은 전체 Plugin 상태가 정상이라고 암시하는 대신 그 사실을 표시합니다.

구성된 Plugin이 디스크에 존재하지만 로더의 경로 안전 검사에 의해 차단된 경우, 구성 검증은 Plugin 항목을 유지하고 이를 present but blocked로 보고합니다. plugins.entries.<id> 또는 plugins.allow 구성을 제거하는 대신, 경로 소유권이나 전역 쓰기 가능 권한 같은 앞선 차단 Plugin 진단을 수정하세요.

register/activate 내보내기 누락 같은 모듈 형태 실패의 경우, 진단 출력에 간결한 내보내기 형태 요약을 포함하려면 OPENCLAW_PLUGIN_LOAD_DEBUG=1로 다시 실행하세요.

레지스트리

openclaw plugins registryopenclaw plugins registry --refreshopenclaw plugins registry --json

로컬 Plugin 레지스트리는 설치된 Plugin 식별자, 활성화 상태, 소스 메타데이터, 기여 소유권에 대한 OpenClaw의 지속 저장된 콜드 읽기 모델입니다. 일반 시작, provider 소유자 조회, 채널 설정 분류, Plugin 인벤토리는 Plugin 런타임 모듈을 가져오지 않고 이를 읽을 수 있습니다.

plugins registry를 사용하여 지속 저장된 레지스트리가 존재하는지, 최신인지, 오래되었는지 검사하세요. --refresh를 사용하면 지속 저장된 Plugin 인덱스, 구성 정책, 매니페스트/패키지 메타데이터에서 이를 다시 빌드합니다. 이는 런타임 활성화 경로가 아니라 복구 경로입니다.

openclaw doctor --fix는 레지스트리와 인접한 관리 npm 드리프트도 복구합니다. 관리되는 Plugin npm 프로젝트 또는 레거시 플랫 관리 npm 루트 아래의 고아 또는 복구된 @openclaw/* 패키지가 번들 Plugin을 가리는 경우, doctor는 해당 오래된 패키지를 제거하고 레지스트리를 다시 빌드하여 시작 시 번들 매니페스트를 기준으로 검증되도록 합니다. 또한 doctor는 호스트 openclaw 패키지를 peerDependencies.openclaw를 선언하는 관리 npm Plugin에 다시 링크하므로, 업데이트나 npm 복구 후 openclaw/plugin-sdk/* 같은 패키지 로컬 런타임 가져오기가 확인됩니다.

마켓플레이스

openclaw plugins marketplace entriesopenclaw plugins marketplace entries --offlineopenclaw plugins marketplace entries --jsonopenclaw plugins marketplace entries --feed-profile <name>openclaw plugins marketplace entries --feed-url <url>openclaw plugins marketplace list <source>openclaw plugins marketplace list <source> --jsonopenclaw plugins marketplace refreshopenclaw plugins marketplace refresh --feed-profile <name>openclaw plugins marketplace refresh --feed-url <url>openclaw plugins marketplace refresh --expected-sha256 <sha256> --json

plugins marketplace entries는 구성된 OpenClaw 마켓플레이스 피드의 항목을 나열합니다. 기본적으로 호스팅된 피드를 시도하고, 최신 승인 스냅샷 또는 번들 데이터로 대체합니다. 특정 구성 프로필을 읽으려면 --feed-profile <name>을 사용하고, 명시적인 호스팅 피드 URL을 읽으려면 --feed-url <url>을 사용하며, 피드를 가져오지 않고 최신 승인 스냅샷을 읽으려면 --offline을 사용하세요.

plugins marketplace refresh는 구성된 호스팅 피드 스냅샷을 새로 고치고 OpenClaw가 호스팅 데이터, 호스팅 스냅샷 또는 번들 대체 데이터를 승인했는지 보고합니다. 호출자가 최신 호스팅 페이로드가 고정된 체크섬과 일치하지 않으면 명령이 실패해야 하는 경우 --expected-sha256을 사용하세요.

마켓플레이스 list는 로컬 마켓플레이스 경로, marketplace.json 경로, owner/repo 같은 GitHub 축약형, GitHub 리포지토리 URL 또는 git URL을 허용합니다. --json은 확인된 소스 레이블과 파싱된 마켓플레이스 매니페스트 및 Plugin 항목을 출력합니다.

마켓플레이스 새로 고침은 호스팅된 OpenClaw 마켓플레이스 피드를 로드하고 검증된 응답을 로컬 호스팅 피드 스냅샷으로 유지합니다. 옵션이 없으면 구성된 기본 피드 프로필을 사용합니다. 특정 구성 프로필을 새로 고치려면 --feed-profile <name>을 사용하고, 명시적인 호스팅 피드 URL을 새로 고치려면 --feed-url <url>을 사용하며, 일치하는 페이로드 체크섬(sha256:<hex> 또는 64자 원시 16진수 다이제스트)을 요구하려면 --expected-sha256 <sha256>를 사용하고, 기계 판독 가능 출력에는 --json을 사용하세요. 명시적인 호스팅 피드 URL에는 자격 증명, 쿼리 문자열 또는 프래그먼트가 포함되어서는 안 됩니다. 고정되지 않은 새로 고침은 명령을 실패시키지 않고 호스팅 스냅샷 또는 번들 대체 결과를 보고할 수 있습니다. 고정된 새로 고침은 최신 호스팅 페이로드를 승인하지 않는 한 실패하며, 성공적인 호스팅 새로 고침은 OpenClaw가 검증된 스냅샷을 유지할 수 없으면 실패합니다.

관련 항목

• Plugin 빌드
• CLI 참조
• ClawHub