Plugin Codex native

Dukungan Plugin Codex native memungkinkan agen OpenClaw dalam mode Codex menggunakan kemampuan aplikasi dan Plugin milik app-server Codex di dalam utas Codex yang sama yang menangani giliran OpenClaw. Panggilan Plugin tetap berada dalam transkrip Codex native; app-server Codex menangani eksekusi MCP yang didukung aplikasi. OpenClaw tidak menerjemahkan Plugin Codex menjadi alat dinamis OpenClaw sintetis codex_plugin_*.

Gunakan halaman ini setelah harness Codex dasar berfungsi.

Persyaratan

• Runtime agen harus berupa harness Codex native.
• plugins.entries.codex.enabled bernilai true.
• plugins.entries.codex.config.codexPlugins.enabled bernilai true.
• App-server Codex target dapat melihat inventaris marketplace, Plugin, dan aplikasi yang diharapkan.
• Migrasi hanya mendukung Plugin openai-curated yang teramati terinstal dari sumber di direktori home Codex sumber.
• Plugin workspace-directory yang dikonfigurasi secara manual memerlukan app-server Codex yang plugin/list-nya menerima marketplaceKinds dan ringkasan workspace tanpa path-nya menyertakan remotePluginId. Plugin harus sudah terinstal dan diaktifkan, serta aplikasi yang dimilikinya harus dapat diakses di app/list.

codexPlugins tidak berpengaruh pada proses yang menggunakan penyedia OpenClaw, pengikatan percakapan ACP, atau harness lain karena jalur tersebut tidak pernah membuat utas app-server Codex dengan konfigurasi apps native.

Akun Codex, ketersediaan aplikasi, dan kontrol aplikasi/Plugin workspace di sisi OpenAI berasal dari akun Codex yang telah masuk. Lihat Menggunakan Codex dengan paket ChatGPT Anda untuk model akun dan administrasi OpenAI.

Mulai cepat

Pratinjau migrasi dari direktori home Codex sumber:

openclaw migrate codex --dry-run

Tambahkan --verify-plugin-apps agar migrasi memanggil app/list sumber dan mewajibkan setiap aplikasi yang dimiliki tersedia, diaktifkan, serta dapat diakses sebelum merencanakan aktivasi native:

openclaw migrate codex --dry-run --verify-plugin-apps

Terapkan migrasi setelah rencananya terlihat benar:

openclaw migrate apply codex --yes

Migrasi menulis entri codexPlugins eksplisit untuk Plugin yang memenuhi syarat dan memanggil plugin/install app-server Codex untuk Plugin yang dipilih. Konfigurasi hasil migrasi terlihat seperti ini:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          codexPlugins: {            enabled: true,            allow_destructive_actions: true,            plugins: {              "google-calendar": {                enabled: true,                marketplaceName: "openai-curated",                pluginName: "google-calendar",              },            },          },        },      },    },  },}

Migrasi tetap terbatas pada openai-curated. Untuk menggunakan Plugin workspace-directory yang sudah ada, tambahkan secara manual menggunakan summary.id persis yang dilengkapi kualifikasi marketplace dan dikembalikan oleh plugin/list. Misalnya, jika Codex mengembalikan example-plugin@workspace-directory, konfigurasikan nilai lengkap tersebut, bukan nama tampilannya:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          codexPlugins: {            enabled: true,            plugins: {              "example-plugin": {                enabled: true,                marketplaceName: "workspace-directory",                pluginName: "example-plugin@workspace-directory",              },            },          },        },      },    },  },}

OpenClaw tidak memanggil plugin/install atau memulai autentikasi untuk Plugin workspace-directory. Instal, aktifkan, dan autentikasikan Plugin tersebut di Codex sebelum menambahkan atau mengaktifkan kebijakan OpenClaw. OpenClaw tetap menyembunyikan aplikasi ketika respons tidak menyertakan bukti kesiapan aplikasi, marketplace persis, ID Plugin, atau ID detail. Jika Codex menolak permintaan plugin/list workspace eksplisit, OpenClaw melaporkan marketplace_missing untuk setiap Plugin workspace yang diaktifkan dan tetap menyediakan Plugin terkurasi yang ditemukan secara independen.

Setelah perubahan codexPlugins, percakapan Codex baru otomatis menggunakan kumpulan aplikasi yang diperbarui. Jalankan /new atau /reset untuk menyegarkan percakapan saat ini. Gateway tidak perlu dimulai ulang untuk perubahan pengaktifan atau penonaktifan Plugin.

Mengelola Plugin dari obrolan

/codex plugins memeriksa atau mengubah Plugin Codex native yang dikonfigurasi dari obrolan yang sama tempat Anda mengoperasikan harness Codex:

