Sistem plugin pada Codex CLI berkembang dengan sangat cepat. Perintah /plugins kini sudah memungkinkan kita untuk menelusuri, menginstal, serta mengaktifkan atau menonaktifkan plugin berdasarkan kategori pasar. Semakin banyak tim yang mulai mengemas rantai alat internal mereka menjadi plugin Codex yang dapat digunakan kembali. Namun, pintu masuk swalayan di Marketplace resmi saat ini masih dalam tahap "peninjauan". Pengembang perlu memahami struktur manifest dan metode debugging lokal terlebih dahulu, lalu menyelesaikan proses peninjauan sebelum plugin benar-benar dapat diakses oleh pengguna. Artikel ini merangkum alur lengkap mulai dari pembuatan dari nol, pengujian lokal, distribusi melalui Git, hingga pengajuan ke Marketplace resmi, serta beberapa detail jebakan yang sering ditemui.
Apa sebenarnya isi dari plugin Codex?
Sebuah plugin Codex pada dasarnya adalah pengemasan berbagai kemampuan menjadi satu unit yang dapat diinstal dan didistribusikan. Menurut dokumentasi resmi OpenAI, plugin dapat berisi skills (instruksi tugas yang dapat digunakan kembali), aplikasi berbasis MCP (layanan yang menghubungkan alat eksternal), hooks siklus hidup, serta ekstensi peramban dan templat tugas terjadwal opsional. Komponen-komponen ini tidak harus ada secara bersamaan; plugin ringan yang hanya berisi skills pun tetap dapat diinstal dan digunakan dengan normal.
Memahami batasan tanggung jawab setiap komponen adalah prasyarat untuk menulis manifest yang tepat. Tabel di bawah ini merangkum jalur penyimpanan dan fungsi dari empat komponen inti dalam direktori plugin Codex:
| Komponen | Jalur Penyimpanan | Fungsi | Wajib |
|---|---|---|---|
| plugin.json | .codex-plugin/plugin.json |
Identitas dan informasi meta plugin | Ya |
| skills | skills/<skill-name>/SKILL.md |
Mendefinisikan instruksi tugas yang dapat digunakan kembali | Tidak |
| MCP servers | .mcp.json |
Mengonfigurasi koneksi layanan alat eksternal | Tidak |
| hooks | hooks/hooks.json |
Mendeklarasikan perintah hook siklus hidup | Tidak |
Perlu dicatat, jika plugin hanya berupa file SKILL.md yang digunakan kembali di dalam tim, Anda tidak perlu melalui proses manifest yang lengkap—cukup masukkan file tersebut langsung ke direktori .agents/skills/, dan Codex akan menemukannya secara otomatis tanpa memerlukan daftar plugin. Ini adalah bentuk transisi umum bagi banyak tim dari "skrip internal" menjadi "plugin resmi".
Batasan kemampuan plugin jauh lebih luas dari yang dibayangkan banyak orang. Selain skills dan aplikasi berbasis MCP yang merupakan dua komponen paling umum, dokumentasi resmi juga menyebutkan bahwa plugin dapat membawa deklarasi kemampuan yang diperlukan untuk ekstensi peramban, serta templat tugas terjadwal yang dapat digunakan kembali. Artinya, sebuah plugin tidak hanya dapat menangani permintaan interaktif yang "dipicu oleh pengguna", tetapi juga dapat menangani skenario otomatisasi yang "dijalankan di latar belakang secara berkala". Memilih kombinasi komponen untuk sebuah plugin pada dasarnya adalah menyeimbangkan antara pengalaman instalasi dan biaya pemeliharaan—semakin banyak komponen, semakin lengkap fungsi plugin, namun materi peninjauan dan kasus pengujian yang diperlukan juga akan bertambah. Sebelum mengirimkan, sebaiknya pikirkan dengan matang lapisan kemampuan apa yang benar-benar dibutuhkan oleh pengguna target Anda, alih-alih memasukkan semua komponen ke dalam satu paket.
Memulai dari plugin.json: Panduan Lengkap File Manifest Plugin
plugin.json adalah kartu identitas bagi plugin Anda. File ini menentukan bagaimana Codex mengenali, memuat, dan menampilkan plugin tersebut. Manifest minimal yang bisa dijalankan hanya memerlukan tiga kolom:
{
"name": "my-first-plugin",
"version": "1.0.0",
"description": "Alur kerja sapaan yang dapat digunakan kembali",
"skills": "./skills/"
}
Untuk kolom name, disarankan menggunakan format kebab-case yang stabil. Jangan mengubah identitas ini pada pembaruan versi berikutnya agar marketplace tetap bisa mengenali bahwa itu adalah plugin yang sama. Kolom version mengikuti spesifikasi semantic versioning; marketplace mengandalkan kolom ini untuk menentukan apakah pengguna perlu diberi tahu tentang pembaruan. Semua jalur (path) yang direferensikan dalam manifest harus relatif terhadap direktori root plugin, dimulai dengan ./, dan tidak boleh keluar dari direktori root plugin tersebut.
Selain tiga kolom dasar tersebut, skills juga bisa merujuk ke array direktori skill, sementara kolom hooks, mcpServers, dan apps masing-masing merujuk ke file konfigurasi hooks/hooks.json, .mcp.json, dan .app.json. Desain "kolom merujuk ke file" ini menjaga manifest tetap ringkas. Penjelasan skill dan konfigurasi alat dipisahkan ke dalam file independen agar kolaborasi tim lebih mudah tanpa menyebabkan konflik saat memodifikasi komponen yang berbeda secara paralel.
Jika Anda berencana mengirimkan plugin ke Marketplace resmi, Anda perlu melengkapi sekumpulan metadata untuk kebutuhan tampilan. Tabel berikut mencantumkan kolom penting yang disarankan untuk dilengkapi saat tahap publikasi:
| Kolom | Tipe | Penjelasan |
|---|---|---|
| author / repository | String | Identitas sumber plugin, disarankan sesuai dengan identitas terverifikasi |
| interface.displayName | String | Nama plugin yang ditampilkan di daftar marketplace |
| interface.category | String | Kategori plugin, memengaruhi jalur penelusuran pengguna |
| interface.capabilities | Array | Label kemampuan yang dimiliki plugin |
| mcpServers / apps / hooks | Objek | Merujuk ke file konfigurasi komponen terkait |
Kesalahan yang paling sering terjadi saat menulis manifest adalah kesalahan referensi jalur—misalnya, kolom skills ditulis sebagai jalur absolut, atau melewatkan ./ di awal. Hal ini menyebabkan plugin berjalan lancar di lokal, tetapi dianggap sebagai manifest tidak valid saat pengajuan audit. Disarankan untuk mengkloning ulang repositori plugin dengan direktori bersih sebelum pengajuan, guna mensimulasikan lingkungan instalasi nyata dan menjalankan pengujian lengkap.
Scaffolding Lokal dan Debugging: Membuat Plugin Berjalan
Menulis manifest dari nol tidaklah efisien. Pihak resmi menyediakan skill $plugin-creator bawaan untuk menyelesaikan pembuatan scaffolding, yang bisa langsung dibuat melalui percakapan di Codex CLI:
codex "Gunakan scaffolding $plugin-creator untuk membuat plugin bernama infra-monitor"
Perintah ini akan secara otomatis membuat manifest, contoh skill, dan entri marketplace lokal, sehingga Anda tidak perlu repot membuat struktur direktori secara manual. Setelah dibuat, plugin sudah bisa langsung diinstal dan diuji di lingkungan lokal tanpa perlu dipublikasikan ke repositori jarak jauh mana pun.
Pada tahap debugging lokal, jika skill dalam plugin melibatkan pemanggilan Model Bahasa Besar dari vendor yang berbeda untuk pengujian perbandingan, API gateway terpadu dapat secara signifikan mengurangi biaya peralihan konfigurasi lingkungan. Saat memverifikasi kemampuan MCP server plugin, kami biasanya mengarahkan base_url ke layanan proksi API yang disediakan oleh APIYI (apiyi.com). Dengan satu set kunci (key), Anda bisa beralih memanggil model yang berbeda di dalam plugin, sehingga memudahkan perbandingan perbedaan performa setiap model di bawah logika plugin yang sama:
from openai import OpenAI
# Mengatur klien dengan APIYI
client = OpenAI(
api_key="kunci-apiyi-anda",
base_url="https://api.apiyi.com/v1"
)
🎯 Saran Debugging: Selama pengembangan plugin Codex, Anda sering perlu menguji kualitas respons MCP server pada model yang berbeda berulang kali. Kami menyarankan untuk mengelola pemanggilan multimodal secara terpadu melalui platform APIYI (apiyi.com) guna menghindari keharusan mengajukan kunci untuk setiap model dan memelihara logika pemanggilan yang terpisah, sehingga Anda bisa fokus pada penyempurnaan fungsi plugin itu sendiri.
Selain membuat entri marketplace lokal secara manual, Anda juga bisa mendeklarasikan jalur plugin lokal langsung di ~/.agents/plugins/marketplace.json (tingkat personal) atau .agents/plugins/marketplace.json di root repositori (tingkat tim). Cukup atur kolom source ke local untuk merujuk ke direktori lokal, sehingga instalasi dan verifikasi selesai tanpa perlu melakukan push ke jarak jauh.
Jika plugin Anda menyertakan aplikasi berbasis MCP yang memerlukan mode pengembang ChatGPT untuk debugging, pihak resmi menyediakan jalur lain: aktifkan mode pengembang di pengaturan ChatGPT, buat aplikasi berbasis MCP dan dapatkan ID aplikasi yang sesuai, lalu hubungkan ID ini melalui $plugin-creator. Dengan begitu, Anda bisa memverifikasi aliran data antara plugin dan aplikasi di lingkungan percakapan nyata. Langkah ini jauh lebih mendekati pengalaman nyata setelah go-live dibandingkan debugging baris perintah lokal murni, jadi disarankan untuk mencobanya setidaknya sekali sebelum mengajukan audit.
Registrasi Pasar Git dan Distribusi Internal Tim
Setelah plugin berhasil divalidasi secara lokal, distribusi di dalam tim biasanya tidak perlu menunggu tinjauan resmi; cukup gunakan repositori Git untuk membangun sumber pasar. Codex CLI menyediakan sekumpulan perintah khusus untuk manajemen pasar:
| Perintah | Kegunaan |
|---|---|
codex plugin marketplace add owner/repo |
Menambahkan repositori GitHub sebagai sumber pasar |
codex plugin marketplace add owner/repo --ref v2.1.0 |
Mengunci cabang atau tag tertentu untuk mengontrol rilis bertahap |
codex plugin marketplace list |
Melihat daftar pasar yang telah ditambahkan |
codex plugin marketplace upgrade |
Menarik pembaruan pasar |
codex plugin marketplace remove |
Menghapus sumber pasar |
Untuk tim dengan repositori kode yang besar, Anda bisa menggunakan parameter --sparse .agents/plugins untuk hanya menarik direktori yang relevan dengan plugin, sehingga menghindari kloning seluruh repositori yang dapat memperlambat proses instalasi. Model pasar Git ini sangat cocok untuk rantai alat internal perusahaan—tidak perlu melalui tinjauan publik, pembaruan plugin hanya memerlukan pengiriman tag baru, dan anggota tim cukup menjalankan perintah upgrade sekali untuk melakukan sinkronisasi.
Dari sisi praktis, model pasar Git memiliki keunggulan tersembunyi: Anda dapat memisahkan ritme iterasi plugin dari ritme rilis internal tim. Kode bisnis mungkin digabungkan beberapa kali sehari, tetapi karena plugin adalah bagian dari rantai alat percakapan, frekuensi pembaruan yang terlalu tinggi justru dapat mengganggu model mental pengguna. Disarankan untuk mengikat versi plugin dan tag pada jendela rilis yang tetap, misalnya menggabungkan perubahan setiap satu atau dua minggu, guna memastikan kecepatan iterasi fitur tanpa membuat anggota tim harus sering beradaptasi dengan cara interaksi yang baru.
Seluruh Proses Tinjauan Pengajuan Marketplace Resmi
Pintu masuk mandiri untuk Marketplace resmi hingga saat ini belum sepenuhnya dibuka. Dokumentasi OpenAI dengan jelas mencatat bahwa bagian ini "akan segera hadir". Saat ini, pengajuan resmi untuk pengguna publik melalui proses tinjauan manual di portal pengajuan plugin. Sebelum mengajukan, Anda harus menyelesaikan verifikasi identitas—pengembang individu harus menyelesaikan individual verification, sedangkan jika diterbitkan atas nama perusahaan, diperlukan business verification. Peninjau akan memeriksa apakah identitas penerbit sesuai dengan materi yang diajukan.
Daftar materi yang perlu disiapkan untuk pengajuan resmi adalah sebagai berikut:
| Kategori Materi | Persyaratan Spesifik |
|---|---|
| Informasi Dasar Plugin | Nama, deskripsi, logo, kategori, URL terkait |
| Server MCP | Domain yang dapat diakses publik, kebijakan CSP, konfigurasi autentikasi |
| Akun Demo | Dapat langsung masuk, tidak memerlukan MFA atau verifikasi email sekunder |
| Kasus Uji | Tepat 5 skenario positif + 3 skenario negatif |
| Penandaan Alat | readOnlyHint, openWorldHint, destructiveHint harus sesuai dengan perilaku aktual |
Proses pengajuan dibagi menjadi beberapa blok formulir: Info (informasi daftar publik), MCP (konfigurasi server dan autentikasi), Skills (mengunggah paket keterampilan akhir), Prompts (contoh petunjuk awal), Testing (kasus uji), Global (negara dan wilayah yang tersedia), dan terakhir blok Submit untuk mengisi catatan rilis dan menyelesaikan konfirmasi kebijakan. Setelah disetujui, waktu rilis dipilih sendiri oleh pengembang di portal, dan plugin akan muncul secara sinkron di direktori plugin terpadu ChatGPT dan Codex.
Jika plugin menyertakan aplikasi berbasis MCP, Anda juga perlu memverifikasi kepemilikan domain untuk memastikan bahwa domain tempat server MCP disebarkan konsisten dengan domain yang dideklarasikan oleh plugin. Tim peninjau akan fokus memeriksa apakah hasil yang dikembalikan oleh alat berisi data pribadi atau informasi kunci yang tidak perlu; hal ini harus dihindari sejak awal saat merancang format output alat, bukan menunggu hingga ditolak oleh peninjau baru kemudian melakukan perubahan.
Manajemen Versi dan Jebakan Umum
Setelah plugin dirilis, detail manajemen versi akan berdampak langsung pada pengalaman pembaruan pengguna. Marketplace mengandalkan kolom version untuk menentukan apakah pembaruan tersedia, jadi sangat penting untuk mengikuti spesifikasi semantic versioning secara ketat—gunakan versi patch untuk perbaikan bug, versi minor untuk kemampuan baru, dan hanya naikkan versi major untuk perubahan yang bersifat merusak (breaking changes).
Plugin yang sudah terinstal akan di-cache di jalur lokal ~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/. Saat menelusuri masalah seperti "plugin sudah diperbarui tetapi perilakunya tidak berubah", memastikan apakah cache sudah diperbarui ke versi baru sering kali lebih cepat daripada men-debug ulang logika kode. Di lingkungan perusahaan, Anda mungkin akan menemui kebijakan whitelist yang dipaksakan melalui requirements.toml. Server MCP memerlukan kecocokan nama dan identitas secara bersamaan; ketidaksesuaian pada salah satunya akan menyebabkan layanan dinonaktifkan secara diam-diam tanpa pesan kesalahan yang jelas. Untuk masalah seperti ini, disarankan untuk menjalankan konfigurasi kebijakan di lingkungan pengujian terlebih dahulu sebelum masuk ke produksi.
Tabel berikut merangkum beberapa jebakan yang sering dilaporkan pengembang beserta cara mengatasinya:
| Masalah Umum | Cara Mengatasi |
|---|---|
| Jalur manifest ditulis sebagai jalur absolut | Ubah menjadi jalur relatif yang dimulai dengan ./ |
| Pemanggilan implisit memicu plugin yang tidak diinginkan | Gunakan @plugin-name untuk menentukan plugin secara eksplisit |
| Perilaku tidak berubah setelah pembaruan | Periksa apakah direktori cache plugin lokal sudah diperbarui |
| MCP gagal secara diam-diam di bawah kebijakan perusahaan | Periksa apakah nama dan identitas di requirements.toml sudah cocok |
Sebelum mengajukan tinjauan resmi, disarankan untuk menjalankan alat pihak ketiga codex-plugin-scanner. Alat ini akan memberikan skor pada plugin Anda berdasarkan dimensi seperti kemudahan instalasi, status pemeliharaan, keamanan MCP, dan sumber publikasi. Terutama untuk plugin yang akan didistribusikan ke klien perusahaan, menemukan masalah lebih awal jauh lebih hemat waktu daripada harus memperbaiki setelah ditolak saat tinjauan.
Detail lain yang sering terlewatkan adalah perbedaan antara pemanggilan eksplisit dan penemuan implisit. Jika tidak ada plugin yang ditentukan secara spesifik, Codex akan secara otomatis mencocokkan keterampilan yang paling relevan berdasarkan konteks. Jika ada beberapa plugin dengan fungsi serupa terinstal di ruang kerja yang sama, pencocokan implisit ini mungkin tidak memilih plugin yang Anda harapkan. Membiasakan diri untuk mendeklarasikan secara eksplisit dengan @plugin-name, terutama di ruang kerja yang digunakan bersama oleh tim, dapat mengurangi biaya penelusuran masalah akibat "konflik antar plugin".
Pertanyaan Umum (FAQ) Pengembangan Plugin Codex
Apa perbedaan antara plugin dan file SKILL.md terpisah?
SKILL.md adalah komponen di dalam plugin. Saat digunakan secara terpisah, ia tidak memerlukan manifest dan dapat ditemukan secara otomatis cukup dengan menempatkannya di direktori .agents/skills/. Sementara itu, plugin membungkus berbagai komponen seperti skills, server MCP, dan hooks menjadi satu kesatuan yang memiliki identitas dan dapat dikelola versinya, sehingga cocok untuk skenario yang memerlukan distribusi resmi dan pelacakan pembaruan.
Bagaimana jika saya memerlukan beberapa akun model untuk pengujian perbandingan selama tahap pengembangan?
Ini adalah masalah praktis yang sering ditemui dalam pengembangan plugin, terutama untuk plugin yang melibatkan pemilihan model atau optimasi petunjuk. Daripada membuka akun dan mengelola kunci untuk setiap penyedia model secara terpisah, lebih baik gunakan gateway terpadu seperti APIYI (apiyi.com). Anda dapat menggunakan satu kunci API untuk memanggil model-model utama guna melakukan perbandingan A/B, sehingga Anda bisa fokus pada logika plugin itu sendiri alih-alih mengelola akun.
Apakah distribusi pasar Git dan peluncuran di Marketplace resmi bisa berjalan bersamaan?
Bisa. Banyak tim melakukan validasi internal dan gray release skala kecil melalui pasar Git terlebih dahulu, lalu menempuh proses pengajuan resmi setelah dipastikan stabil. Kedua metode distribusi ini tidak saling bertentangan dan struktur manifest-nya pun bersifat universal.
Berapa lama waktu yang dibutuhkan untuk tinjauan plugin?
Dokumentasi resmi saat ini belum memberikan periode waktu tetap, hanya menyebutkan bahwa proses tinjauan masih terus dikembangkan dan diperluas, serta tidak mendukung penanganan prioritas. Disarankan untuk memasukkan periode tinjauan sebagai variabel ketidakpastian dalam jadwal proyek Anda. Menyiapkan semua materi dengan lengkap sebelum pengajuan untuk mengurangi komunikasi bolak-balik akibat kekurangan dokumen adalah cara paling praktis untuk mempercepat waktu peluncuran secara keseluruhan.
Catatan Penutup
Kesulitan utama dalam pengembangan plugin Codex sebenarnya bukan terletak pada kodenya, melainkan pada pemahaman spesifikasi manifest dan persiapan dokumen untuk proses peninjauan. Detail-detail ini tidak sesulit yang dibayangkan, namun sering kali membuat pengajuan ditolak hanya karena kesalahan penulisan path atau kolom yang terlewat. Saya sarankan untuk mengikuti alur: "verifikasi scaffolding lokal → distribusi skala kecil di pasar Git → pengajuan resmi untuk peninjauan", dan pastikan Anda meluangkan waktu untuk pengujian di lingkungan nyata pada setiap tahapnya. Jika plugin Anda melibatkan pemanggilan model dalam jumlah banyak atau sering berganti model untuk pengujian, layanan proksi API yang disediakan oleh APIYI (apiyi.com) dapat menghemat banyak waktu dalam pengaturan lingkungan, sehingga Anda bisa lebih fokus pada penyempurnaan fitur plugin itu sendiri.
