개요

워크스페이스 관리자는 GitHub에서 플러그인 마켓플레이스를 워크스페이스 디렉터리로 가져올 수 있습니다. 마켓플레이스는 가져올 플러그인 목록을 담은 JSON 카탈로그입니다. 가져온 후에는 매일 동기화하여 리포지터리의 변경 사항을 반영하고 플러그인을 최신 상태로 유지합니다.


마켓플레이스 동기화는 플러그인 콘텐츠를 가져오는 기능입니다. 워크스페이스 구성원의 계정을 연결하거나 플러그인에 포함된 앱에 대한 액세스 권한을 부여하지는 않습니다.


플러그인과 플러그인에 포함된 앱에 대한 소개는 ChatGPT 및 Codex의 플러그인을 참조하세요.

시작하기 전에

• 마켓플레이스 리포지터리와 해당 리포지터리가 참조하는 다른 모든 리포지터리에 대한 읽기 권한이 있는 GitHub 계정을 사용하세요. github.com의 공개 및 비공개 리포지터리가 지원됩니다.

• 가져오기에 사용하는 계정으로 해당 리포지터리에 액세스하는 데 필요한 GitHub 조직 승인 절차를 완료하세요.

• 리포지터리 콘텐츠를 검토하세요. 가져오기는 플러그인별 승인 절차 없이 유효한 모든 플러그인을 처리하며, 이후 동기화에서 새 플러그인이 추가될 수 있습니다.

새 플러그인은 설치 정책이 사용 가능으로, 인증 시점이 설치 시로 설정됩니다. 새 마켓플레이스에는 매일 자동 동기화가 활성화되어 있습니다. 가져온 후에는 각 플러그인의 워크스페이스 설정과 필수 앱을 검토하세요.

마켓플레이스 가져오기

1. 관리자 콘솔로 이동하여 원하는 ChatGPT 워크스페이스를 선택하고 플러그인을 여세요. 그런 다음 추가를 선택하고 마켓플레이스 가져오기를 선택하세요.

2. 소스에 https://github.com/example/team-plugins와 같은 리포지터리 URL을 입력하세요. 브랜치나 폴더 URL이 아닌 리포지터리 URL만 사용하세요.

3. 마켓플레이스가 하위 디렉터리에 있으면 경로에 해당 디렉터리를 입력하세요. 예를 들어 team-tools/.agents/plugins/marketplace.json의 경우 team-tools를 입력하세요. 리포지터리 루트에 있으면 경로를 비워 두세요. 매니페스트 파일명은 입력하지 마세요.

4. 필요하면 브랜치, 태그 또는 커밋을 입력하세요. 비워 두면 리포지터리의 기본 브랜치를 사용합니다. 이후 커밋을 반영하려면 브랜치를 사용하세요. 특정 커밋으로 고정하면 해당 리비전이 유지됩니다.

5. 마켓플레이스 가져오기를 선택하고 메시지가 표시되면 GitHub 액세스를 승인하세요.

6. 가져오기 결과를 검토한 다음, 가져온 플러그인을 각각 열어 설치 정책과 필요한 앱을 설정하세요.

규모가 매우 큰 마켓플레이스는 처음 가져올 때 최대 1시간이 걸릴 수 있습니다. 이후 매일 실행되는 동기화는 일반적으로 몇 분 정도 걸립니다.

플러그인을 가져올 수 없는 경우 보고서에 오류 설명이 표시됩니다. 문제가 없는 다른 플러그인은 계속 가져올 수 있습니다.

지원되는 형식

선택한 디렉터리에는 지원되는 매니페스트가 있어야 합니다.

• Codex 마켓플레이스: .agents/plugins/marketplace.json

• Claude 호환 마켓플레이스: .claude-plugin/marketplace.json

• 마켓플레이스 매니페스트가 없는 독립형 Claude 플러그인: .claude-plugin/plugin.json

