Plugin 번들

OpenClaw는 세 가지 외부 생태계인 Codex, Claude, Cursor에서 Plugin을 설치할 수 있습니다. 이를 번들이라고 하며, OpenClaw가 Skills, hook, MCP 도구 같은 네이티브 기능으로 매핑하는 콘텐츠 및 메타데이터 팩입니다.

# 번들이 존재하는 이유

유용한 Plugin 중 다수가 Codex, Claude 또는 Cursor 형식으로 게시됩니다. 작성자가 이를 네이티브 OpenClaw Plugin으로 다시 작성하도록 요구하는 대신, OpenClaw는 이러한 형식을 감지하고 지원되는 콘텐츠를 네이티브 기능 집합으로 매핑합니다. 즉 Claude 명령 팩이나 Codex skill 번들을 설치해 즉시 사용할 수 있습니다.

# 번들 설치

# Local directory
openclaw plugins install ./my-bundle

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

# Claude marketplace
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>

openclaw plugins list
openclaw plugins inspect <id>

openclaw gateway restart

# OpenClaw가 번들에서 매핑하는 항목

현재 모든 번들 기능이 OpenClaw에서 실행되는 것은 아닙니다. 다음은 작동하는 항목과 감지되지만 아직 연결되지 않은 항목입니다.

# 현재 지원됨

# Skill 콘텐츠

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

즉 Claude Markdown 명령 파일은 일반 OpenClaw skill 로더를 통해 작동합니다. Cursor 명령 Markdown도 같은 경로를 통해 작동합니다.

# Hook 팩

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

# Pi용 MCP

• 활성화된 번들은 MCP 서버 구성을 제공할 수 있습니다
• OpenClaw는 번들 MCP 구성을 유효한 임베디드 Pi 설정의 mcpServers로 병합합니다
• OpenClaw는 stdio 서버를 시작하거나 HTTP 서버에 연결하여, 임베디드 Pi agent turn 중 지원되는 번들 MCP 도구를 노출합니다
• coding 및 messaging 도구 프로필은 기본적으로 번들 MCP 도구를 포함합니다. agent 또는 Gateway에서 제외하려면 tools.deny: ["bundle-mcp"]를 사용하세요
• 프로젝트 local Pi 설정은 번들 기본값 이후에도 계속 적용되므로, 필요할 때 workspace 설정이 번들 MCP 항목을 재정의할 수 있습니다
• 번들 MCP 도구 카탈로그는 등록 전에 결정적으로 정렬되므로, upstream listTools() 순서 변경이 prompt-cache 도구 블록을 흔들지 않습니다

# 전송

MCP 서버는 stdio 또는 HTTP 전송을 사용할 수 있습니다.

Stdio는 자식 프로세스를 시작합니다.

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

HTTP는 기본적으로 sse를 통해, 요청된 경우 streamable-http를 통해 실행 중인 MCP 서버에 연결합니다.

