---
read_when:
    - Codex, Claude 또는 Cursor와 호환되는 번들을 설치하려는 경우
    - OpenClaw가 번들 콘텐츠를 네이티브 기능에 매핑하는 방식을 이해해야 합니다
    - 번들 감지 또는 누락된 기능을 디버깅하고 있습니다
summary: Codex, Claude 및 Cursor 번들을 OpenClaw Plugin으로 설치하고 사용하기
title: Plugin 번들
x-i18n:
    generated_at: "2026-07-12T00:59:39Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: d44006866238f53ee2e3e8126cc4f7ed6f7413534257775f7904c9b877778c59
    source_path: plugins/bundles.md
    workflow: 16
---

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

<Info>
  번들은 네이티브 OpenClaw 플러그인과 **동일하지 않습니다**. 네이티브 플러그인은
  프로세스 내에서 실행되며 모든 기능을 등록할 수 있습니다. 번들은 기능이 선택적으로
  매핑되고 신뢰 경계가 더 좁은 콘텐츠 패키지입니다.
</Info>

## 번들이 존재하는 이유

많은 유용한 플러그인이 Codex, Claude 또는 Cursor 형식으로 게시됩니다. 작성자가 이를 네이티브 OpenClaw 플러그인으로 다시 작성하도록 요구하는 대신, OpenClaw은 이러한 형식을 감지하고 지원되는 콘텐츠를 네이티브 기능 세트에 매핑합니다. Claude 명령 패키지나 Codex Skills 번들을 설치하여 즉시 사용할 수 있습니다.

## 번들 설치