/codex plugins/codex plugins list/codex plugins disable google-calendar/codex plugins enable google-calendar

/codex plugins adalah alias untuk /codex plugins list. Daftar tersebut menampilkan kunci, status aktif/nonaktif, nama Plugin Codex, dan marketplace setiap Plugin yang dikonfigurasi dari plugins.entries.codex.config.codexPlugins.plugins.

enable/disable hanya menulis ke ~/.openclaw/openclaw.json; perintah tersebut tidak pernah mengedit ~/.codex/config.toml atau menginstal Plugin Codex baru. Hanya pemilik atau klien Gateway dengan cakupan operator.admin yang dapat menjalankannya.

Mengaktifkan Plugin yang dikonfigurasi juga mengaktifkan sakelar global codexPlugins.enabled. Jika Plugin terkurasi ditulis sebagai nonaktif karena migrasi mengembalikan auth_required, otorisasi ulang aplikasi di Codex sebelum mengaktifkannya di OpenClaw. Untuk entri workspace-directory, mengaktifkannya di sini hanya mengubah kebijakan OpenClaw; Plugin dan aplikasi harus sudah aktif di Codex.

Cara kerja penyiapan Plugin native

Integrasi ini melacak tiga status:

Untuk Plugin openai-curated, migrasi merupakan langkah instalasi/kelayakan yang persisten:

• Selama perencanaan, OpenClaw membaca detail plugin/read Codex sumber dan memeriksa bahwa akun app-server Codex sumber merupakan akun langganan ChatGPT. Respons akun non-ChatGPT atau yang tidak ada menyebabkan Plugin yang didukung aplikasi dilewati dengan codex_subscription_required.
• Secara default, migrasi melewati panggilan app/list sumber: Plugin sumber yang didukung aplikasi dan lolos pemeriksaan akun direncanakan tanpa verifikasi aksesibilitas aplikasi sumber, sedangkan kegagalan transport pencarian akun menyebabkan Plugin dilewati dengan codex_account_unavailable.
• Dengan --verify-plugin-apps, migrasi mengambil snapshot app/list sumber terbaru dan mewajibkan setiap aplikasi yang dimiliki tersedia, diaktifkan, serta dapat diakses sebelum merencanakan aktivasi native. Kegagalan transport pencarian akun kemudian diteruskan ke pemeriksaan inventaris aplikasi sumber, bukan langsung menyebabkan Plugin dilewati.

Untuk Plugin workspace-directory, penyiapan dilakukan di luar OpenClaw. OpenClaw hanya mengkueri marketplace tersebut ketika setidaknya satu entri workspace aktif dikonfigurasi, menyelesaikan setiap Plugin berdasarkan summary.id persis, dan menggunakan kembali pemeriksaan kepemilikan plugin/read serta kesiapan app/list yang ada. Plugin yang belum terinstal, dinonaktifkan, tidak dapat diakses, atau belum diautentikasi tidak menampilkan aplikasi apa pun; OpenClaw tidak mencoba melakukan instalasi atau autentikasi.

Inventaris aplikasi runtime merupakan pemeriksaan aksesibilitas sesi target untuk Plugin terkurasi hasil migrasi dan Plugin workspace yang dikonfigurasi secara manual. Penyiapan sesi harness Codex menghitung konfigurasi aplikasi utas yang restriktif dari aplikasi Plugin yang diaktifkan dan dapat diakses; konfigurasi ini tidak dihitung ulang pada setiap giliran, sehingga /codex plugins enable/disable hanya memengaruhi percakapan Codex baru. Gunakan /new atau /reset agar perubahan diterapkan pada percakapan saat ini.

Batas dukungan V1

• Hanya Plugin openai-curated yang sudah terinstal dalam inventaris app-server Codex sumber yang memenuhi syarat untuk migrasi.
• Runtime juga mendukung entri workspace-directory eksplisit pada versi app-server yang plugin/list-nya mengimplementasikan marketplaceKinds dan mengembalikan remotePluginId untuk ringkasan workspace tanpa path. Entri tersebut harus menggunakan summary.id persis yang dilengkapi kualifikasi marketplace dan harus sudah terinstal, diaktifkan, serta aplikasinya dapat diakses. Permintaan daftar workspace yang ditolak menghasilkan diagnostik marketplace_missing per Plugin yang sudah ada; tidak adanya bukti marketplace, Plugin, detail, atau aplikasi menyebabkan aplikasi workspace tidak ditampilkan. Inventaris terkurasi dari permintaan daftar default tetap dapat digunakan.
• Plugin sumber yang didukung aplikasi harus lolos pemeriksaan langganan saat migrasi. --verify-plugin-apps menambahkan pemeriksaan inventaris aplikasi sumber. Akun yang dibatasi pemeriksaan langganan serta, dalam mode verifikasi, aplikasi sumber yang tidak dapat diakses, dinonaktifkan, atau tidak ada maupun kegagalan penyegaran inventaris aplikasi dilaporkan sebagai item manual yang dilewati, bukan sebagai entri konfigurasi aktif. Detail Plugin yang tidak dapat dibaca dilewati sebelum pemeriksaan inventaris aplikasi.
• Migrasi menulis identitas Plugin eksplisit (marketplaceName dan pluginName); migrasi tidak menulis path cache marketplacePath lokal.
• codexPlugins.enabled adalah satu-satunya sakelar pengaktifan global; tidak ada wildcard plugins["*"] atau kunci konfigurasi yang memberikan kewenangan instalasi arbitrer.
• Marketplace non-terkurasi, bundel Plugin yang disimpan dalam cache, hook, dan berkas konfigurasi Codex dipertahankan dalam laporan migrasi untuk peninjauan manual, bukan diaktifkan secara otomatis. Runtime menerima entri workspace-directory yang dikonfigurasi secara manual; marketplace lain tetap tidak didukung.

