ChatGPT 문서
한국어
문의 goolvyouyou@gmail.com

플러그인 관리

GitHub에서 워크스페이스 플러그인을 가져오고 동기화하기

시작하기 전에

워크스페이스 관리자는 GitHub에서 플러그인 마켓플레이스를 가져오고 저장소를 통해 해당 플러그인을 최신 상태로 유지할 수 있습니다. 마켓플레이스는 가져올 플러그인을 나열한 JSON 카탈로그입니다.

이 페이지에서는 워크스페이스 가져오기와 동기화를 다룹니다. 클라우드 관리형 또는 시스템 config.toml을 통해 로컬 클라이언트에서 마켓플레이스를 직접 구성하려면 플러그인 마켓플레이스 및 기본값 구성을 참고하세요. 특정 프로젝트에서 플러그인을 활성화하거나 비활성화하려면 저장소에서 플러그인 활성화 또는 비활성화를 참고하세요.

마켓플레이스 저장소와 여기서 참조하는 다른 모든 저장소를 읽을 수 있는 GitHub 계정을 사용하세요. 공개 및 비공개 GitHub 저장소를 지원합니다. 가져오기 전에 저장소 액세스에 필요한 GitHub 조직 승인을 모두 완료하세요.

가져오기 전에 저장소 콘텐츠를 검토하세요. 새 플러그인의 설치 정책은 사용 가능 으로, 인증 방식은 설치 시 인증으로 시작됩니다. 새 마켓플레이스에는 매일 자동 동기화가 활성화됩니다. 가져오기는 유효한 항목을 모두 처리하며, 이후 동기화에서는 저장소의 새 플러그인을 자동으로 추가합니다.

마켓플레이스 동기화 구성

  1. 관리자 > 플러그인 을 열고 추가 > 마켓플레이스 가져오기 를 선택합니다.
  2. 소스 에 https://github.com/example/team-plugins 같은 저장소 URL을 입력합니다. 브랜치나 폴더 URL이 아닌 저장소 URL만 사용하세요.
  3. 마켓플레이스가 하위 디렉터리에 있으면 해당 디렉터리를 경로 에 입력합니다. 예를 들어 team-tools/.agents/plugins/marketplace.json의 경우 team-tools를 사용합니다. 저장소 루트를 사용하려면 경로 를 비워 두세요. 매니페스트 파일 이름은 입력하지 마세요.
  4. 필요에 따라 브랜치, 태그 또는 커밋 을 입력합니다. 저장소의 기본 브랜치를 사용하려면 비워 두세요. 향후 커밋을 받으려면 브랜치를 사용하세요. 고정 커밋을 사용하면 해당 리비전으로 유지됩니다.
  5. 마켓플레이스 가져오기 를 선택하고 메시지가 표시되면 GitHub 액세스를 승인합니다. 매우 큰 마켓플레이스의 최초 가져오기는 최대 1시간이 걸릴 수 있습니다. 이후 매일 수행되는 동기화에는 일반적으로 몇 분이 걸립니다.
  6. 가져오기 결과 를 검토한 다음, 가져온 각 플러그인을 열어 설치 정책과 필요한 앱을 구성합니다.

매일 수행되는 동기화를 기다리지 않고 업데이트를 요청하려면 관리자 > 플러그인 > 마켓플레이스 에서 마켓플레이스를 열고 지금 동기화 를 선택합니다.

지원되는 형식

선택한 디렉터리에는 다음 파일 중 하나가 있어야 합니다.

파일 형식
.agents/plugins/marketplace.json plugins 배열이 있는 Codex 마켓플레이스입니다.
.claude-plugin/marketplace.json plugins 배열이 있는 Claude 호환 마켓플레이스입니다.
.claude-plugin/plugin.json 마켓플레이스 매니페스트가 없을 때 사용하는 독립형 Claude 플러그인입니다.

마켓플레이스의 항목은 .codex-plugin/plugin.json이 있는 네이티브 플러그인, Claude 호환 플러그인, Agent Plugins 1.0 패키지 또는 지원되는 스킬 패키지를 참조할 수 있습니다.

Codex 마켓플레이스에서는 같은 저장소에 있는 플러그인에 로컬 경로를 사용합니다.