<Steps>
  <Step title="디렉터리, 아카이브 또는 마켓플레이스에서 설치">
    ```bash
    # 로컬 디렉터리
    openclaw plugins install ./my-bundle

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

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

    `<source>`는 로컬 마켓플레이스 경로/저장소 또는 git/GitHub 소스입니다.

  </Step>

  <Step title="감지 확인">
    ```bash
    openclaw plugins list
    openclaw plugins inspect <id>
    ```

    번들에는 `Format: bundle`과 함께 `codex`, `claude` 또는 `cursor`인 `Bundle format:` 값이 표시됩니다.

  </Step>

  <Step title="재시작 후 사용">
    ```bash
    openclaw gateway restart
    ```

    매핑된 기능(Skills, 훅, MCP 도구, LSP 기본값)은 다음 세션에서 사용할 수 있습니다.

  </Step>
</Steps>

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

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

### 현재 지원됨

| 기능          | 매핑 방식                                                                                         | 적용 대상      |
| ------------- | ------------------------------------------------------------------------------------------------- | -------------- |
| Skills 콘텐츠 | 번들의 Skills 루트를 일반 OpenClaw Skills로 로드                                                  | 모든 형식      |
| 명령          | `commands/` 및 `.cursor/commands/`를 Skills 루트로 처리                                           | Claude, Cursor |
| 훅 패키지     | OpenClaw 형식의 `HOOK.md` + `handler.ts` 레이아웃                                                 | Codex          |
| MCP 도구      | 번들 MCP 구성을 내장 OpenClaw 설정에 병합하고 지원되는 stdio 및 HTTP 서버를 로드                  | 모든 형식      |
| LSP 서버      | Claude `.lsp.json` 및 매니페스트에 선언된 `lspServers`를 내장 OpenClaw LSP 기본값에 병합           | Claude         |
| 설정          | Claude `settings.json`을 내장 OpenClaw 기본값으로 가져오기                                        | Claude         |

#### Skills 콘텐츠

- 번들의 Skills 루트는 일반 OpenClaw Skills 루트로 로드됩니다.
- Claude `commands/` 루트는 추가 Skills 루트로 처리됩니다.
- Cursor `.cursor/commands/` 루트는 추가 Skills 루트로 처리됩니다.

Claude 마크다운 명령 파일과 Cursor 명령 마크다운은 모두 일반 OpenClaw Skills 로더를 통해 작동합니다.

#### 훅 패키지

번들 훅 루트는 일반 OpenClaw 훅 패키지 레이아웃인 `HOOK.md`와 `handler.ts` 또는 `handler.js`를 사용하는 경우에만 작동합니다. 현재 이는 주로 Codex 호환 사례에 해당합니다.

#### 내장 OpenClaw용 MCP

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

##### 전송 방식

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

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

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

**HTTP**는 실행 중인 MCP 서버에 연결하며, `streamable-http`를 요청하지 않으면 기본값으로 `sse`를 사용합니다.

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

- `transport`에는 `"streamable-http"` 또는 `"sse"`를 사용할 수 있으며, 생략하면 기본값은 `sse`입니다.
- `type: "http"`는 CLI 네이티브 다운스트림 형식입니다. OpenClaw 구성에서는 `transport: "streamable-http"`를 사용합니다. `openclaw mcp set`과 `openclaw doctor --fix`는 일반적인 별칭을 정규화합니다.
- `http:` 및 `https:` URL 스킴만 허용됩니다.
- `headers` 값은 `${ENV_VAR}` 보간을 지원합니다.
- `command`와 `url`이 모두 있는 서버 항목은 거부됩니다.
- URL 자격 증명(사용자 정보 및 쿼리 매개변수)은 도구 설명과 로그에서 가려집니다.
- `connectionTimeoutMs`는 stdio 및 HTTP 전송 방식 모두에서 기본 연결 제한 시간인 30초를 재정의합니다. 요청 제한 시간의 기본값은 60초이며 `requestTimeoutMs`로 재정의할 수 있습니다.

##### 도구 이름 지정

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

- `A-Za-z0-9_-` 이외의 문자는 `-`로 대체됩니다.
- 문자가 아닌 값으로 시작하게 되는 조각에는 문자 접두사가 추가되므로, `12306` 같은 숫자 서버 키도 공급자에 안전한 도구 접두사가 됩니다.
- 서버 접두사는 최대 30자로 제한됩니다.
- 전체 도구 이름은 최대 64자로 제한됩니다.
- 빈 서버 이름은 `mcp`로 대체됩니다.
- 정리된 이름이 충돌하면 숫자 접미사를 사용하여 구분합니다.
- 최종적으로 노출되는 도구 순서는 안전 이름을 기준으로 결정되므로, 내장 에이전트를 반복 실행해도 캐시가 안정적으로 유지됩니다.
- 프로필 필터링은 하나의 번들 MCP 서버에서 제공하는 모든 도구를 `bundle-mcp`가 소유한 플러그인 도구로 처리하므로, 프로필 허용/거부 목록에서 개별 노출 도구 이름이나 `bundle-mcp` 플러그인 키를 참조할 수 있습니다.

#### 내장 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/hooks.json` 자동화, `outputStyles`
- Cursor `.cursor/agents`, `.cursor/hooks.json`, `.cursor/rules`
- 기능 보고 이외의 Codex `.app.json` 메타데이터

## 번들 형식

<AccordionGroup>
  <Accordion title="Codex 번들">
    표식: `.codex-plugin/plugin.json`

    선택적 콘텐츠: `skills/`, `hooks/`, `.mcp.json`, `.app.json`

    Codex 번들은 Skills 루트와 OpenClaw 형식의 훅 패키지 디렉터리(`HOOK.md` + `handler.ts`)를 사용할 때 OpenClaw에 가장 적합합니다.

  </Accordion>

  <Accordion title="Claude 번들">
    두 가지 감지 모드:

    - **매니페스트 기반:** `.claude-plugin/plugin.json`
    - **매니페스트 없음:** 기본 Claude 레이아웃(`skills/`, `commands/`, `agents/`, `hooks/`, `.mcp.json`, `.lsp.json`, `settings.json`)

    Claude 전용 동작:

    - `commands/`는 Skills 콘텐츠로 처리됩니다.
    - `settings.json`은 내장 OpenClaw 설정으로 가져옵니다(셸 재정의 키는 정리됨).
    - `.mcp.json`은 지원되는 stdio 도구를 내장 OpenClaw에 노출합니다.
    - `.lsp.json`과 매니페스트에 선언된 `lspServers` 경로는 내장 OpenClaw LSP 기본값으로 로드됩니다.
    - `hooks/hooks.json`은 감지되지만 실행되지 않습니다.
    - 매니페스트의 사용자 지정 구성 요소 경로는 추가 방식으로 적용되며, 기본값을 대체하지 않고 확장합니다.

  </Accordion>

  <Accordion title="Cursor 번들">
    표식: `.cursor-plugin/plugin.json`

    선택적 콘텐츠: `skills/`, `.cursor/commands/`, `.cursor/agents/`, `.cursor/rules/`, `.cursor/hooks.json`, `.mcp.json`

    - `.cursor/commands/`는 Skills 콘텐츠로 처리됩니다.
    - `.cursor/rules/`, `.cursor/agents/`, `.cursor/hooks.json`은 감지만 수행합니다.

  </Accordion>