Inventaris dan kepemilikan aplikasi

OpenClaw membaca inventaris aplikasi Codex melalui app/list app-server, menyimpannya dalam cache memori selama satu jam, dan menyegarkan entri yang kedaluwarsa atau tidak ada secara asinkron. Cache bersifat lokal untuk proses; memulai ulang CLI atau Gateway akan menghapusnya, dan OpenClaw membangunnya kembali dari pembacaan app/list berikutnya.

Migrasi dan runtime menggunakan kunci cache terpisah:

• Verifikasi migrasi sumber menggunakan direktori home dan opsi mulai Codex sumber. Verifikasi hanya berjalan dengan --verify-plugin-apps dan memaksa penelusuran app/list sumber terbaru untuk proses perencanaan tersebut.
• Penyiapan runtime target menggunakan identitas app-server Codex milik agen target saat membangun konfigurasi aplikasi utas. Aktivasi Plugin terkurasi membatalkan kunci cache target tersebut, lalu memaksanya disegarkan setelah plugin/install. Penyiapan workspace-directory tidak pernah menjalankan jalur aktivasi ini.

Aplikasi Plugin hanya ditampilkan ketika OpenClaw dapat memetakannya kembali ke Plugin yang dikonfigurasi melalui kepemilikan stabil: ID aplikasi persis dari detail Plugin, nama server MCP yang diketahui, atau metadata stabil yang unik. Kepemilikan yang hanya berdasarkan nama tampilan atau bersifat ambigu dikecualikan hingga penyegaran inventaris berikutnya membuktikan kepemilikan.

Aplikasi akun yang terhubung

Agen yang dioperasikan pemilik dapat memilih untuk menggunakan setiap aplikasi yang sudah terhubung ke akun Codex mereka tanpa memerlukan paket Plugin yang cocok:

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          codexPlugins: {            enabled: true,            allow_all_plugins: true,            allow_destructive_actions: "auto",          },        },      },    },  },}

allow_all_plugins: true mengambil snapshot app/list lengkap saat utas Codex native baru dibuat dan hanya mengizinkan aplikasi yang ditandai dapat diakses oleh akun tersebut. Opsi ini tidak menginstal, mengautentikasi, atau mengaktifkan aplikasi secara global. Utas yang sudah ada mempertahankan kumpulan aplikasi tersimpannya; gunakan /new, /reset, atau mulai ulang Gateway agar aplikasi yang baru terhubung atau dicabut diterapkan.

Aplikasi akun mewarisi nilai global codexPlugins.allow_destructive_actions, yang menerima true, false, "auto", atau "ask". Kebijakan eksplisit per Plugin menggantikan kebijakan global untuk ID aplikasi yang tumpang tindih. Kegagalan inventaris ditutup secara aman dan tidak beralih ke default tanpa batasan.

Konfigurasi aplikasi utas

OpenClaw menyuntikkan patch config.apps yang restriktif untuk utas Codex: _default dinonaktifkan, dan hanya aplikasi milik plugin terkonfigurasi yang diaktifkan atau aplikasi akun yang dapat diakses dan diizinkan oleh allow_all_plugins yang diaktifkan.

destructive_enabled pada setiap aplikasi berasal dari kebijakan efektif global atau per-plugin allow_destructive_actions; true, "auto", dan "ask" semuanya menetapkan destructive_enabled: true, sedangkan false menetapkannya ke false. Codex tetap menerapkan metadata alat destruktif dari anotasi alat aplikasi native-nya. _default dinonaktifkan dengan open_world_enabled: false; aplikasi plugin yang diaktifkan mendapatkan open_world_enabled: true. OpenClaw tidak menyediakan kenop kebijakan dunia-terbuka terpisah pada tingkat plugin dan tidak memelihara daftar penolakan nama alat destruktif per-plugin.