{
  "name": "team-plugins",
  "interface": {
    "displayName": "Team plugins"
  },
  "plugins": [
    {
      "name": "team-tools",
      "source": {
        "source": "local",
        "path": "./plugins/team-tools"
      }
    }
  ]
}

경로는 .agents/plugins/ 디렉터리가 아니라 선택한 마켓플레이스 루트를 기준으로 합니다.

Claude 호환 마켓플레이스에서는 각 로컬 플러그인에 경로 문자열을 사용할 수 있습니다.

{
  "name": "team-plugins",
  "plugins": [
    {
      "name": "team-tools",
      "source": "./plugins/team-tools"
    }
  ]
}

Codex 마켓플레이스 항목은 GitHub 저장소 루트에 있는 플러그인의 경우 source: "url"을, GitHub 하위 디렉터리에 있는 플러그인의 경우 source: "git-subdir"를 지원합니다. 예를 들면 다음과 같습니다.

{
  "name": "team-tools",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/example/team-tools.git",
    "path": "./plugins/team-tools",
    "ref": "main"
  }
}

Git 소스에서는 ref 또는 전체 40자 커밋 sha를 선택할 수 있습니다. 액세스를 승인하는 GitHub 계정은 참조되는 모든 저장소를 읽을 수 있어야 합니다. 현재 워크스페이스 가져오기는 GitHub 저장소만 지원합니다.

워크스페이스 액세스 구성

GitHub 가져오기 및 동기화에는 AVAILABLE, INSTALLED_BY_DEFAULT, NOT_AVAILABLE, ON_INSTALL, ON_USE를 비롯한 저장소의 설치 또는 인증 정책이 적용되지 않습니다. 워크스페이스 관리자는 각 플러그인에 대해 이러한 설정을 구성합니다. 업데이트를 동기화하거나 기존 플러그인을 GitHub 관리로 전환해도 해당 워크스페이스 정책은 유지됩니다.

설치 정책 을 사용하여 자격이 있는 각 역할에 대해 사용 가능 또는 설치됨 을 선택합니다. 필요한 앱도 활성화해야 하며, 구성원은 연결된 서비스에 액세스할 수 있어야 합니다. 플러그인을 가져와도 앱 액세스 권한이 부여되거나 구성원의 계정이 연결되지는 않습니다. 역할, 앱 및 작업 제어에 대해서는 플러그인 제어를 참조하세요.

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

기존 플러그인의 마켓플레이스 항목에 pluginId를 추가합니다.

{
  "name": "team-tools",
  "pluginId": "plugin_0123456789abcdef0123456789abcdef",
  "source": {
    "source": "local",
    "path": "./plugins/team-tools"
  }
}

관리자 > 플러그인 에서 플러그인을 열고 URL에서 /admin/plugins/ 뒤에 있는 ID를 복사합니다. 마켓플레이스 항목에서 pluginId를 name 및 source 옆에 배치합니다. 기존 플러그인은 같은 워크스페이스에 있어야 합니다.

이렇게 하면 업로드된 워크스페이스 플러그인이나 달리 관리되지 않는 워크스페이스 플러그인을 GitHub 관리로 전환할 수 있습니다. 플러그인의 ID, 공유 설정 및 워크스페이스 정책은 유지됩니다. 향후 업데이트는 GitHub에서 가져오며, 더 이상 아카이브 업로드로 관리되는 플러그인을 교체할 수 없습니다. 이미 다른 GitHub 소스에서 관리 중인 플러그인은 이 방법으로 인계받을 수 없습니다.

데스크톱 전용 플러그인

가져온 플러그인이 mcp.json 또는 .mcp.json에 MCP server를 선언하면 데스크톱 전용 으로 표시되며 ChatGPT 데스크톱 앱에서만 작동합니다. 원격 HTTPS URL을 사용하는 서버도 여기에 포함됩니다. 인라인 서버 선언과 같이 지원되는 다른 MCP 구성 형식에도 동일한 제한이 적용됩니다.

.app.json을 사용하여 기존 앱 참조

플러그인 루트에 .app.json을 추가합니다. 파일 이름에는 앞에 점이 포함됩니다. 점이 없는 app.json은 지원되지 않습니다.

{
  "apps": {
    "team-tools": {
      "id": "asdk_app_example",
      "required": true
    }
  }
}

