Codex App Server

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 Codex GitHub (openai/codex/codex-rs/app-server). Lihat halaman Sumber Terbuka untuk mengetahui 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 balik TLS. Simpan bearer token dalam variabel lingkungan dan teruskan namanya alih-alih 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 port-nya diteruskan melalui 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 localhost atau koneksi 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 ditransmisikan).

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 frame 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 ekspos transportasi lokal.

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

• GET /readyz mengembalikan 200 OK setelah listener menerima koneksi baru.
• GET /healthz mengembalikan 200 OK jika 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 mengizinkan koneksi tanpa autentikasi secara default 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 bearer token 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 initialize JSON-RPC.

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

Dalam mode WebSocket, app-server menggunakan antrean berbatas. Saat antrean masuk permintaan penuh, server menolak permintaan baru dengan kode kesalahan JSON-RPC -32001 dan pesan "Server overloaded; retry later." Klien harus mencoba lagi 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 serta 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

1. 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).
2. Hubungkan klien melalui transportasi yang dipilih, lalu kirim initialize diikuti notifikasi initialized.
3. 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 beserta 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 pancarkan initialized. Server menolak setiap permintaan pada koneksi tersebut sebelum handshake ini.
• Memulai (atau melanjutkan) thread: Panggil thread/start untuk percakapan baru, thread/resume untuk melanjutkan percakapan yang sudah ada, atau thread/fork untuk mencabangkan riwayat ke id thread baru.
• Memulai turn: Panggil turn/start dengan threadId target dan masukan pengguna. Field opsional mengganti model, personality, cwd, kebijakan sandbox, dan lainnya.
• Mengarahkan turn aktif: Panggil turn/steer untuk menambahkan masukan pengguna ke turn yang sedang berlangsung tanpa membuat turn baru.
• Mengalirkan 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.
• Menyelesaikan turn: Server memancarkan 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 kemampuan klien berikut:

• optOutNotificationMethods - nama metode notifikasi persis yang akan disembunyikan untuk koneksi ini. Pencocokan harus persis (tanpa wildcard atau prefiks); nama yang tidak dikenal diterima dan diabaikan.
• requestAttestation - memilih ikut serta dalam permintaan attestation/generate yang dimulai server. Host desktop yang menyediakan atestasi upstream merespons dengan nilai { "token": "..." } buram.
• mcpServerOpenaiFormElicitation - mengizinkan server MCP downstream mengirim varian format 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 di balik kemampuan 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 memilih ikut serta, app-server menolaknya dengan:

<descriptor> requires experimentalApi capability

Ikhtisar API