마켓플레이스 항목은 같은 리포지터리의 플러그인 폴더 또는 지원되는 GitHub 리포지터리 소스를 참조할 수 있습니다. 워크스페이스 가져오기에서는 다른 Git 호스트와 npm 같은 패키지 레지스트리 소스를 지원하지 않습니다.

지원되는 형식, JSON 예시, 소스 필드는 플러그인 관리를 참조하세요.

워크스페이스 액세스 설정하기

GitHub는 플러그인 콘텐츠를 제공하고, 워크스페이스 설정은 설치와 인증을 제어합니다. 가져오기와 동기화 시에는 AVAILABLE이나 ON_USE 같은 리포지터리 정책 값이 적용되지 않습니다. 이 설정은 워크스페이스의 각 플러그인에서 구성하세요.



설치 정책에서 대상 역할별로 사용 가능 또는 설치됨을 선택하세요. 필수 앱도 활성화해야 하며, 구성원은 연결된 서비스에 대한 액세스 권한을 갖추고 필요한 인증을 완료해야 합니다.


플러그인 업데이트를 동기화하거나 기존 플러그인을 GitHub 관리로 전환해도 워크스페이스 정책은 유지됩니다. 플러그인을 가져와도 앱 액세스 권한이 부여되거나 구성원의 계정이 연결되지는 않습니다.


워크스페이스 메뉴 탐색, 앱 액세스, 워크스페이스 제어에 대해서는 플러그인 및 앱의 관리자 제어, 보안, 규정 준수를 참조하세요.

플러그인을 최신 상태로 유지하기

새 마켓플레이스는 매일 업데이트를 확인합니다. 자동 동기화를 기다리지 않고 업데이트를 요청하려면 다음 단계를 따르세요.

1. 관리자 콘솔로 이동하여 원하는 ChatGPT 워크스페이스를 선택하고 플러그인을 여세요.

2. 마켓플레이스를 열고 해당 마켓플레이스를 선택하세요.

3. 지금 동기화를 선택하세요.

동기화를 통해 마켓플레이스의 새 항목을 추가하고 기존 플러그인을 업데이트할 수 있습니다. 자동 동기화는 별도의 가져오기 단계 없이 새 플러그인을 가져올 수 있으므로, 리포지터리의 변경 사항을 병합하기 전에 검토하세요.

동기화 결과 검토하기

동기화 후에는 상태와 저장된 보고서를 검토하세요. 완료 — 오류 N개는 동기화가 끝났지만 일부 플러그인을 처리하지 못했다는 뜻입니다.


기존 플러그인의 업데이트가 유효하지 않으면 마지막으로 정상 작동한 버전이 유지됩니다. 문제가 없는 다른 업데이트는 계속 완료할 수 있습니다. GitHub에서 보고된 문제를 수정한 다음 지금 동기화를 선택하여 다시 시도하세요.


관리자 화면에서 개별적으로 가져온 플러그인에 새로고침이 표시되면 이를 사용하여 해당 플러그인을 새로고침하세요. 플러그인 목록 새로고침은 표시된 목록만 다시 불러오며, GitHub에서 동기화하지는 않습니다.

제거와 삭제 이해하기

리포지터리에서 항목을 제거해도 워크스페이스로 가져온 사본은 삭제되지 않습니다. 해당 플러그인에는 소스에 더 이상 없음이 표시됩니다.


ChatGPT에서 마켓플레이스를 삭제하면 해당 마켓플레이스에서 가져온 모든 플러그인이 삭제됩니다. GitHub를 다시 연결하거나 소유권을 변경하려는 목적으로 마켓플레이스를 삭제하지 마세요.

GitHub 액세스 재연결 또는 변경하기

마켓플레이스 동기화는 해당 마켓플레이스를 가져온 관리자의 GitHub 연결을 사용합니다. 해당 계정은 마켓플레이스 리포지터리와 참조된 모든 리포지터리에 대한 액세스 권한을 계속 유지해야 합니다.

기존 계정 다시 연결하기

