​

Plugin Bundles

​

bundles가 존재하는 이유

​

bundle 설치

# 로컬 디렉터리
openclaw plugins install ./my-bundle

# 아카이브
openclaw plugins install ./my-bundle.tgz

# Claude 마켓플레이스
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>

openclaw plugins list
openclaw plugins inspect <id>

openclaw gateway restart

​

OpenClaw가 bundles에서 매핑하는 항목

​

현재 지원됨

​

Skill 콘텐츠

• bundle skill 루트는 일반 OpenClaw skill 루트로 로드됩니다
• Claude commands 루트는 추가 skill 루트로 처리됩니다
• Cursor .cursor/commands 루트는 추가 skill 루트로 처리됩니다

​

Hook packs

• bundle hook 루트는 일반 OpenClaw hook-pack 레이아웃을 사용할 때만 동작합니다. 현재는 주로 Codex 호환 사례입니다:
  • HOOK.md
  • handler.ts 또는 handler.js

​

Pi용 MCP

• 활성화된 bundles는 MCP 서버 config를 제공할 수 있습니다
• OpenClaw는 bundle MCP config를 유효한 내장 Pi 설정의 mcpServers로 병합합니다
• OpenClaw는 지원되는 bundle MCP tools를 내장 Pi agent 턴 동안 노출하며, 이를 위해 stdio 서버를 실행하거나 HTTP 서버에 연결합니다
• 프로젝트 로컬 Pi 설정은 여전히 bundle 기본값 이후에 적용되므로, 필요할 경우 워크스페이스 설정이 bundle MCP 항목을 재정의할 수 있습니다
• bundle MCP tool 카탈로그는 등록 전에 결정론적으로 정렬되므로, 업스트림 listTools() 순서 변경이 prompt-cache tool 블록을 불필요하게 흔들지 않습니다

전송 방식

{
  "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
      }
    }
  }
}

• transport는 "streamable-http" 또는 "sse"로 설정할 수 있으며, 생략하면 OpenClaw는 sse를 사용합니다
• http: 및 https: URL 스킴만 허용됩니다
• headers 값은 ${ENV_VAR} 보간을 지원합니다
• command와 url을 모두 가진 서버 항목은 거부됩니다
• URL 자격 증명(userinfo 및 쿼리 파라미터)은 tool 설명과 로그에서 마스킹됩니다
• connectionTimeoutMs는 stdio 및 HTTP 전송 모두의 기본 30초 연결 시간 초과를 재정의합니다

Tool 이름 지정

• A-Za-z0-9_- 외의 문자는 -로 대체됩니다
• 서버 접두사는 최대 30자로 제한됩니다
• 전체 tool 이름은 최대 64자로 제한됩니다
• 빈 서버 이름은 mcp로 대체됩니다
• 정규화 후 이름이 충돌하면 숫자 접미사로 구분됩니다
• 최종 노출되는 tool 순서는 safe name 기준으로 결정론적으로 정렬되어 반복되는 Pi 턴의 캐시 안정성을 유지합니다

​

내장 Pi 설정

• Claude settings.json은 bundle이 활성화되면 기본 내장 Pi 설정으로 가져와집니다
• OpenClaw는 적용 전에 shell override 키를 정리합니다

• shellPath
• shellCommandPrefix

​

내장 Pi LSP

• 활성화된 Claude bundles는 LSP 서버 config를 제공할 수 있습니다
• OpenClaw는 .lsp.json과 manifest에 선언된 모든 lspServers 경로를 로드합니다
• bundle LSP config는 유효한 내장 Pi LSP 기본값에 병합됩니다
• 현재 실행 가능한 것은 지원되는 stdio 기반 LSP 서버뿐이며, 지원되지 않는 전송은 여전히 openclaw plugins inspect <id>에 표시됩니다

​

감지되지만 실행되지는 않음

• Claude agents, hooks.json 자동화, outputStyles
• Cursor .cursor/agents, .cursor/hooks.json, .cursor/rules
• 기능 보고를 넘어서는 Codex 인라인/app 메타데이터

​

Bundle 형식

​

감지 우선순위

1. openclaw.plugin.json 또는 openclaw.extensions가 있는 유효한 package.json — 네이티브 plugin으로 처리
2. Bundle 마커(.codex-plugin/, .claude-plugin/, 또는 기본 Claude/Cursor 레이아웃) — bundle로 처리

​

보안

• OpenClaw는 임의의 bundle 런타임 모듈을 인프로세스로 로드하지 않습니다
• Skills 및 hook-pack 경로는 plugin 루트 내부에 있어야 합니다(경계 검사됨)
• Settings 파일도 동일한 경계 검사로 읽습니다
• 지원되는 stdio MCP 서버는 하위 프로세스로 실행될 수 있습니다

​

문제 해결

​

관련 항목

• Plugins 설치 및 구성
• Plugins 빌드 — 네이티브 plugin 만들기
• Plugin Manifest — 네이티브 manifest 스키마