OpenClaw 플러그인 관리 가이드: 설치부터 업데이트까지

개발을 하다 보면 수많은 플러그인과 확장 기능을 관리하는 게 정말 번거로울 때가 있죠. 설정이 꼬이거나 버전이 맞지 않아 고생한 경험, 다들 한 번쯤은 있을 거예요. OpenClaw는 이런 고민을 해결하기 위해 강력하고 직관적인 플러그인 관리 시스템을 제공합니다.

openclaw plugins를 사용하면 Gateway 플러그인, hook 팩, 그리고 호환 번들을 아주 쉽게 관리할 수 있어요.

명령어

openclaw plugins list
openclaw plugins install <path-or-spec>
openclaw plugins inspect <id>
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins uninstall <id>
openclaw plugins doctor
openclaw plugins update <id>
openclaw plugins update --all
openclaw plugins marketplace list <marketplace>

번들 플러그인은 OpenClaw와 함께 제공되지만 처음에는 비활성화되어 있어요. plugins enable을 사용해서 활성화하면 됩니다.

네이티브 OpenClaw 플러그인은 인라인 JSON Schema(configSchema, 비어 있어도 무관)가 포함된 openclaw.plugin.json 파일을 함께 배포해야 해요. 호환 번들은 대신 자체 번들 manifest를 사용합니다.

plugins list를 실행하면 Format: openclaw 또는 Format: bundle이 표시돼요. 상세 리스트나 정보 출력 시에는 번들 하위 유형(codex, claude, cursor)과 감지된 번들 기능(capabilities)도 함께 확인할 수 있습니다.

설치 (Install)

openclaw plugins install <package>                      # ClawHub first, then npm
openclaw plugins install clawhub:<package>              # ClawHub only
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)

패키지 이름만 입력하면 ClawHub를 먼저 확인하고, 그 다음 npm을 확인해요. 보안을 위해 플러그인 설치는 코드를 직접 실행하는 것과 같이 주의해야 합니다. 가급적 버전을 고정(pinned versions)해서 사용하는 것을 추천해요.

--dangerously-force-unsafe-install은 내장된 위험 코드 스캐너에서 오탐이 발생했을 때 사용하는 비상용 옵션이에요. 스캐너가 critical 결과를 보고하더라도 설치를 계속할 수 있게 해주지만, 플러그인의 before_install hook 정책 블록이나 스캔 실패 자체를 우회하지는 않습니다.

이 CLI 플래그는 openclaw plugins install에 적용됩니다. Gateway 기반의 skill 의존성 설치는 그에 맞는 dangerouslyForceUnsafeInstall 요청 오버라이드를 사용하며, openclaw skills install은 별도의 ClawHub skill 다운로드/설치 흐름을 따릅니다.

plugins install은 package.json에 openclaw.hooks를 노출하는 hook 팩의 설치 창구이기도 해요. 필터링된 hook 가시성이나 개별 hook 활성화가 필요하다면 패키지 설치가 아닌 openclaw hooks 명령어를 사용하세요.

npm 스펙은 registry 전용(패키지 이름 + 선택 사항인 정확한 버전 또는 dist-tag)입니다. Git, URL, 파일 스펙이나 semver 범위는 허용되지 않아요. 안전을 위해 의존성 설치는 --ignore-scripts와 함께 실행됩니다.

일반 스펙이나 @latest는 안정 버전(stable track)을 유지해요. 만약 npm이 이를 프리릴리스(prerelease)로 해석하면 OpenClaw는 실행을 멈추고 @beta, @rc 같은 프리릴리스 태그나 @1.2.3-beta.4 같은 정확한 프리릴리스 버전을 명시하도록 요청합니다.

설치하려는 이름이 번들 플러그인 ID(예: diffs)와 일치하면 OpenClaw는 번들 플러그인을 직접 설치해요. 같은 이름의 npm 패키지를 설치하고 싶다면 @scope/diffs처럼 명시적인 스코프 스펙을 사용해야 합니다.

지원되는 아카이브 형식은 .zip, .tgz, .tar.gz, .tar입니다. Claude marketplace 설치도 지원해요.

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

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

이제 OpenClaw는 일반적인 npm 안전 플러그인 스펙에 대해서도 ClawHub를 우선적으로 확인해요. ClawHub에 해당 패키지나 버전이 없을 때만 npm으로 넘어갑니다.

openclaw plugins install openclaw-codex-app-server

OpenClaw는 ClawHub에서 패키지 아카이브를 다운로드하고, 광고된 플러그인 API 및 최소 Gateway 호환성을 확인한 뒤 일반적인 아카이브 경로를 통해 설치합니다. 기록된 설치 정보에는 나중에 업데이트할 때 사용할 수 있도록 ClawHub 소스 메타데이터가 유지돼요.

Claude의 로컬 레지스트리 캐시(~/.claude/plugins/known_marketplaces.json)에 marketplace 이름이 있다면 plugin@marketplace 약칭을 사용할 수 있습니다.

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

