Plugin

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

명령어

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>                    # inspect의 별칭openclaw 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 도구 플러그인을 생성합니다. 첫 번째 인수는 플러그인 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은 생성된 매니페스트, 패키지 메타데이터 및 현재 엔트리 내보내기가 여전히 일치하는지 확인합니다. 전체 작성 워크플로는 도구 플러그인을 참조하십시오.

스캐폴드는 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 호환 모델 제공자 플러그인을 생성합니다. 제공자 스캐폴드는 Skills을 생성하지 않으며 openclaw plugins build/validate을 사용하지 않습니다. 해당 명령어는 도구 스캐폴드의 생성된 메타데이터 경로에 사용됩니다.

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

설치

openclaw plugins search "calendar"                      # ClawHub 플러그인 검색openclaw plugins install @openclaw/<package>            # 신뢰할 수 있는 공식 카탈로그openclaw plugins install <package>                       # 임의의 npm 패키지openclaw plugins install clawhub:<package>                # ClawHub 전용openclaw plugins install npm:<package>                    # npm 전용openclaw plugins install npm-pack:<path.tgz>               # 로컬 npm-pack tarballopenclaw plugins install git:github.com/<owner>/<repo>     # git 저장소openclaw plugins install git:github.com/<owner>/<repo>@<ref>openclaw plugins install <path>                            # 로컬 경로 또는 아카이브openclaw plugins install -l <path>                         # 복사하는 대신 연결openclaw plugins install <plugin>@<marketplace>             # 마켓플레이스 축약형openclaw plugins install <plugin> --marketplace <name>      # 마켓플레이스(명시적)openclaw plugins install <package> --force                  # 소스 확인/기존 항목 덮어쓰기openclaw plugins install <package> --pin                    # 확인된 npm 버전 고정openclaw plugins install clawhub:<package> --acknowledge-clawhub-riskopenclaw plugins install <package> --dangerously-force-unsafe-install

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

plugins search은 설치 가능한 code-plugin 및 bundle-plugin 패키지를 ClawHub에서 조회합니다(Skills은 해당하지 않으며, 이에 대해서는 openclaw skills search을 사용하십시오). 기본 --limit은 20이며 최대 100으로 제한됩니다. 원격 카탈로그만 읽으며 로컬 상태 검사, 구성 변경, 패키지 설치 또는 플러그인 런타임 로드는 수행하지 않습니다. 결과에는 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, 타르볼 이름 및 ClawPack 다이제스트 정보를 유지합니다. 버전이 지정되지 않은 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 루트로 복사되지 않으며, ~/.openclaw/extensions 또는 <workspace>/.openclaw/extensions에 직접 배치해도 로드되지 않습니다. 이러한 자동 검색 루트는 Plugin 패키지 또는 번들 디렉터리를 로드하고 최상위 스크립트 파일은 로컬 도우미로 간주하여 건너뜁니다. 대신 독립 실행형 파일을 plugins.load.paths에 명시적으로 나열하십시오.

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

openclaw plugins install -l ./my-plugin

--link은 --marketplace 또는 git: 설치에서 지원되지 않으며, 이미 존재하는 로컬 경로가 필요합니다. 비대화형 로컬 링크의 경우 소스를 검토한 후 --force을 전달하십시오. 이 옵션은 출처를 확인하지만 연결된 디렉터리를 복사하거나 덮어쓰지 않습니다.

목록

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 또는 openclaw plugins inspect <id>을 나열된 Plugin 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은 모듈을 로드한 검사 단계에서 등록된 훅과 진단 정보를 표시합니다. 런타임 검사는 종속성을 설치하지 않습니다. openclaw doctor --fix을 사용하여 레거시 종속성 상태를 정리하거나 설정에서 참조하지만 누락된 다운로드 가능 Plugin을 복구하십시오.
• 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 인덱스, Plugin 허용/거부 목록 항목 및 해당하는 경우 연결된 plugins.load.paths 항목을 제거합니다. --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 @acme/demoopenclaw plugins update openclaw-codex-app-server --acknowledge-clawhub-riskopenclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install

업데이트는 관리형 Plugin 인덱스에서 추적되는 Plugin 설치와 hooks.internal.installs에서 추적되는 훅 팩 설치에 적용됩니다. 사용자가 Plugin을 설치할 때 이미 선택한 소스를 재사용하므로 소스를 다시 확인할 필요가 없습니다.

검사

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을 활성화하거나 다시 시작하기 전에 신뢰할 수 있는 표면 선언을 감사할 수 있습니다. --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은 런타임에 실제로 등록하는 항목에 따라 분류됩니다.

기능 모델에 대한 자세한 내용은 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의 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>을, 일치하는 페이로드 체크섬 (sha256:<hex> 또는 64자 16진수 다이제스트)을 요구하려면 --expected-sha256 <sha256>을, 기계 판독 가능 출력을 사용하려면 --json을 사용하십시오. 명시적인 호스팅 피드 URL에는 자격 증명, 쿼리 문자열 또는 프래그먼트가 포함되어서는 안 됩니다. 고정되지 않은 새로 고침은 명령 실패 없이 호스팅 스냅샷 또는 번들 대체 결과를 보고할 수 있습니다. 고정된 새로 고침은 새로운 호스팅 페이로드를 수락하는 경우에만 성공하며, 호스팅 새로 고침이 성공했더라도 OpenClaw가 검증된 스냅샷을 영구 저장할 수 없으면 실패합니다.

관련 항목

• Plugin 빌드
• CLI 참조
• ClawHub