asdk_app_example을 기존 앱의 ID로 바꿉니다. 지원되는 앱 ID는 asdk_app_, connector_ 또는 templated_apps_으로 시작합니다. plugin_... ID가 아닌 앱 ID를 사용하세요. 예를 들어 plugin_asdk_app_example이 포함된 플러그인 URL은 앱 asdk_app_example을 나타냅니다.

키 team-tools는 이 파일 내에서 참조의 이름을 지정합니다. 플러그인이 앱에 종속되어 있으면 required를 true로 설정합니다. 다른 기존 앱을 참조하려면 항목을 더 추가할 수 있습니다.

네이티브 플러그인의 경우 .codex-plugin/plugin.json에서 apps를 ./.app.json으로 설정합니다. 다음은 이 예시의 전체 매니페스트입니다.

{
  "name": "team-tools",
  "version": "1.0.0",
  "description": "Use the team's approved tools.",
  "author": {
    "name": "Example team"
  },
  "apps": "./.app.json",
  "interface": {
    "displayName": "Team tools",
    "shortDescription": "Use approved team tools",
    "longDescription": "Connect to the team's existing app.",
    "developerName": "Example team",
    "category": "Productivity",
    "capabilities": ["Read"]
  }
}

파일을 다음 레이아웃으로 유지합니다.

team-plugins/
├── .agents/plugins/marketplace.json
└── plugins/team-tools/
    ├── .codex-plugin/plugin.json
    └── .app.json

참조로 앱이 생성되거나 권한이 부여되지는 않습니다. 관리자는 대상 역할이 앱을 사용할 수 있도록 설정해야 하며, 구성원은 필요한 인증을 모두 완료해야 합니다. 기존 앱 권한, 작업 제어 및 서비스 액세스는 계속 적용됩니다.

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

새 마켓플레이스는 매일 업데이트를 확인합니다. 자동 동기화를 기다리지 않고 업데이트를 요청하려면 관리자 > 플러그인 > 마켓플레이스 를 열고 마켓플레이스를 선택한 다음 지금 동기화 를 선택합니다.

동기화를 통해 새 마켓플레이스 항목을 추가하고 기존 플러그인을 업데이트할 수 있습니다. 자동 동기화에서는 새 플러그인을 모두 가져오므로 변경 사항을 병합하기 전에 저장소의 변경 내용을 검토하세요.

동기화 후 상태와 저장된 보고서를 검토합니다. 완료됨 — 오류 N개 는 작업이 완료되었지만 일부 플러그인을 처리할 수 없었음을 의미합니다. 기존 플러그인의 업데이트가 유효하지 않으면 마지막으로 정상 작동한 버전이 유지됩니다. GitHub에서 보고된 문제를 수정한 다음 지금 동기화 를 선택하여 다시 시도하세요.

저장소에서 항목을 제거해도 가져온 워크스페이스 사본은 삭제되지 않습니다. 대신 더 이상 소스에 없음 으로 표시됩니다. ChatGPT에서 마켓플레이스를 삭제하면 해당 마켓플레이스에서 가져온 모든 플러그인이 삭제됩니다.

GitHub 액세스 다시 연결 또는 변경

GitHub 액세스를 다시 연결 하려면 먼저 가져오기에 사용한 GitHub 계정이 저장소와 참조된 모든 저장소에 계속 액세스할 수 있는지 확인합니다. 그런 다음 마켓플레이스 동기화에는 해당 관리자의 GitHub 연결이 사용되므로, 처음 마켓플레이스를 가져온 관리자가 ChatGPT에서 GitHub 플러그인을 열고 계정을 다시 연결해야 합니다.

새 소유자에게 이전 하려면 새 워크스페이스 관리자가 관리자 > 플러그인 > 추가 > 마켓플레이스 가져오기 를 열고 동일한 소스, 경로, 브랜치, 태그 또는 커밋 값을 사용하여 같은 마켓플레이스를 가져와야 합니다. 이후 동기화에는 해당 관리자의 GitHub 연결이 사용됩니다.

마켓플레이스를 다시 연결하거나 소유권을 변경하기 위해 마켓플레이스를 삭제하지 마세요. 삭제하면 여기서 가져온 플러그인도 제거됩니다.