{
  "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를 사용합니다
• type: "http"는 CLI 네이티브 downstream 형태입니다. OpenClaw 구성에서는 transport: "streamable-http"를 사용하세요. openclaw mcp set 및 openclaw doctor --fix는 일반 alias를 정규화합니다.
• http: 및 https: URL scheme만 허용됩니다
• headers 값은 ${ENV_VAR} 보간을 지원합니다
• command와 url을 모두 포함한 서버 항목은 거부됩니다
• URL 자격 증명(userinfo 및 query params)은 도구 설명과 로그에서 수정 처리됩니다
• connectionTimeoutMs는 stdio 및 HTTP 전송 모두에 대해 기본 30초 연결 제한 시간을 재정의합니다

# 도구 이름 지정

OpenClaw는 번들 MCP 도구를 serverName__toolName 형식의 provider 안전 이름으로 등록합니다. 예를 들어 "vigil-harbor" 키의 서버가 memory_search 도구를 노출하면 vigil-harbor__memory_search로 등록됩니다.

• A-Za-z0-9_- 밖의 문자는 -로 대체됩니다
• 서버 prefix는 30자로 제한됩니다
• 전체 도구 이름은 64자로 제한됩니다
• 빈 서버 이름은 mcp로 대체됩니다
• 정리된 이름이 충돌하면 숫자 suffix로 구분됩니다
• 최종 노출 도구 순서는 safe name 기준으로 결정적이어서 반복되는 Pi turn의 캐시 안정성을 유지합니다
• 프로필 필터링은 하나의 번들 MCP 서버에서 나온 모든 도구를 bundle-mcp가 소유한 Plugin으로 처리하므로, 프로필 allowlist 및 deny list에는 개별 노출 도구 이름이나 bundle-mcp Plugin 키를 포함할 수 있습니다

# 임베디드 Pi 설정

• 번들이 활성화되면 Claude settings.json이 기본 임베디드 Pi 설정으로 가져와집니다
• OpenClaw는 shell override 키를 적용하기 전에 정리합니다

정리된 키:

• shellPath
• shellCommandPrefix

# 임베디드 Pi LSP

• 활성화된 Claude 번들은 LSP 서버 구성을 제공할 수 있습니다
• OpenClaw는 .lsp.json과 매니페스트에 선언된 모든 lspServers 경로를 로드합니다
• 번들 LSP 구성은 유효한 임베디드 Pi LSP 기본값에 병합됩니다
• 현재 지원되는 stdio 기반 LSP 서버만 실행할 수 있습니다. 지원되지 않는 전송도 openclaw plugins inspect <id>에는 계속 표시됩니다

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

다음 항목은 인식되어 진단에 표시되지만, OpenClaw는 실행하지 않습니다.

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

# 번들 형식

# 감지 우선순위

OpenClaw는 먼저 네이티브 Plugin 형식을 확인합니다.

1. openclaw.plugin.json 또는 openclaw.extensions가 포함된 유효한 package.json — 네이티브 Plugin으로 처리됨
2. 번들 마커(.codex-plugin/, .claude-plugin/ 또는 기본 Claude/Cursor 레이아웃) — 번들로 처리됨

디렉터리에 둘 다 포함되어 있으면 OpenClaw는 네이티브 경로를 사용합니다. 이렇게 하면 이중 형식 package가 번들로 부분 설치되는 일을 방지할 수 있습니다.

# 런타임 의존성 및 정리

• 타사 호환 번들은 시작 시 npm install 복구를 받지 않습니다. openclaw plugins install을 통해 설치되어야 하며, 설치된 Plugin 디렉터리에 필요한 모든 것을 포함해 제공해야 합니다.
• OpenClaw 소유 번들 Plugin은 core에 경량으로 포함되어 제공되거나 Plugin 설치 프로그램을 통해 다운로드할 수 있습니다. Gateway 시작은 이들을 위해 package manager를 실행하지 않습니다.
• openclaw doctor --fix는 레거시 staged 의존성 디렉터리를 제거하며, 구성이 참조하지만 local Plugin 인덱스에 없는 다운로드 가능한 Plugin을 복구할 수 있습니다.

# 보안

번들은 네이티브 Plugin보다 더 좁은 신뢰 경계를 가집니다.

• OpenClaw는 임의의 번들 런타임 모듈을 프로세스 내에서 로드하지 않습니다
• Skills 및 hook 팩 경로는 Plugin 루트 안에 있어야 합니다(경계 확인)
• 설정 파일은 동일한 경계 확인으로 읽힙니다
• 지원되는 stdio MCP 서버는 하위 프로세스로 시작될 수 있습니다

이로 인해 번들은 기본적으로 더 안전하지만, 타사 번들은 여전히 이들이 노출하는 기능에 대해 신뢰할 수 있는 콘텐츠로 취급해야 합니다.

# 문제 해결

# 관련 항목

• Plugin 설치 및 구성
• Plugin 빌드 — 네이티브 Plugin 만들기
• Plugin Manifest — 네이티브 매니페스트 schema