1. 가져오기에 사용한 GitHub 계정에 필요한 모든 리포지터리에 대한 액세스 권한이 여전히 있는지 확인하세요.

2. 처음 마켓플레이스를 가져온 관리자에게 ChatGPT에서 GitHub 플러그인을 열고 자신의 계정을 다시 연결하도록 요청하세요.

새 관리자에게 이전하기

새 워크스페이스 관리자는 자신의 GitHub 연결을 사용하여 같은 마켓플레이스를 가져올 수 있습니다.

1. 관리자 콘솔로 이동하여 원하는 ChatGPT 워크스페이스를 선택하고 플러그인을 여세요. 그런 다음 추가 > 마켓플레이스 가져오기를 선택하세요.

2. 기존 마켓플레이스에 사용한 것과 동일한 소스, 경로, 브랜치, 태그 또는 커밋 값을 입력하세요.

3. 마켓플레이스 가져오기를 선택하고 메시지가 표시되면 GitHub 액세스를 승인하세요.

이후 동기화는 새 관리자의 GitHub 연결을 사용합니다. 새 관리자의 계정에는 마켓플레이스 리포지터리와 해당 리포지터리가 참조하는 모든 리포지터리에 대한 읽기 권한이 있어야 합니다.

기존 플러그인을 GitHub 관리로 전환하기

아카이브로 업로드했거나 아직 GitHub 소스로 관리하지 않는 기존 워크스페이스 플러그인을 마켓플레이스로 관리할 수 있습니다. 기존 플러그인은 같은 워크스페이스에 있어야 하며, 플러그인 이름도 같아야 합니다. 다른 GitHub 소스에서 관리하는 플러그인은 이 방식으로 관리 소스를 변경할 수 없습니다.


마켓플레이스에서 기존 플러그인을 식별하려면 다음 단계를 따르세요.

1. 관리자 콘솔로 이동하여 원하는 ChatGPT 워크스페이스를 선택하고 플러그인을 여세요. 해당 플러그인을 여세요.

2. URL에서 /admin/plugins/ 뒤에 있는 플러그인 ID를 복사하세요.

3. 마켓플레이스의 plugins 배열에서 해당 항목을 찾아 name, source와 함께 pluginId 필드를 추가하고, 복사한 ID를 값으로 입력하세요. 플러그인의 plugin.json 파일에는 추가하지 마세요.

플러그인의 ID, 공유 설정, 워크스페이스 정책은 유지됩니다. 이후 업데이트는 GitHub를 소스로 사용하므로, 나중에 아카이브를 업로드해도 해당 플러그인을 대체할 수 없습니다.


마이그레이션 예시와 요구 사항은 플러그인 관리를 참조하세요.

기존 앱 참조하기

플러그인은 루트 디렉터리의 .app.json에서 기존 앱을 참조할 수 있습니다. 파일명 앞에 점을 포함하고, 플러그인 ID가 아닌 앱 ID를 사용하세요. 네이티브 플러그인의 경우 .codex-plugin/plugin.json의 apps 필드를 ./.app.json으로 설정하세요.


참조를 추가해도 앱이 생성되거나 추가 권한이 부여되지는 않습니다. 앱의 기존 워크스페이스 액세스, 인증, 작업 제어 및 연결된 서비스의 권한이 그대로 적용됩니다.


JSON 형식은 플러그인 관리를 참조하세요.

데스크톱 전용 표시 이해하기

데스크톱 전용으로 표시된 플러그인은 웹 버전 ChatGPT에서 실행할 수 없습니다. 가져온 플러그인이 mcp.json이나 .mcp.json 등에 MCP 서버를 선언하면, 서버가 원격 HTTPS URL을 사용하더라도 이 표시가 붙을 수 있습니다.



.app.json 참조를 추가하는 것만으로는 데스크톱 전용 표시가 제거되지 않습니다. 참조된 모든 앱은 구성원의 역할에서 사용 가능해야 하며, 앱의 일반적인 액세스 및 인증 요구 사항이 그대로 적용됩니다.