Pengelolaan plugin

Sebelum memulai

Admin ruang kerja dapat mengimpor marketplace plugin dari GitHub dan terus memperbarui pluginnya dari repositori. Marketplace adalah katalog JSON yang mencantumkan plugin yang akan diimpor.

Halaman ini membahas impor dan sinkronisasi ruang kerja. Untuk mengonfigurasi marketplace secara langsung pada klien lokal melalui config.toml yang dikelola melalui cloud atau di tingkat sistem, lihat Konfigurasi marketplace plugin dan pengaturan default. Untuk mengaktifkan atau menonaktifkan plugin bagi proyek tertentu, lihat Mengaktifkan atau menonaktifkan plugin untuk repo.

Gunakan akun GitHub yang dapat membaca repositori marketplace dan setiap repositori lain yang dirujuknya. Repositori GitHub publik dan privat didukung. Selesaikan persetujuan organisasi GitHub yang diperlukan untuk akses repositori Anda sebelum mengimpor.

Tinjau konten repositori sebelum mengimpor. Plugin baru dimulai dengan penginstalan Available dan autentikasi saat penginstalan. Marketplace baru mengaktifkan sinkronisasi harian otomatis. Impor memproses semua entri yang valid, dan sinkronisasi mendatang secara otomatis menambahkan plugin baru apa pun di repositori.

Mengonfigurasi sinkronisasi marketplace

1. Buka Admin > Plugins, lalu pilih Add > Import marketplace.
2. Di Source, masukkan URL repositori, seperti https://github.com/example/team-plugins. Gunakan URL repositori saja, tanpa URL cabang atau folder.
3. Jika marketplace berada dalam subdirektori, masukkan direktori tersebut di Path. Misalnya, gunakan team-tools untuk team-tools/.agents/plugins/marketplace.json. Kosongkan Path untuk root repositori. Jangan masukkan nama file manifes.
4. Secara opsional, masukkan Branch, tag, or commit. Kosongkan bagian ini untuk menggunakan cabang default repositori. Gunakan cabang untuk menerima commit mendatang; commit tetap akan bertahan pada revisi tersebut.
5. Pilih Import marketplace dan otorisasi akses GitHub ketika diminta. Impor awal dapat memerlukan waktu hingga satu jam untuk marketplace yang sangat besar. Sinkronisasi harian berikutnya biasanya memerlukan waktu beberapa menit.
6. Tinjau Import results, lalu buka setiap plugin yang diimpor untuk mengonfigurasi kebijakan penginstalan dan aplikasi apa pun yang diperlukan.

Untuk meminta pembaruan tanpa menunggu sinkronisasi harian, buka marketplace di Admin > Plugins > Marketplaces, lalu pilih Sync now.

Format yang didukung

Direktori yang dipilih harus berisi salah satu file berikut:

Dalam marketplace, entri dapat merujuk ke plugin native dengan .codex-plugin/plugin.json, plugin yang kompatibel dengan Claude, paket Agent Plugins 1.0, atau paket skill yang didukung.

Untuk marketplace Codex, gunakan jalur lokal bagi plugin dalam repositori yang sama:

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

Jalur tersebut relatif terhadap root marketplace yang dipilih, bukan terhadap .agents/plugins/.

Marketplace yang kompatibel dengan Claude dapat menggunakan string jalur untuk setiap plugin lokal:

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

Entri marketplace Codex juga mendukung source: "url" untuk plugin di root repositori GitHub dan source: "git-subdir" untuk plugin dalam subdirektori GitHub. Contoh:

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

Sumber Git dapat memilih ref atau sha berupa commit 40 karakter lengkap. Akun GitHub yang memberikan otorisasi harus dapat membaca setiap repositori yang dirujuk. Impor ruang kerja saat ini hanya mendukung repositori GitHub.

Mengonfigurasi akses ruang kerja

Impor dan sinkronisasi GitHub tidak menerapkan kebijakan penginstalan atau autentikasi repositori, termasuk AVAILABLE, INSTALLED_BY_DEFAULT, NOT_AVAILABLE, ON_INSTALL, dan ON_USE. Admin ruang kerja mengonfigurasi pengaturan ini untuk setiap plugin. Menyinkronkan pembaruan atau memindahkan plugin yang sudah ada ke pengelolaan GitHub akan mempertahankan kebijakan ruang kerjanya.

Gunakan Installation policy untuk memilih Available atau Installed bagi setiap peran yang memenuhi syarat. Aplikasi yang diperlukan juga harus diaktifkan, dan anggota harus memiliki akses ke layanan terhubung. Mengimpor plugin tidak memberikan akses aplikasi atau menghubungkan akun anggota. Lihat Kontrol plugin untuk kontrol peran, aplikasi, dan tindakan.

