플러그인 제출 오류

공개 디렉터리에 제출하는 플러그인에는 워크스페이스에 설치하는 플러그인보다 엄격한 기준이 적용됩니다. 디렉터리에 제출하려면 공통 패키지 검사뿐 아니라 등록 정보 필드, 심사 자료, MCP 도구, 스킬, 에셋, 이미지에 대한 추가 검사도 통과해야 합니다. 이 문서에서는 MCP 서버 참조 검사처럼 제출 포털 밖에서도 실행될 수 있는 공통 패키지 검사도 다룹니다.

제출할 때 반환된 오류 코드로 해당 요구 사항을 찾으세요. 오류가 있으면 제출할 수 없습니다. 경고가 있어도 제출할 수 있지만 계속하기 전에 내용을 확인하세요.

비워 둘 수 없는 값에는 공백이 아닌 문자가 하나 이상 있어야 합니다. 지원되는 텍스트에는 제어 문자, 유니코드 줄 구분자나 단락 구분자, 지원되지 않는 비가시적 서식 문자가 포함되지 않습니다. HTTPS URL에는 호스트가 있어야 하며, 인증 정보나 지원되지 않는 문자가 들어가면 안 됩니다.

디렉터리 최종 제출

패키지가 업로드 검증을 통과해도 디렉터리 최종 제출 단계에서 실패할 수 있습니다. 최종 제출 단계에서는 등록 정보에 더 엄격한 제한을 적용하고 MCP 구성, 스킬 검사 결과, 테스트 케이스, 정책 준수 확인 사항을 검토합니다.

모든 플러그인 제출 시 다음 요건도 충족해야 합니다.

• 패키지에 포함된 모든 스킬이 안전 및 보안 검사를 통과해야 합니다. 검사에는 최대 2시간이 걸릴 수 있습니다.
• 개발자 또는 사업자 신원이 확인되어야 하며 필수 정책 준수 확인 절차를 모두 완료해야 합니다.

원격 MCP 플러그인을 최종 제출할 때는 다음 요건도 충족해야 합니다.

• 위 규칙에 맞는 웹사이트, 지원, 개인정보 보호 정책, 이용약관 URL을 제공하세요.
• 지원하는 플랫폼에서 주요 사용 사례와 도구를 시연하는 녹화 영상의 URL을 제공하세요.
• 정상 동작을 확인하는 테스트 케이스를 정확히 5개, 예외 상황을 확인하는 테스트 케이스를 정확히 3개 제공하고 릴리스 노트를 첨부하세요.
• 프로덕션 HTTPS MCP 서버 URL을 제공하고 도메인 검증 챌린지를 완료하세요. 최신 도구 검사도 통과해야 합니다.
• 모든 MCP 도구에 readOnlyHint, openWorldHint, destructiveHint 값을 명시하고 각 값을 설정한 근거를 제시하세요.
• 서버가 OAuth를 사용한다면 심사자가 바로 사용할 수 있는 데모용 인증 정보를 제공하세요.

최종 제출 메타데이터 오류

다음 오류 이름에서 subtitle은 짧은 설명을, description은 상세 설명을 뜻합니다.

MCP 및 심사 오류

다음 오류는 원격 MCP 제출 시 적용됩니다.

아카이브 오류

ZIP 업로드 오류 및 경고

포털의 스킬 전용 제출 옵션에서는 스킬 ZIP 패키지와 승인된 로컬 MCP 플러그인을 업로드할 수 있습니다. 승인된 로컬 MCP 플러그인에는 스킬이 없어도 됩니다. 오류가 있으면 업로드할 수 없으며 경고가 있으면 확인이 필요합니다.

ZIP 구조 및 제한 오류

플러그인 루트 오류

플러그인 매니페스트 오류

등록 정보 및 인터페이스 오류

플러그인 매니페스트의 interface 객체는 사용자에게 공개되는 디렉터리 등록 정보를 정의합니다. 이 객체는 .codex-plugin/plugin.json에 있으며 displayName, shortDescription 등의 필드를 사용합니다.

{
  "interface": {
    "displayName": "Example Plugin",
    "shortDescription": "Summarize documents",
    "longDescription": "Summarize and organize documents.",
    "developerName": "Example",
    "category": "Productivity",
    "capabilities": ["Summarize documents"]
  }
}

스킬 전용 플러그인을 ZIP으로 업로드할 때는 등록 정보의 URL 4개(웹사이트, 개인정보 보호 정책, 이용약관, 지원)가 선택 사항입니다. 원격 MCP 제출 시에는 모두 필수입니다. 각 URL의 길이 제한은 패키지 검증 시 2,048자, 디렉터리 최종 제출 시 1,024자입니다.

플러그인 콘텐츠 오류

MCP 매니페스트 오류

다음 오류는 호환성을 위한 .mcp.json 파일에 적용됩니다. 이식 가능한 패키지를 가져올 때는 이 파일과 .codex-plugin/plugin.json을 루트의 plugin.json과 mcp.json에서 생성합니다. 위의 구성 요소 경로 오류가 이렇게 생성된 파일을 가리킬 수도 있습니다. 이 경우 이식 가능한 패키지의 원본 구성을 수정하세요. 호환성 진단 메시지에 표시된 이름에 맞추려고 mcp.json의 이름을 .mcp.json으로 변경하지 마세요.

스킬 오류

스킬 에이전트 메타데이터 오류

패키지에 포함된 스킬은 자체 interface를 skills/<skill>/agents/openai.yaml에 정의할 수 있습니다. 이 설정은 스킬이 사용자에게 어떻게 표시되는지 결정하며 플러그인 매니페스트의 interface와는 별개입니다. 스킬 인터페이스 필드 이름에는 snake_case를 사용합니다.

interface:
  display_name: "Summarize documents"
  short_description: "Summarize a document"
  icon_small: "./assets/icon.png"
  default_prompt: "Summarize the selected document."

에셋 경로 오류

이미지 오류

디렉터리에 표시할 브랜드 이미지는 지원되는 파일 형식을 사용하고 아래의 파일 크기 및 이미지 치수 제한을 충족해야 합니다. 이 규칙은 패키지에 포함된 브랜드 에셋에 적용됩니다.

MCP 서버 참조 오류

플러그인이 등록된 MCP 서버를 참조하면 공통 패키지 검사에서 .app.json을 검증합니다. 제출 포털에서는 기존 통합에 대한 참조를 게시하지 않습니다. 스킬 전용 옵션으로 업로드하면 .app.json이 제거됩니다. MCP 서버를 직접 제출하려면 MCP 포함 옵션을 사용하세요.

로컬 패키지와 워크스페이스 패키지에서는 최상위 apps 객체가 각 MCP 서버 별칭을 등록된 서버 항목에 매핑합니다. 이러한 구성 이름과 오류 코드에서는 app 표기를 그대로 사용합니다.

패키지 경고

다음 경고는 검증 과정에서 무시되거나 정규화되는 패키지 콘텐츠를 알려 줍니다. 경고가 있어도 제출할 수 있습니다. 경고 내용을 검토해 제출하는 플러그인에 의도한 파일과 설정이 포함되어 있는지 확인하세요.

다음 단계

검증 오류를 모두 해결한 후 플러그인 제출 페이지로 돌아가 제출을 완료하세요.