Plugin 번들

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

번들이 존재하는 이유

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

번들 설치

# Local directoryopenclaw plugins install ./my-bundle # Archiveopenclaw plugins install ./my-bundle.tgz # Claude marketplaceopenclaw plugins marketplace list <marketplace-name>openclaw plugins install <plugin-name>@<marketplace-name>

openclaw plugins listopenclaw plugins inspect <id>

openclaw gateway restart

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

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

현재 지원됨

Skill 콘텐츠

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

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

훅 팩

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

임베디드 OpenClaw용 MCP

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

전송

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

Stdio는 자식 프로세스를 실행합니다.

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

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

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

도구 이름 지정

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

• A-Za-z0-9_- 외의 문자는 -로 대체됩니다
• 문자가 아닌 것으로 시작할 조각에는 문자 접두사가 붙으므로, 12306 같은 숫자 서버 키도 공급자 안전 도구 접두사가 됩니다
• 서버 접두사는 30자로 제한됩니다
• 전체 도구 이름은 64자로 제한됩니다
• 빈 서버 이름은 mcp로 대체됩니다
• 충돌하는 정제된 이름은 숫자 접미사로 구분됩니다
• 최종 노출 도구 순서는 반복되는 임베디드 에이전트 턴의 캐시를 안정적으로 유지하기 위해 안전 이름 기준으로 결정론적입니다
• 프로필 필터링은 하나의 번들 MCP 서버에서 온 모든 도구를 bundle-mcp가 소유한 Plugin으로 취급하므로, 프로필 허용 목록과 거부 목록에는 개별 노출 도구 이름 또는 bundle-mcp Plugin 키를 포함할 수 있습니다

임베디드 OpenClaw 설정

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

정제된 키:

• shellPath
• shellCommandPrefix

임베디드 OpenClaw LSP

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

감지되지만 실행되지 않음

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

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

번들 형식

감지 우선순위

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

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

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

런타임 의존성 및 정리

• 서드파티 호환 번들은 시작 시 npm install 복구를 받지 않습니다. 이들은 openclaw plugins install을 통해 설치되어야 하며, 필요한 모든 것을 설치된 Plugin 디렉터리에 포함해 배포해야 합니다.
• OpenClaw 소유 번들 Plugin은 코어에 경량으로 포함되어 배포되거나 Plugin 설치 관리자를 통해 다운로드할 수 있습니다. Gateway 시작 시 이들을 위해 패키지 관리자가 실행되는 일은 없습니다.
• openclaw doctor --fix는 레거시 스테이징 의존성 디렉터리를 제거하고, 구성에서 참조하지만 로컬 Plugin 인덱스에 없는 다운로드 가능 Plugin을 복구할 수 있습니다.

보안

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

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

이로 인해 번들은 기본적으로 더 안전하지만, 그래도 서드파티 번들은 노출하는 기능에 대해 신뢰할 수 있는 콘텐츠로 취급해야 합니다.

문제 해결

관련 항목

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