Memindahkan plugin yang sudah ada ke pengelolaan GitHub

Tambahkan pluginId ke entri marketplace plugin yang sudah ada:

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

Buka plugin dari Admin > Plugins, lalu salin ID setelah /admin/plugins/ dalam URL-nya. Letakkan pluginId di samping name dan source dalam entri marketplace. Plugin yang sudah ada harus berada dalam ruang kerja yang sama.

Tindakan ini memindahkan plugin ruang kerja yang diunggah atau tidak dikelola dengan cara lain ke pengelolaan GitHub. Plugin mempertahankan ID, pengaturan berbagi, dan kebijakan ruang kerjanya. Pembaruan mendatang berasal dari GitHub; unggahan arsip tidak lagi dapat menggantikan plugin terkelola. Plugin yang sudah dikelola oleh sumber GitHub lain tidak dapat diambil alih dengan cara ini.

Plugin khusus desktop

Setiap plugin yang diimpor dan mendeklarasikan MCP server dalam mcp.json atau .mcp.json ditandai Desktop only dan hanya berfungsi di aplikasi desktop ChatGPT. Ini mencakup server yang menggunakan URL HTTPS jarak jauh. Pembatasan yang sama berlaku untuk bentuk konfigurasi MCP lain yang didukung, seperti deklarasi server inline.

Merujuk aplikasi yang sudah ada dengan .app.json

Tambahkan .app.json di root plugin. Nama file menyertakan tanda titik di awal; app.json tanpa tanda titik tidak didukung.

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

Ganti asdk_app_example dengan ID aplikasi yang sudah ada. ID aplikasi yang didukung diawali dengan asdk_app_, connector_, atau templated_apps_. Gunakan ID aplikasi, bukan ID plugin_.... Misalnya, URL plugin yang memuat plugin_asdk_app_example mewakili aplikasi asdk_app_example.

Kunci team-tools menamai referensi dalam file ini. Atur required menjadi true jika plugin bergantung pada aplikasi tersebut. Anda dapat menambahkan lebih banyak entri untuk merujuk aplikasi lain yang sudah ada.

Untuk plugin native, atur apps menjadi ./.app.json dalam .codex-plugin/plugin.json. Berikut manifes lengkap untuk contoh ini:

{
  "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"]
  }
}

Pertahankan file dalam tata letak berikut:

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

Referensi tersebut tidak membuat aplikasi atau memberikan izin. Admin harus menyediakan aplikasi bagi peran yang dituju, dan anggota harus menyelesaikan autentikasi apa pun yang diperlukan. Izin aplikasi, kontrol tindakan, dan akses layanan yang sudah ada tetap berlaku.

Menjaga plugin tetap mutakhir

Marketplace baru memeriksa pembaruan setiap hari. Buka Admin > Plugins > Marketplaces, pilih marketplace, lalu pilih Sync now untuk meminta pembaruan tanpa menunggu sinkronisasi otomatis.

Sinkronisasi dapat menambahkan entri marketplace baru dan memperbarui plugin yang sudah ada. Tinjau perubahan pada repositori sebelum menggabungkannya karena sinkronisasi otomatis akan mengimpor setiap plugin baru.

Setelah sinkronisasi, tinjau status dan laporan yang disimpan. Completed — N errors berarti proses telah selesai, tetapi beberapa plugin tidak dapat diproses. Jika pembaruan plugin yang sudah ada tidak valid, versi terakhir yang berfungsi akan dipertahankan. Perbaiki masalah yang dilaporkan di GitHub, lalu pilih Sync now untuk mencoba lagi.

Menghapus entri dari repositori tidak menghapus salinan ruang kerja yang telah diimpor. Salinan tersebut ditandai No longer in source. Menghapus marketplace di ChatGPT akan menghapus semua plugin yang diimpor darinya.

Menghubungkan kembali atau mengubah akses GitHub

Untuk menghubungkan kembali akses GitHub, pertama-tama pastikan akun GitHub yang digunakan untuk impor masih memiliki akses ke repositori dan setiap repositori yang dirujuk. Admin yang awalnya mengimpor marketplace kemudian harus membuka plugin GitHub di ChatGPT dan menghubungkan kembali akunnya karena sinkronisasi marketplace menggunakan koneksi GitHub admin tersebut.

Untuk mengalihkan kepemilikan kepada pemilik baru, admin ruang kerja yang baru harus membuka Admin > Plugins > Add > Import marketplace, lalu mengimpor marketplace yang sama menggunakan nilai Source, Path, dan Branch, tag, or commit yang sama. Sinkronisasi mendatang akan menggunakan koneksi GitHub mereka.

Jangan menghapus marketplace hanya untuk menghubungkannya kembali atau mengubah kepemilikan: penghapusan juga akan menghapus plugin yang diimpor darinya.