Plugin bundles

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

핵심 요약

Install and use Codex, Claude, and Cursor bundles as OpenClaw plugins

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

문서 구성

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

Why bundles exist
Install a bundle
What OpenClaw maps from bundles
Supported now
Detected but not executed
Bundle formats
Detection precedence
Runtime dependencies and cleanup
보안
트러블슈팅
관련 문서

상세 내용

본문

OpenClaw can install plugins from three external ecosystems: Codex, Claude, and Cursor. These are called bundles - content and metadata packs that OpenClaw maps into native features like skills, hooks, and MCP tools.

Why bundles exist

Many useful plugins are published in Codex, Claude, or Cursor format. Instead of requiring authors to rewrite them as native OpenClaw plugins, OpenClaw detects these formats and maps their supported content into the native feature set. You can install a Claude command pack or a Codex skill bundle and use it immediately.

Install a bundle

`` is a local marketplace path/repo or a git/GitHub source.

# Local directory
    openclaw plugins install ./my-bundle

    # Archive
    openclaw plugins install ./my-bundle.tgz

    # Claude marketplace
    openclaw plugins marketplace list <source>
    openclaw plugins install <plugin> --marketplace <source>

openclaw plugins list
    openclaw plugins inspect <id>

openclaw gateway restart

What OpenClaw maps from bundles

Not every bundle feature runs in OpenClaw today. Here is what works and what is detected but not yet wired.

Supported now

Claude markdown command files and Cursor command markdown both work through the normal OpenClaw skill loader.

주요 항목:

Bundle skill roots load as normal OpenClaw skill roots.
Claude commands/ roots are treated as additional skill roots.
Cursor .cursor/commands/ roots are treated as additional skill roots.
Enabled bundles can contribute MCP server config.
OpenClaw merges bundle MCP config into the effective embedded OpenClaw
OpenClaw exposes supported bundle MCP tools during embedded OpenClaw agent
The coding and messaging tool profiles include bundle MCP tools by
Project-local embedded agent settings still apply after bundle defaults, so
Bundle MCP tool catalogs are sorted deterministically before registration, so
transport accepts "streamable-http" or "sse"; omitted defaults to sse.
type: "http" is a CLI-native downstream shape; use transport: "streamable-http" in OpenClaw config. openclaw mcp set and openclaw doctor --fix normalize the common alias.
Only http: and https: URL schemes are allowed.
headers values support ${ENV_VAR} interpolation.
A server entry with both command and url is rejected.
URL credentials (userinfo and query params) are redacted from tool
connectionTimeoutMs overrides the default 30-second connection timeout for
Characters outside A-Za-z0-9_- are replaced with -.
Fragments that would start with a non-letter get a letter prefix, so numeric
Server prefixes are capped at 30 characters.
Full tool names are capped at 64 characters.
Empty server names fall back to mcp.
Colliding sanitized names are disambiguated with numeric suffixes.
Final exposed tool order is deterministic by safe name, keeping repeated
Profile filtering treats every tool from one bundle MCP server as
shellPath

Feature	How it maps	Applies to
Skill content	Bundle skill roots load as normal OpenClaw skills	All formats
Commands	`commands/` and `.cursor/commands/` treated as skill roots	Claude, Cursor
Hook packs	OpenClaw-style `HOOK.md` + `handler.ts` layouts	Codex
MCP tools	Bundle MCP config merged into embedded OpenClaw settings; supported stdio and HTTP servers loaded	All formats
LSP servers	Claude `.lsp.json` and manifest-declared `lspServers` merged into embedded OpenClaw LSP defaults	Claude
Settings	Claude `settings.json` imported as embedded OpenClaw defaults	Claude

{
  "mcp": {
    "servers": {
      "my-server": {
        "command": "node",
        "args": ["server.js"],
        "env": { "PORT": "3000" }
      }
    }
  }
}

{
  "mcp": {
    "servers": {
      "my-server": {
        "url": "http://localhost:3100/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer ${MY_SECRET_TOKEN}"
        },
        "connectionTimeoutMs": 30000
      }
    }
  }
}

Detected but not executed

These are recognized and shown in diagnostics, but OpenClaw does not run them:

주요 항목:

Claude agents, hooks/hooks.json automation, outputStyles
Cursor .cursor/agents, .cursor/hooks.json, .cursor/rules
Codex .app.json metadata beyond capability reporting

Bundle formats

Optional content: skills/, hooks/, .mcp.json, .app.json

주요 항목:

