Plugin 번들

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

번들이 존재하는 이유

​

번들 설치

# 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가 번들에서 매핑하는 항목

​

현재 지원됨

​

Skill 콘텐츠

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

​

훅 팩

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

​

Pi용 MCP

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

전송

{
  "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를 사용합니다
• 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초 연결 제한 시간을 재정의합니다

도구 이름 지정

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

​

내장 Pi 설정

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

• shellPath
• shellCommandPrefix

​

내장 Pi LSP

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

​

감지되지만 실행되지 않음

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

​

번들 형식

​

감지 우선순위

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

​

런타임 의존성 및 정리

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

​

보안

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

​

문제 해결

​

관련

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