Plugin

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

# 명령

openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins search <query>
openclaw plugins search <query> --limit 20
openclaw plugins search <query> --json
openclaw plugins install <path-or-spec>
openclaw plugins inspect <id>
openclaw plugins inspect <id> --runtime
openclaw plugins inspect <id> --json
openclaw plugins inspect --all
openclaw plugins info <id>
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins registry
openclaw plugins registry --refresh
openclaw plugins uninstall <id>
openclaw plugins doctor
openclaw plugins update <id-or-npm-spec>
openclaw plugins update --all
openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json

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

# 설치

openclaw plugins search "calendar"                   # search ClawHub plugins
openclaw plugins install <package>                      # npm by default
openclaw plugins install clawhub:<package>              # ClawHub only
openclaw plugins install npm:<package>                  # npm only
openclaw plugins install npm-pack:<path.tgz>            # local npm pack through npm install semantics
openclaw plugins install git:github.com/<owner>/<repo>  # git repo
openclaw plugins install git:github.com/<owner>/<repo>@<ref>
openclaw plugins install <package> --force              # overwrite existing install
openclaw plugins install <package> --pin                # pin version
openclaw plugins install <package> --dangerously-force-unsafe-install
openclaw plugins install <path>                         # local path
openclaw plugins install <plugin>@<marketplace>         # marketplace
openclaw plugins install <plugin> --marketplace <name>  # marketplace (explicit)
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>

plugins search는 설치 가능한 Plugin 패키지를 ClawHub에서 쿼리하고 바로 설치할 수 있는 패키지 이름을 출력합니다. 코드 Plugin 및 번들 Plugin 패키지를 검색하며, Skills는 검색하지 않습니다. ClawHub Skills에는 openclaw skills search를 사용하세요.

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

openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:[email protected]

시작 전환 중에는 단순 npm 안전 Plugin 명세가 기본적으로 npm에서 설치됩니다.

openclaw plugins install openclaw-codex-app-server

npm 전용 해석을 명시적으로 만들려면 npm:을 사용하세요.

openclaw plugins install npm:openclaw-codex-app-server
openclaw plugins install npm:@scope/[email protected]

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:[email protected] 및 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)

# 목록

openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins search <query>
openclaw plugins search <query> --limit 20
openclaw plugins search <query> --json

--enabledboolean

활성화된 Plugin만 표시합니다.

--verboseboolean

테이블 보기에서 Plugin별 소스/출처/버전/활성화 메타데이터가 포함된 세부 줄로 전환합니다.

--jsonboolean

머신이 읽을 수 있는 인벤터리와 레지스트리 진단 및 패키지 의존성 설치 상태입니다.

plugins search는 원격 ClawHub 카탈로그 조회입니다. 로컬 상태를 검사하거나, 구성을 변경하거나, 패키지를 설치하거나, Plugin 런타임 코드를 로드하지 않습니다. 검색 결과에는 ClawHub 패키지 이름, 패밀리, 채널, 버전, 요약, 그리고 openclaw plugins install clawhub:<package> 같은 설치 힌트가 포함됩니다.

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

런타임 hook 디버깅의 경우:

• openclaw plugins inspect <id> --runtime --json은 모듈 로드 검사 패스에서 등록된 hook과 진단을 표시합니다. 런타임 검사는 의존성을 설치하지 않습니다. 기존 의존성 상태를 정리하거나 구성에서 참조된 누락된 다운로드 가능 Plugin을 복구하려면 openclaw doctor --fix를 사용하세요.
• openclaw gateway status --deep --require-rpc는 연결 가능한 Gateway, 서비스/프로세스 힌트, 구성 경로, 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가 필요합니다.

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

openclaw plugins install -l ./my-plugin

# Plugin 인덱스

Plugin 설치 메타데이터는 사용자가 설정하는 구성이 아니라 머신이 관리하는 상태입니다. 설치와 업데이트는 활성 OpenClaw 상태 디렉터리 아래의 plugins/installs.json에 이를 기록합니다. 최상위 installRecords 맵은 손상되었거나 누락된 Plugin 매니페스트의 기록을 포함해 설치 메타데이터의 지속적인 소스입니다. plugins 배열은 매니페스트에서 파생된 콜드 레지스트리 캐시입니다. 이 파일에는 편집 금지 경고가 포함되어 있으며 openclaw plugins update, 제거, 진단, 콜드 Plugin 레지스트리에서 사용됩니다.

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

# 제거

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

uninstall은 해당되는 경우 plugins.entries, 영구 저장된 Plugin 인덱스, Plugin 허용/거부 목록 항목, 연결된 plugins.load.paths 항목에서 Plugin 기록을 제거합니다. --keep-files가 설정되지 않은 한, 제거는 OpenClaw의 Plugin extensions 루트 내부에 있는 추적된 관리형 설치 디렉터리도 제거합니다. Active Memory Plugin의 경우 메모리 슬롯은 memory-core로 재설정됩니다.

# 업데이트

openclaw plugins update <id-or-npm-spec>
openclaw plugins update --all
openclaw plugins update <id-or-npm-spec> --dry-run
openclaw plugins update @openclaw/voice-call
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install

업데이트는 관리형 Plugin 인덱스에서 추적되는 Plugin 설치와 hooks.internal.installs에서 추적되는 hook-pack 설치에 적용됩니다.

# 검사

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

검사는 기본적으로 Plugin 런타임을 가져오지 않고 ID, 로드 상태, 소스, 매니페스트 기능, 정책 플래그, 진단, 설치 메타데이터, 번들 기능, 감지된 MCP 또는 LSP 서버 지원을 표시합니다. --runtime을 추가하면 Plugin 모듈을 로드하고 등록된 hook, 도구, 명령, 서비스, 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 — 하나의 기능 유형(예: 제공자 전용 Plugin)
• hybrid-capability — 여러 기능 유형(예: 텍스트 + 음성 + 이미지)
• hook-only — 후크만 있고 기능이나 표면은 없음
• non-capability — 도구/명령/서비스가 있지만 기능은 없음

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

# Doctor

openclaw plugins doctor

doctor는 Plugin 로드 오류, 매니페스트/검색 진단, 호환성 알림을 보고합니다. 모든 것이 정상이면 No plugin issues detected.를 출력합니다.

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

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

# 레지스트리

openclaw plugins registry
openclaw plugins registry --refresh
openclaw plugins registry --json

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

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

openclaw doctor --fix는 레지스트리 인접 관리형 npm 드리프트도 복구합니다. 관리형 Plugin npm 루트 아래의 고아 또는 복구된 @openclaw/* 패키지가 번들 Plugin을 가리는 경우, doctor는 해당 오래된 패키지를 제거하고 레지스트리를 다시 빌드하여 시작 시 번들 매니페스트를 기준으로 검증하도록 합니다.

# Marketplace

openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json

Marketplace 목록은 로컬 Marketplace 경로, marketplace.json 경로, owner/repo 같은 GitHub 축약형, GitHub 저장소 URL, 또는 git URL을 받습니다. --json은 해석된 소스 레이블과 파싱된 Marketplace 매니페스트 및 Plugin 항목을 출력합니다.

# 관련 항목

• Plugin 빌드하기
• CLI 참조
• 커뮤니티 Plugin