App Server | Bangun dengan Codex | Dokumentasi ChatGPT

Codex app-server adalah antarmuka yang digunakan Codex untuk mendukung klien kaya fitur (misalnya, ekstensi Codex VS Code). Gunakan antarmuka ini saat Anda menginginkan integrasi mendalam di dalam produk Anda sendiri: autentikasi, riwayat percakapan, persetujuan, dan peristiwa agen yang dialirkan. Implementasi app-server bersifat sumber terbuka di repositori GitHub Codex (openai/codex/codex-rs/app-server). Lihat halaman Sumber Terbuka untuk daftar lengkap komponen Codex sumber terbuka.

Menghubungkan antarmuka terminal CLI

Mode antarmuka terminal jarak jauh memungkinkan Anda menjalankan app-server di satu mesin dan menghubungkan antarmuka terminal Codex CLI dari mesin lain. Mulai listener WebSocket:

codex app-server --listen ws://127.0.0.1:4500

Kemudian hubungkan antarmuka terminal:

codex --remote ws://127.0.0.1:4500

Untuk koneksi nonlokal, konfigurasikan autentikasi WebSocket dan tempatkan koneksi di belakang TLS. Simpan token bearer dalam variabel lingkungan dan teruskan namanya, bukan menempatkan token di baris perintah:

export CODEX_REMOTE_TOKEN="$(cat "$HOME/.codex/app-server-token")"
codex --remote wss://remote-host:4500 \
  --remote-auth-token-env CODEX_REMOTE_TOKEN

Opsi --remote menerima endpoint ws://, wss://, unix://, dan unix://PATH. Gunakan WebSocket biasa hanya untuk localhost atau koneksi yang diteruskan melalui port SSH.

Menghubungkan host Code Mode jarak jauh

Secara default, app-server memulai host Code Mode lokal. Untuk menggunakan host jarak jauh sebagai gantinya, teruskan URL WebSocket amannya:

codex app-server --code-mode-host wss://code-mode.example.com/host

--code-mode-host mengontrol koneksi keluar dari app-server ke host Code Mode-nya. Opsi ini tidak mengubah --listen, yang mengontrol cara klien terhubung ke app-server. Setiap thread dalam proses app-server yang sama berbagi koneksi host Code Mode yang dipilih.

Gunakan wss:// untuk host jarak jauh. Gunakan ws:// hanya untuk koneksi localhost atau yang diteruskan melalui SSH. Perintah app-server dan transportasi WebSocket bersifat eksperimental dan tidak didukung untuk beban kerja produksi.

Protokol

Seperti MCP, codex app-server mendukung komunikasi dua arah menggunakan pesan JSON-RPC 2.0 (dengan header "jsonrpc":"2.0" dihilangkan saat dikirim melalui jaringan).

Transportasi yang didukung:

