Plugin manifest (openclaw.plugin.json)

모든 plugin은 plugin 루트에 openclaw.plugin.json 파일을 반드시 포함해야 합니다. OpenClaw는 이 manifest를 사용하여 plugin 코드를 실행하지 않고 설정을 검증합니다. 누락되거나 유효하지 않은 manifest는 plugin 오류로 처리되며 설정 검증을 차단합니다.

전체 plugin 시스템 가이드: Plugins.

필수 필드

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

필수 키:

  • id (string): 정식 plugin ID
  • configSchema (object): plugin 설정을 위한 JSON Schema (인라인)

선택적 키:

  • kind (string): plugin 종류 (예: "memory")
  • channels (array): 이 plugin이 등록하는 channel ID (예: ["matrix"])
  • providers (array): 이 plugin이 등록하는 provider ID
  • skills (array): 로드할 skill 디렉토리 (plugin 루트 기준 상대 경로)
  • name (string): plugin 표시 이름
  • description (string): 짧은 plugin 요약
  • uiHints (object): UI 렌더링을 위한 설정 필드 레이블/플레이스홀더/민감 플래그
  • version (string): plugin 버전 (정보용)

JSON Schema 요구 사항

  • 모든 plugin은 설정을 허용하지 않더라도 JSON Schema를 제공해야 합니다.
  • 빈 스키마도 허용됩니다(예: { "type": "object", "additionalProperties": false }).
  • 스키마는 런타임이 아닌 설정 읽기/쓰기 시점에 검증됩니다.

검증 동작

  • 알 수 없는 channels.* 키는 오류입니다. plugin manifest가 선언한 channel ID가 아닌 경우입니다.
  • plugins.entries.<id>, plugins.allow, plugins.deny, plugins.slots.*는 검색 가능한 plugin ID를 참조해야 합니다. 알 수 없는 ID는 오류입니다.
  • Plugin이 설치되었지만 manifest 또는 스키마가 손상되었거나 누락된 경우 검증이 실패하고 Doctor가 plugin 오류를 보고합니다.
  • Plugin 설정이 존재하지만 plugin이 비활성화된 경우 설정은 유지되고 Doctor + 로그에 경고가 표시됩니다.

참고 사항

  • Manifest는 로컬 파일 시스템 로드를 포함한 모든 plugin에 필수입니다.
  • 런타임은 여전히 plugin 모듈을 별도로 로드합니다; manifest는 발견 + 검증용입니다.
  • Plugin이 네이티브 모듈에 의존하는 경우 빌드 단계와 패키지 관리자 허용 목록 요구 사항을 문서화하세요(예: pnpm allow-build-scripts + pnpm rebuild <package>).
← 문서로 돌아가기