Plugin

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

명령어

openclaw plugins list [--enabled] [--verbose] [--json]openclaw plugins search <query> [--limit <n>] [--json]openclaw plugins install <path-or-spec> [--link] [--force] [--pin] [--marketplace <source>]openclaw plugins inspect <id> [--runtime] [--json]openclaw plugins inspect --all [--runtime] [--json]openclaw plugins info <id>                    # alias for inspectopenclaw plugins enable <id>openclaw plugins disable <id>openclaw plugins uninstall <id> [--dry-run] [--keep-files] [--force]openclaw plugins update <id-or-npm-spec> | --all [--dry-run]openclaw plugins registry [--refresh] [--json]openclaw plugins doctoropenclaw plugins init <id> [--name <name>] [--type tool|provider] [--directory <path>]openclaw plugins build [--entry <path>] [--check]openclaw plugins validate [--entry <path>]openclaw plugins marketplace entries [--offline] [--feed-profile <name>] [--json]openclaw plugins marketplace list <source> [--json]openclaw plugins marketplace refresh [--feed-profile <name>] [--expected-sha256 <sha256>] [--json]

설치, 검사, 제거 또는 레지스트리 새로 고침이 느린 원인을 조사하려면 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을 사용하며, 빌드한 다음 openclaw plugins build/validate를 호출하는 package.json 스크립트 plugin:build와 plugin:validate를 생성합니다.

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

공급자 스캐폴드는 API 키 인증 처리, clawhub package validate를 실행하는 npm run validate 스크립트, ClawHub 패키지 메타데이터 및 향후 GitHub OIDC를 통한 신뢰할 수 있는 게시를 위해 수동으로 실행하는 GitHub Actions 워크플로가 포함된 범용 OpenAI 호환 모델 공급자 Plugin을 생성합니다. 공급자 스캐폴드는 Skills를 생성하지 않으며 openclaw plugins build/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 tarballopenclaw plugins install git:github.com/<owner>/<repo>     # git repoopenclaw plugins install git:github.com/<owner>/<repo>@<ref>openclaw plugins install <path>                            # local path or archiveopenclaw plugins install -l <path>                         # link instead of copyopenclaw plugins install <plugin>@<marketplace>             # marketplace shorthandopenclaw plugins install <plugin> --marketplace <name>      # marketplace (explicit)openclaw plugins install <package> --force                  # overwrite existing installopenclaw plugins install <package> --pin                    # pin resolved npm versionopenclaw plugins install clawhub:<package> --acknowledge-clawhub-riskopenclaw plugins install <package> --dangerously-force-unsafe-install

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

plugins search는 설치할 수 있는 code-plugin 및 bundle-plugin 패키지를 ClawHub에서 검색합니다(Skills는 제외되며, Skills 검색에는 openclaw skills search를 사용하세요). 기본 --limit은 20이며 최댓값은 100입니다. 이 명령은 원격 카탈로그만 읽으며 로컬 상태 검사, 구성 변경, 패키지 설치 또는 Plugin 런타임 로드를 수행하지 않습니다. 결과에는 ClawHub 패키지 이름, 계열, 채널, 버전, 요약 및 openclaw plugins install clawhub:<package>과 같은 설치 안내가 포함됩니다.

ClawHub 설치는 명시적인 clawhub:<package> 로케이터를 사용합니다.

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

공식 Plugin ID와 일치하지 않는 한, npm에 안전한 범위 없는 Plugin 사양은 전환 출시 기간에 기본적으로 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 다이제스트 헤더와 아티팩트 다이제스트를 검증한 다음 일반 아카이브 경로를 통해 설치합니다. ClawPack 메타데이터가 없는 이전 ClawHub 버전은 기존 패키지 아카이브 검증 경로를 통해 계속 설치됩니다. 기록된 설치에는 이후 업데이트를 위해 ClawHub 소스 메타데이터, 아티팩트 종류, npm 무결성 값, npm shasum, tarball 이름 및 ClawPack 다이제스트 정보가 유지됩니다. 버전이 지정되지 않은 ClawHub 설치는 버전 없는 기록 사양을 유지하므로 openclaw plugins update가 더 새로운 ClawHub 릴리스를 따를 수 있습니다. clawhub:pkg@1.2.3 및 clawhub:pkg@beta와 같은 명시적 버전 또는 태그 선택자는 해당 선택자에 계속 고정됩니다.

마켓플레이스 축약형

Claude의 로컬 레지스트리 캐시인 ~/.claude/plugins/known_marketplaces.json에 마켓플레이스 이름이 있는 경우 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 루트로 복사되지 않으며, ~/.openclaw/extensions 또는 <workspace>/.openclaw/extensions에 직접 배치해도 로드되지 않습니다. 이러한 자동 검색 루트는 Plugin 패키지 또는 번들 디렉터리를 로드하며 최상위 스크립트 파일은 로컬 도우미로 간주하여 건너뜁니다. 대신 독립형 파일을 plugins.load.paths에 명시적으로 나열하세요.

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

openclaw plugins install -l ./my-plugin

--link는 --force(연결된 Plugin은 소스 경로를 직접 가리키므로 제자리에서 덮어쓸 항목이 없음), --marketplace 또는 git: 설치와 함께 사용할 수 없으며, 이미 존재하는 로컬 경로가 필요합니다.

목록

openclaw plugins listopenclaw plugins list --enabledopenclaw plugins list --verboseopenclaw plugins list --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가 설치 출처를 기록하도록 하세요.