• thread/start - membuat thread baru; memancarkan thread/started dan secara otomatis membuat Anda berlangganan peristiwa turn/item untuk thread tersebut.
• thread/resume - membuka kembali thread yang sudah ada berdasarkan id agar panggilan turn/start berikutnya ditambahkan ke thread tersebut.
• thread/fork - mencabangkan thread ke id thread baru dengan menyalin riwayat tersimpan. Teruskan lastTurnId untuk menyalin riwayat hingga turn tersebut dan menghilangkan turn sesudahnya, atau ephemeral: true untuk membuat cabang dalam memori. Memancarkan 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 serta modelProviders, sourceKinds, archived, isPinned, cwd, useStateDbOnly, searchTerm, dan filter eksperimental parentThreadId atau ancestorThreadId. 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, dan secara opsional membatasinya ke satu turnId. Penyimpanan thread aktif harus mendukung paginasi item.
• thread/loaded/list - mencantumkan id thread yang saat ini dimuat dalam memori.
• thread/name/set - menetapkan atau memperbarui nama thread yang ditampilkan kepada pengguna untuk thread yang dimuat atau rollout yang dipersistenkan; memancarkan thread/name/updated.
• thread/goal/set - menetapkan tujuan thread; memancarkan thread/goal/updated.
• thread/goal/get - membaca tujuan thread saat ini.
• thread/goal/clear - menghapus tujuan thread; memancarkan 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 yang belum diarsipkan; mengembalikan {} jika berhasil dan memancarkan 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 memancarkan thread/deleted untuk setiap thread yang dihapus.
• thread/unsubscribe - menghentikan langganan koneksi ini dari peristiwa turn/item thread. Jika ini adalah pelanggan terakhir, server membongkar thread setelah masa tenggang tidak aktif tanpa pelanggan dan memancarkan thread/closed.
• thread/unarchive - memulihkan rollout thread yang diarsipkan kembali ke direktori sesi aktif; mengembalikan thread yang dipulihkan dan memancarkan thread/unarchived.
• thread/status/changed - notifikasi yang dipancarkan ketika status runtime thread yang dimuat berubah.
• thread/compact/start - memicu pemadatan riwayat percakapan untuk thread; langsung 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 atau output alat mandiri ke thread dan memulai pembuatan oleh 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 thread yang terlihat oleh model tanpa memulai turn pengguna.
• turn/steer - menambahkan masukan pengguna ke turn aktif yang sedang berlangsung untuk thread; mengembalikan turnId yang diterima.
• turn/interrupt - meminta pembatalan turn yang sedang berlangsung; keberhasilan ditandai dengan {} dan turn berakhir dengan status: "interrupted".
• review/start - memulai peninjau Codex untuk thread; memancarkan 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) - dipancarkan untuk potongan stdout/stderr berenkode base64 dari sesi command/exec streaming.
• 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) - dipancarkan untuk keluaran proses streaming dan status keluar proses (eksperimental).
• model/list - mencantumkan model yang tersedia (atur includeHidden: true untuk menyertakan entri dengan hidden: true) beserta opsi effort, upgrade opsional, dan inputModalities.
• modelProvider/capabilities/read - membaca batas kemampuan penyedia untuk kombinasi model/penyedia.
• experimentalFeature/list - mencantumkan flag fitur beserta 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; menghubungkan ke lingkungan eksekusi yang dikonfigurasi dan mengembalikan shell beserta direktori kerja default-nya.
• 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 keterampilan untuk satu atau beberapa nilai cwd (mendukung forceReload dan perCwdExtraUserRoots opsional).
• skills/extraRoots/set - mengganti root tambahan tingkat proses yang digunakan untuk menemukan keterampilan mandiri tanpa mempersistenkannya.
• skills/changed (notifikasi) - dipancarkan saat file keterampilan 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 - sedang dikembangkan; 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 dulu.
• plugin/read - sedang dikembangkan; membaca satu plugin berdasarkan jalur marketplace atau nama marketplace jarak jauh dan nama plugin, termasuk keterampilan terbundel, aplikasi, nama server MCP, dan shareUrl plugin jarak jauh jika katalog jarak jauh menyediakannya. Jangan panggil metode ini dari klien produksi dulu.
• plugin/install - sedang dikembangkan; menginstal plugin dari jalur marketplace atau nama marketplace jarak jauh. Jangan panggil metode ini dari klien produksi dulu.
• plugin/uninstall - sedang dikembangkan; menghapus instalasi plugin yang terinstal. Jangan panggil metode ini dari klien produksi dulu.
• plugin/skill/read - membaca Markdown keterampilan plugin jarak jauh sesuai permintaan berdasarkan marketplace jarak jauh, id plugin, dan nama keterampilan.
• app/installed - membaca status runtime aplikasi terinstal, termasuk status efektif aktif dan dapat dipanggil untuk setiap aplikasi.
• app/list - mencantumkan aplikasi (konektor) yang tersedia dengan paginasi serta metadata aksesibilitas/keaktifan.
• app/read - mengambil metadata dan ringkasan alat opsional yang hanya untuk ditampilkan bagi id aplikasi tertentu.
• skills/config/write - mengaktifkan atau menonaktifkan keterampilan berdasarkan jalur.
• mcpServer/oauth/login - memulai login OAuth untuk server MCP yang dikonfigurasi; mengembalikan URL otorisasi dan memancarkan mcpServer/oauthLogin/completed setelah selesai.
• tool/requestUserInput - meminta pengguna menjawab 1-3 pertanyaan singkat untuk panggilan alat (eksperimental); pertanyaan dapat mengatur isOther untuk opsi isian bebas.
• mcpServer/elicitation/request (permintaan server) - meminta masukan formulir terstruktur atau konfirmasi alur URL dari klien yang diminta oleh server MCP.
• item/permissions/requestApproval (permintaan server) - meminta klien memberikan subset 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, alat, sumber daya, dan status autentikasi MCP (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) - dipancarkan saat status startup server MCP yang dikonfigurasi berubah untuk thread yang dimuat.
• windowsSandbox/setupStart - memulai penyiapan sandbox Windows untuk mode elevated atau unelevated; segera kembali dan kemudian memancarkan windowsSandbox/setupCompleted.
• feedback/upload - mengirim laporan umpan balik (klasifikasi + alasan/log opsional + id percakapan, serta lampiran extraLogFiles opsional).
• config/read - mengambil konfigurasi efektif di 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 bersama cwd (null untuk home). Jenis item yang didukung mencakup konfigurasi, keterampilan, AGENTS.md, plugin, konfigurasi server MCP, subagen, hook, perintah, dan sesi; impor yang tidak kosong memancarkan externalAgentConfig/import/progress dan externalAgentConfig/import/completed saat pekerjaan selesai. Impor plugin dan sesi dapat selesai secara asinkron.
• config/value/write - menulis satu kunci/nilai konfigurasi ke config.toml pengguna di disk.
• config/batchWrite - menerapkan pengeditan konfigurasi secara atomik ke config.toml pengguna di disk.
• configRequirements/read - mengambil persyaratan dari requirements.toml dan/atau MDM, termasuk konfigurasi terkelola yang persis, daftar izin, featureRequirements yang disematkan, dan persyaratan 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 yang hanya tersedia dari jarak jauh, PluginMarketplaceEntry.path dapat berupa null; teruskan remoteMarketplaceName alih-alih marketplacePath saat membaca atau menginstal plugin tersebut.