Manifest-based: .claude-plugin/plugin.json
Manifestless: default Claude layout (skills/, commands/, agents/, hooks/, .mcp.json, .lsp.json, settings.json)
commands/ is treated as skill content
settings.json is imported into embedded OpenClaw settings (shell override keys are sanitized)
.mcp.json exposes supported stdio tools to embedded OpenClaw
.lsp.json plus manifest-declared lspServers paths load into embedded OpenClaw LSP defaults
hooks/hooks.json is detected but not executed
Custom component paths in the manifest are additive; they extend defaults, not replace them
.cursor/commands/ is treated as skill content
.cursor/rules/, .cursor/agents/, and .cursor/hooks.json are detect-only

Detection precedence

OpenClaw checks for native plugin format first:

Runtime dependencies and cleanup

should be installed through openclaw plugins install and ship everything they need in the installed plugin directory.

주요 항목:

Third-party compatible bundles do not get startup npm install repair. They
OpenClaw-owned bundled plugins are either shipped lightweight in core or
openclaw doctor --fix removes stale local bundled-plugin install records

보안

Bundles have a narrower trust boundary than native plugins:

주요 항목:

OpenClaw does not load arbitrary bundle runtime modules in-process.
Skills and hook-pack paths must stay inside the plugin root (boundary-checked).
Settings files are read with the same boundary checks.
Supported stdio MCP servers may be launched as subprocesses.

트러블슈팅

Run openclaw plugins inspect . If a capability is listed but marked as not wired, that is a product limit, not a broken install.

실습 체크리스트

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

자주 쓰는 명령·설정 예시

# Local directory
    openclaw plugins install ./my-bundle

    # Archive
    openclaw plugins install ./my-bundle.tgz

    # Claude marketplace
    openclaw plugins marketplace list <source>
    openclaw plugins install <plugin> --marketplace <source>

openclaw plugins list
    openclaw plugins inspect <id>

openclaw gateway restart

{
  "mcp": {
    "servers": {
      "my-server": {
        "command": "node",
        "args": ["server.js"],
        "env": { "PORT": "3000" }
      }
    }
  }
}

{
  "mcp": {
    "servers": {
      "my-server": {
        "url": "http://localhost:3100/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer ${MY_SECRET_TOKEN}"
        },
        "connectionTimeoutMs": 30000
      }
    }
  }
}

Plugin bundles

핵심 요약

Install and use Codex, Claude, and Cursor bundles as OpenClaw plugins

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

문서 구성

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

Why bundles exist
Install a bundle
What OpenClaw maps from bundles
Supported now
Detected but not executed
Bundle formats
Detection precedence
Runtime dependencies and cleanup
보안
트러블슈팅
관련 문서

상세 내용

본문

Why bundles exist

Install a bundle

`` is a local marketplace path/repo or a git/GitHub source.

# Local directory
    openclaw plugins install ./my-bundle

    # Archive
    openclaw plugins install ./my-bundle.tgz

    # Claude marketplace
    openclaw plugins marketplace list <source>
    openclaw plugins install <plugin> --marketplace <source>

openclaw plugins list
    openclaw plugins inspect <id>

openclaw gateway restart

What OpenClaw maps from bundles

Not every bundle feature runs in OpenClaw today. Here is what works and what is detected but not yet wired.

Supported now

Claude markdown command files and Cursor command markdown both work through the normal OpenClaw skill loader.

주요 항목:

Bundle skill roots load as normal OpenClaw skill roots.
Claude commands/ roots are treated as additional skill roots.
Cursor .cursor/commands/ roots are treated as additional skill roots.
Enabled bundles can contribute MCP server config.
OpenClaw merges bundle MCP config into the effective embedded OpenClaw
OpenClaw exposes supported bundle MCP tools during embedded OpenClaw agent
The coding and messaging tool profiles include bundle MCP tools by
Project-local embedded agent settings still apply after bundle defaults, so
Bundle MCP tool catalogs are sorted deterministically before registration, so
transport accepts "streamable-http" or "sse"; omitted defaults to sse.
type: "http" is a CLI-native downstream shape; use transport: "streamable-http" in OpenClaw config. openclaw mcp set and openclaw doctor --fix normalize the common alias.
Only http: and https: URL schemes are allowed.
headers values support ${ENV_VAR} interpolation.
A server entry with both command and url is rejected.
URL credentials (userinfo and query params) are redacted from tool
connectionTimeoutMs overrides the default 30-second connection timeout for
Characters outside A-Za-z0-9_- are replaced with -.
Fragments that would start with a non-letter get a letter prefix, so numeric
Server prefixes are capped at 30 characters.
Full tool names are capped at 64 characters.
Empty server names fall back to mcp.
Colliding sanitized names are disambiguated with numeric suffixes.
Final exposed tool order is deterministic by safe name, keeping repeated
Profile filtering treats every tool from one bundle MCP server as
shellPath