Mode persetujuan alat secara default bersifat otomatis untuk aplikasi yang diizinkan, sehingga alat baca non-destruktif berjalan tanpa permintaan persetujuan dalam utas yang sama. Alat destruktif tetap dikendalikan oleh kebijakan destructive_enabled setiap aplikasi.

Kebijakan tindakan destruktif

Permintaan konfirmasi destruktif dari plugin secara default diizinkan untuk plugin Codex yang dikonfigurasi, sedangkan skema yang tidak aman dan kepemilikan yang ambigu ditolak secara aman:

• allow_destructive_actions global secara default bernilai true.
• allow_destructive_actions per-plugin menggantikan kebijakan global untuk plugin tersebut.
• false: OpenClaw mengembalikan penolakan deterministik.
• true: OpenClaw menerima secara otomatis hanya skema aman yang dapat dipetakannya ke respons persetujuan, seperti bidang persetujuan boolean.
• "auto": OpenClaw mengekspos tindakan plugin destruktif kepada Codex, lalu mengubah permintaan konfirmasi persetujuan MCP dengan kepemilikan yang telah terbukti menjadi persetujuan plugin OpenClaw sebelum mengembalikan respons persetujuan Codex.
• "ask": OpenClaw menggunakan pembatasan penulisan/destruktif Codex yang sama seperti "auto", menghapus penggantian persetujuan per-alat Codex yang persisten untuk aplikasi sebelum utas dimulai, dan hanya menawarkan persetujuan atau penolakan sekali pakai agar persetujuan persisten tidak dapat meniadakan permintaan tindakan tulis berikutnya. Untuk setiap aplikasi yang diizinkan dan menggunakan "ask", OpenClaw memilih peninjau persetujuan manusia Codex untuk aplikasi tersebut agar Codex mengirimkan permintaan konfirmasi persetujuannya ke OpenClaw; aplikasi lain dan persetujuan utas non-aplikasi tetap menggunakan peninjau dan kebijakan yang dikonfigurasi.
• Identitas plugin yang tidak ada, kepemilikan ambigu, id giliran yang tidak ada atau tidak cocok, maupun skema permintaan konfirmasi yang tidak aman akan ditolak alih-alih memunculkan permintaan.

Pemecahan masalah

Plugin ruang kerja terpasang tetapi tidak terlihat: pastikan hasil plugin/list ruang kerja melaporkan ID terkonfigurasi yang tepat sebagai terpasang dan diaktifkan, lalu pastikan app/list melaporkan setiap aplikasi milik plugin dapat diakses untuk akun Codex yang sama. OpenClaw dapat mengaktifkan aplikasi yang dapat diakses untuk utas meskipun inventaris akun saat ini melaporkan aplikasi tersebut dinonaktifkan. Jika Anda mengubah status tersebut setelah Gateway menyimpan inventaris aplikasi dalam cache, tunggu penyegaran cache satu jam atau mulai ulang Gateway, lalu gunakan /new atau /reset. OpenClaw tidak memperbaiki atau mengautentikasi plugin ruang kerja. Jika permintaan daftar ruang kerja eksplisit ditolak, setiap entri ruang kerja yang diaktifkan melaporkan marketplace_missing; entri terkurasi yang tidak terkait tetap diproses dari respons daftar default.

Untuk plugin_detail_unavailable, ringkasan ruang kerja tanpa jalur harus menyertakan remotePluginId; OpenClaw tetap menyembunyikan aplikasi milik plugin ketika pemilih tersebut atau hasil plugin/read berikutnya tidak tersedia. Untuk plugin_activation_failed, plugin terkurasi dapat melaporkan kegagalan marketplace, autentikasi, atau penyegaran pascapemasangan. Plugin ruang kerja melaporkan kode ini ketika belum aktif; pasang, aktifkan, dan autentikasikan di luar OpenClaw.

Konfigurasi berubah tetapi agen tidak dapat melihat plugin: jalankan /codex plugins list untuk memastikan status yang dikonfigurasi, lalu /new atau /reset. Pengikatan utas Codex yang ada mempertahankan konfigurasi aplikasi yang digunakan saat dimulai hingga OpenClaw membuat sesi harness baru atau mengganti pengikatan yang kedaluwarsa.

Tindakan destruktif ditolak: periksa nilai global dan per-plugin allow_destructive_actions. Bahkan dengan true, "auto", atau "ask", skema permintaan konfirmasi yang tidak aman dan identitas plugin yang ambigu tetap ditolak secara aman.

Terkait

• Harness Codex
• Referensi harness Codex
• Runtime harness Codex
• Referensi konfigurasi
• CLI migrasi