Model

Mencantumkan model (model/list)

Panggil model/list untuk menemukan model yang tersedia beserta kemampuannya sebelum merender pemilih model atau personality.

{ "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 effort yang didukung untuk model.
• defaultReasoningEffort - effort default yang disarankan untuk klien.
• upgrade - id model peningkatan opsional yang direkomendasikan untuk prompt migrasi di klien.
• upgradeInfo - metadata peningkatan opsional untuk prompt migrasi di klien.
• hidden - apakah model disembunyikan dari daftar pemilih default.
• inputModalities - jenis masukan yang didukung model (misalnya text, image).
• supportsPersonality - apakah model mendukung instruksi khusus personality 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 ada, nilai tersebut adalah URI file: kanonis yang menggunakan sintaksis jalur asli lingkungan. 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, dan secara opsional membatasinya ke satu turn.
• thread/list mendukung paginasi kursor serta pemfilteran modelProviders, sourceKinds, archived, isPinned, cwd, useStateDbOnly, searchTerm, dan parentThreadId atau ancestorThreadId 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 yang 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 tidak aktif.
• thread/unarchive memulihkan rollout thread yang diarsipkan kembali ke direktori sesi aktif.
• thread/compact/start memicu pemadatan dan langsung 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 thread yang terlihat oleh model 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 nilai ini jika 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 sintaksis absolut asli lingkungan sumbernya, termasuk untuk lingkungan jarak jauh.

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

Klien beta yang memilih ikut serta dalam capabilities.experimentalApi dapat meneruskan id profil izin bernama di permissions sebagai pengganti field sandbox lama. Jangan kirim permissions dan sandbox bersamaan. Gunakan permissionProfile/list bersama 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 fork mempertahankan id sesi dari root asalnya. Klien harus membaca id sesi dari thread.sessionId alih-alih menurunkannya dari id thread.

Untuk melanjutkan sesi tersimpan, panggil thread/resume dengan thread.id yang Anda catat sebelumnya. Bentuk responsnya 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 memperbarui thread.updatedAt (atau waktu modifikasi file rollout) dengan sendirinya. Stempel waktu diperbarui saat Anda memulai turn.

Jika Anda menandai server MCP yang diaktifkan 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 saat thread/resume jika Anda tidak menyediakan alat dinamis baru.

Jika Anda melanjutkan dengan model yang berbeda dari model yang tercatat dalam rollout, Codex memancarkan peringatan dan menerapkan instruksi pergantian model satu kali pada turn berikutnya.

Mengelola tujuan thread

Gunakan thread/goal/set, thread/goal/get, dan thread/goal/clear untuk mengelola status tujuan persisten 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 tujuan tidak boleh kosong dan panjangnya paling banyak 4.000 karakter. Memberikan objektif baru akan mengganti tujuan 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 sesi tersimpan, panggil thread/fork dengan thread.id. Tindakan ini membuat id thread baru dan memancarkan notifikasi thread/started untuknya. Teruskan lastTurnId untuk menyalin riwayat hingga dan termasuk turn tersebut, serta menghilangkan turn sesudahnya:

{ "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, fork akan mencatat penanda interupsi alih-alih mempertahankan turn parsial tanpa penanda.

Teruskan ephemeral: true untuk membuat fork 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
    }
  }
}