Feature	How it maps	Applies to
Skill content	Bundle skill roots load as normal OpenClaw skills	All formats
Commands	`commands/` and `.cursor/commands/` treated as skill roots	Claude, Cursor
Hook packs	OpenClaw-style `HOOK.md` + `handler.ts` layouts	Codex
MCP tools	Bundle MCP config merged into embedded OpenClaw settings; supported stdio and HTTP servers loaded	All formats
LSP servers	Claude `.lsp.json` and manifest-declared `lspServers` merged into embedded OpenClaw LSP defaults	Claude
Settings	Claude `settings.json` imported as embedded OpenClaw defaults	Claude

{
  "mcp": {
    "servers": {
      "my-server": {
        "command": "node",
        "args": ["server.js"],
        "env": { "PORT": "3000" }
      }
    }
  }
}

{
  "mcp": {
    "servers": {
      "my-server": {
        "url": "http://localhost:3100/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer ${MY_SECRET_TOKEN}"
        },
        "connectionTimeoutMs": 30000
      }
    }
  }
}

Detected but not executed

These are recognized and shown in diagnostics, but OpenClaw does not run them:

주요 항목:

Claude agents, hooks/hooks.json automation, outputStyles
Cursor .cursor/agents, .cursor/hooks.json, .cursor/rules
Codex .app.json metadata beyond capability reporting

Bundle formats

Optional content: skills/, hooks/, .mcp.json, .app.json

주요 항목:

Manifest-based: .claude-plugin/plugin.json
Manifestless: default Claude layout (skills/, commands/, agents/, hooks/, .mcp.json, .lsp.json, settings.json)
commands/ is treated as skill content
settings.json is imported into embedded OpenClaw settings (shell override keys are sanitized)
.mcp.json exposes supported stdio tools to embedded OpenClaw
.lsp.json plus manifest-declared lspServers paths load into embedded OpenClaw LSP defaults
hooks/hooks.json is detected but not executed
Custom component paths in the manifest are additive; they extend defaults, not replace them
.cursor/commands/ is treated as skill content
.cursor/rules/, .cursor/agents/, and .cursor/hooks.json are detect-only

Detection precedence

OpenClaw checks for native plugin format first:

Runtime dependencies and cleanup

should be installed through openclaw plugins install and ship everything they need in the installed plugin directory.

주요 항목:

Third-party compatible bundles do not get startup npm install repair. They
OpenClaw-owned bundled plugins are either shipped lightweight in core or
openclaw doctor --fix removes stale local bundled-plugin install records

보안

Bundles have a narrower trust boundary than native plugins:

주요 항목:

OpenClaw does not load arbitrary bundle runtime modules in-process.
Skills and hook-pack paths must stay inside the plugin root (boundary-checked).
Settings files are read with the same boundary checks.
Supported stdio MCP servers may be launched as subprocesses.

트러블슈팅

Run openclaw plugins inspect . If a capability is listed but marked as not wired, that is a product limit, not a broken install.

실습 체크리스트

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

자주 쓰는 명령·설정 예시

# Local directory
    openclaw plugins install ./my-bundle

    # Archive
    openclaw plugins install ./my-bundle.tgz

    # Claude marketplace
    openclaw plugins marketplace list <source>
    openclaw plugins install <plugin> --marketplace <source>

openclaw plugins list
    openclaw plugins inspect <id>

openclaw gateway restart

{
  "mcp": {
    "servers": {
      "my-server": {
        "command": "node",
        "args": ["server.js"],
        "env": { "PORT": "3000" }
      }
    }
  }
}

{
  "mcp": {
    "servers": {
      "my-server": {
        "url": "http://localhost:3100/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer ${MY_SECRET_TOKEN}"
        },
        "connectionTimeoutMs": 30000
      }
    }
  }
}

Plugin bundles

핵심 요약

문서 구성

상세 내용

본문

Why bundles exist

Install a bundle

What OpenClaw maps from bundles

Supported now

Detected but not executed

Bundle formats

Detection precedence

Runtime dependencies and cleanup

보안

트러블슈팅

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Plugin bundles

핵심 요약

문서 구성

상세 내용

본문

Why bundles exist

Install a bundle

What OpenClaw maps from bundles

Supported now

Detected but not executed

Bundle formats

Detection precedence

Runtime dependencies and cleanup

보안

트러블슈팅

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드