​

플러그인 매니페스트 (openclaw.plugin.json)

• Codex 번들: .codex-plugin/plugin.json
• Claude 번들: .claude-plugin/plugin.json 또는 manifest가 없는 기본 Claude component 레이아웃
• Cursor 번들: .cursor-plugin/plugin.json

​

이 파일의 역할

• plugin 식별
• config 검증
• plugin 런타임을 부팅하지 않고도 사용할 수 있어야 하는 auth 및 onboarding 메타데이터
• plugin 런타임이 로드되기 전에 해석되어야 하는 alias 및 자동 활성화 메타데이터
• plugin 런타임이 로드되기 전에 plugin을 자동 활성화해야 하는 shorthand model-family 소유권 메타데이터
• 번들 호환 연결 및 계약 커버리지에 사용되는 정적 기능 소유권 스냅샷
• 런타임을 로드하지 않고 카탈로그 및 검증 표면에 병합되어야 하는 채널별 config 메타데이터
• config UI 힌트

• 런타임 동작 등록
• 코드 entrypoint 선언
• npm 설치 메타데이터

​

최소 예시

{
  "id": "voice-call",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  }
}

​

확장 예시

{
  "id": "openrouter",
  "name": "OpenRouter",
  "description": "OpenRouter provider plugin",
  "version": "1.0.0",
  "providers": ["openrouter"],
  "modelSupport": {
    "modelPrefixes": ["router-"]
  },
  "cliBackends": ["openrouter-cli"],
  "providerAuthEnvVars": {
    "openrouter": ["OPENROUTER_API_KEY"]
  },
  "providerAuthChoices": [
    {
      "provider": "openrouter",
      "method": "api-key",
      "choiceId": "openrouter-api-key",
      "choiceLabel": "OpenRouter API 키",
      "groupId": "openrouter",
      "groupLabel": "OpenRouter",
      "optionKey": "openrouterApiKey",
      "cliFlag": "--openrouter-api-key",
      "cliOption": "--openrouter-api-key <key>",
      "cliDescription": "OpenRouter API 키",
      "onboardingScopes": ["text-inference"]
    }
  ],
  "uiHints": {
    "apiKey": {
      "label": "API 키",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  },
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": {
        "type": "string"
      }
    }
  }
}

​

최상위 필드 참조

​

providerAuthChoices 참조

​

uiHints 참조

{
  "uiHints": {
    "apiKey": {
      "label": "API 키",
      "help": "OpenRouter 요청에 사용됨",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  }
}

​

contracts 참조

{
  "contracts": {
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "mediaUnderstandingProviders": ["openai", "openai-codex"],
    "imageGenerationProviders": ["openai"],
    "videoGenerationProviders": ["qwen"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}

​

channelConfigs 참조

{
  "channelConfigs": {
    "matrix": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "homeserverUrl": { "type": "string" }
        }
      },
      "uiHints": {
        "homeserverUrl": {
          "label": "Homeserver URL",
          "placeholder": "https://matrix.example.com"
        }
      },
      "label": "Matrix",
      "description": "Matrix homeserver connection",
      "preferOver": ["matrix-legacy"]
    }
  }
}

​

modelSupport 참조

{
  "modelSupport": {
    "modelPrefixes": ["gpt-", "o1", "o3", "o4"],
    "modelPatterns": ["^computer-use-preview"]
  }
}

• 명시적 provider/model ref는 소유 providers manifest 메타데이터를 사용합니다
• modelPatterns가 modelPrefixes보다 우선합니다
• 하나의 비번들 plugin과 하나의 번들 plugin이 모두 일치하면 비번들 plugin이 우선합니다
• 남은 모호성은 사용자 또는 config가 provider를 지정할 때까지 무시됩니다

​

Manifest와 package.json의 차이

• OpenClaw가 plugin 코드를 로드하기 전에 알아야 한다면 openclaw.plugin.json에 두세요
• 패키징, 엔트리 파일 또는 npm 설치 동작에 관한 것이라면 package.json에 두세요

​

discovery에 영향을 주는 package.json 필드

​

JSON Schema 요구 사항

• 모든 plugin은 JSON Schema를 포함해야 하며, config를 받지 않더라도 예외는 없습니다.
• 빈 스키마도 허용됩니다(예: { "type": "object", "additionalProperties": false }).
• 스키마는 런타임이 아니라 config 읽기/쓰기 시점에 검증됩니다.

​

검증 동작

• plugin manifest에서 채널 ID를 선언하지 않은 한, 알 수 없는 channels.* 키는 오류입니다.
• plugins.entries.<id>, plugins.allow, plugins.deny, plugins.slots.*는 반드시 발견 가능한 plugin ID를 참조해야 합니다. 알 수 없는 ID는 오류입니다.
• plugin이 설치되어 있지만 manifest 또는 schema가 깨졌거나 누락된 경우, 검증은 실패하고 Doctor가 plugin 오류를 보고합니다.
• plugin config가 존재하지만 plugin이 비활성화된 경우, config는 유지되며 Doctor + 로그에 경고가 표시됩니다.

​

참고

• manifest는 로컬 파일시스템 로드를 포함한 네이티브 OpenClaw plugins에 필수입니다.
• 런타임은 여전히 plugin 모듈을 별도로 로드합니다. manifest는 discovery + validation 전용입니다.
• 네이티브 manifest는 JSON5로 파싱되므로 주석, 후행 쉼표, 따옴표 없는 키도 최종 값이 여전히 객체인 한 허용됩니다.
• manifest 로더는 문서화된 manifest 필드만 읽습니다. 여기에 사용자 지정 최상위 키를 추가하지 마세요.
• providerAuthEnvVars는 auth probe, env-marker 검증 및 이와 유사한 provider-auth 표면을 위해 plugin 런타임을 부팅하지 않고 env 이름만 검사해야 할 때 사용하는 가벼운 메타데이터 경로입니다.
• providerAuthChoices는 auth-choice picker, --auth-choice 해석, preferred-provider 매핑, 그리고 provider 런타임이 로드되기 전의 단순 onboarding CLI flag 등록을 위한 가벼운 메타데이터 경로입니다. provider 코드가 필요한 런타임 wizard 메타데이터는 Provider runtime hooks를 참조하세요.
• 배타적 plugin 종류는 plugins.slots.*를 통해 선택됩니다.
  • kind: "memory"는 plugins.slots.memory로 선택됩니다.
  • kind: "context-engine"는 plugins.slots.contextEngine으로 선택됩니다 (기본값: 내장 legacy).
• plugin에 필요 없으면 channels, providers, cliBackends, skills는 생략할 수 있습니다.
• plugin이 네이티브 모듈에 의존한다면 빌드 단계와 패키지 관리자 allowlist 요구 사항(예: pnpm allow-build-scripts
  • pnpm rebuild <package>)을 문서화하세요.

​

관련

• Building Plugins — plugin 시작하기
• Plugin Architecture — 내부 아키텍처
• SDK Overview — Plugin SDK 참조