Fork 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 ditetapkan, 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 ditetapkan 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 memancarkan thread/started.

Mencantumkan turn thread

thread/turns/list bersifat eksperimental. Gunakan metode ini 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 respons:

• notLoaded menghilangkan item.
• summary mengembalikan data item yang diringkas dan merupakan 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 ke satu turn, atau hilangkan untuk menelusuri item di seluruh thread. Penyimpanan thread aktif harus mendukung paginasi item; jika tidak, server mengembalikan kesalahan metode 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 buram dari respons sebelumnya; hilangkan untuk halaman pertama.
• limit - server menggunakan ukuran halaman yang wajar secara default jika tidak ditetapkan.
• sortKey - created_at (default), updated_at, atau recency_at.
• sortDirection - desc (default) atau asc.
• modelProviders - membatasi hasil ke penyedia tertentu; nilai yang tidak ditetapkan, null, atau array kosong menyertakan semua penyedia.
• sourceKinds - membatasi hasil ke sumber thread tertentu. Jika dihilangkan atau [], server secara default hanya menggunakan 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 penyematan persisten yang cocok. Hilangkan untuk mengembalikan thread yang disematkan maupun tidak.
• cwd - membatasi hasil ke thread yang direktori kerja sesi saat ininya sama persis dengan jalur ini, atau salah satu jalur dalam array. Jalur relatif ditentukan 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 ke thread yang judul hasil ekstraksinya berisi fragmen teks peka huruf besar-kecil ini.
• parentThreadId - membatasi hasil ke thread turunan langsung dari thread induk yang diberikan. Filter ini bersifat eksperimental dan memerlukan capabilities.experimentalApi = true.
• ancestorThreadId - membatasi hasil ke turunan yang dibuat dari thread tertentu pada kedalaman apa pun. Filter ini bersifat 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 membatalkan penyematan thread, atau perbarui gitInfo untuk mengubah metadata Git yang dipersistenkan. Field yang dihilangkan tetap tidak berubah; null eksplisit menghapus nilai metadata Git 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 dipancarkan 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 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 adalah pelanggan terakhir, server mempertahankan thread dalam keadaan dimuat hingga thread tidak memiliki pelanggan dan tidak ada aktivitas thread selama 30 menit. Saat masa tenggang berakhir, app-server membongkar thread dan memancarkan 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 di disk) ke direktori sesi arsip. Mengarsipkan thread juga mencoba mengarsipkan thread turunan yang dibuat yang 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 thread/list berikutnya kecuali Anda meneruskan archived: true. Server memancarkan satu notifikasi thread/archived untuk setiap thread yang benar-benar diarsipkan; jika thread 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 yang diarsipkan beserta thread turunan yang dibuatnya. Server menghapus file rollout yang ada dan metadata terkait sebelum mengembalikan keberhasilan; file rollout yang tidak ada 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 rollout thread yang diarsipkan kembali 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 memancarkan progres sebagai notifikasi turn/* dan item/* standar 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 menjadi bagian dari suatu thread. Permintaan segera mengembalikan {} sementara progres dialirkan melalui notifikasi turn/* dan item/* standar.

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

Jika thread sudah memiliki giliran aktif, perintah berjalan sebagai tindakan tambahan pada giliran tersebut dan output terformatnya dimasukkan ke aliran pesan giliran. Jika thread sedang menganggur, app-server memulai giliran mandiri untuk perintah shell tersebut.

Atur timeoutMs untuk membatasi waktu eksekusi dalam milidetik. Jika dihilangkan atau diberi nilai null, batas waktu bawaan satu jam akan digunakan. 0 meminta batas waktu segera; nilai negatif ditolak. Batas waktu tersebut tidak menunda respons RPC yang langsung dikirim.

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

Membersihkan terminal latar belakang

Gunakan thread/backgroundTerminals/clean untuk menghentikan semua terminal latar belakang yang sedang berjalan dan terkait dengan suatu 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 cursor dan limit standar, 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 giliran terbaru

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

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

Giliran

Bidang 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 untuk setiap giliran (model, upaya, kepribadian, cwd, kebijakan sandbox, ringkasan). Jika ditentukan, pengaturan ini menjadi nilai default bagi giliran berikutnya pada thread yang sama. outputSchema hanya berlaku untuk giliran 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 terbatas).
• workspaceWrite: readOnlyAccess opsional ({ "type": "fullAccess" } secara default, atau root terbatas).

Bentuk akses baca terbatas:

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

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

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 giliran

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

Untuk memulai giliran dengan output dari alat yang dijalankan klien Anda, teruskan toolOutput dengan name yang tidak kosong, namespace opsional, serta output berupa string atau array item konten. Atur input menjadi array kosong; Anda tidak dapat menggabungkan toolOutput dengan input pengguna yang tidak kosong.

{
  "method": "turn/start",
  "id": 31,
  "params": {
    "threadId": "thr_123",
    "input": [],
    "toolOutput": {
      "name": "run_tests",
      "namespace": null,
      "output": "All 42 tests passed."
    }
  }
}

Output tersebut tetap menjadi output alat dalam percakapan dan muncul sebagai item functionCallOutput dalam notifikasi dan riwayat persisten. Jika giliran reguler sudah aktif, Codex mengantrekan output tersebut untuk giliran itu.

Memasukkan item ke dalam thread

Gunakan thread/inject_items untuk menambahkan item Responses API yang telah dibuat sebelumnya ke riwayat prompt thread yang dimuat tanpa memulai giliran pengguna. Item ini disimpan 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 giliran aktif

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

• Sertakan expectedTurnId; nilainya harus cocok dengan ID giliran aktif.
• Permintaan gagal jika thread tidak memiliki giliran aktif.
• turn/steer tidak memancarkan notifikasi turn/started baru.
• turn/steer tidak menerima penggantian tingkat giliran (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 giliran (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 giliran

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

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

Peninjauan

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

• uncommittedChanges
• baseBranch (diff terhadap sebuah cabang)
• commit (meninjau commit tertentu)
• custom (instruksi bentuk bebas)

Gunakan delivery: "inline" (default) untuk menjalankan peninjauan pada thread yang ada, atau delivery: "detached" untuk membuat fork 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 memancarkan notifikasi thread/started untuk thread baru tersebut sebelum mengalirkan giliran peninjauan.

Codex mengalirkan notifikasi turn/started seperti 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 memancarkan item/started dan item/completed yang memuat 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 API ini hanya jika klien Anda secara 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 seperti 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 sedang 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 alih-alih memblokir 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 memancarkan notifikasi penyelesaian:

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

Mode:

• elevated - menjalankan jalur penyiapan sandbox Windows dengan hak akses tinggi.
• unelevated - menjalankan jalur penyiapan/pemeriksaan awal 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 memancarkan fs/changed untuk path file tersebut, termasuk pembaruan yang dikirimkan melalui operasi penggantian atau pengubahan nama.

Peristiwa

Notifikasi peristiwa adalah aliran yang dimulai server untuk siklus hidup thread, siklus hidup giliran, dan item di dalamnya. Setelah 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.

Menolak notifikasi

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

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

Peristiwa pencarian file fuzzy (eksperimental)

API sesi pencarian file fuzzy memancarkan notifikasi untuk setiap 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 dipancarkan setelah permintaan windowsSandbox/setupStart selesai.

Peristiwa giliran

• turn/started - { turn } dengan ID giliran, items kosong, dan status: "inProgress".
• turn/completed - { turn } dengan turn.status berupa completed, interrupted, atau failed; kegagalan memuat { error: { message, codexErrorInfo?, additionalDetails? } }.
• turn/diff/updated - { threadId, turnId, diff } dengan unified diff gabungan terbaru untuk setiap perubahan file dalam giliran.
• turn/plan/updated - { turnId, explanation?, plan } setiap kali agen membagikan atau mengubah rencananya; setiap entri plan adalah { step, status } dengan status di pending, inProgress, atau completed.
• hook/started dan hook/completed - { threadId, turnId?, run } saat hook siklus hidup sinkron dimulai dan saat ringkasan eksekusi akhirnya tersedia. Notifikasi ini tidak dipancarkan untuk hook asinkron.
• 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 giliran.

Item

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

• userMessage - {id, content} dengan content berupa daftar input pengguna (text, image, atau localImage).
• functionCallOutput - {id, name, namespace, output} untuk output alat mandiri yang diberikan melalui turn/start.toolOutput. namespace dapat berupa null.
• agentMessage - {id, text, phase?} yang memuat balasan agen yang terakumulasi. Jika ada, phase menggunakan nilai wire Responses API (commentary, final_answer).
• plan - {id, text} yang memuat teks rencana yang diusulkan dalam mode rencana. Perlakukan item plan terakhir dari item/completed sebagai acuan otoritatif.
• reasoning - {id, summary, content} dengan summary yang menyimpan ringkasan penalaran yang dialirkan dan content yang menyimpan blok penalaran mentah.
• commandExecution - {id, command, cwd, status, commandActions, aggregatedOutput?, exitCode?, durationMs?}.
• fileChange - {id, changes, status} yang menjelaskan edit 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 tersimpan mungkin tidak menyertakan metadata yang lebih baru. Gunakan appContext.resourceUri sebagai pengganti mcpAppResourceUri tingkat atas yang tidak digunakan lagi.
• 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 dikeluarkan agen.
• imageView - {id, path} yang dipancarkan saat agen memanggil alat penampil gambar.
• enteredReviewMode - {id, review} yang dikirim saat peninjau mulai bekerja.
• exitedReviewMode - {id, review} yang dipancarkan saat peninjau selesai.
• contextCompaction - {id} yang dipancarkan 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 menggunakan notifikasi lama thread/compacted; gunakan item contextCompaction sebagai gantinya.

Semua item memancarkan dua peristiwa siklus hidup bersama:

• item/started - memancarkan item lengkap saat unit kerja baru dimulai; item.id cocok dengan itemId yang digunakan oleh delta.
• item/completed - mengirimkan 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 antarbagiannya dalam 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 yang tidak digunakan lagi untuk output teks apply_patch lama. Versi app-server saat ini tidak lagi memancarkannya; gunakan item fileChange dan turn/diff/updated sebagai gantinya.

Kesalahan

Jika giliran gagal, server memancarkan peristiwa error dengan { error: { message, codexErrorInfo?, additionalDetails? } } lalu menyelesaikan giliran 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:

1. item/started menampilkan item commandExecution yang tertunda dengan command, cwd, dan bidang lainnya.
2. 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. Semua path sistem file di dalam additionalPermissions bersifat absolut pada wire.
3. Klien merespons dengan salah satu keputusan persetujuan eksekusi perintah di atas.
4. serverRequest/resolved mengonfirmasi bahwa permintaan tertunda telah dijawab atau dihapus.
5. item/completed mengembalikan item commandExecution akhir dengan status: completed | failed | declined.

Jika networkApprovalContext tersedia, 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 yang berbeda pada host yang sama diperlakukan secara terpisah.

Persetujuan perubahan file

Urutan pesan:

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

tool/requestUserInput

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

Parameter permintaan menyertakan autoResolutionMs sebagai batas waktu integer dalam milidetik atau null. Jika tersedia, klien host dapat menyelesaikan prompt secara otomatis setelah interval tersebut jika 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 memuat subset yang diberikan. Atur scope ke "session" untuk mempertahankan pemberian izin bagi giliran berikutnya dalam sesi yang sama; hilangkan atau gunakan "turn" untuk pemberian izin yang terbatas pada satu giliran. Izin yang tidak diminta akan diabaikan.

Permintaan elisitasi server MCP

Server MCP dapat menginterupsi giliran 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 memancarkan serverRequest/resolved. Untuk menerima varian openai/form, ikut serta dengan initialize.params.capabilities.mcpServerOpenaiFormElicitation.

Pemanggilan alat dinamis (eksperimental)

dynamicTools pada thread/start dan 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 suatu giliran, app-server memancarkan:

1. item/started dengan item.type = "dynamicToolCall", status = "inProgress", serta tool dan arguments.
2. item/tool/call sebagai permintaan server kepada klien.
3. Payload respons klien dengan item konten yang dikembalikan.
4. item/completed dengan item.type = "dynamicToolCall", status akhir, dan 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 melalui 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 (disarankan) agar server memasukkan instruksi skill lengkap alih-alih mengandalkan model untuk mengidentifikasi 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 tersebut, 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 berdasarkan 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 untuk setiap cwd; atur forceReload: true untuk memuat ulang dari disk. Jika tersedia, 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 memancarkan 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 jika 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 alih-alih konfigurasi thread yang dimuat. Atur forceRefresh: true untuk memuat ulang snapshot runtime konektor sebelum membacanya. Jika kebijakan global atau ruang kerja memblokir akses aplikasi, aplikasi yang teramati 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 bidang 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 terbaru. Entri cache hanya diganti jika pemuatan ulang berhasil.

Server juga memancarkan 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 terinstalnya. Teruskan maksimal 100 appIds. Server hanya menyimpan 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 menggagalkan seluruh permintaan.

{
  "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 mengotorisasi pemanggilan alat; gunakan app/installed untuk memeriksa status enabled dan callable yang efektif.

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

{
  "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 cadangan 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 edit 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 source tingkat atas yang opsional memberi label pada produk yang menghasilkan item migrasi terpilih.

Server memancarkan externalAgentConfig/import/progress saat setiap jenis item selesai, dan externalAgentConfig/import/completed setelah semua impor sinkron dan latar belakang selesai. Notifikasi ini menyertakan importId yang sama dari respons serta itemTypeResults dengan successes dan failures untuk setiap jenis. Penyelesaian dapat tiba tepat 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 dimigrasikan oleh Codex. Deteksi hanya mengembalikan item yang masih memerlukan tindakan. 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 ada, Codex menyimpulkan anthropics/claude-plugins-official sebagai sumbernya.

Endpoint autentikasi

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

Mode autentikasi

Codex mendukung mode autentikasi berikut. account/updated.authMode menampilkan 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.
• ChatGPT terkelola (chatgpt) - Codex mengelola alur OAuth ChatGPT, menyimpan token, dan memperbaruinya 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 mengelola siklus hidup autentikasi ChatGPT pengguna. Aplikasi host memberikan accessToken, chatgptAccountId, dan chatgptPlanType opsional secara langsung, serta harus memperbarui 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; memperbarui token secara opsional.
• account/login/start - memulai login (apiKey, chatgpt, chatgptDeviceCode, atau chatgptAuthTokens eksperimental).
• account/login/completed (notifikasi) - dipancarkan saat upaya login selesai (berhasil atau mengalami kesalahan).
• account/login/cancel - membatalkan login ChatGPT terkelola yang tertunda berdasarkan loginId.
• account/logout - logout; memicu account/updated.
• account/updated (notifikasi) - dipancarkan 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 kesalahan otorisasi.
• account/rateLimits/read - mengambil batas laju ChatGPT.
• account/rateLimits/updated (notifikasi) - dipancarkan setiap kali batas laju ChatGPT pengguna berubah.
• account/sendAddCreditsNudgeEmail - meminta ChatGPT mengirim email kepada pemilik ruang kerja 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 kelompok data harian.
• account/workspaceMessages/read - mengambil pesan ruang kerja aktif, termasuk judul notifikasi jika tersedia.
• mcpServer/oauthLogin/completed (notifikasi) - dipancarkan setelah alur mcpServer/oauth/login selesai; payload menyertakan { name, threadId, success, error? }. threadId dapat berupa null untuk alur OAuth dalam cakupan aplikasi atau plugin.
• mcpServer/startupStatus/updated (notifikasi) - dipancarkan saat status startup server MCP yang dikonfigurasi berubah; payload menyertakan { threadId, name, status, error, failureReason }. threadId adalah null untuk startup dalam cakupan aplikasi. Jika startup gagal, failureReason: "reauthenticationRequired" berarti kredensial OAuth yang tersimpan telah kedaluwarsa dan tidak dapat diperbarui, sehingga klien sebaiknya menawarkan untuk menyambungkan 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 bidang:

• refreshToken (boolean): atur true untuk memaksa pembaruan 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; ini tidak memvalidasi bahwa rantai kredensial AWS dapat memperoleh kredensial.

2) Login dengan API key

1. Kirim:

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

2. Harapkan:

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

3. Notifikasi:

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

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

3) Login dengan ChatGPT (alur browser)

1. Mulai:

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

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

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

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

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

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

3b) Login dengan ChatGPT (alur kode perangkat)

Gunakan alur ini jika klien Anda mengelola proses masuk atau jika callback browser tidak andal.

1. 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"
     }
   }

2. Tampilkan verificationUrl dan userCode kepada pengguna; frontend mengelola UX.
3. 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 mengelola siklus hidup autentikasi ChatGPT pengguna dan memberikan token secara langsung. Klien harus mengatur capabilities.experimentalApi = true selama initialize sebelum menggunakan jenis login ini.

1. Kirim:

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

2. Harapkan:

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

3. 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 diperbarui 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 menerima respons pembaruan yang berhasil. Waktu permintaan habis setelah sekitar 10 detik.

4) Membatalkan login ChatGPT

{ "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 bidang:

• rateLimits adalah tampilan satu kelompok yang kompatibel dengan versi sebelumnya.
• rateLimitsByLimitId (jika tersedia) adalah tampilan multikelompok yang dikunci berdasarkan limit_id terukur (misalnya codex).
• limitId adalah pengenal kelompok terukur.
• limitName adalah label opsional untuk kelompok yang ditampilkan kepada pengguna.
• 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 suatu kelompok.
• credits disertakan saat server mengembalikan detail sisa kredit ruang kerja.
• rateLimitReachedType mengidentifikasi status batas yang diklasifikasikan server saat suatu batas telah tercapai.
• rateLimitResetCredits memuat jumlah pengaturan ulang yang diperoleh dan tersedia jika layanan menyediakannya; jika tidak, nilainya adalah null.
• rateLimitResetCredits.credits adalah null jika hanya jumlah yang diketahui. Array kosong berarti layanan mengambil detail dan tidak menemukan kredit yang tersedia. Layanan dapat membatasi baris detail, sehingga availableCount merupakan nilai 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 bidang ringkasan aktivitas token ChatGPT dan kelompok data 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 bidang:

• Nilai summary dapat berupa null jika layanan belum mengembalikan metrik tersebut.
• dailyUsageBuckets dapat berupa null; jika tersedia, setiap kelompok menyertakan startDate dan tokens.
• Endpoint memerlukan autentikasi yang didukung oleh layanan Codex. ChatGPT, token ChatGPT eksternal, identitas agen, dan autentikasi token akses pribadi 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 bidang:

• idempotencyKey tidak boleh kosong. Gunakan UUID untuk setiap upaya penukaran logis dan gunakan kembali nilai yang sama saat mencoba ulang 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 diselesaikan sebelumnya. Perlakukan ini sebagai keberhasilan idempoten dan perbarui 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 diperbarui dari respons ini.

9) Memberi tahu pemilik ruang kerja tentang suatu batas

Gunakan account/sendAddCreditsNudgeEmail untuk meminta ChatGPT mengirim email kepada pemilik ruang kerja 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 ruang kerja habis, atau creditType: "usage_limit" saat batas penggunaan ruang kerja telah tercapai. Jika pemilik sudah diberi tahu baru-baru ini, status responsnya adalah cooldown_active.

10) Pesan ruang kerja (ChatGPT)

Gunakan account/workspaceMessages/read untuk mengambil pesan aktif bagi ruang kerja 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 }
] } }