Gateway Plugin, 훅 팩, 호환 번들을 관리합니다.Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
Plugin 시스템
Plugin 설치, 활성화, 문제 해결을 위한 최종 사용자 가이드입니다.
Plugin 관리
설치, 목록, 업데이트, 제거, 게시를 위한 빠른 예시입니다.
Plugin 번들
번들 호환성 모델입니다.
Plugin 매니페스트
매니페스트 필드와 설정 스키마입니다.
보안
Plugin 설치를 위한 보안 강화입니다.
명령
OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1로 명령을 실행합니다. 추적은 단계별 소요 시간을
stderr에 기록하고 JSON 출력은 파싱 가능한 상태로 유지합니다. 디버깅을 참조하세요.
Nix 모드(
OPENCLAW_NIX_MODE=1)에서는 Plugin 수명 주기 변경 작업이 비활성화됩니다. 이 설치에는 plugins install, plugins update, plugins uninstall, plugins enable, plugins disable 대신 Nix 소스를 사용하세요. nix-openclaw의 경우 에이전트 우선 빠른 시작을 사용하세요.번들 Plugin은 OpenClaw와 함께 제공됩니다. 일부는 기본적으로 활성화되어 있으며(예: 번들 모델 제공자, 번들 음성 제공자, 번들 브라우저 Plugin), 나머지는
plugins enable이 필요합니다.네이티브 OpenClaw Plugin은 인라인 JSON Schema(configSchema, 비어 있어도 포함)를 포함한 openclaw.plugin.json을 제공해야 합니다. 호환 번들은 대신 자체 번들 매니페스트를 사용합니다.plugins list는 Format: openclaw 또는 Format: bundle을 표시합니다. 자세한 목록/정보 출력은 번들 하위 유형(codex, claude, cursor)과 감지된 번들 기능도 표시합니다.설치
plugins search는 ClawHub에서 설치 가능한 Plugin 패키지를 쿼리하고
설치 준비가 된 패키지 이름을 출력합니다. Skills가 아니라 code-plugin 및 bundle-plugin 패키지를
검색합니다. ClawHub Skills에는 openclaw skills search를 사용하세요.
ClawHub는 대부분의 Plugin에 대한 기본 배포 및 탐색 표면입니다. Npm은
지원되는 대체 경로이자 직접 설치 경로로 유지됩니다. OpenClaw 소유
@openclaw/* Plugin 패키지는 다시 npm에 게시됩니다. 현재 목록은
npmjs.com/org/openclaw 또는
Plugin 인벤토리를 참조하세요. 안정 설치는 latest를 사용합니다.
베타 채널 설치와 업데이트는 해당 태그가 있으면 npm beta dist-tag를 우선 사용하고,
그다음 latest로 폴백합니다.설정 include 및 잘못된 설정 복구
설정 include 및 잘못된 설정 복구
plugins 섹션이 단일 파일 $include로 뒷받침되는 경우, plugins install/update/enable/disable/uninstall은 해당 포함 파일에 직접 기록하고 openclaw.json은 그대로 둡니다. 루트 include, include 배열, 형제 재정의가 있는 include는 평탄화하는 대신 안전하게 실패합니다. 지원되는 형태는 설정 include를 참조하세요.설치 중 설정이 잘못된 경우 plugins install은 일반적으로 안전하게 실패하고 먼저 openclaw doctor --fix를 실행하라고 안내합니다. Gateway 시작 및 핫 리로드 중에는 잘못된 Plugin 설정이 다른 잘못된 설정과 마찬가지로 안전하게 실패합니다. openclaw doctor --fix는 잘못된 Plugin 항목을 격리할 수 있습니다. 문서화된 유일한 설치 시점 예외는 openclaw.install.allowInvalidConfigRecovery에 명시적으로 옵트인한 Plugin을 위한 좁은 범위의 번들 Plugin 복구 경로입니다.--force 및 재설치와 업데이트
--force 및 재설치와 업데이트
--force는 기존 설치 대상을 재사용하고 이미 설치된 Plugin 또는 훅 팩을 제자리에서 덮어씁니다. 새 로컬 경로, 아카이브, ClawHub 패키지 또는 npm 아티팩트에서 같은 id를 의도적으로 재설치할 때 사용하세요. 이미 추적 중인 npm Plugin의 일반적인 업그레이드에는 openclaw plugins update <id-or-npm-spec>를 권장합니다.이미 설치된 Plugin id에 대해 plugins install을 실행하면 OpenClaw는 중단하고 일반 업그레이드에는 plugins update <id-or-npm-spec>를, 현재 설치를 다른 소스에서 정말로 덮어쓰려는 경우에는 plugins install <package> --force를 안내합니다.--pin 범위
--pin 범위
--pin은 npm 설치에만 적용됩니다. git: 설치에서는 지원되지 않습니다. 고정된 소스를 원할 때는 git:github.com/acme/plugin@v1.2.3처럼 명시적인 git ref를 사용하세요. --marketplace에서도 지원되지 않습니다. marketplace 설치는 npm spec 대신 marketplace 소스 메타데이터를 유지하기 때문입니다.--dangerously-force-unsafe-install
--dangerously-force-unsafe-install
--dangerously-force-unsafe-install은 내장 위험 코드 스캐너의 오탐을 위한 비상 옵션입니다. 내장 스캐너가 critical 결과를 보고하더라도 설치를 계속할 수 있게 하지만, Plugin before_install 훅 정책 차단을 우회하지 않으며 스캔 실패도 우회하지 않습니다.이 CLI 플래그는 Plugin 설치/업데이트 흐름에 적용됩니다. Gateway 기반 skill 의존성 설치는 대응되는 dangerouslyForceUnsafeInstall 요청 재정의를 사용하며, openclaw skills install은 별도의 ClawHub skill 다운로드/설치 흐름으로 유지됩니다.ClawHub에 게시한 Plugin이 레지스트리 스캔으로 차단된 경우 ClawHub의 게시자 단계를 사용하세요.훅 팩 및 npm spec
훅 팩 및 npm spec
plugins install은 package.json에서 openclaw.hooks를 노출하는 훅 팩의 설치 표면이기도 합니다. 패키지 설치가 아니라 필터링된 훅 표시와 훅별 활성화에는 openclaw hooks를 사용하세요.Npm spec은 레지스트리 전용입니다(패키지 이름 + 선택적 정확한 버전 또는 dist-tag). Git/URL/file spec과 semver 범위는 거부됩니다. 의존성 설치는 셸에 전역 npm 설치 설정이 있더라도 안전을 위해 --ignore-scripts로 프로젝트 로컬에서 실행됩니다. 관리형 Plugin npm 루트는 OpenClaw의 패키지 수준 npm overrides를 상속하므로 호스트 보안 핀이 호이스팅된 Plugin 의존성에도 적용됩니다.npm 해석을 명시적으로 만들고 싶을 때 npm:<package>를 사용하세요. 단독 패키지 spec도 출시 전환 기간 동안 npm에서 직접 설치됩니다.단독 spec과 @latest는 안정 트랙에 유지됩니다. 2026.5.3-1 같은 OpenClaw 날짜 스탬프 수정 버전은 이 검사에서 안정 릴리스입니다. npm이 이 중 하나를 프리릴리스로 해석하면 OpenClaw는 중단하고 @beta/@rc 같은 프리릴리스 태그 또는 @1.2.3-beta.4 같은 정확한 프리릴리스 버전으로 명시적으로 옵트인하라고 요청합니다.단독 설치 spec이 공식 Plugin id(예: diffs)와 일치하면 OpenClaw는 카탈로그 항목을 직접 설치합니다. 같은 이름의 npm 패키지를 설치하려면 명시적인 scoped spec(예: @scope/diffs)을 사용하세요.Git 저장소
Git 저장소
git 저장소에서 직접 설치하려면
git:<repo>를 사용하세요. 지원되는 형식에는 git:github.com/owner/repo, git:owner/repo, 전체 https://, ssh://, git://, file://, git@host:owner/repo.git clone URL이 포함됩니다. 설치 전에 브랜치, 태그 또는 커밋을 체크아웃하려면 @<ref> 또는 #<ref>를 추가하세요.Git 설치는 임시 디렉터리에 clone하고, 요청된 ref가 있으면 체크아웃한 다음, 일반 Plugin 디렉터리 설치 프로그램을 사용합니다. 즉 매니페스트 검증, 위험 코드 스캔, 패키지 관리자 설치 작업, 설치 기록이 npm 설치처럼 동작합니다. 기록된 git 설치에는 소스 URL/ref와 해석된 커밋이 포함되어 openclaw plugins update가 나중에 소스를 다시 해석할 수 있습니다.git에서 설치한 후에는 Gateway 메서드 및 CLI 명령 같은 런타임 등록을 확인하려면 openclaw plugins inspect <id> --runtime --json을 사용하세요. Plugin이 api.registerCli로 CLI 루트를 등록했다면 OpenClaw 루트 CLI를 통해 해당 명령을 직접 실행하세요. 예: openclaw demo-plugin ping.아카이브
아카이브
지원되는 아카이브:
.zip, .tgz, .tar.gz, .tar. 네이티브 OpenClaw Plugin 아카이브는 압축 해제된 Plugin 루트에 유효한 openclaw.plugin.json을 포함해야 합니다. package.json만 포함한 아카이브는 OpenClaw가 설치 기록을 쓰기 전에 거부됩니다.파일이 npm-pack tarball이고 레지스트리 설치에서 사용하는 동일한 관리형 npm-root 설치 경로를 테스트하려면
npm-pack:<path.tgz>를 사용하세요.
여기에는 package-lock.json 검증, 호이스팅된 의존성 스캔,
npm 설치 기록이 포함됩니다. 일반 아카이브 경로는 여전히
Plugin extensions 루트 아래 로컬 아카이브로 설치됩니다.Claude marketplace 설치도 지원됩니다.clawhub:<package> locator를 사용합니다.
npm:을 사용하세요.
.tgz를 다운로드하고 ClawHub 다이제스트 헤더와 아티팩트 다이제스트를 검증한 다음, 일반 아카이브 경로를 통해 설치합니다. ClawPack 메타데이터가 없는 이전 ClawHub 버전은 여전히 레거시 패키지 아카이브 검증 경로를 통해 설치됩니다. 기록된 설치는 이후 업데이트를 위해 ClawHub 소스 메타데이터, 아티팩트 종류, npm 무결성, npm shasum, tarball 이름, ClawPack 다이제스트 정보를 유지합니다.
버전이 지정되지 않은 ClawHub 설치는 버전이 지정되지 않은 기록된 spec을 유지하므로 openclaw plugins update가 더 새로운 ClawHub 릴리스를 따라갈 수 있습니다. clawhub:pkg@1.2.3 및 clawhub:pkg@beta 같은 명시적 버전 또는 태그 선택자는 해당 선택자에 계속 고정됩니다.
마켓플레이스 약칭
마켓플레이스 이름이~/.claude/plugins/known_marketplaces.json의 Claude 로컬 레지스트리 캐시에 있을 때는 plugin@marketplace 약칭을 사용합니다.
--marketplace를 사용합니다.
- 마켓플레이스 소스
- 원격 마켓플레이스 규칙
~/.claude/plugins/known_marketplaces.json의 Claude 알려진 마켓플레이스 이름- 로컬 마켓플레이스 루트 또는
marketplace.json경로 owner/repo같은 GitHub repo 약칭https://github.com/owner/repo같은 GitHub repo URL- git URL
- 네이티브 OpenClaw Plugin(
openclaw.plugin.json) - Codex 호환 번들(
.codex-plugin/plugin.json) - Claude 호환 번들(
.claude-plugin/plugin.json또는 기본 Claude 컴포넌트 레이아웃) - Cursor 호환 번들(
.cursor-plugin/plugin.json)
호환 번들은 일반 Plugin 루트에 설치되며 동일한 list/info/enable/disable 흐름에 참여합니다. 현재는 번들 skills, Claude command-skills, Claude
settings.json 기본값, Claude .lsp.json / manifest 선언 lspServers 기본값, Cursor command-skills, 호환 Codex hook 디렉터리가 지원됩니다. 그 밖에 감지된 번들 기능은 diagnostics/info에 표시되지만 아직 런타임 실행에 연결되어 있지는 않습니다.목록
활성화된 Plugin만 표시합니다.
테이블 보기에서 Plugin별 source/origin/version/activation 메타데이터 상세 줄로 전환합니다.
레지스트리 diagnostics 및 패키지 dependency 설치 상태를 포함한 기계 판독 가능 inventory입니다.
plugins list는 먼저 저장된 로컬 Plugin 레지스트리를 읽고, 레지스트리가 없거나 유효하지 않을 때는 manifest 전용 파생 fallback을 사용합니다. Plugin이 설치되고 활성화되었으며 콜드 스타트업 계획에 보이는지 확인하는 데 유용하지만, 이미 실행 중인 Gateway 프로세스의 live 런타임 probe는 아닙니다. Plugin 코드, 활성화 상태, hook 정책 또는 plugins.load.paths를 변경한 뒤에는 새 register(api) 코드나 hook이 실행될 것으로 기대하기 전에 해당 채널을 제공하는 Gateway를 다시 시작하세요. 원격/컨테이너 배포에서는 wrapper 프로세스만이 아니라 실제 openclaw gateway run child를 다시 시작하고 있는지 확인하세요.plugins list --json에는 package.json dependencies와 optionalDependencies에서 가져온 각 Plugin의 dependencyStatus가 포함됩니다. OpenClaw는 해당 패키지 이름이 Plugin의 일반 Node node_modules lookup path에 있는지만 확인합니다. Plugin 런타임 코드를 import하거나, 패키지 매니저를 실행하거나, 누락된 dependencies를 복구하지 않습니다.plugins search는 원격 ClawHub 카탈로그 조회입니다. 로컬 상태를 검사하거나, config를 변경하거나, 패키지를 설치하거나, Plugin 런타임 코드를 로드하지 않습니다. 검색 결과에는 ClawHub 패키지 이름, family, channel, version, summary 및 openclaw plugins install clawhub:<package> 같은 설치 힌트가 포함됩니다.
패키징된 Docker 이미지 안에서 번들 Plugin을 작업하려면 Plugin 소스 디렉터리를 /app/extensions/synology-chat 같은 일치하는 패키징 소스 경로 위에 bind-mount하세요. OpenClaw는 /app/dist/extensions/synology-chat보다 먼저 해당 mount된 소스 overlay를 발견합니다. 단순히 복사된 소스 디렉터리는 비활성 상태로 남으므로 일반 패키지 설치는 여전히 컴파일된 dist를 사용합니다.
런타임 hook 디버깅:
openclaw plugins inspect <id> --runtime --json은 module-loaded inspection pass에서 등록된 hook과 diagnostics를 표시합니다. 런타임 inspection은 dependencies를 설치하지 않습니다. 레거시 dependency 상태를 정리하거나 config에서 참조하는 누락된 다운로드 가능 Plugin을 복구하려면openclaw doctor --fix를 사용하세요.openclaw gateway status --deep --require-rpc는 도달 가능한 Gateway, service/process 힌트, config 경로 및 RPC 상태를 확인합니다.- 번들되지 않은 conversation 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에 추가됨).
linked 설치는 관리되는 설치 대상 위로 복사하는 대신 소스 경로를 재사용하므로
--force는 --link와 함께 지원되지 않습니다.npm 설치에서 --pin을 사용하면 기본 동작은 고정하지 않은 상태로 유지하면서, 해석된 정확한 spec(name@version)을 관리되는 Plugin 인덱스에 저장할 수 있습니다.Plugin 인덱스
Plugin 설치 메타데이터는 사용자 config가 아니라 기계가 관리하는 상태입니다. 설치와 업데이트는 활성 OpenClaw 상태 디렉터리 아래plugins/installs.json에 이를 기록합니다. 최상위 installRecords map은 깨졌거나 누락된 Plugin manifest의 record를 포함해 설치 메타데이터의 지속적인 소스입니다. plugins 배열은 manifest에서 파생된 콜드 레지스트리 캐시입니다. 이 파일에는 편집 금지 경고가 포함되어 있으며 openclaw plugins update, uninstall, diagnostics 및 콜드 Plugin 레지스트리에서 사용됩니다.
OpenClaw가 config에서 제공된 레거시 plugins.installs record를 발견하면, 런타임 read는 openclaw.json을 다시 쓰지 않고 이를 호환성 입력으로 취급합니다. 명시적 Plugin write와 openclaw doctor --fix는 config write가 허용될 때 해당 record를 Plugin 인덱스로 옮기고 config key를 제거합니다. 어느 한쪽 write가 실패하면 설치 메타데이터가 손실되지 않도록 config record가 유지됩니다.
제거
uninstall은 plugins.entries, 저장된 Plugin 인덱스, Plugin allow/deny list 항목 및 적용 가능한 linked plugins.load.paths 항목에서 Plugin record를 제거합니다. --keep-files가 설정되어 있지 않으면 uninstall은 추적된 관리 설치 디렉터리가 OpenClaw의 Plugin extensions 루트 안에 있을 때 해당 디렉터리도 제거합니다. Active Memory Plugin의 경우 memory slot이 memory-core로 재설정됩니다.
--keep-config는 --keep-files의 deprecated alias로 지원됩니다.업데이트
hooks.internal.installs에서 추적되는 hook-pack 설치에 적용됩니다.
Plugin id와 npm spec 해석
Plugin id와 npm spec 해석
Plugin id를 전달하면 OpenClaw는 해당 Plugin에 대해 기록된 설치 spec을 재사용합니다. 즉 이전에 저장된
@beta 같은 dist-tag와 정확히 고정된 버전은 이후 update <id> 실행에서도 계속 사용됩니다.npm 설치의 경우 dist-tag 또는 정확한 버전이 포함된 명시적 npm 패키지 spec을 전달할 수도 있습니다. OpenClaw는 해당 패키지 이름을 추적 중인 Plugin record로 다시 해석하고, 설치된 해당 Plugin을 업데이트하며, 향후 id 기반 업데이트를 위해 새 npm spec을 기록합니다.버전이나 태그 없이 npm 패키지 이름만 전달해도 추적 중인 Plugin record로 다시 해석됩니다. Plugin이 정확한 버전에 고정되어 있었고 이를 레지스트리의 기본 릴리스 라인으로 되돌리고 싶을 때 사용하세요.Beta 채널 업데이트
Beta 채널 업데이트
openclaw plugins update는 새 spec을 전달하지 않는 한 추적 중인 Plugin spec을 재사용합니다. openclaw update는 추가로 활성 OpenClaw 업데이트 채널을 알고 있습니다. beta 채널에서는 기본 라인의 npm 및 ClawHub Plugin record가 먼저 @beta를 시도한 뒤, Plugin beta 릴리스가 없으면 기록된 기본/latest spec으로 fallback합니다. 이 fallback은 경고로 보고되며 core 업데이트를 실패시키지 않습니다. 정확한 버전과 명시적 태그는 해당 선택자에 계속 고정됩니다.버전 확인 및 무결성 드리프트
버전 확인 및 무결성 드리프트
live npm 업데이트 전에 OpenClaw는 설치된 패키지 버전을 npm 레지스트리 메타데이터와 비교해 확인합니다. 설치된 버전과 기록된 아티팩트 identity가 이미 해석된 대상과 일치하면, 다운로드, 재설치 또는
openclaw.json 재작성 없이 업데이트를 건너뜁니다.저장된 무결성 hash가 있고 가져온 아티팩트 hash가 변경된 경우, OpenClaw는 이를 npm 아티팩트 드리프트로 취급합니다. 대화형 openclaw plugins update 명령은 예상 hash와 실제 hash를 출력하고 계속하기 전에 확인을 요청합니다. 비대화형 update helper는 호출자가 명시적 continuation policy를 제공하지 않는 한 fail closed됩니다.업데이트에서 --dangerously-force-unsafe-install 사용
업데이트에서 --dangerously-force-unsafe-install 사용
--dangerously-force-unsafe-install은 Plugin 업데이트 중 내장 dangerous-code scan false positive에 대한 break-glass override로 plugins update에서도 사용할 수 있습니다. 이 옵션은 여전히 Plugin before_install policy block이나 scan-failure blocking을 우회하지 않으며, hook-pack 업데이트가 아니라 Plugin 업데이트에만 적용됩니다.검사
--runtime을 추가하면 Plugin 모듈을 로드하고 등록된 hook, tool, command, service, Gateway method 및 HTTP route를 포함합니다. 런타임 inspection은 누락된 Plugin dependencies를 직접 보고합니다. 설치와 복구는 openclaw plugins install, openclaw plugins update, openclaw doctor --fix에 남아 있습니다.
Plugin 소유 CLI command는 보통 root openclaw command group으로 설치되지만, Plugin은 openclaw nodes 같은 core parent 아래에 nested command를 등록할 수도 있습니다. inspect --runtime이 cliCommands 아래에 command를 표시한 뒤에는 나열된 경로에서 실행하세요. 예를 들어 demo-git을 등록하는 Plugin은 openclaw demo-git ping으로 확인할 수 있습니다.
각 Plugin은 런타임에서 실제로 등록하는 항목에 따라 분류됩니다:
- plain-capability — 하나의 기능 유형(예: 제공자 전용 Plugin)
- hybrid-capability — 여러 기능 유형(예: 텍스트 + 음성 + 이미지)
- hook-only — 훅만 있고 기능이나 표면 없음
- non-capability — 도구/명령/서비스는 있지만 기능 없음
--json 플래그는 스크립팅과 감사에 적합한 기계 판독 가능 보고서를 출력합니다. inspect --all은 형태, 기능 종류, 호환성 알림, 번들 기능, 훅 요약 열이 포함된 전체 플릿 범위의 표를 렌더링합니다. info는 inspect의 별칭입니다.진단
doctor는 Plugin 로드 오류, 매니페스트/검색 진단, 호환성 알림을 보고합니다. 모두 정상일 때는 No plugin issues detected.를 출력합니다.
구성된 Plugin이 디스크에 있지만 로더의 경로 안전성 검사에 의해 차단된 경우, 구성 검증은 Plugin 항목을 유지하고 present but blocked로 보고합니다. plugins.entries.<id> 또는 plugins.allow 구성을 제거하는 대신, 경로 소유권이나 전역 쓰기 가능 권한 같은 앞선 차단된 Plugin 진단을 수정하세요.
register/activate 내보내기가 없는 경우와 같은 모듈 형태 실패의 경우, OPENCLAW_PLUGIN_LOAD_DEBUG=1로 다시 실행하여 진단 출력에 간결한 내보내기 형태 요약을 포함하세요.
레지스트리
plugins registry를 사용해 영구 레지스트리가 있는지, 최신인지, 오래되었는지 검사하세요. --refresh를 사용해 영구 Plugin 인덱스, 구성 정책, 매니페스트/패키지 메타데이터에서 다시 빌드하세요. 이는 복구 경로이며 런타임 활성화 경로가 아닙니다.
openclaw doctor --fix는 레지스트리 인접 관리형 npm 드리프트도 복구합니다. 관리형 Plugin npm 루트 아래의 고아 또는 복구된 @openclaw/* 패키지가 번들 Plugin을 가리는 경우, doctor는 해당 오래된 패키지를 제거하고 레지스트리를 다시 빌드하여 시작 시 번들 매니페스트를 기준으로 검증하게 합니다. 또한 Doctor는 호스트 openclaw 패키지를 peerDependencies.openclaw를 선언하는 관리형 npm Plugin에 다시 연결하므로, 업데이트나 npm 복구 후 openclaw/plugin-sdk/* 같은 패키지 로컬 런타임 가져오기가 해석됩니다.
마켓플레이스
marketplace.json 경로, owner/repo 같은 GitHub 축약형, GitHub 저장소 URL 또는 git URL을 받습니다. --json은 확인된 소스 레이블과 파싱된 마켓플레이스 매니페스트 및 Plugin 항목을 출력합니다.