marketplace 소스를 직접 전달하고 싶을 때는 --marketplace를 사용하세요.

openclaw plugins install <plugin-name> --marketplace <marketplace-name>
openclaw plugins install <plugin-name> --marketplace <owner/repo>
openclaw plugins install <plugin-name> --marketplace ./my-marketplace

marketplace 소스는 다음과 같을 수 있습니다:

~/.claude/plugins/known_marketplaces.json에 정의된 Claude의 알려진 marketplace 이름
로컬 marketplace 루트 또는 marketplace.json 경로
owner/repo 형태의 GitHub 저장소 약칭
git URL

GitHub나 git에서 로드된 원격 marketplace의 경우, 플러그인 항목은 반드시 클론된 marketplace 저장소 내부에 있어야 해요. OpenClaw는 해당 저장소 내의 상대 경로 소스는 허용하지만, 원격 manifest에 포함된 외부 git, GitHub, URL/아카이브, 절대 경로 플러그인 소스는 거부합니다.

로컬 경로와 아카이브의 경우 OpenClaw가 다음 항목들을 자동으로 감지합니다:

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

호환 번들은 일반적인 extensions 루트에 설치되며 동일한 list/info/enable/disable 흐름을 따릅니다. 현재 번들 skills, Claude command-skills, Claude settings.json 기본값, Cursor command-skills, 그리고 호환되는 Codex hook 디렉토리가 지원됩니다. 감지된 다른 번들 기능들은 진단/정보 창에 표시되지만 아직 런타임 실행에는 연결되지 않았습니다.

로컬 디렉토리를 복사하지 않고 연결만 하려면 --link를 사용하세요 (plugins.load.paths에 추가됩니다).

openclaw plugins install -l ./my-plugin

npm 설치 시 --pin을 사용하면 확인된 정확한 스펙(name@version)을 plugins.installs에 저장할 수 있습니다. 기본 동작은 버전을 고정하지 않는 방식이에요.

삭제 (Uninstall)

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

uninstall은 plugins.entries, plugins.installs, 플러그인 허용 목록(allowlist), 그리고 해당하는 경우 연결된 plugins.load.paths 항목에서 플러그인 기록을 제거합니다. 활성화된 memory 플러그인의 경우 memory 슬롯이 memory-core로 초기화돼요.

기본적으로 삭제 시 활성 state-dir 플러그인 루트 아래의 플러그인 설치 디렉토리도 함께 제거됩니다. 파일을 디스크에 남겨두고 싶다면 --keep-files를 사용하세요.

--keep-config는 --keep-files의 예전 이름(alias)으로 계속 지원됩니다.

업데이트 (Update)

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@beta

업데이트는 plugins.installs에 추적된 설치 건과 hooks.internal.installs에 추적된 hook 팩 설치 건에 적용됩니다.

플러그인 ID를 전달하면 OpenClaw는 해당 플러그인에 기록된 설치 스펙을 재사용해요. 즉, 이전에 저장된 @beta 같은 dist-tag나 고정된 정확한 버전이 이후 update <id> 실행 시에도 계속 사용됩니다.

npm 설치의 경우 dist-tag나 정확한 버전이 포함된 명시적인 npm 패키지 스펙을 전달할 수도 있어요. OpenClaw는 해당 패키지 이름을 추적된 플러그인 기록과 대조하여 업데이트하고, 향후 ID 기반 업데이트를 위해 새로운 npm 스펙을 기록합니다.

저장된 무결성 해시(integrity hash)가 있고 가져온 아티팩트의 해시가 변경된 경우, OpenClaw는 경고를 출력하고 진행하기 전에 확인을 요청합니다. CI나 비대화형 환경에서는 글로벌 --yes 플래그를 사용해서 확인 절차를 건너뛸 수 있어요.

조회 (Inspect)

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

단일 플러그인에 대한 심층적인 내부 정보를 보여줍니다. ID, 로드 상태, 소스, 등록된 기능, hook, 도구, 명령어, 서비스, Gateway 메서드, HTTP 경로, 정책 플래그, 진단 정보 및 설치 메타데이터를 확인할 수 있어요.

각 플러그인은 런타임에 실제로 등록하는 내용에 따라 다음과 같이 분류됩니다:

plain-capability — 한 가지 기능 유형 (예: provider 전용 플러그인)
hybrid-capability — 여러 기능 유형 (예: 텍스트 + 음성 + 이미지)
hook-only — 기능이나 인터페이스 없이 hook만 있는 경우
non-capability — 도구/명령어/서비스는 있지만 기능(capability)은 없는 경우

기능 모델에 대한 자세한 내용은 Plugin shapes를 참고하세요.

--json 플래그를 사용하면 스크립트 작성이나 감사(auditing)에 적합한 기계 판독 가능 보고서를 출력합니다.

info는 inspect와 동일한 명령어입니다.

AI Setup Assistant

다음 단계

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.