패키징된 Docker 이미지 내부에서 번들 Plugin을 작업하려면 Plugin 소스 디렉터리를 /app/extensions/synology-chat과 같이 일치하는 패키징 소스 경로에 바인드 마운트하세요. OpenClaw는 /app/dist/extensions/synology-chat보다 먼저 마운트된 소스 오버레이를 검색합니다. 단순히 복사된 소스 디렉터리는 비활성 상태로 유지되므로 일반 패키징 설치는 계속 컴파일된 dist를 사용합니다.

런타임 훅 디버깅의 경우:

• openclaw plugins inspect <id> --runtime --json은 모듈을 로드하는 검사 과정에서 등록된 훅과 진단 정보를 표시합니다. 런타임 검사는 종속성을 설치하지 않습니다. 기존 종속성 상태를 정리하거나 설정에서 참조하지만 누락된 다운로드 가능 Plugin을 복구하려면 openclaw doctor --fix를 사용하세요.
• openclaw gateway status --deep --require-rpc는 접근 가능한 Gateway URL/프로필, 서비스/프로세스 정보, 설정 경로 및 RPC 상태를 확인합니다.
• 번들에 포함되지 않은 대화 훅(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 인덱스

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-filesopenclaw plugins uninstall <id> --force

uninstall은 plugins.entries, 영구 저장된 Plugin 인덱스, Plugin 허용/거부 목록 항목 및 해당하는 경우 연결된 plugins.load.paths 항목에서 Plugin 레코드를 제거합니다. --keep-files가 설정되지 않으면 추적 중인 관리형 설치 디렉터리도 제거하지만, 해당 디렉터리가 OpenClaw의 Plugin 확장 루트 내부로 확인되는 경우에만 제거합니다. 현재 Plugin이 memory 또는 contextEngine 슬롯을 소유하고 있으면 해당 슬롯은 기본값(메모리는 memory-core, 컨텍스트 엔진은 legacy)으로 재설정됩니다.

uninstall은 변경하기 전에 제거될 항목의 미리 보기를 출력한 다음 Uninstall plugin "<id>"? 확인 메시지를 표시합니다. 확인 메시지를 건너뛰려면 --force를 전달하세요. 스크립트와 비대화형 실행에 유용합니다. 이 옵션이 없으면 제거에는 대화형 TTY가 필요합니다. --dry-run은 동일한 미리 보기를 출력하고 확인 메시지를 표시하거나 항목을 변경하지 않은 채 종료합니다.

업데이트

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> --jsonopenclaw plugins inspect --all

검사는 기본적으로 Plugin 런타임을 가져오지 않고 ID, 로드 상태, 소스, 매니페스트 기능, 정책 플래그, 진단, 설치 메타데이터, 번들 기능 및 감지된 MCP 또는 LSP 서버 지원을 표시합니다. JSON 출력에는 contracts.agentToolResultMiddleware와 contracts.trustedToolPolicies 같은 Plugin 매니페스트 계약이 포함되므로, 운영자는 Plugin을 활성화하거나 재시작하기 전에 신뢰 표면 선언을 감사할 수 있습니다. Plugin 모듈을 로드하고 등록된 훅, 도구, 명령, 서비스, Gateway 메서드 및 HTTP 경로를 포함하려면 --runtime을 추가하세요. 런타임 검사는 누락된 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은 런타임에 실제로 등록하는 항목에 따라 분류됩니다.

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

진단

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의 ID, 활성화 상태, 소스 메타데이터 및 기여 소유권을 위한 OpenClaw의 영구 저장된 콜드 읽기 모델입니다. 일반적인 시작, 제공자 소유자 조회, 채널 설정 분류 및 Plugin 인벤토리는 Plugin 런타임 모듈을 가져오지 않고 이를 읽을 수 있습니다.

영구 레지스트리의 존재 여부와 최신 상태 또는 오래된 상태를 검사하려면 plugins registry를 사용하세요. 영구 저장된 Plugin 인덱스, 설정 정책 및 매니페스트/패키지 메타데이터에서 다시 빌드하려면 --refresh를 사용하세요. 이는 복구 경로이며 런타임 활성화 경로가 아닙니다.

openclaw doctor --fix는 레지스트리와 관련된 관리형 npm 변동도 복구합니다. 관리형 Plugin npm 프로젝트 또는 기존 플랫 관리형 npm 루트 아래의 고립되거나 복구된 @openclaw/* 패키지가 번들 Plugin을 가리는 경우, doctor는 해당 오래된 패키지를 제거하고 시작 시 번들 매니페스트를 기준으로 검증하도록 레지스트리를 다시 빌드합니다. 또한 doctor는 peerDependencies.openclaw를 선언하는 관리형 npm Plugin에 호스트 openclaw 패키지를 다시 연결하므로, 업데이트 또는 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>을, 페이로드 체크섬의 일치를 요구하려면 --expected-sha256 <sha256>을 사용하고(sha256:<hex> 또는 접두사 없는 64자 16진수 다이제스트), 머신 판독 가능 출력에는 --json을 사용합니다. 명시적인 호스팅 피드 URL에는 자격 증명, 쿼리 문자열 또는 프래그먼트가 포함되어서는 안 됩니다. 고정되지 않은 새로 고침은 명령을 실패시키지 않고 호스팅 스냅샷 또는 번들 대체 결과를 보고할 수 있습니다. 고정된 새로 고침은 새로운 호스팅 페이로드를 승인한 경우에만 성공하며, 호스팅 새로 고침에 성공했더라도 OpenClaw가 검증된 스냅샷을 저장할 수 없으면 실패합니다.

관련 항목

• Plugin 빌드하기
• CLI 참조
• ClawHub