</AccordionGroup>

## 감지 우선순위

OpenClaw은 먼저 네이티브 플러그인 형식을 확인합니다.

1. `openclaw.plugin.json` 또는 `openclaw.extensions`가 포함된 유효한 `package.json` - **네이티브 플러그인**으로 처리
2. 번들 표식(`.codex-plugin/`, `.claude-plugin/` 또는 기본 Claude/Cursor 레이아웃) - **번들**로 처리

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

## 런타임 종속성과 정리

- 타사 호환 번들에는 시작 시 `npm install` 복구가 적용되지 않습니다. 이러한 번들은 `openclaw plugins install`을 통해 설치해야 하며 필요한 모든 항목을 설치된 플러그인 디렉터리에 포함해야 합니다.
- OpenClaw 소유의 번들 플러그인은 코어에 경량 형태로 포함되어 배포되거나 플러그인 설치 프로그램을 통해 다운로드할 수 있습니다. Gateway는 시작 시 이러한 플러그인을 위해 패키지 관리자를 실행하지 않습니다.
- `openclaw doctor --fix`는 오래된 로컬 번들 플러그인 설치 레코드를 제거하며, 구성에서 계속 참조하지만 로컬 플러그인 색인에는 없는 다운로드 가능 플러그인을 복구할 수 있습니다.

## 보안

번들의 신뢰 경계는 네이티브 플러그인보다 좁습니다.

- OpenClaw은 임의의 번들 런타임 모듈을 프로세스 내에서 로드하지 **않습니다**.
- Skills 및 훅 패키지 경로는 플러그인 루트 내부에 있어야 합니다(경계 검사 적용).
- 설정 파일도 동일한 경계 검사를 거쳐 읽습니다.
- 지원되는 stdio MCP 서버는 하위 프로세스로 시작될 수 있습니다.

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

## 문제 해결

<AccordionGroup>
  <Accordion title="번들이 감지되지만 기능이 실행되지 않음">
    `openclaw plugins inspect <id>`를 실행합니다. 기능이 나열되어 있지만 연결되지 않은 것으로 표시되면 설치 오류가 아니라 제품의 제한 사항입니다.
  </Accordion>

  <Accordion title="Claude 명령 파일이 표시되지 않음">
    번들이 활성화되어 있고 마크다운 파일이 감지된 `commands/` 또는 `skills/` 루트 내부에 있는지 확인합니다.
  </Accordion>

  <Accordion title="Claude 설정이 적용되지 않음">
    `settings.json`의 내장 OpenClaw 설정만 지원됩니다. OpenClaw은 번들 설정을 원시 구성 패치로 처리하지 않습니다.
  </Accordion>

  <Accordion title="Claude 훅이 실행되지 않음">
    `hooks/hooks.json`은 감지만 수행합니다. 실행 가능한 훅이 필요하면 OpenClaw 훅 패키지 레이아웃을 사용하거나 네이티브 플러그인을 배포합니다.
  </Accordion>
</AccordionGroup>

## 관련 문서

- [플러그인 설치 및 구성](/ko/tools/plugin)
- [플러그인 빌드](/ko/plugins/building-plugins) - 네이티브 플러그인 만들기
- [플러그인 매니페스트](/ko/plugins/manifest) - 네이티브 매니페스트 스키마