stdio (--listen stdio://, default): JSON yang dibatasi baris baru (JSONL).
websocket (--listen ws://IP:PORT, eksperimental dan tidak didukung): satu pesan JSON-RPC per bingkai teks WebSocket.
Soket Unix (--listen unix:// atau --listen unix://PATH): koneksi WebSocket melalui soket kontrol app-server default Codex atau jalur soket Unix khusus, menggunakan handshake HTTP Upgrade standar.
off (--listen off): jangan mengekspos transportasi lokal.

Saat Anda menjalankan dengan --listen ws://IP:PORT, listener yang sama juga melayani pemeriksaan kesehatan HTTP dasar:

GET /readyz mengembalikan 200 OK setelah listener menerima koneksi baru.
GET /healthz mengembalikan 200 OK saat permintaan tidak menyertakan header Origin.
Permintaan dengan header Origin ditolak dengan 403 Forbidden.

Transportasi WebSocket bersifat eksperimental dan tidak didukung. Listener lokal seperti ws://127.0.0.1:PORT sesuai untuk alur kerja localhost dan penerusan port SSH. Listener WebSocket non-loopback saat ini secara default mengizinkan koneksi tanpa autentikasi selama peluncuran bertahap, jadi konfigurasikan autentikasi WebSocket sebelum mengeksposnya dari jarak jauh.

Flag autentikasi WebSocket yang didukung:

--ws-auth capability-token --ws-token-file /absolute/path
--ws-auth capability-token --ws-token-sha256 HEX
--ws-auth signed-bearer-token --ws-shared-secret-file /absolute/path

Untuk token bearer bertanda tangan, Anda juga dapat mengatur --ws-issuer, --ws-audience, dan --ws-max-clock-skew-seconds. Klien menyajikan kredensial sebagai Authorization: Bearer <token> selama handshake WebSocket, dan app-server memberlakukan autentikasi sebelum JSON-RPC initialize.

Utamakan --ws-token-file daripada meneruskan token bearer mentah di baris perintah. Gunakan --ws-token-sha256 hanya jika klien menyimpan token mentah berentropi tinggi dalam penyimpanan rahasia lokal terpisah; hash hanya merupakan pemverifikasi, dan klien tetap memerlukan token asli.

Dalam mode WebSocket, app-server menggunakan antrean terbatas. Saat antrean masuk permintaan penuh, server menolak permintaan baru dengan kode kesalahan JSON-RPC -32001 dan pesan "Server overloaded; retry later." Klien harus mencoba kembali dengan penundaan yang meningkat secara eksponensial dan jitter.

Skema pesan

Permintaan menyertakan method, params, dan id:

{ "method": "thread/start", "id": 10, "params": { "model": "gpt-5.6-terra" } }

Respons menggemakan id dengan result atau error:

{ "id": 10, "result": { "thread": { "id": "thr_123" } } }

{ "id": 10, "error": { "code": 123, "message": "Something went wrong" } }

Notifikasi menghilangkan id dan hanya menggunakan method dan params:

{ "method": "turn/started", "params": { "turn": { "id": "turn_456" } } }

Anda dapat menghasilkan skema TypeScript atau bundel JSON Schema dari CLI. Setiap keluaran khusus untuk versi Codex yang Anda jalankan, sehingga artefak yang dihasilkan sama persis dengan versi tersebut:

codex app-server generate-ts --out ./schemas
codex app-server generate-json-schema --out ./schemas

Memulai

Mulai server dengan codex app-server (transportasi stdio default), codex app-server --listen ws://127.0.0.1:4500 (TCP WebSocket), atau codex app-server --listen unix:// (soket Unix default).
Hubungkan klien melalui transportasi yang dipilih, lalu kirim initialize yang diikuti oleh notifikasi initialized.
Mulai thread dan turn, lalu terus baca notifikasi dari aliran transportasi aktif.

Contoh (Node.js / TypeScript):




const proc = spawn("codex", ["app-server"], {
  stdio: ["pipe", "pipe", "inherit"],
});
const rl = readline.createInterface({ input: proc.stdout });

const send = (message: unknown) => {
  proc.stdin.write(`${JSON.stringify(message)}\n`);
};

let threadId: string | null = null;

rl.on("line", (line) => {
  const msg = JSON.parse(line) as any;
  console.log("server:", msg);

  if (msg.id === 1 && msg.result?.thread?.id && !threadId) {
    threadId = msg.result.thread.id;
    send({
      method: "turn/start",
      id: 2,
      params: {
        threadId,
        input: [{ type: "text", text: "Summarize this repo." }],
      },
    });
  }
});

send({
  method: "initialize",
  id: 0,
  params: {
    clientInfo: {
      name: "my_product",
      title: "My Product",
      version: "0.1.0",
    },
  },
});
send({ method: "initialized", params: {} });
send({ method: "thread/start", id: 1, params: { model: "gpt-5.6-terra" } });

Primitif inti

Thread: Percakapan antara pengguna dan agen Codex. Thread berisi turn.
Turn: Satu permintaan pengguna dan pekerjaan agen yang mengikutinya. Turn berisi item dan mengalirkan pembaruan inkremental.
Item: Unit masukan atau keluaran (pesan pengguna, pesan agen, eksekusi perintah, perubahan file, panggilan alat, dan lainnya).

Gunakan API thread untuk membuat, mencantumkan, atau mengarsipkan percakapan. Jalankan percakapan dengan API turn dan alirkan progres melalui notifikasi turn.

Ikhtisar siklus hidup

Inisialisasi sekali per koneksi: Segera setelah membuka koneksi transportasi, kirim permintaan initialize dengan metadata klien Anda, lalu kirim initialized. Server menolak setiap permintaan pada koneksi tersebut sebelum handshake ini.
Mulai (atau lanjutkan) thread: Panggil thread/start untuk percakapan baru, thread/resume untuk melanjutkan percakapan yang ada, atau thread/fork untuk mencabangkan riwayat ke id thread baru.
Mulai turn: Panggil turn/start dengan threadId target dan masukan pengguna. Field opsional menimpa model, kepribadian, cwd, kebijakan sandbox, dan lainnya.
Arahkan turn aktif: Panggil turn/steer untuk menambahkan masukan pengguna ke turn yang sedang berlangsung tanpa membuat turn baru.
Alirkan peristiwa: Setelah turn/start, terus baca notifikasi di stdout: thread/archived, thread/unarchived, item/started, item/completed, item/agentMessage/delta, progres alat, dan pembaruan lainnya.
Selesaikan turn: Server mengirim turn/completed dengan status akhir saat model selesai atau setelah pembatalan turn/interrupt.

Inisialisasi

Klien harus mengirim satu permintaan initialize per koneksi transportasi sebelum memanggil metode lain pada koneksi tersebut, lalu mengakuinya dengan notifikasi initialized. Permintaan yang dikirim sebelum inisialisasi menerima kesalahan Not initialized, dan panggilan initialize berulang pada koneksi yang sama mengembalikan Already initialized.

Server mengembalikan string agen pengguna yang akan disajikannya kepada layanan upstream beserta nilai platformFamily dan platformOs yang menjelaskan target runtime. Atur clientInfo untuk mengidentifikasi integrasi Anda.

initialize.params.capabilities juga mendukung kapabilitas klien berikut:

optOutNotificationMethods - nama metode notifikasi persis yang akan disembunyikan untuk koneksi ini. Pencocokan bersifat persis (tanpa wildcard atau prefiks); nama yang tidak dikenal diterima dan diabaikan.
requestAttestation - ikut serta dalam permintaan attestation/generate yang dimulai server. Host desktop yang menyediakan pengesahan upstream merespons dengan nilai { "token": "..." } yang opak.
mcpServerOpenaiFormElicitation - mengizinkan server MCP downstream mengirim varian bentuk diperluas OpenAI dari mcpServer/elicitation/request.

Penting: Gunakan clientInfo.name untuk mengidentifikasi klien Anda bagi OpenAI Compliance Logs Platform. Jika Anda mengembangkan integrasi Codex baru yang ditujukan untuk penggunaan perusahaan, hubungi OpenAI agar integrasi tersebut ditambahkan ke daftar klien yang dikenal. Untuk konteks selengkapnya, lihat referensi log Codex.

Contoh (dari ekstensi Codex VS Code):

{
  "method": "initialize",
  "id": 0,
  "params": {
    "clientInfo": {
      "name": "codex_vscode",
      "title": "Codex VS Code Extension",
      "version": "0.1.0"
    }
  }
}

Contoh dengan penolakan notifikasi:

{
  "method": "initialize",
  "id": 1,
  "params": {
    "clientInfo": {
      "name": "my_client",
      "title": "My Client",
      "version": "0.1.0"
    },
    "capabilities": {
      "experimentalApi": true,
      "optOutNotificationMethods": ["thread/started", "item/agentMessage/delta"]
    }
  }
}

Keikutsertaan API eksperimental

Beberapa metode dan field app-server sengaja dibatasi oleh kapabilitas experimentalApi.

Hilangkan capabilities (atau atur experimentalApi ke false) agar tetap menggunakan permukaan API stabil, dan server akan menolak metode/field eksperimental.
Atur capabilities.experimentalApi ke true untuk mengaktifkan metode dan field eksperimental.

{
  "method": "initialize",
  "id": 1,
  "params": {
    "clientInfo": {
      "name": "my_client",
      "title": "My Client",
      "version": "0.1.0"
    },
    "capabilities": {
      "experimentalApi": true
    }
  }
}

Jika klien mengirim metode atau field eksperimental tanpa ikut serta, app-server menolaknya dengan:

<descriptor> requires experimentalApi capability

Ikhtisar API

thread/start - membuat thread baru; mengirim thread/started dan secara otomatis membuat Anda berlangganan peristiwa turn/item untuk thread tersebut.
thread/resume - membuka kembali thread yang ada berdasarkan id agar panggilan turn/start berikutnya ditambahkan ke thread tersebut.
thread/fork - mencabangkan thread ke id thread baru dengan menyalin riwayat yang tersimpan. Teruskan lastTurnId untuk menyalin riwayat hingga turn tersebut dan menghilangkan turn berikutnya, atau ephemeral: true untuk membuat cabang dalam memori. Mengirim thread/started untuk thread baru; thread yang dikembalikan menyertakan forkedFromId jika tersedia.
thread/read - membaca thread tersimpan berdasarkan id tanpa melanjutkannya; atur includeTurns untuk mengembalikan riwayat turn lengkap. Objek thread yang dikembalikan menyertakan status runtime.
thread/list - menelusuri log thread tersimpan per halaman; mendukung paginasi berbasis kursor beserta filter modelProviders, sourceKinds, archived, isPinned, cwd, useStateDbOnly, searchTerm, dan parentThreadId atau ancestorThreadId yang eksperimental. Objek thread yang dikembalikan menyertakan status runtime.
thread/turns/list - eksperimental; menelusuri riwayat turn thread tersimpan per halaman tanpa melanjutkannya. itemsView mengontrol apakah item turn dihilangkan, diringkas, atau dimuat sepenuhnya.
thread/items/list - eksperimental; menelusuri item thread yang dipersistenkan per halaman, dengan opsi membatasinya pada satu turnId. Penyimpanan thread aktif harus mendukung paginasi item.
thread/loaded/list - mencantumkan id thread yang sedang dimuat dalam memori.
thread/name/set - mengatur atau memperbarui nama thread yang ditampilkan kepada pengguna untuk thread yang dimuat atau rollout yang dipersistenkan; mengirim thread/name/updated.
thread/goal/set - mengatur sasaran untuk thread; mengirim thread/goal/updated.
thread/goal/get - membaca sasaran saat ini untuk thread.
thread/goal/clear - menghapus sasaran; mengirim thread/goal/cleared.
thread/metadata/update - menambal metadata thread tersimpan berbasis SQLite, termasuk gitInfo dan isPinned yang dipersistenkan.
thread/archive - memindahkan file log thread ke direktori arsip dan mencoba mengarsipkan log thread turunan yang dibuat dan belum diarsipkan; mengembalikan {} jika berhasil dan mengirim thread/archived untuk setiap thread yang diarsipkan.
thread/delete - menghapus secara permanen thread aktif atau arsip yang dipersistenkan beserta semua thread turunan yang dibuat; mengembalikan {} jika berhasil dan mengirim thread/deleted untuk setiap thread yang dihapus.
thread/unsubscribe - menghentikan langganan koneksi ini dari peristiwa turn/item thread. Jika ini pelanggan terakhir, server membongkar thread setelah masa tenggang tanpa aktivitas tanpa pelanggan dan mengirim thread/closed.
thread/unarchive - memulihkan rollout thread yang diarsipkan ke direktori sesi aktif; mengembalikan thread yang dipulihkan dan mengirim thread/unarchived.
thread/status/changed - notifikasi yang dikirim saat status runtime thread yang dimuat berubah.
thread/compact/start - memicu pemadatan riwayat percakapan untuk thread; segera mengembalikan {} sementara progres dialirkan melalui notifikasi turn/* dan item/*.
thread/shellCommand - menjalankan perintah shell yang dimulai pengguna terhadap thread. Perintah ini berjalan di luar sandbox dengan akses penuh dan tidak mewarisi kebijakan sandbox thread.
thread/backgroundTerminals/clean - menghentikan semua terminal latar belakang yang berjalan untuk thread (eksperimental; memerlukan capabilities.experimentalApi).
thread/backgroundTerminals/list - mencantumkan terminal latar belakang yang berjalan untuk thread yang dimuat (eksperimental; memerlukan capabilities.experimentalApi).
thread/backgroundTerminals/terminate - menghentikan satu terminal latar belakang yang berjalan berdasarkan processId app-server (eksperimental; memerlukan capabilities.experimentalApi).
thread/rollback - tidak digunakan lagi; menghapus N turn terakhir dari konteks dalam memori dan mempersistenkan penanda rollback; mengembalikan thread yang diperbarui.
turn/start - menambahkan masukan pengguna ke thread dan memulai pembuatan Codex; merespons dengan turn awal dan mengalirkan peristiwa. Untuk collaborationMode, settings.developer_instructions: null berarti "gunakan instruksi bawaan untuk mode yang dipilih."
thread/inject_items - menambahkan item Responses API mentah ke riwayat yang terlihat oleh model pada thread yang dimuat tanpa memulai turn pengguna.
turn/steer - menambahkan masukan pengguna ke turn aktif yang sedang berlangsung untuk suatu thread; mengembalikan turnId yang diterima.
turn/interrupt - meminta pembatalan turn yang sedang berlangsung; keberhasilan dinyatakan dengan {} dan turn berakhir dengan status: "interrupted".
review/start - memulai peninjau Codex untuk thread; mengirim item enteredReviewMode dan exitedReviewMode.
command/exec - menjalankan satu perintah di bawah sandbox server tanpa memulai thread/turn.
command/exec/write - menulis byte stdin ke sesi command/exec yang berjalan atau menutup stdin.
command/exec/resize - mengubah ukuran sesi command/exec berbasis PTY yang berjalan.
command/exec/terminate - menghentikan sesi command/exec yang berjalan.
command/exec/outputDelta (notifikasi) - dikirim untuk potongan stdout/stderr berkode base64 dari sesi command/exec yang dialirkan.
process/spawn - memulai sesi proses eksplisit di luar sandbox Codex (eksperimental; memerlukan capabilities.experimentalApi).
process/writeStdin - menulis byte stdin ke sesi process/spawn yang berjalan atau menutup stdin (eksperimental).
process/resizePty - mengubah ukuran sesi proses berbasis PTY yang berjalan (eksperimental).
process/kill - menghentikan sesi proses yang berjalan (eksperimental).
process/outputDelta dan process/exited (notifikasi) - dikirim untuk keluaran proses yang dialirkan dan status keluar proses (eksperimental).
model/list - mencantumkan model yang tersedia (atur includeHidden: true untuk menyertakan entri dengan hidden: true) beserta opsi upaya, upgrade opsional, dan inputModalities.
modelProvider/capabilities/read - membaca batas kapabilitas penyedia untuk kombinasi model/penyedia.
experimentalFeature/list - mencantumkan flag fitur dengan metadata tahap siklus hidup dan paginasi kursor.
experimentalFeature/enablement/set - menambal pengaturan runtime dalam memori untuk kunci fitur yang didukung seperti apps dan plugins.
environment/info - eksperimental; terhubung ke lingkungan eksekusi yang dikonfigurasi dan mengembalikan shell beserta direktori kerja defaultnya.
permissionProfile/list - mencantumkan profil izin beta dan apakah persyaratan efektif mengizinkannya, dengan paginasi kursor.
collaborationMode/list - mencantumkan preset mode kolaborasi (eksperimental, tanpa paginasi).
skills/list - mencantumkan skill untuk satu atau beberapa nilai cwd (mendukung forceReload dan perCwdExtraUserRoots opsional).
skills/extraRoots/set - mengganti root tambahan tingkat proses yang digunakan untuk menemukan skill mandiri tanpa mempersistenkannya.
skills/changed (notifikasi) - dikirim saat file skill lokal yang dipantau berubah.
hooks/list - mencantumkan hook siklus hidup yang ditemukan untuk satu atau beberapa nilai cwd.
marketplace/add - menambahkan marketplace plugin jarak jauh dan mempersistenkannya ke konfigurasi marketplace pengguna.
marketplace/remove - menghapus marketplace yang dikonfigurasi dan root marketplace terinstalnya jika ada.
marketplace/upgrade - menyegarkan marketplace Git yang dikonfigurasi, atau semua marketplace Git yang dikonfigurasi jika nama marketplace dihilangkan.
plugin/list - dalam pengembangan; mencantumkan marketplace plugin yang ditemukan dan status plugin, termasuk metadata kebijakan instalasi/autentikasi, kesalahan pemuatan marketplace, id plugin unggulan, serta metadata sumber plugin lokal, Git, registri paket, atau jarak jauh. Ringkasan dapat menyertakan version jarak jauh, localVersion lokal, ikon terang/gelap terstruktur, dan installPolicySource, yang dapat berupa null, WORKSPACE_SETTING, atau IMPLICIT_CANONICAL_APP untuk baris jarak jauh saat ini. Jangan panggil metode ini dari klien produksi untuk saat ini.
plugin/read - dalam pengembangan; membaca satu plugin berdasarkan jalur marketplace atau nama marketplace jarak jauh dan nama plugin, termasuk skill yang dibundel, app, nama server MCP, dan shareUrl plugin jarak jauh jika katalog jarak jauh menyediakannya. Jangan panggil metode ini dari klien produksi untuk saat ini.
plugin/install - dalam pengembangan; menginstal plugin dari jalur marketplace atau nama marketplace jarak jauh. Jangan panggil metode ini dari klien produksi untuk saat ini.
plugin/uninstall - dalam pengembangan; menghapus instalasi plugin yang terinstal. Jangan panggil metode ini dari klien produksi untuk saat ini.
plugin/skill/read - membaca Markdown skill plugin jarak jauh sesuai permintaan berdasarkan marketplace jarak jauh, id plugin, dan nama skill.
app/installed - membaca status runtime app yang terinstal, termasuk status aktif dan dapat dipanggil yang efektif untuk setiap app.
app/list - mencantumkan app (konektor) yang tersedia dengan paginasi serta metadata aksesibilitas/aktif.
app/read - mengambil metadata dan ringkasan alat opsional khusus tampilan untuk id app tertentu.
skills/config/write - mengaktifkan atau menonaktifkan skill berdasarkan jalur.
mcpServer/oauth/login - memulai login OAuth untuk server MCP yang dikonfigurasi; mengembalikan URL otorisasi dan mengirim mcpServer/oauthLogin/completed saat selesai.
tool/requestUserInput - meminta pengguna menjawab 1–3 pertanyaan singkat untuk panggilan alat (eksperimental); pertanyaan dapat mengatur isOther untuk opsi bentuk bebas.
mcpServer/elicitation/request (permintaan server) - meminta klien memberikan masukan formulir terstruktur atau konfirmasi alur URL yang diminta oleh server MCP.
item/permissions/requestApproval (permintaan server) - meminta klien memberikan sebagian izin jaringan atau sistem file yang diminta oleh alat bawaan request_permissions.
config/mcpServer/reload - memuat ulang konfigurasi server MCP dari disk dan mengantrekan penyegaran untuk thread yang dimuat.
mcpServerStatus/list - mencantumkan server MCP, alat, sumber daya, dan status autentikasi (paginasi kursor + batas). Gunakan detail: "full" untuk data lengkap atau detail: "toolsAndAuthOnly" untuk menghilangkan sumber daya.
mcpServer/resource/read - membaca satu sumber daya MCP melalui server MCP yang telah diinisialisasi.
mcpServer/tool/call - memanggil alat pada server MCP yang dikonfigurasi untuk thread.
mcpServer/startupStatus/updated (notifikasi) - dikirim saat status startup server MCP yang dikonfigurasi berubah untuk thread yang dimuat.
windowsSandbox/setupStart - memulai penyiapan sandbox Windows untuk mode elevated atau unelevated; segera mengembalikan hasil dan kemudian mengirim windowsSandbox/setupCompleted.
feedback/upload - mengirim laporan umpan balik (klasifikasi + alasan/log opsional + id percakapan, beserta lampiran extraLogFiles opsional).
config/read - mengambil konfigurasi efektif pada disk setelah menyelesaikan pelapisan konfigurasi.
externalAgentConfig/detect - mendeteksi artefak agen eksternal yang dapat dimigrasikan dengan includeHome dan cwds opsional; setiap item yang terdeteksi menyertakan cwd (null untuk home).
externalAgentConfig/import - menerapkan item migrasi agen eksternal yang dipilih dengan meneruskan migrationItems eksplisit beserta cwd (null untuk home). Jenis item yang didukung mencakup konfigurasi, skill, AGENTS.md, plugin, konfigurasi server MCP, subagen, hook, perintah, dan sesi; impor yang tidak kosong mengirim externalAgentConfig/import/progress dan externalAgentConfig/import/completed saat pekerjaan selesai. Impor plugin dan sesi dapat diselesaikan secara asinkron.
config/value/write - menulis satu kunci/nilai konfigurasi ke config.toml pengguna pada disk.
config/batchWrite - menerapkan pengeditan konfigurasi secara atomik ke config.toml pengguna pada disk.
configRequirements/read - mengambil persyaratan dari requirements.toml dan/atau MDM, termasuk konfigurasi terkelola yang tepat, daftar yang diizinkan, featureRequirements yang disematkan, dan persyaratan residensi/jaringan (atau null jika Anda belum menyiapkannya).
fs/readFile, fs/writeFile, fs/createDirectory, fs/getMetadata, fs/readDirectory, fs/remove, fs/copy, fs/watch, fs/unwatch, dan fs/changed (notifikasi) - beroperasi pada jalur sistem file absolut melalui API sistem file app-server v2.

Ringkasan plugin menyertakan union source. Plugin lokal mengembalikan { "type": "local", "path": ... }, entri marketplace berbasis Git mengembalikan { "type": "git", "url": ..., "path": ..., "refName": ..., "sha": ... }, entri registri paket mengembalikan { "type": "npm", "package": ..., "version": ..., "registry": ... }, dan entri katalog jarak jauh mengembalikan { "type": "remote" }. Untuk entri katalog khusus jarak jauh, PluginMarketplaceEntry.path dapat berupa null; teruskan remoteMarketplaceName sebagai pengganti marketplacePath saat membaca atau menginstal plugin tersebut.

Model

Mencantumkan model (`model/list`)

Panggil model/list untuk menemukan model yang tersedia dan kapabilitasnya sebelum merender pemilih model atau kepribadian.

{ "method": "model/list", "id": 6, "params": { "limit": 20, "includeHidden": false } }
{ "id": 6, "result": {
  "data": [{
    "id": "gpt-5.6-sol",
    "model": "gpt-5.6-sol",
    "displayName": "GPT-5.6-Sol",
    "hidden": false,
    "defaultReasoningEffort": "low",
    "supportedReasoningEfforts": [{
      "reasoningEffort": "low",
      "description": "Fast responses with lighter reasoning"
    }],
    "inputModalities": ["text", "image"],
    "supportsPersonality": true,
    "isDefault": true
  }],
  "nextCursor": null
} }

Setiap entri model dapat menyertakan:

supportedReasoningEfforts - opsi upaya yang didukung untuk model.
defaultReasoningEffort - upaya default yang disarankan untuk klien.
upgrade - id model peningkatan opsional yang direkomendasikan untuk prompt migrasi dalam klien.
upgradeInfo - metadata peningkatan opsional untuk prompt migrasi dalam klien.
hidden - apakah model disembunyikan dari daftar pemilih default.
inputModalities - jenis masukan yang didukung untuk model (misalnya text, image).
supportsPersonality - apakah model mendukung instruksi khusus kepribadian seperti /personality.
isDefault - apakah model merupakan default yang direkomendasikan.

Secara default, model/list hanya mengembalikan model yang terlihat di pemilih. Atur includeHidden: true jika Anda memerlukan daftar lengkap dan ingin memfilter di sisi klien menggunakan hidden.

Jika inputModalities tidak ada (katalog model lama), perlakukan sebagai ["text", "image"] untuk kompatibilitas mundur.

Mencantumkan fitur eksperimental (`experimentalFeature/list`)

Gunakan endpoint ini untuk menemukan flag fitur beserta metadata dan tahap siklus hidup:

{ "method": "experimentalFeature/list", "id": 7, "params": { "limit": 20 } }
{ "id": 7, "result": {
  "data": [{
    "name": "unified_exec",
    "stage": "beta",
    "displayName": "Unified exec",
    "description": "Use the unified PTY-backed execution tool.",
    "announcement": "Beta rollout for improved command execution reliability.",
    "enabled": false,
    "defaultEnabled": false
  }],
  "nextCursor": null
} }

stage dapat berupa beta, underDevelopment, stable, deprecated, atau removed. Untuk flag non-beta, displayName, description, dan announcement dapat berupa null.

Memeriksa lingkungan eksekusi (eksperimental)

Gunakan environment/info untuk memeriksa lingkungan jarak jauh yang dikonfigurasi sebelum memulai pekerjaan di sana. Metode ini memerlukan capabilities.experimentalApi = true.

{ "method": "environment/info", "id": 8, "params": { "environmentId": "devbox" } }
{ "id": 8, "result": {
  "shell": { "name": "zsh", "path": "/bin/zsh" },
  "cwd": "file:///workspace/project"
} }

cwd dapat berupa null. Jika tersedia, nilainya adalah URI file: kanonis yang menggunakan sintaks jalur asli lingkungan tersebut. ID lingkungan yang tidak dikenal serta kegagalan koneksi atau protokol mengembalikan kesalahan permintaan.

Thread

thread/read membaca thread tersimpan tanpa berlangganan; atur includeTurns untuk menyertakan turn.
thread/turns/list bersifat eksperimental dan menelusuri riwayat turn thread tersimpan per halaman tanpa melanjutkannya. Gunakan itemsView untuk memilih apakah item turn dihilangkan, diringkas, atau dimuat sepenuhnya.
thread/items/list bersifat eksperimental dan menelusuri item thread yang dipersistenkan per halaman, dengan opsi membatasinya pada satu turn.
thread/list mendukung paginasi kursor beserta pemfilteran modelProviders, sourceKinds, archived, isPinned, cwd, useStateDbOnly, searchTerm, dan parentThreadId atau ancestorThreadId yang eksperimental.
thread/loaded/list mengembalikan ID thread yang saat ini berada dalam memori.
thread/archive memindahkan log JSONL thread yang dipersistenkan ke direktori arsip dan mencoba mengarsipkan log thread turunan yang dibuat dan belum diarsipkan.
thread/delete menghapus secara permanen thread aktif atau arsip yang dipersistenkan beserta thread turunannya yang dibuat.
thread/metadata/update menambal metadata thread tersimpan, termasuk gitInfo dan isPinned yang dipersistenkan.
thread/unsubscribe menghentikan langganan koneksi saat ini dari thread yang dimuat dan dapat memicu thread/closed setelah masa tenggang tanpa aktivitas.
thread/unarchive memulihkan rollout thread yang diarsipkan ke direktori sesi aktif.
thread/compact/start memicu pemadatan dan segera mengembalikan {}.
thread/rollback tidak digunakan lagi. Metode ini menghapus N turn terakhir dari konteks dalam memori dan mencatat penanda rollback dalam log JSONL thread yang dipersistenkan.
thread/inject_items menambahkan item Responses API mentah ke riwayat yang terlihat oleh model pada thread yang dimuat tanpa memulai turn pengguna.

Memulai atau melanjutkan thread

Mulai thread baru saat Anda memerlukan percakapan Codex baru.

{ "method": "thread/start", "id": 10, "params": {
  "model": "gpt-5.6-terra",
  "cwd": "/Users/me/project",
  "approvalPolicy": "never",
  "sandbox": "workspaceWrite",
  "personality": "friendly",
  "serviceName": "my_app_server_client"
} }
{ "id": 10, "result": {
  "thread": {
    "id": "thr_123",
    "sessionId": "thr_123",
    "preview": "",
    "ephemeral": false,
    "modelProvider": "openai",
    "createdAt": 1730910000
  }
} }
{ "method": "thread/started", "params": { "thread": { "id": "thr_123" } } }

serviceName bersifat opsional. Atur saat Anda ingin app-server menandai metrik tingkat thread dengan nama layanan integrasi Anda.

thread/start, thread/resume, dan thread/fork mengembalikan instructionSources, yaitu array jalur file instruksi yang dimuat. Setiap jalur menggunakan sintaks absolut asli lingkungan sumbernya, termasuk untuk lingkungan jarak jauh.

Klien eksperimental dapat mengatur historyMode pada thread/start ke "legacy" (default) atau "paginated". Pembuatan thread dengan paginasi belum didukung dan mengembalikan kesalahan JSON-RPC -32601. App-server dapat mencantumkan dan membaca ringkasan untuk catatan berpaginasi yang ada, tetapi pembacaan riwayat lengkap, paginasi turn, dan pelanjutan ditolak hingga riwayat berpaginasi didukung.

Klien beta yang ikut serta dalam capabilities.experimentalApi dapat meneruskan id profil izin bernama dalam permissions sebagai pengganti field lama sandbox. Jangan kirim permissions dan sandbox bersamaan. Gunakan permissionProfile/list dengan cwd proyek untuk menemukan profil yang tersedia dan apakah persyaratan terkelola mengizinkan masing-masing profil.

thread.sessionId mengidentifikasi root pohon sesi aktif saat ini. Thread root menggunakan id thread-nya sendiri sebagai id sesi; thread hasil pencabangan mempertahankan id sesi dari root asalnya. Klien harus membaca id sesi dari thread.sessionId dan bukan menurunkannya dari id thread.

Untuk melanjutkan sesi tersimpan, panggil thread/resume dengan thread.id yang Anda catat sebelumnya. Bentuk respons sama dengan thread/start. Anda juga dapat meneruskan penggantian konfigurasi yang sama dengan yang didukung oleh thread/start, seperti personality:

{ "method": "thread/resume", "id": 11, "params": {
  "threadId": "thr_123",
  "personality": "friendly"
} }
{ "id": 11, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes", "ephemeral": false } } }

Melanjutkan thread tidak dengan sendirinya memperbarui thread.updatedAt (atau waktu modifikasi file rollout). Stempel waktu diperbarui saat Anda memulai turn.

Jika Anda menandai server MCP yang aktif sebagai required dalam konfigurasi dan server tersebut gagal diinisialisasi, thread/start dan thread/resume akan gagal alih-alih melanjutkan tanpanya.

dynamicTools pada thread/start adalah field eksperimental (memerlukan capabilities.experimentalApi = true). Codex mempersistenkan alat dinamis ini dalam metadata rollout thread dan memulihkannya pada thread/resume saat Anda tidak menyediakan alat dinamis baru.

Jika Anda melanjutkan dengan model yang berbeda dari model yang dicatat dalam rollout, Codex mengirim peringatan dan menerapkan instruksi peralihan model satu kali pada turn berikutnya.

Mengelola sasaran thread

Gunakan thread/goal/set, thread/goal/get, dan thread/goal/clear untuk mengelola status sasaran terpersisten yang sama dengan yang ditampilkan oleh /goal di TUI.

{ "method": "thread/goal/set", "id": 13, "params": {
  "threadId": "thr_123",
  "objective": "Finish the migration and keep tests green",
  "status": "active",
  "tokenBudget": 40000
} }
{ "id": 13, "result": { "goal": {
  "threadId": "thr_123",
  "objective": "Finish the migration and keep tests green",
  "status": "active",
  "tokenBudget": 40000,
  "tokensUsed": 0,
  "timeUsedSeconds": 0
} } }
{ "method": "thread/goal/updated", "params": {
  "threadId": "thr_123",
  "goal": {
    "threadId": "thr_123",
    "objective": "Finish the migration and keep tests green",
    "status": "active",
    "tokenBudget": 40000,
    "tokensUsed": 0,
    "timeUsedSeconds": 0
  }
} }

Objektif sasaran tidak boleh kosong dan panjangnya maksimum 4.000 karakter. Memberikan objektif baru akan mengganti sasaran dan mengatur ulang penghitungan penggunaan. Memberikan objektif nonterminal saat ini, atau menghilangkan objective, akan memperbarui status atau anggaran token sekaligus mempertahankan riwayat penggunaan.

Untuk mencabangkan dari sesi tersimpan, panggil thread/fork dengan thread.id. Tindakan ini membuat id thread baru dan mengirim notifikasi thread/started untuknya. Teruskan lastTurnId untuk menyalin riwayat hingga dan termasuk turn tersebut serta menghilangkan turn berikutnya:

{ "method": "thread/fork", "id": 12, "params": { "threadId": "thr_123", "lastTurnId": "turn_456" } }
{ "id": 12, "result": { "thread": { "id": "thr_456", "sessionId": "thr_123", "forkedFromId": "thr_123" } } }
{ "method": "thread/started", "params": { "thread": { "id": "thr_456" } } }

App-server menolak lastTurnId yang sedang berlangsung. Jika Anda menghilangkan field tersebut saat thread sumber berada di tengah turn, cabang mencatat penanda interupsi alih-alih mempertahankan turn parsial tanpa penanda.

Teruskan ephemeral: true untuk membuat cabang dalam memori tanpa menambahkannya ke daftar thread tersimpan:

{
  "method": "thread/fork",
  "id": 13,
  "params": {
    "threadId": "thr_123",
    "ephemeral": true
  }
}
{
  "id": 13,
  "result": {
    "thread": {
      "id": "thr_789",
      "sessionId": "thr_789",
      "forkedFromId": "thr_123",
      "ephemeral": true
    }
  }
}

Cabang sementara dari thread berpaginasi juga memerlukan excludeTurns: true. Field tersebut bersifat eksperimental dan memerlukan capabilities.experimentalApi = true.

Jika judul thread yang ditampilkan kepada pengguna telah diatur, app-server menghidrasi thread.name pada respons thread/list, thread/read, thread/resume, thread/unarchive, dan thread/rollback. thread/start dan thread/fork dapat menghilangkan name (atau mengembalikan null) hingga judul diatur kemudian.

Membaca thread tersimpan (tanpa melanjutkan)

Gunakan thread/read saat Anda menginginkan data thread tersimpan tetapi tidak ingin melanjutkan thread atau berlangganan peristiwanya.

includeTurns - jika true, respons menyertakan turn thread; jika false atau dihilangkan, Anda hanya mendapatkan ringkasan thread.
Objek thread yang dikembalikan menyertakan status runtime (notLoaded, idle, systemError, atau active dengan activeFlags).

{ "method": "thread/read", "id": 19, "params": { "threadId": "thr_123", "includeTurns": true } }
{ "id": 19, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes", "ephemeral": false, "status": { "type": "notLoaded" }, "turns": [] } } }

Tidak seperti thread/resume, thread/read tidak memuat thread ke dalam memori atau mengirim thread/started.

Mencantumkan turn thread

thread/turns/list bersifat eksperimental. Gunakan untuk menelusuri riwayat turn thread tersimpan per halaman tanpa melanjutkannya. Hasil secara default diurutkan dari yang terbaru agar klien dapat mengambil turn yang lebih lama dengan nextCursor. Respons juga menyertakan backwardsCursor; teruskan sebagai cursor dengan sortDirection: "asc" untuk mengambil turn yang lebih baru daripada item pertama dari halaman sebelumnya.

itemsView mengontrol jumlah data item turn yang disertakan dalam respons:

notLoaded menghilangkan item.
summary mengembalikan data item yang diringkas dan menjadi default jika dihilangkan.
full mengembalikan data item lengkap.

{ "method": "thread/turns/list", "id": 20, "params": {
  "threadId": "thr_123",
  "limit": 50,
  "sortDirection": "desc",
  "itemsView": "summary"
} }
{ "id": 20, "result": {
  "data": [],
  "nextCursor": "older-turns-cursor-or-null",
  "backwardsCursor": "newer-turns-cursor-or-null"
} }

thread/items/list juga bersifat eksperimental. Metode ini menelusuri item yang dipersistenkan per halaman tanpa melanjutkan thread. Teruskan turnId untuk membatasi hasil pada satu turn, atau hilangkan untuk menelusuri item di seluruh thread. Penyimpanan thread aktif harus mendukung paginasi item; jika tidak, server mengembalikan kesalahan metode yang tidak didukung.

Mencantumkan thread (dengan paginasi & filter)

thread/list memungkinkan Anda merender UI riwayat. Hasil secara default diurutkan dari yang terbaru berdasarkan createdAt. Filter diterapkan sebelum paginasi. Teruskan kombinasi apa pun dari:

cursor - string opak dari respons sebelumnya; hilangkan untuk halaman pertama.
limit - server menggunakan ukuran halaman yang wajar secara default jika tidak diatur.
sortKey - created_at (default), updated_at, atau recency_at.
sortDirection - desc (default) atau asc.
modelProviders - membatasi hasil pada penyedia tertentu; tidak diatur, null, atau array kosong akan menyertakan semua penyedia.
sourceKinds - membatasi hasil pada sumber thread tertentu. Jika dihilangkan atau [], server secara default hanya menyertakan sumber interaktif: cli dan vscode.
archived - jika true, hanya mencantumkan thread yang diarsipkan. Jika false atau dihilangkan, mencantumkan thread yang tidak diarsipkan (default).
isPinned - jika diberikan, hanya mengembalikan thread dengan status sematan terpersisten yang cocok. Hilangkan untuk mengembalikan thread yang disematkan dan tidak disematkan.
cwd - membatasi hasil pada thread yang direktori kerja sesi saat ini sama persis dengan jalur ini, atau salah satu jalur dalam array. Jalur relatif diselesaikan dari direktori kerja proses app-server.
useStateDbOnly - jika true, mengembalikan hasil basis data status tanpa memindai log thread JSONL untuk memperbaiki metadata. Hilangkan atau teruskan false untuk perilaku pindai-dan-perbaiki default.
searchTerm - membatasi hasil pada thread yang judul ekstraknya berisi fragmen teks peka huruf besar-kecil ini.
parentThreadId - membatasi hasil pada thread anak langsung dari thread induk yang diberikan. Filter ini eksperimental dan memerlukan capabilities.experimentalApi = true.
ancestorThreadId - membatasi hasil pada turunan yang dibuat dari thread yang diberikan pada kedalaman berapa pun. Filter ini eksperimental dan memerlukan capabilities.experimentalApi = true; jangan gabungkan dengan parentThreadId.

sourceKinds menerima nilai berikut:

cli
vscode
exec
appServer
subAgent
subAgentReview
subAgentCompact
subAgentThreadSpawn
subAgentOther
unknown

Contoh:

{ "method": "thread/list", "id": 20, "params": {
  "cursor": null,
  "limit": 25,
  "sortKey": "created_at"
} }
{ "id": 20, "result": {
  "data": [
    { "id": "thr_a", "preview": "Create a TUI", "ephemeral": false, "isPinned": true, "modelProvider": "openai", "createdAt": 1730831111, "updatedAt": 1730831111, "name": "TUI prototype", "status": { "type": "notLoaded" } },
    { "id": "thr_b", "preview": "Fix tests", "ephemeral": false, "isPinned": false, "modelProvider": "openai", "createdAt": 1730750000, "updatedAt": 1730750000, "status": { "type": "notLoaded" } }
  ],
  "nextCursor": "opaque-token-or-null"
} }

Jika nextCursor adalah null, Anda telah mencapai halaman terakhir.

Memperbarui metadata thread tersimpan

Gunakan thread/metadata/update untuk menambal metadata thread tersimpan tanpa melanjutkan thread. Atur isPinned untuk menyematkan atau melepas sematan thread, atau perbarui gitInfo untuk mengubah metadata Git yang dipersistenkan. Field yang dihilangkan tetap tidak berubah; null eksplisit menghapus nilai metadata Git yang tersimpan.

{ "method": "thread/metadata/update", "id": 21, "params": {
  "threadId": "thr_123",
  "isPinned": true,
  "gitInfo": { "branch": "feature/sidebar-pr" }
} }
{ "id": 21, "result": {
  "thread": {
    "id": "thr_123",
    "isPinned": true,
    "gitInfo": { "sha": null, "branch": "feature/sidebar-pr", "originUrl": null }
  }
} }

Melacak perubahan status thread

thread/status/changed dikirim setiap kali status runtime thread yang dimuat berubah. Payload menyertakan threadId dan status baru.

{
  "method": "thread/status/changed",
  "params": {
    "threadId": "thr_123",
    "status": { "type": "active", "activeFlags": ["waitingOnApproval"] }
  }
}

Mencantumkan thread yang dimuat

thread/loaded/list mengembalikan ID thread yang saat ini dimuat dalam memori.

{ "method": "thread/loaded/list", "id": 21 }
{ "id": 21, "result": { "data": ["thr_123", "thr_456"] } }

Menghentikan langganan dari thread yang dimuat

thread/unsubscribe menghapus langganan koneksi saat ini dari suatu thread. Status respons adalah salah satu dari:

unsubscribed jika koneksi sebelumnya berlangganan dan kini telah dihapus.
notSubscribed jika koneksi tidak berlangganan thread tersebut.
notLoaded jika thread tidak dimuat.

Jika ini pelanggan terakhir, server tetap memuat thread hingga thread tidak memiliki pelanggan dan tidak memiliki aktivitas selama 30 menit. Saat masa tenggang berakhir, app-server membongkar thread dan mengirim transisi thread/status/changed ke notLoaded beserta thread/closed.

{ "method": "thread/unsubscribe", "id": 22, "params": { "threadId": "thr_123" } }
{ "id": 22, "result": { "status": "unsubscribed" } }

Jika thread kemudian kedaluwarsa:

{ "method": "thread/status/changed", "params": {
    "threadId": "thr_123",
    "status": { "type": "notLoaded" }
} }
{ "method": "thread/closed", "params": { "threadId": "thr_123" } }

Mengarsipkan thread

Gunakan thread/archive untuk memindahkan log thread yang dipersistenkan (disimpan sebagai file JSONL pada disk) ke direktori sesi yang diarsipkan. Mengarsipkan thread juga akan mencoba mengarsipkan thread turunan yang dibuat dan belum diarsipkan.

{ "method": "thread/archive", "id": 22, "params": { "threadId": "thr_b" } }
{ "id": 22, "result": {} }
{ "method": "thread/archived", "params": { "threadId": "thr_b" } }
{ "method": "thread/archived", "params": { "threadId": "thr_child" } }

Thread yang diarsipkan tidak akan muncul dalam panggilan mendatang ke thread/list kecuali Anda meneruskan archived: true. Server mengirim satu notifikasi thread/archived untuk setiap thread yang benar-benar diarsipkannya; jika turunan yang dibuat tidak dapat diarsipkan, permintaan tetap dapat berhasil tanpa notifikasi pengarsipan untuk turunan tersebut.

Menghapus thread

Gunakan thread/delete untuk menghapus secara permanen thread aktif atau arsip yang dipersistenkan beserta thread turunannya yang dibuat. Server menghapus file rollout yang ada dan metadata terkait sebelum mengembalikan keberhasilan; file rollout yang tidak ditemukan dianggap sudah dihapus. Thread root sementara tidak dapat dihapus.

{ "method": "thread/delete", "id": 23, "params": { "threadId": "thr_b" } }
{ "id": 23, "result": {} }
{ "method": "thread/deleted", "params": { "threadId": "thr_b" } }
{ "method": "thread/deleted", "params": { "threadId": "thr_child" } }

Membatalkan pengarsipan thread

Gunakan thread/unarchive untuk memindahkan kembali rollout thread yang diarsipkan ke direktori sesi aktif.

{ "method": "thread/unarchive", "id": 24, "params": { "threadId": "thr_b" } }
{ "id": 24, "result": { "thread": { "id": "thr_b", "name": "Bug bash notes" } } }
{ "method": "thread/unarchived", "params": { "threadId": "thr_b" } }

Memicu pemadatan thread

Gunakan thread/compact/start untuk memicu pemadatan riwayat secara manual bagi sebuah thread. Permintaan segera mengembalikan {}.

App-server mengirim progres sebagai notifikasi standar turn/* dan item/* pada threadId yang sama, termasuk siklus hidup item contextCompaction (item/started lalu item/completed).

{ "method": "thread/compact/start", "id": 25, "params": { "threadId": "thr_b" } }
{ "id": 25, "result": {} }

Menjalankan perintah shell thread

Gunakan thread/shellCommand untuk perintah shell yang dimulai pengguna dan merupakan bagian dari sebuah thread. Permintaan segera mengembalikan {}, sementara progres dialirkan melalui notifikasi standar turn/* dan item/*.

API ini berjalan di luar sandbox dengan akses penuh dan tidak mewarisi kebijakan sandbox thread. Klien sebaiknya hanya mengeksposnya untuk perintah yang secara eksplisit dimulai pengguna.

Jika thread sudah memiliki turn aktif, perintah berjalan sebagai tindakan tambahan pada turn tersebut dan output yang telah diformat disisipkan ke aliran pesan turn. Jika thread sedang tidak aktif, app-server memulai turn mandiri untuk perintah shell tersebut.

{ "method": "thread/shellCommand", "id": 26, "params": { "threadId": "thr_b", "command": "git status --short" } }
{ "id": 26, "result": {} }

Membersihkan terminal latar belakang

Gunakan thread/backgroundTerminals/clean untuk menghentikan semua terminal latar belakang yang sedang berjalan dan terkait dengan sebuah thread. Metode ini bersifat eksperimental dan memerlukan capabilities.experimentalApi = true.

{ "method": "thread/backgroundTerminals/clean", "id": 27, "params": { "threadId": "thr_b" } }
{ "id": 27, "result": {} }

Gunakan thread/backgroundTerminals/list untuk memeriksa terminal latar belakang yang sedang berjalan bagi thread yang telah dimuat. Permintaan mendukung paginasi standar cursor dan limit, dan processId yang dikembalikan adalah ID proses app-server. Metode ini bersifat eksperimental dan memerlukan capabilities.experimentalApi = true:

{ "method": "thread/backgroundTerminals/list", "id": 28, "params": { "threadId": "thr_b" } }
{ "id": 28, "result": { "data": [
  {
    "itemId": "item_456",
    "processId": "42",
    "command": "python3 -m http.server",
    "cwd": "/workspace",
    "osPid": null,
    "cpuPercent": null,
    "rssKb": null
  }
], "nextCursor": null } }

Gunakan thread/backgroundTerminals/terminate dengan processId tersebut untuk menghentikan satu terminal latar belakang. Metode ini bersifat eksperimental dan memerlukan capabilities.experimentalApi = true:

{ "method": "thread/backgroundTerminals/terminate", "id": 29, "params": { "threadId": "thr_b", "processId": "42" } }
{ "id": 29, "result": { "terminated": true } }

Mengembalikan turn terbaru

thread/rollback sudah tidak direkomendasikan dan akan dihapus. Metode ini menghapus numTurns entri terakhir dari konteks dalam memori dan menyimpan penanda rollback dalam log rollout. thread yang dikembalikan mencakup turns yang telah diisi setelah rollback.

{ "method": "thread/rollback", "id": 30, "params": { "threadId": "thr_b", "numTurns": 1 } }
{ "id": 30, "result": { "thread": { "id": "thr_b", "name": "Bug bash notes", "ephemeral": false } } }

Turn

Kolom input menerima daftar item:

{ "type": "text", "text": "Explain this diff" }
{ "type": "image", "url": "https://.../design.png" }
{ "type": "localImage", "path": "/tmp/screenshot.png" }

Anda dapat mengganti pengaturan konfigurasi per turn (model, upaya, kepribadian, cwd, kebijakan sandbox, ringkasan). Jika ditentukan, pengaturan ini menjadi nilai default bagi turn berikutnya pada thread yang sama. outputSchema hanya berlaku untuk turn saat ini. Untuk sandboxPolicy.type = "externalSandbox", atur networkAccess ke restricted atau enabled; untuk workspaceWrite, networkAccess tetap berupa boolean.

Untuk turn/start.collaborationMode, settings.developer_instructions: null berarti "gunakan instruksi bawaan untuk mode yang dipilih", bukan menghapus instruksi mode.

Akses baca sandbox (`ReadOnlyAccess`)

sandboxPolicy mendukung kontrol akses baca eksplisit:

readOnly: access opsional ({ "type": "fullAccess" } secara default, atau root yang dibatasi).
workspaceWrite: readOnlyAccess opsional ({ "type": "fullAccess" } secara default, atau root yang dibatasi).

Bentuk akses baca terbatas:

{
  "type": "restricted",
  "includePlatformDefaults": true,
  "readableRoots": ["/Users/me/shared-read-only"]
}

Di macOS, includePlatformDefaults: true menambahkan kebijakan Seatbelt default platform yang telah dikurasi untuk sesi dengan akses baca terbatas. Hal ini meningkatkan kompatibilitas alat tanpa mengizinkan seluruh /System secara luas.

Contoh:

{ "type": "readOnly", "access": { "type": "fullAccess" } }

{
  "type": "workspaceWrite",
  "writableRoots": ["/Users/me/project"],
  "readOnlyAccess": {
    "type": "restricted",
    "includePlatformDefaults": true,
    "readableRoots": ["/Users/me/shared-read-only"]
  },
  "networkAccess": false
}

Memulai turn

{ "method": "turn/start", "id": 30, "params": {
  "threadId": "thr_123",
  "input": [ { "type": "text", "text": "Run tests" } ],
  "cwd": "/Users/me/project",
  "approvalPolicy": "unlessTrusted",
  "sandboxPolicy": {
    "type": "workspaceWrite",
    "writableRoots": ["/Users/me/project"],
    "networkAccess": true
  },
  "model": "gpt-5.6-terra",
  "effort": "medium",
  "summary": "concise",
  "personality": "friendly",
  "outputSchema": {
    "type": "object",
    "properties": { "answer": { "type": "string" } },
    "required": ["answer"],
    "additionalProperties": false
  }
} }
{ "id": 30, "result": { "turn": { "id": "turn_456", "status": "inProgress", "items": [], "error": null } } }

Menyisipkan item ke dalam thread

Gunakan thread/inject_items untuk menambahkan item Responses API siap pakai ke riwayat prompt thread yang telah dimuat tanpa memulai turn pengguna. Item ini dipersistenkan ke rollout dan disertakan dalam permintaan model berikutnya.

{ "method": "thread/inject_items", "id": 31, "params": {
  "threadId": "thr_123",
  "items": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Previously computed context." }]
    }
  ]
} }
{ "id": 31, "result": {} }

Mengarahkan turn aktif

Gunakan turn/steer untuk menambahkan input pengguna ke turn aktif yang sedang berlangsung.

Sertakan expectedTurnId; nilainya harus cocok dengan ID turn aktif.
Permintaan gagal jika tidak ada turn aktif pada thread.
turn/steer tidak mengirim notifikasi turn/started baru.
turn/steer tidak menerima penggantian tingkat turn (model, cwd, sandboxPolicy, atau outputSchema).

{ "method": "turn/steer", "id": 32, "params": {
  "threadId": "thr_123",
  "input": [ { "type": "text", "text": "Actually focus on failing tests first." } ],
  "expectedTurnId": "turn_456"
} }
{ "id": 32, "result": { "turnId": "turn_456" } }

Memulai turn (memanggil skill)

Panggil skill secara eksplisit dengan menyertakan $<skill-name> dalam input teks dan menambahkan item input skill bersamanya.

{ "method": "turn/start", "id": 33, "params": {
  "threadId": "thr_123",
  "input": [
    { "type": "text", "text": "$skill-creator Add a new skill for triaging flaky CI and include step-by-step usage." },
    { "type": "skill", "name": "skill-creator", "path": "/Users/me/.codex/skills/skill-creator/SKILL.md" }
  ]
} }
{ "id": 33, "result": { "turn": { "id": "turn_457", "status": "inProgress", "items": [], "error": null } } }

Menginterupsi turn

{ "method": "turn/interrupt", "id": 31, "params": { "threadId": "thr_123", "turnId": "turn_456" } }
{ "id": 31, "result": {} }

Jika berhasil, turn selesai dengan status: "interrupted".

Peninjauan

review/start menjalankan peninjau Codex untuk sebuah thread dan mengalirkan item peninjauan. Target mencakup:

uncommittedChanges
baseBranch (diff terhadap sebuah branch)
commit (meninjau commit tertentu)
custom (instruksi berformat bebas)

Gunakan delivery: "inline" (default) untuk menjalankan peninjauan pada thread yang ada, atau delivery: "detached" untuk membuat fork berupa thread peninjauan baru.

Contoh permintaan/respons:

{ "method": "review/start", "id": 40, "params": {
  "threadId": "thr_123",
  "delivery": "inline",
  "target": { "type": "commit", "sha": "1234567deadbeef", "title": "Polish tui colors" }
} }
{ "id": 40, "result": {
  "turn": {
    "id": "turn_900",
    "status": "inProgress",
    "items": [
      { "type": "userMessage", "id": "turn_900", "content": [ { "type": "text", "text": "Review commit 1234567: Polish tui colors" } ] }
    ],
    "error": null
  },
  "reviewThreadId": "thr_123"
} }

Untuk peninjauan terpisah, gunakan "delivery": "detached". Bentuk responsnya sama, tetapi reviewThreadId akan menjadi ID thread peninjauan baru (berbeda dari threadId asli). Server juga mengirim notifikasi thread/started untuk thread baru tersebut sebelum mengalirkan turn peninjauan.

Codex mengalirkan notifikasi turn/started yang biasa, diikuti oleh item/started dengan item enteredReviewMode:

{
  "method": "item/started",
  "params": {
    "item": {
      "type": "enteredReviewMode",
      "id": "turn_900",
      "review": "current changes"
    }
  }
}

Saat peninjau selesai, server mengirim item/started dan item/completed yang berisi item exitedReviewMode dengan teks peninjauan akhir:

{
  "method": "item/completed",
  "params": {
    "item": {
      "type": "exitedReviewMode",
      "id": "turn_900",
      "review": "Looks solid overall..."
    }
  }
}

Gunakan notifikasi ini untuk merender output peninjau di klien Anda.

Eksekusi proses

process/* adalah API kontrol proses eksplisit yang bersifat eksperimental. API ini memerlukan capabilities.experimentalApi = true dan berjalan di luar sandbox Codex. Gunakan hanya jika klien Anda sengaja mengekspos kontrol proses lokal tanpa sandbox.

Mulai proses dengan process/spawn dan berikan processHandle, lalu gunakan handle tersebut untuk permintaan stdin, pengubahan ukuran, dan penghentian. Output dialirkan melalui notifikasi process/outputDelta dan penyelesaian dialirkan melalui process/exited.

{ "method": "process/spawn", "id": 48, "params": {
  "command": ["python3", "-m", "pytest", "-q"],
  "processHandle": "pytest-1",
  "cwd": "/Users/me/project",
  "tty": true
} }
{ "id": 48, "result": {} }
{ "method": "process/outputDelta", "params": {
  "processHandle": "pytest-1",
  "stream": "stdout",
  "deltaBase64": "Li4u"
} }
{ "method": "process/exited", "params": {
  "processHandle": "pytest-1",
  "exitCode": 0
} }

Gunakan process/writeStdin dengan deltaBase64, closeStdin, atau keduanya untuk mengirim input. Gunakan process/resizePty untuk peristiwa pengubahan ukuran PTY dan process/kill untuk menghentikan proses yang sedang berjalan.

Eksekusi perintah

command/exec menjalankan satu perintah (array argv) di dalam sandbox server tanpa membuat thread.

{ "method": "command/exec", "id": 50, "params": {
  "command": ["ls", "-la"],
  "cwd": "/Users/me/project",
  "sandboxPolicy": { "type": "workspaceWrite" },
  "timeoutMs": 10000
} }
{ "id": 50, "result": { "exitCode": 0, "stdout": "...", "stderr": "" } }

Gunakan sandboxPolicy.type = "externalSandbox" jika Anda sudah menjalankan proses server dalam sandbox dan ingin Codex melewati penerapan sandbox-nya sendiri. Untuk mode sandbox eksternal, atur networkAccess ke restricted (default) atau enabled. Untuk readOnly dan workspaceWrite, gunakan struktur opsional access / readOnlyAccess yang sama seperti ditunjukkan di atas.

Catatan:

Server menolak array command kosong.
sandboxPolicy menerima bentuk yang sama dengan yang digunakan oleh turn/start (misalnya, dangerFullAccess, readOnly, workspaceWrite, externalSandbox).
Jika dihilangkan, timeoutMs kembali ke nilai default server.
Atur tty: true untuk sesi berbasis PTY, dan gunakan processId jika Anda berencana menindaklanjutinya dengan command/exec/write, command/exec/resize, atau command/exec/terminate.
Atur streamStdoutStderr: true untuk menerima notifikasi command/exec/outputDelta saat perintah berjalan.

Membaca persyaratan admin (`configRequirements/read`)

Gunakan configRequirements/read untuk memeriksa persyaratan admin efektif yang dimuat dari requirements.toml dan/atau MDM.

{ "method": "configRequirements/read", "id": 52, "params": {} }
{ "id": 52, "result": {
  "requirements": {
    "allowedApprovalPolicies": ["onRequest", "unlessTrusted"],
    "allowedSandboxModes": ["readOnly", "workspaceWrite"],
    "featureRequirements": {
      "personality": true,
      "unified_exec": false
    },
    "network": {
      "enabled": true,
      "allowedDomains": ["api.openai.com"],
      "allowUnixSockets": ["/tmp/example.sock"],
      "dangerouslyAllowAllUnixSockets": false
    }
  }
} }

result.requirements adalah null jika tidak ada persyaratan yang dikonfigurasi. Lihat dokumentasi tentang requirements.toml untuk detail mengenai kunci dan nilai yang didukung.

Penyiapan sandbox Windows (`windowsSandbox/setupStart`)

Klien Windows khusus dapat memicu penyiapan sandbox secara asinkron agar tidak terblokir oleh pemeriksaan saat startup.

{ "method": "windowsSandbox/setupStart", "id": 53, "params": { "mode": "elevated" } }
{ "id": 53, "result": { "started": true } }

App-server memulai penyiapan di latar belakang dan kemudian mengirim notifikasi penyelesaian:

{
  "method": "windowsSandbox/setupCompleted",
  "params": { "mode": "elevated", "success": true, "error": null }
}

Mode:

elevated - menjalankan jalur penyiapan sandbox Windows dengan hak akses yang ditingkatkan.
unelevated - menjalankan jalur penyiapan/pemeriksaan awal versi lama.

Sistem file

API sistem file v2 beroperasi pada path absolut. Gunakan fs/watch saat klien perlu membatalkan validitas status UI setelah file atau direktori berubah.

{ "method": "fs/watch", "id": 54, "params": {
  "watchId": "0195ec6b-1d6f-7c2e-8c7a-56f2c4a8b9d1",
  "path": "/Users/me/project/.git/HEAD"
} }
{ "id": 54, "result": { "path": "/Users/me/project/.git/HEAD" } }
{ "method": "fs/changed", "params": {
  "watchId": "0195ec6b-1d6f-7c2e-8c7a-56f2c4a8b9d1",
  "changedPaths": ["/Users/me/project/.git/HEAD"]
} }
{ "method": "fs/unwatch", "id": 55, "params": {
  "watchId": "0195ec6b-1d6f-7c2e-8c7a-56f2c4a8b9d1"
} }
{ "id": 55, "result": {} }

Pemantauan file mengirim fs/changed untuk path file tersebut, termasuk pembaruan yang dikirim melalui operasi penggantian atau penggantian nama.

Peristiwa

Notifikasi peristiwa merupakan aliran yang dimulai server untuk siklus hidup thread, siklus hidup turn, dan item di dalamnya. Setelah Anda memulai atau melanjutkan thread, terus baca aliran transport aktif untuk notifikasi thread/started, thread/archived, thread/unarchived, thread/closed, thread/status/changed, turn/*, item/*, dan serverRequest/resolved.

Menonaktifkan notifikasi

Klien dapat menyembunyikan notifikasi tertentu per koneksi dengan mengirim nama metode persis dalam initialize.params.capabilities.optOutNotificationMethods.

Hanya kecocokan persis: item/agentMessage/delta hanya menyembunyikan metode tersebut.
Nama metode yang tidak dikenal diabaikan.
Berlaku untuk thread/*, turn/*, item/*, dan notifikasi v2 terkait saat ini.
Tidak berlaku untuk permintaan, respons, atau kesalahan.

Peristiwa pencarian file fuzzy (eksperimental)

API sesi pencarian file fuzzy mengirim notifikasi per kueri:

fuzzyFileSearch/sessionUpdated - { sessionId, query, files } dengan kecocokan saat ini untuk kueri aktif.
fuzzyFileSearch/sessionCompleted - { sessionId } setelah pengindeksan dan pencocokan untuk kueri tersebut selesai.

Peristiwa peringatan

configWarning - { summary, details?, path?, range? } untuk masalah konfigurasi atau inisialisasi yang dapat dipulihkan.
warning - { threadId?, message } untuk peringatan runtime yang tidak fatal.

Peristiwa penyiapan sandbox Windows

windowsSandbox/setupCompleted - { mode, success, error } yang dikirim setelah permintaan windowsSandbox/setupStart selesai.

Peristiwa turn

turn/started - { turn } dengan ID turn, items kosong, dan status: "inProgress".
turn/completed - { turn } dengan turn.status berupa completed, interrupted, atau failed; kegagalan membawa { error: { message, codexErrorInfo?, additionalDetails? } }.
turn/diff/updated - { threadId, turnId, diff } dengan unified diff gabungan terbaru untuk setiap perubahan file dalam turn.
turn/plan/updated - { turnId, explanation?, plan } setiap kali agen membagikan atau mengubah rencananya; setiap entri plan adalah { step, status } dengan status berupa pending, inProgress, atau completed.
hook/started dan hook/completed - { threadId, turnId?, run } saat hook siklus hidup dimulai dan ketika ringkasan eksekusi akhirnya tersedia.
model/safetyBuffering/updated - { threadId, turnId, model, useCases, reasons, showBufferingUi, fasterModel } saat respons memasuki buffering keamanan sementara.
model/rerouted - { threadId, turnId, fromModel, toModel, reason } saat layanan merutekan permintaan ke model lain.
model/verification - { threadId, turnId, verifications } saat layanan memerlukan verifikasi akun tambahan.
thread/tokenUsage/updated - pembaruan penggunaan untuk thread aktif.

turn/diff/updated dan turn/plan/updated saat ini menyertakan array items kosong meskipun peristiwa item dialirkan. Gunakan notifikasi item/* sebagai sumber kebenaran untuk item turn.

Item

ThreadItem adalah tagged union yang dibawa dalam respons turn dan notifikasi item/*. Jenis item umum mencakup:

userMessage - {id, content} dengan content berupa daftar input pengguna (text, image, atau localImage).
agentMessage - {id, text, phase?} yang berisi balasan agen yang telah diakumulasi. Jika ada, phase menggunakan nilai wire Responses API (commentary, final_answer).
plan - {id, text} yang berisi teks rencana yang diusulkan dalam mode rencana. Perlakukan item plan terakhir dari item/completed sebagai sumber otoritatif.
reasoning - {id, summary, content} dengan summary menyimpan ringkasan penalaran yang dialirkan dan content menyimpan blok penalaran mentah.
commandExecution - {id, command, cwd, status, commandActions, aggregatedOutput?, exitCode?, durationMs?}.
fileChange - {id, changes, status} yang menjelaskan pengeditan yang diusulkan; changes mencantumkan {path, kind, diff}.
mcpToolCall - {id, server, tool, status, arguments, appContext?, pluginId?, result?, error?}. Untuk aplikasi MCP tepercaya, appContext dapat menyertakan connectorId, linkId, resourceUri, appName, templateId, dan konektor stabil actionName. Item lama yang dipersistenkan dapat tidak menyertakan metadata yang lebih baru. Gunakan appContext.resourceUri sebagai pengganti mcpAppResourceUri tingkat atas yang sudah tidak direkomendasikan.
dynamicToolCall - {id, tool, arguments, status, contentItems?, success?, durationMs?} untuk pemanggilan alat dinamis yang dijalankan klien.
collabToolCall - {id, tool, status, senderThreadId, receiverThreadId?, newThreadId?, prompt?, agentStatus?}.
webSearch - {id, query, action?} untuk permintaan pencarian web yang dibuat oleh agen.
imageView - {id, path} yang dikirim saat agen memanggil alat penampil gambar.
enteredReviewMode - {id, review} yang dikirim saat peninjau mulai bekerja.
exitedReviewMode - {id, review} yang dikirim saat peninjau selesai.
contextCompaction - {id} yang dikirim saat Codex memadatkan riwayat percakapan.

Untuk webSearch.action, tindakan type dapat berupa search (query?, queries?), openPage (url?), atau findInPage (url?, pattern?).

App-server tidak lagi merekomendasikan notifikasi lama thread/compacted; gunakan item contextCompaction sebagai gantinya.

Semua item mengirim dua peristiwa siklus hidup bersama:

item/started - mengirim item lengkap saat unit kerja baru dimulai; item.id cocok dengan itemId yang digunakan oleh delta.
item/completed - mengirim item akhir setelah pekerjaan selesai; perlakukan ini sebagai status otoritatif.

Delta item

item/agentMessage/delta - menambahkan teks yang dialirkan untuk pesan agen.
item/plan/delta - mengalirkan teks rencana yang diusulkan. Item plan akhir mungkin tidak sama persis dengan gabungan delta.
item/reasoning/summaryTextDelta - mengalirkan ringkasan penalaran yang mudah dibaca; summaryIndex bertambah saat bagian ringkasan baru dibuka.
item/reasoning/summaryPartAdded - menandai batas antara bagian ringkasan penalaran.
item/reasoning/textDelta - mengalirkan teks penalaran mentah (jika didukung oleh model).
item/commandExecution/outputDelta - mengalirkan stdout/stderr untuk sebuah perintah; tambahkan delta secara berurutan.
item/fileChange/outputDelta - notifikasi kompatibilitas untuk output teks apply_patch lama yang sudah tidak direkomendasikan. Versi app-server saat ini tidak lagi mengirimnya; gunakan item fileChange dan turn/diff/updated sebagai gantinya.

Kesalahan

Jika turn gagal, server mengirim peristiwa error dengan { error: { message, codexErrorInfo?, additionalDetails? } }, lalu menyelesaikan turn dengan status: "failed". Jika status HTTP upstream tersedia, status tersebut muncul dalam codexErrorInfo.httpStatusCode.

Nilai codexErrorInfo yang umum mencakup:

ContextWindowExceeded
UsageLimitExceeded
HttpConnectionFailed (kesalahan upstream 4xx/5xx)
ResponseStreamConnectionFailed
ResponseStreamDisconnected
ResponseTooManyFailedAttempts
BadRequest, Unauthorized, SandboxError, InternalServerError, Other

Jika status HTTP upstream tersedia, server meneruskannya dalam httpStatusCode pada varian codexErrorInfo yang relevan.

Persetujuan

Bergantung pada pengaturan Codex pengguna, eksekusi perintah dan perubahan file mungkin memerlukan persetujuan. App-server mengirim permintaan JSON-RPC yang dimulai server kepada klien, lalu klien merespons dengan payload keputusan.

Keputusan eksekusi perintah: accept, acceptForSession, decline, cancel, atau { "acceptWithExecpolicyAmendment": { "execpolicy_amendment": ["cmd", "..."] } }.
Keputusan perubahan file: accept, acceptForSession, decline, cancel.
Permintaan menyertakan threadId dan turnId - gunakan keduanya untuk membatasi status UI ke percakapan aktif.
Server melanjutkan atau menolak pekerjaan dan mengakhiri item dengan item/completed.

Persetujuan eksekusi perintah

Urutan pesan:

item/started menampilkan item commandExecution yang menunggu dengan command, cwd, dan kolom lainnya.
item/commandExecution/requestApproval menyertakan itemId, threadId, turnId, reason opsional, command opsional, cwd opsional, commandActions opsional, proposedExecpolicyAmendment opsional, networkApprovalContext opsional, dan availableDecisions opsional. Jika initialize.params.capabilities.experimentalApi = true, payload juga dapat menyertakan additionalPermissions eksperimental yang menjelaskan akses sandbox per perintah yang diminta. Setiap path sistem file di dalam additionalPermissions bersifat absolut pada wire.
Klien merespons dengan salah satu keputusan persetujuan eksekusi perintah di atas.
serverRequest/resolved mengonfirmasi bahwa permintaan yang menunggu telah dijawab atau dihapus.
item/completed mengembalikan item commandExecution akhir dengan status: completed | failed | declined.

Jika networkApprovalContext ada, prompt tersebut ditujukan untuk akses jaringan terkelola (bukan persetujuan perintah shell umum). Skema v2 saat ini mengekspos target host dan protocol; klien sebaiknya merender prompt khusus jaringan dan tidak mengandalkan command sebagai pratinjau perintah shell yang bermakna bagi pengguna.

Codex mengelompokkan prompt persetujuan jaringan serentak berdasarkan tujuan (host, protokol, dan port). Karena itu, app-server dapat mengirim satu prompt yang membuka blokir beberapa permintaan dalam antrean ke tujuan yang sama, sedangkan port berbeda pada host yang sama diperlakukan secara terpisah.

Persetujuan perubahan file

Urutan pesan:

item/started mengirim item fileChange dengan usulan changes dan status: "inProgress".
item/fileChange/requestApproval menyertakan itemId, threadId, turnId, reason opsional, dan grantRoot opsional.
Klien merespons dengan salah satu keputusan persetujuan perubahan file di atas.
serverRequest/resolved mengonfirmasi bahwa permintaan yang menunggu telah dijawab atau dihapus.
item/completed mengembalikan item fileChange akhir dengan status: completed | failed | declined.

`tool/requestUserInput`

Saat klien merespons item/tool/requestUserInput, app-server mengirim serverRequest/resolved dengan { threadId, requestId }. Jika permintaan yang menunggu dihapus karena turn dimulai, turn selesai, atau turn diinterupsi sebelum klien menjawab, server mengirim notifikasi yang sama untuk pembersihan tersebut.

Parameter permintaan menyertakan autoResolutionMs sebagai batas waktu milidetik berupa bilangan bulat atau null. Jika ada, klien host dapat menyelesaikan prompt secara otomatis setelah interval tersebut apabila pengguna tidak menjawab.

Permintaan izin

Alat bawaan request_permissions mengirim item/permissions/requestApproval dengan threadId, turnId, itemId, environmentId, cwd, reason opsional, dan izin jaringan atau sistem file yang diminta. Respons dengan permissions yang hanya berisi subset yang diberikan. Atur scope ke "session" untuk mempertahankan pemberian izin bagi turn berikutnya dalam sesi yang sama; hilangkan atau gunakan "turn" untuk pemberian izin yang cakupannya terbatas pada turn. Izin yang tidak diminta akan diabaikan.

Permintaan elisitasi server MCP

Server MCP dapat menginterupsi turn dengan mcpServer/elicitation/request. Permintaan menyertakan threadId, turnId opsional, serverName, dan salah satu bentuk permintaan berikut:

mode: "form" atau mode: "openai/form", dengan message dan requestedSchema.
mode: "url", dengan message, url, dan elicitationId.

Respons dengan action: "accept" dan content yang diminta, atau dengan action: "decline" atau "cancel" dan content: null. App-server kemudian mengirim serverRequest/resolved. Untuk menerima varian openai/form, ikut serta dengan initialize.params.capabilities.mcpServerOpenaiFormElicitation.

Pemanggilan alat dinamis (eksperimental)

dynamicTools pada thread/start serta alur permintaan atau respons item/tool/call yang terkait merupakan API eksperimental.

Nama alat dinamis dan nama namespace harus mengikuti batasan penamaan Responses API. Hindari nama namespace khusus yang digunakan oleh alat bawaan Codex.

Saat alat dinamis dipanggil selama turn, app-server mengirim:

item/started dengan item.type = "dynamicToolCall", status = "inProgress", serta tool dan arguments.
item/tool/call sebagai permintaan server kepada klien.
Payload respons klien dengan item konten yang dikembalikan.
item/completed dengan item.type = "dynamicToolCall", status akhir, serta setiap nilai contentItems atau success yang dikembalikan.

Persetujuan pemanggilan alat MCP (aplikasi)

Pemanggilan alat aplikasi (konektor) juga dapat memerlukan persetujuan. Jika pemanggilan alat aplikasi memiliki efek samping, server dapat meminta persetujuan dengan tool/requestUserInput dan opsi seperti Terima, Tolak, dan Batal. Anotasi alat yang bersifat destruktif selalu memicu persetujuan meskipun alat tersebut juga mengiklankan petunjuk dengan hak akses lebih rendah. Jika pengguna menolak atau membatalkan, item mcpToolCall terkait selesai dengan kesalahan tanpa menjalankan alat.

Skill

Panggil skill dengan menyertakan $<skill-name> dalam input teks pengguna. Tambahkan item input skill (direkomendasikan) agar server menyisipkan instruksi skill lengkap, bukan mengandalkan model untuk menemukan namanya.

{
  "method": "turn/start",
  "id": 101,
  "params": {
    "threadId": "thread-1",
    "input": [
      {
        "type": "text",
        "text": "$skill-creator Add a new skill for triaging flaky CI."
      },
      {
        "type": "skill",
        "name": "skill-creator",
        "path": "/Users/me/.codex/skills/skill-creator/SKILL.md"
      }
    ]
  }
}

Jika Anda menghilangkan item skill, model tetap akan mengurai penanda $<skill-name> dan mencoba menemukan skill, yang dapat menambah latensi.

Contoh:

$skill-creator Add a new skill for triaging flaky CI and include step-by-step usage.

Gunakan skills/list untuk mengambil skill yang tersedia (secara opsional dibatasi oleh cwds, dengan forceReload). Anda juga dapat menyertakan perCwdExtraUserRoots untuk memindai path absolut tambahan sebagai cakupan user bagi nilai cwd tertentu. App-server mengabaikan entri yang cwd-nya tidak ada dalam cwds. skills/list dapat menggunakan kembali hasil cache per cwd; atur forceReload: true untuk memuat ulang dari disk. Jika ada, server membaca interface dan dependencies dari SKILL.json.

{ "method": "skills/list", "id": 25, "params": {
  "cwds": ["/Users/me/project", "/Users/me/other-project"],
  "forceReload": true,
  "perCwdExtraUserRoots": [
    {
      "cwd": "/Users/me/project",
      "extraUserRoots": ["/Users/me/shared-skills"]
    }
  ]
} }
{ "id": 25, "result": {
  "data": [{
    "cwd": "/Users/me/project",
    "skills": [
      {
        "name": "skill-creator",
        "description": "Create or update a Codex skill",
        "enabled": true,
        "interface": {
          "displayName": "Skill Creator",
          "shortDescription": "Create or update a Codex skill"
        },
        "dependencies": {
          "tools": [
            {
              "type": "env_var",
              "value": "GITHUB_TOKEN",
              "description": "GitHub API token"
            },
            {
              "type": "mcp",
              "value": "github",
              "transport": "streamable_http",
              "url": "https://example.com/mcp"
            }
          ]
        }
      }
    ],
    "errors": []
  }]
} }

Server juga mengirim notifikasi skills/changed saat file skill lokal yang dipantau berubah. Perlakukan ini sebagai sinyal pembatalan validitas dan jalankan kembali skills/list dengan parameter Anda saat ini bila diperlukan.

Untuk mengaktifkan atau menonaktifkan skill berdasarkan path:

{
  "method": "skills/config/write",
  "id": 26,
  "params": {
    "path": "/Users/me/.codex/skills/skill-creator/SKILL.md",
    "enabled": false
  }
}

Aplikasi (konektor)

Gunakan app/installed untuk membaca snapshot runtime aplikasi terinstal terbaru yang telah di-commit. Setiap hasil menyertakan id aplikasi, runtimeName (atau null), status enabled efektif, dan status callable. Aplikasi hanya dapat dipanggil jika konfigurasi efektif mengaktifkannya dan setidaknya satu alat yang terlihat oleh model mematuhi kebijakan aplikasi dan alat.

{
  "method": "app/installed",
  "id": 49,
  "params": {
    "threadId": "thread-1",
    "forceRefresh": false
  }
}
{
  "id": 49,
  "result": {
    "apps": [
      {
        "id": "demo-app",
        "runtimeName": "Demo App",
        "enabled": true,
        "callable": true
      }
    ]
  }
}

Hilangkan threadId untuk menggunakan konfigurasi global, bukan konfigurasi thread yang telah dimuat. Atur forceRefresh: true untuk menyegarkan snapshot runtime konektor sebelum membacanya. Jika kebijakan global atau workspace memblokir akses aplikasi, aplikasi yang terdeteksi tetap dapat muncul dengan enabled dan callable yang diatur ke false.

Gunakan app/list untuk mengambil aplikasi yang tersedia. Di CLI/TUI, /apps adalah pemilih yang ditampilkan kepada pengguna; di klien khusus, panggil app/list secara langsung. Setiap entri menyertakan isAccessible (tersedia bagi pengguna) dan isEnabled (diaktifkan dalam config.toml), sehingga klien dapat membedakan instalasi/akses dari status aktif lokal. Entri aplikasi juga dapat menyertakan kolom opsional branding, appMetadata, dan labels.

{ "method": "app/list", "id": 50, "params": {
  "cursor": null,
  "limit": 50,
  "threadId": "thread-1",
  "forceRefetch": false
} }
{ "id": 50, "result": {
  "data": [
    {
      "id": "demo-app",
      "name": "Demo App",
      "description": "Example connector for documentation.",
      "logoUrl": "https://example.com/demo-app.png",
      "logoUrlDark": null,
      "distributionChannel": null,
      "branding": null,
      "appMetadata": null,
      "labels": null,
      "installUrl": "https://chatgpt.com/apps/demo-app/demo-app",
      "isAccessible": true,
      "isEnabled": true
    }
  ],
  "nextCursor": null
} }

Jika Anda memberikan threadId, pembatasan fitur aplikasi (features.apps) menggunakan snapshot konfigurasi thread tersebut. Jika dihilangkan, app-server menggunakan konfigurasi global terbaru.

app/list kembali setelah aplikasi yang dapat diakses dan aplikasi direktori selesai dimuat. Atur forceRefetch: true untuk melewati cache aplikasi dan mengambil data baru. Entri cache hanya diganti jika penyegaran berhasil.

Server juga mengirim notifikasi app/list/updated setiap kali salah satu sumber (aplikasi yang dapat diakses atau aplikasi direktori) selesai dimuat. Setiap notifikasi menyertakan daftar aplikasi gabungan terbaru.

{
  "method": "app/list/updated",
  "params": {
    "data": [
      {
        "id": "demo-app",
        "name": "Demo App",
        "description": "Example connector for documentation.",
        "logoUrl": "https://example.com/demo-app.png",
        "logoUrlDark": null,
        "distributionChannel": null,
        "branding": null,
        "appMetadata": null,
        "labels": null,
        "installUrl": "https://chatgpt.com/apps/demo-app/demo-app",
        "isAccessible": true,
        "isEnabled": true
      }
    ]
  }
}

Gunakan app/read jika Anda sudah mengetahui ID aplikasi dan memerlukan metadata aplikasi, bukan status runtime yang terinstal. Teruskan maksimal 100 appIds. Server hanya mempertahankan kemunculan pertama setiap ID yang berulang dan mempertahankan urutan tersebut dalam apps maupun missingAppIds. Aplikasi yang tidak dikenal atau tidak dapat diakses dikembalikan dalam missingAppIds tanpa menyebabkan seluruh permintaan gagal.

{
  "method": "app/read",
  "id": 52,
  "params": {
    "appIds": ["demo-app", "missing-app"],
    "includeTools": true
  }
}
{
  "id": 52,
  "result": {
    "apps": [
      {
        "id": "demo-app",
        "name": "Demo App",
        "description": "Example connector for documentation.",
        "iconUrl": null,
        "iconUrlDark": null,
        "distributionChannel": null,
        "installUrl": null,
        "pluginDisplayNames": [],
        "toolSummaries": [
          {
            "name": "search",
            "title": "Search",
            "description": "Search the app.",
            "isEnabled": true,
            "disabledReason": null,
            "isReadOnly": true
          }
        ]
      }
    ],
    "missingAppIds": ["missing-app"]
  }
}

Atur includeTools: true untuk meminta ringkasan alat publik yang hanya ditujukan bagi tampilan. Respons metadata tidak menyertakan status runtime aplikasi terinstal atau memberikan otorisasi untuk pemanggilan alat; gunakan app/installed untuk memeriksa status efektif enabled dan callable.

Panggil aplikasi dengan menyisipkan $<app-slug> dalam input teks dan menambahkan item input mention dengan path app://<id> (direkomendasikan).

{
  "method": "turn/start",
  "id": 51,
  "params": {
    "threadId": "thread-1",
    "input": [
      {
        "type": "text",
        "text": "$demo-app Pull the latest updates from the team."
      },
      {
        "type": "mention",
        "name": "Demo App",
        "path": "app://demo-app"
      }
    ]
  }
}

Contoh RPC konfigurasi untuk pengaturan aplikasi

Gunakan config/read, config/value/write, dan config/batchWrite untuk memeriksa atau memperbarui kontrol aplikasi dalam config.toml.

Baca bentuk konfigurasi aplikasi efektif (termasuk _default dan penggantian per alat):

{ "method": "config/read", "id": 60, "params": { "includeLayers": false } }
{ "id": 60, "result": {
  "config": {
    "apps": {
      "_default": {
        "enabled": true,
        "destructive_enabled": true,
        "open_world_enabled": true,
        "approvals_reviewer": "user",
        "default_tools_approval_mode": "auto"
      },
      "google_drive": {
        "enabled": true,
        "destructive_enabled": false,
        "approvals_reviewer": "auto_review",
        "default_tools_approval_mode": "prompt",
        "tools": {
          "files/delete": { "enabled": false, "approval_mode": "approve" }
        }
      }
    }
  }
} }

apps._default.approvals_reviewer menetapkan peninjau untuk semua aplikasi kecuali nilai per aplikasi menggantikannya. Jika keduanya dihilangkan, aplikasi mewarisi nilai approvals_reviewer tingkat atas. apps._default.default_tools_approval_mode menetapkan mode persetujuan fallback untuk alat tanpa penggantian per aplikasi atau per alat. Persyaratan mode persetujuan terkelola menggantikan pengaturan mode persetujuan alat.

Perbarui satu pengaturan aplikasi:

{
  "method": "config/value/write",
  "id": 61,
  "params": {
    "keyPath": "apps.google_drive.default_tools_approval_mode",
    "value": "prompt",
    "mergeStrategy": "replace"
  }
}

Terapkan beberapa pengeditan aplikasi secara atomik:

{
  "method": "config/batchWrite",
  "id": 62,
  "params": {
    "edits": [
      {
        "keyPath": "apps._default.destructive_enabled",
        "value": false,
        "mergeStrategy": "upsert"
      },
      {
        "keyPath": "apps.google_drive.tools.files/delete.approval_mode",
        "value": "approve",
        "mergeStrategy": "upsert"
      }
    ]
  }
}

Mendeteksi dan mengimpor konfigurasi agen eksternal

Gunakan externalAgentConfig/detect untuk menemukan artefak agen eksternal yang dapat dimigrasikan, lalu teruskan entri yang dipilih ke externalAgentConfig/import.

Contoh deteksi:

{ "method": "externalAgentConfig/detect", "id": 63, "params": {
  "includeHome": true,
  "cwds": ["/Users/me/project"]
} }
{ "id": 63, "result": {
  "items": [
    {
      "itemType": "AGENTS_MD",
      "description": "Import /Users/me/project/CLAUDE.md to /Users/me/project/AGENTS.md.",
      "cwd": "/Users/me/project"
    },
    {
      "itemType": "SKILLS",
      "description": "Copy skill folders from /Users/me/.claude/skills to /Users/me/.agents/skills.",
      "cwd": null
    }
  ]
} }

Contoh impor:

{ "method": "externalAgentConfig/import", "id": 64, "params": {
  "migrationItems": [
    {
      "itemType": "AGENTS_MD",
      "description": "Import /Users/me/project/CLAUDE.md to /Users/me/project/AGENTS.md.",
      "cwd": "/Users/me/project"
    }
  ],
  "source": "claude-code"
} }
{ "id": 64, "result": { "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868" } }

Parameter impor tingkat atas opsional source memberi label pada produk yang menghasilkan item migrasi yang dipilih.

Server mengirim externalAgentConfig/import/progress saat jenis item selesai, dan externalAgentConfig/import/completed setelah semua impor sinkron dan latar belakang selesai. Notifikasi ini menyertakan importId yang sama dari respons dan itemTypeResults dengan successes serta failures per jenis. Penyelesaian dapat tiba segera setelah respons atau setelah impor jarak jauh di latar belakang selesai.

{ "method": "externalAgentConfig/import/progress", "params": {
  "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868",
  "itemTypeResults": [
    {
      "itemType": "AGENTS_MD",
      "successes": [
        { "itemType": "AGENTS_MD", "cwd": "/Users/me/project", "source": null, "target": "/Users/me/project/AGENTS.md" }
      ],
      "failures": []
    }
  ]
} }
{ "method": "externalAgentConfig/import/completed", "params": {
  "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868",
  "itemTypeResults": [
    {
      "itemType": "AGENTS_MD",
      "successes": [
        { "itemType": "AGENTS_MD", "cwd": "/Users/me/project", "source": null, "target": "/Users/me/project/AGENTS.md" }
      ],
      "failures": []
    }
  ]
} }

Baca impor terdahulu yang telah selesai:

{ "method": "externalAgentConfig/import/readHistories", "id": 65 }
{ "id": 65, "result": { "data": [
  {
    "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868",
    "completedAtMs": 1781784000000,
    "successes": [
      { "itemType": "AGENTS_MD", "cwd": "/Users/me/project", "source": null, "target": "/Users/me/project/AGENTS.md" }
    ],
    "failures": []
  }
] } }

Nilai itemType yang didukung adalah AGENTS_MD, CONFIG, SKILLS, PLUGINS, MCP_SERVER_CONFIG, SUBAGENTS, HOOKS, COMMANDS, dan SESSIONS. Untuk item PLUGINS, details.plugins mencantumkan setiap marketplaceName dan pluginNames yang dapat dicoba Codex untuk dimigrasikan. Deteksi hanya mengembalikan item yang masih memerlukan pekerjaan. Misalnya, Codex melewati migrasi AGENTS jika AGENTS.md sudah ada dan tidak kosong, dan impor skill tidak menimpa direktori skill yang ada.

Saat mendeteksi plugin dari .claude/settings.json, Codex membaca sumber marketplace yang dikonfigurasi dari extraKnownMarketplaces. Jika enabledPlugins berisi plugin dari claude-plugins-official tetapi sumber marketplace tidak ditemukan, Codex menyimpulkan anthropics/claude-plugins-official sebagai sumbernya.

Endpoint autentikasi

Permukaan autentikasi/akun JSON-RPC mengekspos metode permintaan/respons serta notifikasi yang dimulai server (tanpa id). Gunakan ini untuk menentukan status autentikasi, memulai atau membatalkan login, logout, memeriksa batas laju ChatGPT, dan memberi tahu pemilik workspace tentang kredit yang habis atau batas penggunaan.

Mode autentikasi

Codex mendukung mode autentikasi berikut. account/updated.authMode menunjukkan mode aktif dan menyertakan planType ChatGPT saat ini jika tersedia. account/read juga melaporkan detail akun dan paket.

API key (apikey) - pemanggil memberikan OpenAI API key melalui type: "apiKey", dan Codex menyimpannya untuk permintaan API.
Dikelola ChatGPT (chatgpt) - Codex menangani alur OAuth ChatGPT, menyimpan token, dan menyegarkannya secara otomatis. Mulai dengan type: "chatgpt" untuk alur browser atau type: "chatgptDeviceCode" untuk alur kode perangkat.
Token eksternal ChatGPT (chatgptAuthTokens) - bersifat eksperimental dan ditujukan bagi aplikasi host yang sudah menangani siklus hidup autentikasi ChatGPT pengguna. Aplikasi host memberikan accessToken, chatgptAccountId, dan chatgptPlanType opsional secara langsung, serta harus menyegarkan token saat diminta.
Amazon Bedrock - account/read melaporkan akun Bedrock sebagai type: "amazonBedrock" dan menunjukkan apakah kredensial berasal dari Bedrock API key yang dikelola Codex (credentialSource: "codexManaged") atau rantai kredensial AWS eksternal (credentialSource: "awsManaged"). account/updated.authMode menggunakan bedrockApiKey untuk Bedrock API key yang dikelola Codex.

Ringkasan API

account/read - mengambil informasi akun saat ini; menyegarkan token secara opsional.
account/login/start - memulai login (apiKey, chatgpt, chatgptDeviceCode, atau chatgptAuthTokens eksperimental).
account/login/completed (notifikasi) - dikirim saat upaya login selesai (berhasil atau mengalami kesalahan).
account/login/cancel - membatalkan login ChatGPT terkelola yang sedang menunggu berdasarkan loginId.
account/logout - logout; memicu account/updated.
account/updated (notifikasi) - dikirim setiap kali mode autentikasi berubah (authMode: apikey, chatgpt, chatgptAuthTokens, agentIdentity, personalAccessToken, bedrockApiKey, atau null) dan menyertakan planType jika tersedia.
account/chatgptAuthTokens/refresh (permintaan server) - meminta token ChatGPT baru yang dikelola secara eksternal setelah terjadi kesalahan otorisasi.
account/rateLimits/read - mengambil batas laju ChatGPT.
account/rateLimits/updated (notifikasi) - dikirim setiap kali batas laju ChatGPT pengguna berubah.
account/sendAddCreditsNudgeEmail - meminta ChatGPT mengirim email kepada pemilik workspace tentang kredit yang habis atau batas penggunaan yang tercapai.
account/rateLimitResetCredit/consume - menggunakan satu pengaturan ulang batas laju yang diperoleh dengan nilai idempotencyKey yang diberikan pemanggil.
account/usage/read - mengambil ringkasan aktivitas token akun ChatGPT dan bucket harian.
account/workspaceMessages/read - mengambil pesan workspace aktif, termasuk judul notifikasi jika tersedia.
mcpServer/oauthLogin/completed (notifikasi) - dikirim setelah alur mcpServer/oauth/login selesai; payload menyertakan { name, threadId, success, error? }. threadId dapat berupa null untuk alur OAuth yang cakupannya terbatas pada aplikasi atau plugin.
mcpServer/startupStatus/updated (notifikasi) - dikirim saat status startup server MCP yang dikonfigurasi berubah; payload menyertakan { threadId, name, status, error, failureReason }. threadId adalah null untuk startup yang cakupannya terbatas pada aplikasi. Jika startup gagal, failureReason: "reauthenticationRequired" berarti kredensial OAuth yang tersimpan telah kedaluwarsa dan tidak dapat disegarkan, sehingga klien sebaiknya menawarkan untuk menghubungkan kembali server.

1) Memeriksa status autentikasi

Permintaan:

{ "method": "account/read", "id": 1, "params": { "refreshToken": false } }

Contoh respons:

{ "id": 1, "result": { "account": null, "requiresOpenaiAuth": false } }

{ "id": 1, "result": { "account": null, "requiresOpenaiAuth": true } }

{
  "id": 1,
  "result": { "account": { "type": "apiKey" }, "requiresOpenaiAuth": true }
}

{
  "id": 1,
  "result": {
    "account": {
      "type": "amazonBedrock",
      "credentialSource": "codexManaged"
    },
    "requiresOpenaiAuth": false
  }
}

{
  "id": 1,
  "result": {
    "account": {
      "type": "amazonBedrock",
      "credentialSource": "awsManaged"
    },
    "requiresOpenaiAuth": false
  }
}

{
  "id": 1,
  "result": {
    "account": {
      "type": "chatgpt",
      "email": "user@example.com",
      "planType": "pro"
    },
    "requiresOpenaiAuth": true
  }
}

Catatan kolom:

refreshToken (boolean): atur true untuk memaksa penyegaran token dalam mode ChatGPT terkelola. Dalam mode token eksternal (chatgptAuthTokens), app-server mengabaikan flag ini.
email adalah null jika akun ChatGPT tidak memiliki alamat email.
requiresOpenaiAuth mencerminkan penyedia aktif; jika false, Codex dapat berjalan tanpa kredensial OpenAI.
Amazon Bedrock melaporkan credentialSource: "codexManaged" saat menggunakan Bedrock API key yang dikelola Codex. Amazon Bedrock melaporkan credentialSource: "awsManaged" untuk jalur kredensial AWS eksternal. Ini mengidentifikasi sumber kredensial yang dipilih; hal ini tidak memvalidasi bahwa rantai kredensial AWS dapat menemukan kredensial.

Kirim:

   {
     "method": "account/login/start",
     "id": 2,
     "params": { "type": "apiKey", "apiKey": "sk-..." }
   }

Respons yang diharapkan:

   { "id": 2, "result": { "type": "apiKey" } }

Notifikasi:

   {
     "method": "account/login/completed",
     "params": { "loginId": null, "success": true, "error": null }
   }

   {
     "method": "account/updated",
     "params": { "authMode": "apikey", "planType": null }
   }

Mulai:

   {
     "method": "account/login/start",
     "id": 3,
     "params": {
       "type": "chatgpt",
       "useHostedLoginSuccessPage": true,
       "appBrand": "chatgpt"
     }
   }

Secara default, callback browser yang berhasil mengalihkan ke halaman sukses lokal. Atur useHostedLoginSuccessPage: true untuk menggunakan halaman sukses yang di-host jika penyiapan organisasi tidak diperlukan. Jika halaman sukses yang di-host diaktifkan, appBrand dapat berupa "codex" atau "chatgpt"; nilai yang dihilangkan atau null secara default menggunakan "codex".

   {
     "id": 3,
     "result": {
       "type": "chatgpt",
       "loginId": "<uuid>",
       "authUrl": "https://chatgpt.com/...&redirect_uri=http%3A%2F%2Flocalhost%3A<port>%2Fauth%2Fcallback"
     }
   }

Buka authUrl di browser; app-server meng-host callback lokal.
Tunggu notifikasi:

   {
     "method": "account/login/completed",
     "params": { "loginId": "<uuid>", "success": true, "error": null }
   }

   {
     "method": "account/updated",
     "params": { "authMode": "chatgpt", "planType": "plus" }
   }

Gunakan alur ini saat klien Anda menangani proses login atau ketika callback browser tidak andal.

Mulai:

   {
     "method": "account/login/start",
     "id": 4,
     "params": { "type": "chatgptDeviceCode" }
   }

   {
     "id": 4,
     "result": {
       "type": "chatgptDeviceCode",
       "loginId": "<uuid>",
       "verificationUrl": "https://auth.openai.com/codex/device",
       "userCode": "ABCD-1234"
     }
   }

Tampilkan verificationUrl dan userCode kepada pengguna; frontend menangani UX.
Tunggu notifikasi:

   {
     "method": "account/login/completed",
     "params": { "loginId": "<uuid>", "success": true, "error": null }
   }

   {
     "method": "account/updated",
     "params": { "authMode": "chatgpt", "planType": "plus" }
   }

3c) Login dengan token ChatGPT yang dikelola secara eksternal (`chatgptAuthTokens`)

Gunakan mode eksperimental ini hanya jika aplikasi host menangani siklus hidup autentikasi ChatGPT pengguna dan memberikan token secara langsung. Klien harus mengatur capabilities.experimentalApi = true selama initialize sebelum menggunakan jenis login ini.

Kirim:

   {
     "method": "account/login/start",
     "id": 7,
     "params": {
       "type": "chatgptAuthTokens",
       "accessToken": "<jwt>",
       "chatgptAccountId": "org-123",
       "chatgptPlanType": "business"
     }
   }

Respons yang diharapkan:

   { "id": 7, "result": { "type": "chatgptAuthTokens" } }

Notifikasi:

   {
     "method": "account/login/completed",
     "params": { "loginId": null, "success": true, "error": null }
   }

   {
     "method": "account/updated",
     "params": { "authMode": "chatgptAuthTokens", "planType": "business" }
   }

Saat server menerima 401 Unauthorized, server dapat meminta token yang telah disegarkan dari aplikasi host:

{
  "method": "account/chatgptAuthTokens/refresh",
  "id": 8,
  "params": { "reason": "unauthorized", "previousAccountId": "org-123" }
}
{ "id": 8, "result": { "accessToken": "<jwt>", "chatgptAccountId": "org-123", "chatgptPlanType": "business" } }

Server mencoba kembali permintaan asli setelah respons penyegaran berhasil. Batas waktu permintaan tercapai setelah sekitar 10 detik.

{ "method": "account/login/cancel", "id": 4, "params": { "loginId": "<uuid>" } }
{ "method": "account/login/completed", "params": { "loginId": "<uuid>", "success": false, "error": "..." } }

5) Logout

{ "method": "account/logout", "id": 5 }
{ "id": 5, "result": {} }
{ "method": "account/updated", "params": { "authMode": null, "planType": null } }

6) Batas laju (ChatGPT)

{ "method": "account/rateLimits/read", "id": 6 }
{ "id": 6, "result": {
  "rateLimits": {
    "limitId": "codex",
    "limitName": null,
    "primary": { "usedPercent": 25, "windowDurationMins": 15, "resetsAt": 1730947200 },
    "secondary": null,
    "rateLimitReachedType": null
  },
  "rateLimitsByLimitId": {
    "codex": {
      "limitId": "codex",
      "limitName": null,
      "primary": { "usedPercent": 25, "windowDurationMins": 15, "resetsAt": 1730947200 },
      "secondary": null,
      "rateLimitReachedType": null
    },
    "codex_other": {
      "limitId": "codex_other",
      "limitName": "codex_other",
      "primary": { "usedPercent": 42, "windowDurationMins": 60, "resetsAt": 1730950800 },
      "secondary": null,
      "rateLimitReachedType": null
    }
  },
  "rateLimitResetCredits": {
    "availableCount": 2,
    "credits": [{
      "id": "RateLimitResetCredit_1",
      "resetType": "codexRateLimits",
      "status": "available",
      "grantedAt": 1781654400,
      "expiresAt": 1784246400,
      "title": "Rate-limit reset",
      "description": "Reset an eligible Codex rate-limit window."
    }]
  }
} }
{ "method": "account/rateLimits/updated", "params": {
  "rateLimits": {
    "limitId": "codex",
    "primary": { "usedPercent": 31, "windowDurationMins": 15, "resetsAt": 1730948100 }
  }
} }

Catatan kolom:

rateLimits adalah tampilan satu bucket yang kompatibel dengan versi sebelumnya.
rateLimitsByLimitId (jika ada) adalah tampilan beberapa bucket yang menggunakan limit_id terukur sebagai kunci (misalnya codex).
limitId adalah pengidentifikasi bucket terukur.
limitName adalah label opsional yang ditampilkan kepada pengguna untuk bucket tersebut.
usedPercent adalah penggunaan saat ini dalam jendela kuota.
windowDurationMins adalah panjang jendela kuota.
resetsAt adalah stempel waktu Unix (detik) untuk pengaturan ulang berikutnya.
planType disertakan saat server mengembalikan paket ChatGPT yang terkait dengan bucket.
credits disertakan saat server mengembalikan detail sisa kredit workspace.
rateLimitReachedType mengidentifikasi status batas yang diklasifikasikan server saat batas telah tercapai.
rateLimitResetCredits berisi jumlah pengaturan ulang yang diperoleh dan tersedia jika layanan menyediakannya; jika tidak, nilainya adalah null.
rateLimitResetCredits.credits adalah null jika hanya jumlahnya yang diketahui. Array kosong berarti layanan telah mengambil detail dan tidak menemukan kredit yang tersedia. Layanan dapat membatasi baris detail, sehingga availableCount bersifat otoritatif.
Setiap baris detail menyertakan id buram, resetType, status, grantedAt, expiresAt (yang dapat berupa null), title (yang dapat berupa null), dan description (yang dapat berupa null).
Ambil account/rateLimits/read setelah menggunakan pengaturan ulang.

7) Penggunaan token (ChatGPT)

Gunakan account/usage/read untuk mengambil kolom ringkasan aktivitas token ChatGPT dan bucket harian opsional.

{ "method": "account/usage/read", "id": 7 }
{ "id": 7, "result": {
  "summary": {
    "lifetimeTokens": 1234567,
    "peakDailyTokens": 45678,
    "longestRunningTurnSec": 540,
    "currentStreakDays": 8,
    "longestStreakDays": 14
  },
  "dailyUsageBuckets": [
    { "startDate": "2026-06-18", "tokens": 12345 }
  ]
} }

Catatan kolom:

Nilai summary dapat berupa null jika layanan belum mengembalikan metrik tersebut.
dailyUsageBuckets dapat berupa null; jika ada, setiap bucket menyertakan startDate dan tokens.
Endpoint memerlukan autentikasi yang didukung oleh layanan Codex. ChatGPT, token ChatGPT eksternal, identitas agen, dan autentikasi personal access token dapat digunakan; autentikasi yang hanya menggunakan API key dan autentikasi Bedrock tidak dapat digunakan.

8) Pengaturan ulang batas laju yang diperoleh (ChatGPT)

Gunakan account/rateLimitResetCredit/consume untuk menggunakan satu pengaturan ulang yang diperoleh.

{ "method": "account/rateLimitResetCredit/consume", "id": 8, "params": { "idempotencyKey": "8ae96ff3-3425-4f4c-8772-b6fd61502868", "creditId": "RateLimitResetCredit_1" } }
{ "id": 8, "result": { "outcome": "reset" } }

Catatan kolom:

idempotencyKey tidak boleh kosong. Gunakan UUID untuk setiap upaya penukaran logis dan gunakan kembali nilai yang sama saat mencoba kembali upaya tersebut.
creditId bersifat opsional. Jika diberikan, nilainya harus berupa ID buram yang tidak kosong dari account/rateLimits/read. Jika dihilangkan, layanan memilih kredit berikutnya yang tersedia.
reset berarti kredit telah digunakan.
alreadyRedeemed berarti penukaran yang sama telah selesai sebelumnya. Perlakukan ini sebagai keberhasilan idempoten dan segarkan batas akun.
nothingToReset berarti tidak ada jendela batas laju yang memenuhi syarat untuk diatur ulang.
noCredit berarti akun tidak memiliki kredit pengaturan ulang yang diperoleh dan tersedia.
Ambil account/rateLimits/read setelah menggunakan pengaturan ulang, bukan menyimpulkan jendela yang telah diperbarui dari respons ini.

9) Memberi tahu pemilik workspace tentang batas

Gunakan account/sendAddCreditsNudgeEmail untuk meminta ChatGPT mengirim email kepada pemilik workspace saat kredit habis atau batas penggunaan telah tercapai.

{ "method": "account/sendAddCreditsNudgeEmail", "id": 9, "params": { "creditType": "credits" } }
{ "id": 9, "result": { "status": "sent" } }

Gunakan creditType: "credits" saat kredit workspace habis, atau creditType: "usage_limit" saat batas penggunaan workspace telah tercapai. Jika pemilik baru-baru ini sudah diberi tahu, status responsnya adalah cooldown_active.

10) Pesan workspace (ChatGPT)

Gunakan account/workspaceMessages/read untuk mengambil pesan aktif bagi workspace saat ini, termasuk judul notifikasi jika tersedia.

{ "method": "account/workspaceMessages/read", "id": 10 }
{ "id": 10, "result": { "featureEnabled": true, "messages": [
  { "messageId": "msg_123", "messageType": "headline", "messageBody": "Workspace maintenance starts at 5pm.", "createdAt": 1781395200, "archivedAt": null }
] } }

Menghubungkan antarmuka terminal CLI

Menghubungkan host Code Mode jarak jauh

Protokol

Skema pesan

Memulai

Primitif inti

Ikhtisar siklus hidup

Inisialisasi

Keikutsertaan API eksperimental

Ikhtisar API

Model

Mencantumkan model (model/list)

Mencantumkan fitur eksperimental (experimentalFeature/list)

Memeriksa lingkungan eksekusi (eksperimental)

Thread

Memulai atau melanjutkan thread

Mengelola sasaran thread

Membaca thread tersimpan (tanpa melanjutkan)

Mencantumkan turn thread

Mencantumkan thread (dengan paginasi & filter)

Memperbarui metadata thread tersimpan

Melacak perubahan status thread

Mencantumkan thread yang dimuat

Menghentikan langganan dari thread yang dimuat

Mengarsipkan thread

Menghapus thread

Membatalkan pengarsipan thread

Memicu pemadatan thread

Menjalankan perintah shell thread

Membersihkan terminal latar belakang

Mengembalikan turn terbaru

Turn

Akses baca sandbox (ReadOnlyAccess)

Memulai turn

Menyisipkan item ke dalam thread

Mengarahkan turn aktif

Memulai turn (memanggil skill)

Menginterupsi turn

Peninjauan

Eksekusi proses

Eksekusi perintah

Membaca persyaratan admin (configRequirements/read)

Penyiapan sandbox Windows (windowsSandbox/setupStart)

Sistem file

Peristiwa

Menonaktifkan notifikasi

Peristiwa pencarian file fuzzy (eksperimental)

Peristiwa peringatan

Peristiwa penyiapan sandbox Windows

Peristiwa turn

Item

Delta item

Kesalahan

Persetujuan

Persetujuan eksekusi perintah

Persetujuan perubahan file

tool/requestUserInput

Permintaan izin

Permintaan elisitasi server MCP

Pemanggilan alat dinamis (eksperimental)

Persetujuan pemanggilan alat MCP (aplikasi)

Skill

Aplikasi (konektor)

Contoh RPC konfigurasi untuk pengaturan aplikasi

Mendeteksi dan mengimpor konfigurasi agen eksternal

Endpoint autentikasi

Mode autentikasi

Ringkasan API

1) Memeriksa status autentikasi

2) Login dengan API key

3) Login dengan ChatGPT (alur browser)

3b) Login dengan ChatGPT (alur kode perangkat)

3c) Login dengan token ChatGPT yang dikelola secara eksternal (chatgptAuthTokens)

4) Membatalkan login ChatGPT

5) Logout

6) Batas laju (ChatGPT)

7) Penggunaan token (ChatGPT)

8) Pengaturan ulang batas laju yang diperoleh (ChatGPT)

9) Memberi tahu pemilik workspace tentang batas

10) Pesan workspace (ChatGPT)

Mencantumkan model (`model/list`)

Mencantumkan fitur eksperimental (`experimentalFeature/list`)

Akses baca sandbox (`ReadOnlyAccess`)

Membaca persyaratan admin (`configRequirements/read`)

Penyiapan sandbox Windows (`windowsSandbox/setupStart`)

`tool/requestUserInput`

3c) Login dengan token ChatGPT yang dikelola secara eksternal (`chatgptAuthTokens`)