Plugins
기준일: 2026-07-26
공식 기준: Plugins
Plugins 문서는 OpenClaw 공식 문서(cli/plugins)를 한국어로 정리한 가이드입니다. CLI reference for openclaw plugins (init, build, validate, list, install, marketplace, uninstall, enable/disable, doctor) 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.
핵심 요약
CLI reference for openclaw plugins (init, build, validate, list, install, marketplace, uninstall, enable/disable, doctor)
한국어 가이드 범위: cli/plugins 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.
문서 구성
공식 문서의 주요 섹션은 다음과 같습니다.
- 명령
- Author
- Provider scaffold
- 설치
- Marketplace shorthand
- List
- Plugin index
- Uninstall
- Update
- Inspect
- Doctor
- Registry
- Marketplace
- 관련 문서
상세 내용
본문
Manage Gateway plugins, hook packs, and compatible bundles.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
명령
For slow install, inspect, uninstall, or registry-refresh investigation, run the command with OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1. The trace writes phase timings to stderr and keeps JSON output parseable. See Debugging.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
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> # alias for 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 doctor
openclaw 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]
Author
plugins init creates a minimal TypeScript tool plugin by default. The first argument is the plugin id; --name sets the display name. OpenClaw uses the id for the default output directory and package naming. Tool scaffolds use defineToolPlugin and generate package.json scripts plugin:build and plugin:validate that build then call openclaw plugins build/validate.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
openclaw plugins init stock-quotes --name "Stock Quotes"
cd stock-quotes
npm run plugin:build
npm run plugin:validate
Provider scaffold
Provider scaffolds create a generic OpenAI-compatible model provider plugin with API-key auth plumbing, a npm run validate script that runs clawhub package validate, ClawHub package metadata, and a manually dispatched GitHub Actions workflow for future trusted publishing via GitHub OIDC. Provider scaffolds do not generate skills and do not use openclaw plugins build/validate; those commands are for the tool scaffold's generated-metadata path.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
openclaw plugins init acme-models --name "Acme Models" --type provider
cd acme-models
npm install
npm run build
npm test
npm run validate
설치
Maintainers testing setup-time installs can override automatic plugin install sources with guarded environment variables. See Plugin install overrides.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
openclaw plugins search "calendar" # search ClawHub plugins
openclaw plugins install @openclaw/<package> # trusted official catalog
openclaw plugins install <package> # arbitrary npm package
openclaw plugins install clawhub:<package> # ClawHub only
openclaw plugins install npm:<package> # npm only
openclaw plugins install npm-pack:<path.tgz> # local npm-pack tarball
openclaw plugins install git:github.com/<owner>/<repo> # git repo
openclaw plugins install git:github.com/<owner>/<repo>@<ref>
openclaw plugins install <path> # local path or archive
openclaw plugins install -l <path> # link instead of copy
openclaw plugins install <plugin>@<marketplace> # marketplace shorthand
openclaw plugins install <plugin> --marketplace <name> # marketplace (explicit)
openclaw plugins install <package> --force # confirm source / overwrite existing
openclaw plugins install <package> --pin # pin resolved npm version
openclaw plugins install clawhub:<package> --acknowledge-clawhub-risk
openclaw plugins install <package> --dangerously-force-unsafe-install
openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
openclaw plugins install openclaw-codex-app-server
openclaw plugins install npm:openclaw-codex-app-server
openclaw plugins install npm:@openclaw/discord@2026.5.20
openclaw plugins install npm:@scope/plugin-name@1.0.1
Marketplace shorthand
Use plugin@marketplace shorthand when the marketplace name exists in Claude's local registry cache at ~/.claude/plugins/known_marketplaces.json:
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
주요 항목:
- a Claude known-marketplace name from
~/.claude/plugins/known_marketplaces.json - a local marketplace root or
marketplace.jsonpath - a GitHub repo shorthand such as
owner/repo - a GitHub repo URL such as
https://github.com/owner/repo - a git URL
- native OpenClaw plugins (
openclaw.plugin.json) - Codex-compatible bundles (
.codex-plugin/plugin.json) - Claude-compatible bundles (
.claude-plugin/plugin.json, or the default Claude component layout when that manifest file is absent) - Cursor-compatible bundles (
.cursor-plugin/plugin.json)
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>
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 plugins install -l ./my-plugin
List
Switch from the table view to per-plugin detail lines with format/source/origin/version/activation metadata.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
주요 항목:
openclaw plugins inspect <id> --runtime --jsonshows registered hooks and diagnostics from a module-loaded inspection pass. Runtime inspection never installs dependencies; useopenclaw doctor --fixto clean legacy dependency state or recover missing downloadable plugins that are referenced by config.openclaw gateway status --deep --require-rpcconfirms the reachable Gateway URL/profile, service/process hints, config path, and RPC health.- Non-bundled conversation hooks (
llm_input,llm_output,before_model_resolve,before_agent_reply,before_agent_run,before_agent_finalize,agent_end) requireplugins.entries.<id>.hooks.allowConversationAccess=true.
openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
Plugin index
Plugin install metadata is machine-managed state, not user config. Installs and updates write it to the shared SQLite state database under the active OpenClaw state directory. The installed_plugin_index row stores durable installRecords metadata, including records for broken or missing plugin manifests, plus a manifest-derived cold registry cache used by openclaw plugins update, uninstall, diagnostics, and the cold plugin registry.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
Uninstall
uninstall removes plugin records from plugins.entries, the persisted plugin index, plugin allow/deny list entries, and linked plugins.load.paths entries when applicable. Unless --keep-files is set, uninstall also removes the tracked managed install directory, but only when it resolves inside OpenClaw's plugin extensions root. If the plugin currently owns the memory or contextEngine slot, that slot resets to its default (memory-core for memory, legacy for context engine).
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
openclaw plugins uninstall <id>
openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files
openclaw plugins uninstall <id> --force
Update
Updates apply to tracked plugin installs in the managed plugin index and tracked hook-pack installs in shared SQLite state. They reuse the source that the user already chose when installing the plugin, so they do not require a second source acknowledgement.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
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 @acme/demo
openclaw plugins update openclaw-codex-app-server --acknowledge-clawhub-risk
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
Inspect
Inspect shows identity, load status, source, manifest capabilities, policy flags, diagnostics, install metadata, bundle capabilities, and any detected MCP or LSP server support without importing plugin runtime by default. JSON output includes the plugin manifest contracts, such as contracts.agentToolResultMiddleware and contracts.trustedToolPolicies, so operators can audit trusted-surface declarations before enabling or restarting a plugin. Add --runtime to load the plugin module and include registered hooks, tools, commands, services, gateway methods, and HTTP routes. Runtime inspection reports missing plugin dependencies directly; installs and repairs stay in openclaw plugins install, openclaw plugins update, and openclaw doctor --fix.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
| Shape | Meaning |
|---|---|
plain-capability |
exactly one capability type (e.g. a provider-only plugin) |
hybrid-capability |
more than one capability type (e.g. text + speech + images) |
hook-only |
only hooks, no capabilities, tools, commands, services, or routes |
non-capability |
tools/commands/services but no capabilities |
openclaw plugins inspect <id>
openclaw plugins inspect <id> --runtime
openclaw plugins inspect <id> --json
openclaw plugins inspect --all
Doctor
doctor reports plugin load errors, manifest/discovery diagnostics, compatibility notices, and stale plugin config references such as missing plugin slots. When the install tree and plugin config are clean it prints No plugin issues detected. If stale config remains but the install tree is otherwise healthy, the summary says so instead of implying full plugin health.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
openclaw plugins doctor
Registry
The local plugin registry is OpenClaw's persisted cold read model for installed plugin identity, enablement, source metadata, and contribution ownership. Normal startup, provider owner lookup, channel setup classification, and plugin inventory can read it without importing plugin runtime modules.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
openclaw plugins registry
openclaw plugins registry --refresh
openclaw plugins registry --json
Marketplace
plugins marketplace entries lists entries from the configured OpenClaw marketplace feed. By default it attempts the hosted feed and falls back to the latest accepted snapshot or bundled data. Use --feed-profile to read a specific configured profile, --feed-url to read an explicit hosted feed URL, and --offline to read the latest accepted snapshot without fetching the feed.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
openclaw plugins marketplace entries
openclaw plugins marketplace entries --offline
openclaw plugins marketplace entries --json
openclaw plugins marketplace entries --feed-profile <name>
openclaw plugins marketplace entries --feed-url <url>
openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
openclaw plugins marketplace refresh
openclaw plugins marketplace refresh --feed-profile <name>
openclaw plugins marketplace refresh --feed-url <url>
openclaw plugins marketplace refresh --expected-sha256 <sha256> --json
관련 문서
주요 항목:
- Building plugins
- CLI reference
- ClawHub
실습 체크리스트
- 공식 문서와 로컬 버전을 대조합니다:
https://docs.openclaw.ai/cli/plugins - 관련 CLI는
openclaw --help및 하위 명령--help로 옵션을 확인합니다. - 설정 변경 시
openclaw config/openclaw doctor로 유효성을 검사합니다. - Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.
자주 쓰는 명령·설정 예시
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> # alias for 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 doctor
openclaw 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 plugins init stock-quotes --name "Stock Quotes"
cd stock-quotes
npm run plugin:build
npm run plugin:validate
openclaw plugins init acme-models --name "Acme Models" --type provider
cd acme-models
npm install
npm run build
npm test
npm run validate
openclaw plugins search "calendar" # search ClawHub plugins
openclaw plugins install @openclaw/<package> # trusted official catalog
openclaw plugins install <package> # arbitrary npm package
openclaw plugins install clawhub:<package> # ClawHub only
openclaw plugins install npm:<package> # npm only
openclaw plugins install npm-pack:<path.tgz> # local npm-pack tarball
openclaw plugins install git:github.com/<owner>/<repo> # git repo
openclaw plugins install git:github.com/<owner>/<repo>@<ref>
openclaw plugins install <path> # local path or archive
openclaw plugins install -l <path> # link instead of copy
openclaw plugins install <plugin>@<marketplace> # marketplace shorthand
openclaw plugins install <plugin> --marketplace <name> # marketplace (explicit)
openclaw plugins install <package> --force # confirm source / overwrite existing
openclaw plugins install <package> --pin # pin resolved npm version
openclaw plugins install clawhub:<package> --acknowledge-clawhub-risk
openclaw plugins install <package> --dangerously-force-unsafe-install
openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
openclaw plugins install openclaw-codex-app-server
관련 링크
- 공식 원문: cli/plugins
- OpenClaw 문서 홈
이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.