Plugin dependency resolution

기준일: 2026-07-26
공식 기준: Plugin dependency resolution

Plugin dependency resolution 문서는 OpenClaw 공식 문서(plugins/dependency-resolution)를 한국어로 정리한 가이드입니다. How OpenClaw installs plugin packages and resolves plugin dependencies 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

How OpenClaw installs plugin packages and resolves plugin dependencies

한국어 가이드 범위: plugins/dependency-resolution 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• Responsibility split
• Install roots
• Local plugins
• Startup and reload
• Bundled plugins
• Legacy cleanup

상세 내용

본문

OpenClaw handles plugin dependencies at install/update time only. Runtime loading never runs a package manager, repairs a dependency tree, or mutates the OpenClaw package directory.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Responsibility split

Plugin packages own their dependency graph:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Runtime dependencies live in the plugin package's dependencies or
• SDK/core imports are peer or supplied OpenClaw imports.
• Local development plugins bring their own already-installed dependencies.
• npm and git plugins install into OpenClaw-owned package roots.
• Discover the plugin source.
• Install or update the package when explicitly requested.
• Record install metadata.
• Load the plugin entrypoint.
• Fail with an actionable error when dependencies are missing.

Install roots

npm installs run in that per-plugin project root with:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• npm packages install into per-plugin projects under
• git packages clone under ~/.openclaw/git.
• Local/path/archive installs are copied or referenced without dependency

cd ~/.openclaw/npm/projects/<encoded-package>
npm install --omit=dev --omit=peer --legacy-peer-deps --ignore-scripts --no-audit --no-fund

pnpm deps:shrinkwrap:generate
pnpm deps:shrinkwrap:check

npm pack --pack-destination /tmp
tar -xOf /tmp/<plugin-package>.tgz package/package.json
tar -tf /tmp/<plugin-package>.tgz | grep '^package/dist/'

tmpdir=$(mktemp -d)
(
  cd "$tmpdir"
  npm init -y >/dev/null
  npm install --package-lock-only --omit=dev --omit=peer --legacy-peer-deps --ignore-scripts /tmp/<plugin-package>.tgz
)
rm -rf "$tmpdir"

Local plugins

Local plugins are developer-controlled directories. OpenClaw never runs npm install, pnpm install, or dependency repair for them; if a local plugin has dependencies, install them in that plugin before loading it.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Startup and reload

Gateway startup and config reload never install plugin dependencies. They read the plugin install records, compute the entrypoint, and load it.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

openclaw plugins update <id>
openclaw plugins install <source>
openclaw doctor --fix

Bundled plugins

Lightweight and core-critical bundled plugins ship as part of OpenClaw. They should either carry no heavy runtime dependency tree, or move out to a downloadable package on ClawHub/npm.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Install shape	Bundled plugin location	Dependency owner
npm install -g openclaw	Built runtime tree inside the package	OpenClaw package and explicit plugin install/update/doctor flows
Git checkout plus pnpm install	extensions/<id> workspace packages	The pnpm workspace, including each plugin package's own dependencies
openclaw plugins install ...	Managed npm project/git/ClawHub root	The plugin install/update flow

Legacy cleanup

Older OpenClaw versions generated bundled-plugin dependency roots at startup or during doctor repair. Current doctor cleanup removes those stale directories and symlinks with --fix, including old plugin-runtime-deps roots, global Node-prefix package symlinks pointing at pruned plugin-runtime-deps targets, .openclaw-runtime-deps* manifests, generated plugin node_modules, install stage directories, and package-local pnpm stores. Packaged postinstall also removes those global symlinks before pruning the legacy target roots, so upgrades do not leave dangling ESM package imports.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/plugins/dependency-resolution
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

cd ~/.openclaw/npm/projects/<encoded-package>
npm install --omit=dev --omit=peer --legacy-peer-deps --ignore-scripts --no-audit --no-fund

pnpm deps:shrinkwrap:generate
pnpm deps:shrinkwrap:check

npm pack --pack-destination /tmp
tar -xOf /tmp/<plugin-package>.tgz package/package.json
tar -tf /tmp/<plugin-package>.tgz | grep '^package/dist/'

tmpdir=$(mktemp -d)
(
  cd "$tmpdir"
  npm init -y >/dev/null
  npm install --package-lock-only --omit=dev --omit=peer --legacy-peer-deps --ignore-scripts /tmp/<plugin-package>.tgz
)
rm -rf "$tmpdir"

npm install --omit=dev --ignore-scripts --no-audit --no-fund

openclaw plugins update <id>
openclaw plugins install <source>
openclaw doctor --fix

관련 링크

• 공식 원문: plugins/dependency-resolution
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.