Codex App Server

Codex app-server, Codex'in zengin istemcilere (örneğin Codex VS Code uzantısına) güç sağlamak için kullandığı arayüzdür. Kendi ürününüzde derin bir entegrasyon istediğinizde bunu kullanın: kimlik doğrulama, konuşma geçmişi, onaylar ve akış hâlinde iletilen ajan olayları. app-server uygulaması, Codex GitHub deposunda açık kaynak olarak sunulur (openai/codex/codex-rs/app-server). Açık kaynaklı Codex bileşenlerinin tam listesi için Açık Kaynak sayfasına bakın.

CLI terminal kullanıcı arayüzünü bağlama

Uzak terminal kullanıcı arayüzü modu, app-server'ı bir makinede çalıştırıp Codex CLI terminal arayüzünü başka bir makineden bağlamanıza olanak tanır. Bir WebSocket dinleyicisi başlatın:

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

Ardından terminal kullanıcı arayüzünü bağlayın:

codex --remote ws://127.0.0.1:4500

Yerel olmayan bir bağlantı için WebSocket kimlik doğrulamasını yapılandırın ve bağlantıyı TLS arkasına alın. Taşıyıcı belirtecini bir ortam değişkeninde saklayın ve belirteci komut satırına yazmak yerine değişkenin adını iletin:

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

--remote seçeneği ws://, wss://, unix:// ve unix://PATH uç noktalarını kabul eder. Düz WebSocket bağlantılarını yalnızca localhost veya SSH üzerinden port yönlendirmeli bir bağlantı için kullanın.

Uzak bir Code Mode ana makinesini bağlama

app-server varsayılan olarak yerel bir Code Mode ana makinesi başlatır. Bunun yerine uzak bir ana makine kullanmak için güvenli WebSocket URL'sini iletin:

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

--code-mode-host, app-server'dan Code Mode ana makinesine giden bağlantıyı denetler. İstemcilerin app-server'a nasıl bağlandığını denetleyen --listen değerini değiştirmez. Aynı app-server işlemindeki tüm iş parçacıkları, seçilen Code Mode ana makine bağlantısını paylaşır.

Uzak bir ana makine için wss:// kullanın. ws:// seçeneğini yalnızca localhost veya SSH üzerinden yönlendirilen bir bağlantı için kullanın. app-server komutu ve WebSocket aktarımı deneyseldir ve üretim iş yükleri için desteklenmez.

Protokol

MCP gibi codex app-server de JSON-RPC 2.0 iletilerini kullanarak çift yönlü iletişimi destekler ("jsonrpc":"2.0" üst bilgisi hat üzerinde kullanılmaz).

Desteklenen aktarımlar:

• stdio (--listen stdio://, varsayılan): yeni satırla ayrılmış JSON (JSONL).
• websocket (--listen ws://IP:PORT, deneysel ve desteklenmiyor): her WebSocket metin çerçevesinde bir JSON-RPC iletisi.
• Unix soketi (--listen unix:// veya --listen unix://PATH): standart HTTP Upgrade el sıkışması kullanılarak Codex'in varsayılan app-server denetim soketi veya özel bir Unix soket yolu üzerinden WebSocket bağlantıları.
• off (--listen off): yerel aktarımı kullanıma açmaz.

--listen ws://IP:PORT ile çalıştırdığınızda aynı dinleyici, temel HTTP durum yoklamalarını da sunar:

• Dinleyici yeni bağlantıları kabul etmeye başladığında GET /readyz, 200 OK döndürür.
• İstek bir Origin üst bilgisi içermediğinde GET /healthz, 200 OK döndürür.
• Origin üst bilgisi içeren istekler 403 Forbidden ile reddedilir.

WebSocket aktarımı deneyseldir ve desteklenmez. ws://127.0.0.1:PORT gibi yerel dinleyiciler, localhost ve SSH port yönlendirme iş akışları için uygundur. Geri döngü dışındaki WebSocket dinleyicileri, kullanıma sunma sürecinde şu anda varsayılan olarak kimliği doğrulanmamış bağlantılara izin verir; bu nedenle bir dinleyiciyi uzaktan erişime açmadan önce WebSocket kimlik doğrulamasını yapılandırın.

Desteklenen WebSocket kimlik doğrulama bayrakları:

• --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

İmzalı taşıyıcı belirteçleri için ayrıca --ws-issuer, --ws-audience ve --ws-max-clock-skew-seconds değerlerini ayarlayabilirsiniz. İstemciler kimlik bilgisini WebSocket el sıkışması sırasında Authorization: Bearer <token> olarak sunar ve app-server, JSON-RPC initialize işleminden önce kimlik doğrulamasını uygular.

Ham taşıyıcı belirteçlerini komut satırında iletmek yerine --ws-token-file seçeneğini tercih edin. --ws-token-sha256 seçeneğini yalnızca istemci, ham ve yüksek entropili belirteci ayrı bir yerel gizli bilgi deposunda tutuyorsa kullanın; karma yalnızca bir doğrulayıcıdır ve istemcilerin yine de özgün belirtece ihtiyacı vardır.

WebSocket modunda app-server sınırlı kuyruklar kullanır. İstek giriş kuyruğu dolduğunda sunucu, yeni istekleri JSON-RPC hata kodu -32001 ve "Server overloaded; retry later." iletisiyle reddeder. İstemciler üstel olarak artan gecikme ve rastgele sapma ile yeniden denemelidir.

İleti şeması

İstekler method, params ve id içerir:

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

Yanıtlar id değerini result veya error ile birlikte yansıtır:

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

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

Bildirimler id değerini içermez ve yalnızca method ile params kullanır:

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

CLI üzerinden bir TypeScript şeması veya JSON Schema paketi oluşturabilirsiniz. Her çıktı, çalıştırdığınız Codex sürümüne özgüdür; böylece oluşturulan yapıtlar tam olarak o sürümle eşleşir:

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

Başlarken

1. Sunucuyu codex app-server (varsayılan stdio aktarımı), codex app-server --listen ws://127.0.0.1:4500 (TCP WebSocket) veya codex app-server --listen unix:// (varsayılan Unix soketi) ile başlatın.
2. Seçilen aktarım üzerinden bir istemci bağlayın, ardından initialize ve sonrasında initialized bildirimini gönderin.
3. Bir iş parçacığı ve dönüş başlatın, ardından etkin aktarım akışındaki bildirimleri okumaya devam edin.

Örnek (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" } });

Temel yapı taşları

• İş parçacığı: Bir kullanıcı ile Codex ajanı arasındaki konuşma. İş parçacıkları dönüşler içerir.
• Dönüş: Tek bir kullanıcı isteği ve bunu izleyen ajan çalışması. Dönüşler öğeler içerir ve artımlı güncellemeleri akış hâlinde iletir.
• Öğe: Bir girdi veya çıktı birimi (kullanıcı iletisi, ajan iletisi, komut çalıştırmaları, dosya değişikliği, araç çağrısı ve daha fazlası).

Konuşmaları oluşturmak, listelemek veya arşivlemek için iş parçacığı API'lerini kullanın. Bir konuşmayı dönüş API'leriyle yönetin ve ilerlemeyi dönüş bildirimleri aracılığıyla akış hâlinde alın.

Yaşam döngüsüne genel bakış

• Bağlantı başına bir kez başlatın: Bir aktarım bağlantısını açtıktan hemen sonra istemci meta verilerinizle bir initialize isteği gönderin, ardından initialized yayınlayın. Sunucu, bu el sıkışmadan önce söz konusu bağlantıdaki tüm istekleri reddeder.
• Bir iş parçacığı başlatın (veya sürdürün): Yeni bir konuşma için thread/start, mevcut bir konuşmayı sürdürmek için thread/resume ya da geçmişi yeni bir iş parçacığı kimliğine dallandırmak için thread/fork çağrısını yapın.
• Bir dönüş başlatın: Hedef threadId ve kullanıcı girdisiyle turn/start çağrısını yapın. İsteğe bağlı alanlar modeli, kişiliği, cwd değerini, korumalı alan politikasını ve diğer ayarları geçersiz kılar.
• Etkin bir dönüşü yönlendirin: Yeni bir dönüş oluşturmadan, hâlen devam eden dönüşe kullanıcı girdisi eklemek için turn/steer çağrısını yapın.
• Olayları akış hâlinde alın: turn/start sonrasında stdout üzerindeki bildirimleri okumaya devam edin: thread/archived, thread/unarchived, item/started, item/completed, item/agentMessage/delta, araç ilerlemesi ve diğer güncellemeler.
• Dönüşü tamamlayın: Model tamamlandığında veya bir turn/interrupt iptalinden sonra sunucu, son durumla birlikte turn/completed yayınlar.

Başlatma

İstemciler, bir bağlantıdaki başka herhangi bir yöntemi çağırmadan önce aktarım bağlantısı başına tek bir initialize isteği göndermeli, ardından bunu bir initialized bildirimiyle onaylamalıdır. Başlatmadan önce gönderilen istekler Not initialized hatası alır; aynı bağlantıda yinelenen initialize çağrıları ise Already initialized döndürür.

Sunucu, üst hizmetlere sunacağı kullanıcı ajanı dizesinin yanı sıra çalışma zamanı hedefini açıklayan platformFamily ve platformOs değerlerini döndürür. Entegrasyonunuzu tanımlamak için clientInfo değerini ayarlayın.

initialize.params.capabilities şu istemci yeteneklerini de destekler:

• optOutNotificationMethods - bu bağlantıda engellenecek bildirim yöntemlerinin tam adları. Eşleştirme kesindir (joker karakter veya ön ek yoktur); bilinmeyen adlar kabul edilir ve yok sayılır.
• requestAttestation - sunucu tarafından başlatılan attestation/generate isteğini etkinleştirir. Üst doğrulama sağlayan masaüstü ana makineleri, opak bir { "token": "..." } değeriyle yanıt verir.
• mcpServerOpenaiFormElicitation - alt MCP sunucularının mcpServer/elicitation/request için OpenAI genişletilmiş biçim varyantını göndermesine izin verir.

Önemli: OpenAI Compliance Logs Platform için istemcinizi tanımlamak üzere clientInfo.name kullanın. Kurumsal kullanıma yönelik yeni bir Codex entegrasyonu geliştiriyorsanız bilinen istemciler listesine eklenmesi için lütfen OpenAI ile iletişime geçin. Daha fazla bağlam için Codex günlükleri referansına bakın.

Örnek (Codex VS Code uzantısından):

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

Bildirimleri devre dışı bırakma örneği:

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

Deneysel API'yi etkinleştirme

Bazı app-server yöntemleri ve alanları kasıtlı olarak experimentalApi yeteneğinin arkasında tutulur.

• Kararlı API yüzeyinde kalmak için capabilities değerini atlayın (veya experimentalApi değerini false olarak ayarlayın); sunucu deneysel yöntemleri/alanları reddeder.
• Deneysel yöntemleri ve alanları etkinleştirmek için capabilities.experimentalApi değerini true olarak ayarlayın.

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

Bir istemci etkinleştirmeden deneysel bir yöntem veya alan gönderirse app-server bunu şu iletiyle reddeder:

<descriptor> requires experimentalApi capability

API'ye genel bakış

• thread/start - yeni bir iş parçacığı oluşturur; thread/started yayınlar ve sizi bu iş parçacığının dönüş/öğe olaylarına otomatik olarak abone eder.
• thread/resume - mevcut bir iş parçacığını kimliğine göre yeniden açar; böylece sonraki turn/start çağrıları bu iş parçacığına eklenir.
• thread/fork - depolanan geçmişi kopyalayarak bir iş parçacığını yeni bir iş parçacığı kimliğine çatallar. Geçmişi ilgili dönüş dâhil o noktaya kadar kopyalayıp sonraki dönüşleri atlamak için lastTurnId iletin veya bellek içi bir çatal oluşturmak için ephemeral: true kullanın. Yeni iş parçacığı için thread/started yayınlar; döndürülen iş parçacıkları, mevcut olduğunda forkedFromId içerir.
• thread/read - depolanan bir iş parçacığını sürdürmeden kimliğine göre okur; tam dönüş geçmişini döndürmek için includeTurns değerini ayarlayın. Döndürülen thread nesneleri çalışma zamanı status değerini içerir.
• thread/list - depolanan iş parçacığı günlüklerini sayfalar; imleç tabanlı sayfalamanın yanı sıra modelProviders, sourceKinds, archived, isPinned, cwd, useStateDbOnly, searchTerm ve deneysel parentThreadId ya da ancestorThreadId filtrelerini destekler. Döndürülen thread nesneleri çalışma zamanı status değerini içerir.
• thread/turns/list - deneysel; depolanan bir iş parçacığının dönüş geçmişini sürdürmeden sayfalar. itemsView, dönüş öğelerinin atlanacağını, özetleneceğini veya tamamen yükleneceğini denetler.
• thread/items/list - deneysel; kalıcı iş parçacığı öğelerini, isteğe bağlı olarak tek bir turnId ile sınırlayarak sayfalar. Etkin iş parçacığı deposu öğe sayfalamayı desteklemelidir.
• thread/loaded/list - bellekte yüklü olan iş parçacığı kimliklerini listeler.
• thread/name/set - yüklü bir iş parçacığı veya kalıcı bir çalıştırma kaydı için iş parçacığının kullanıcıya gösterilen adını ayarlar ya da günceller; thread/name/updated yayınlar.
• thread/goal/set - bir iş parçacığının hedefini ayarlar; thread/goal/updated yayınlar.
• thread/goal/get - bir iş parçacığının mevcut hedefini okur.
• thread/goal/clear - bir iş parçacığının hedefini temizler; thread/goal/cleared yayınlar.
• thread/metadata/update - kalıcı gitInfo ve isPinned dâhil SQLite destekli depolanmış iş parçacığı meta verilerine yama uygular.
• thread/archive - bir iş parçacığının günlük dosyasını arşivlenmiş dizine taşır ve daha önce arşivlenmemiş, oluşturulmuş alt iş parçacığı günlüklerini arşivlemeyi dener; başarı durumunda {} döndürür ve arşivlenen her iş parçacığı için thread/archived yayınlar.
• thread/delete - kalıcı etkin veya arşivlenmiş bir iş parçacığını ve oluşturduğu tüm alt iş parçacıklarını kalıcı olarak siler; başarı durumunda {} döndürür ve silinen her iş parçacığı için thread/deleted yayınlar.
• thread/unsubscribe - bu bağlantının iş parçacığı dönüş/öğe olayları aboneliğini kaldırır. Bu son aboneyse sunucu, abonesiz hareketsizlik ek süresinin ardından iş parçacığını bellekten kaldırır ve thread/closed yayınlar.
• thread/unarchive - arşivlenmiş bir iş parçacığı çalıştırma kaydını etkin oturumlar dizinine geri yükler; geri yüklenen thread değerini döndürür ve thread/unarchived yayınlar.
• thread/status/changed - yüklü bir iş parçacığının çalışma zamanı status değeri değiştiğinde yayınlanan bildirim.
• thread/compact/start - bir iş parçacığının konuşma geçmişini sıkıştırmayı tetikler; ilerleme turn/* ve item/* bildirimleriyle akış hâlinde iletilirken hemen {} döndürür.
• thread/shellCommand - bir iş parçacığı üzerinde kullanıcı tarafından başlatılan bir kabuk komutu çalıştırır. Bu işlem, korumalı alanın dışında tam erişimle çalışır ve iş parçacığının korumalı alan politikasını devralmaz.
• thread/backgroundTerminals/clean - bir iş parçacığı için çalışan tüm arka plan terminallerini durdurur (deneysel; capabilities.experimentalApi gerekir).
• thread/backgroundTerminals/list - yüklü bir iş parçacığı için çalışan arka plan terminallerini listeler (deneysel; capabilities.experimentalApi gerekir).
• thread/backgroundTerminals/terminate - app-server processId değerine göre çalışan bir arka plan terminalini sonlandırır (deneysel; capabilities.experimentalApi gerekir).
• thread/rollback - kullanımdan kaldırıldı; bellek içi bağlamdan son N dönüşü çıkarır ve kalıcı bir geri alma işaretçisi kaydeder; güncellenen thread değerini döndürür.
• turn/start - bir iş parçacığına kullanıcı girdisi ekler ve Codex üretimini başlatır; ilk turn ile yanıt verir ve olayları akış hâlinde iletir. collaborationMode için settings.developer_instructions: null, "seçilen modun yerleşik talimatlarını kullan" anlamına gelir.
• thread/inject_items - kullanıcı dönüşü başlatmadan, ham Responses API öğelerini yüklü bir iş parçacığının model tarafından görülebilen geçmişine ekler.
• turn/steer - bir iş parçacığının devam eden etkin dönüşüne kullanıcı girdisi ekler; kabul edilen turnId değerini döndürür.
• turn/interrupt - devam eden bir dönüşün iptal edilmesini ister; başarı sonucu {} olur ve dönüş status: "interrupted" ile sona erer.
• review/start - bir iş parçacığı için Codex inceleyicisini başlatır; enteredReviewMode ve exitedReviewMode öğelerini yayınlar.
• command/exec - iş parçacığı/dönüş başlatmadan sunucunun korumalı alanında tek bir komut çalıştırır.
• command/exec/write - çalışan bir command/exec oturumuna stdin bayt yazar veya stdin kapatır.
• command/exec/resize - PTY destekli çalışan bir command/exec oturumunu yeniden boyutlandırır.
• command/exec/terminate - çalışan bir command/exec oturumunu durdurur.
• command/exec/outputDelta (bildirim) - akış sağlayan bir command/exec oturumundan base64 kodlu stdout/stderr parçaları için yayınlanır.
• process/spawn - Codex'in korumalı alanının dışında açık bir işlem oturumu başlatır (deneysel; capabilities.experimentalApi gerekir).
• process/writeStdin - çalışan bir process/spawn oturumuna stdin baytları yazar veya stdin'i kapatır (deneysel).
• process/resizePty - PTY destekli çalışan bir işlem oturumunu yeniden boyutlandırır (deneysel).
• process/kill - çalışan bir işlem oturumunu sonlandırır (deneysel).
• process/outputDelta ve process/exited (bildirim) - akış hâlindeki işlem çıktısı ve işlem çıkış durumu için yayınlanır (deneysel).
• model/list - kullanılabilir modelleri; efor seçenekleri, isteğe bağlı upgrade ve inputModalities ile listeler (hidden: true içeren girdileri dâhil etmek için includeHidden: true değerini ayarlayın).
• modelProvider/capabilities/read - model/sağlayıcı birleşimleri için sağlayıcı yetenek sınırlarını okur.
• experimentalFeature/list - özellik bayraklarını yaşam döngüsü aşaması meta verileri ve imleçli sayfalamayla listeler.
• experimentalFeature/enablement/set - apps ve plugins gibi desteklenen özellik anahtarlarının bellek içi çalışma zamanı ayarlarına yama uygular.
• environment/info - deneysel; yapılandırılmış bir yürütme ortamına bağlanır ve ortamın kabuğu ile varsayılan çalışma dizinini döndürür.
• permissionProfile/list - beta izin profillerini ve geçerli gereksinimlerin bunlara izin verip vermediğini imleçli sayfalamayla listeler.
• collaborationMode/list - iş birliği modu ön ayarlarını listeler (deneysel, sayfalama yoktur).
• skills/list - bir veya daha fazla cwd değeri için becerileri listeler (forceReload ve isteğe bağlı perCwdExtraUserRoots desteklenir).
• skills/extraRoots/set - bağımsız becerileri keşfetmek için kullanılan işlem düzeyindeki ek kökleri kalıcı hâle getirmeden değiştirir.
• skills/changed (bildirim) - izlenen yerel beceri dosyaları değiştiğinde yayınlanır.
• hooks/list - bir veya daha fazla cwd değeri için keşfedilen yaşam döngüsü kancalarını listeler.
• marketplace/add - uzak bir eklenti pazar yeri ekler ve bunu kullanıcının pazar yeri yapılandırmasına kaydeder.
• marketplace/remove - yapılandırılmış bir pazar yerini ve mevcutsa kurulu pazar yeri kökünü kaldırır.
• marketplace/upgrade - yapılandırılmış bir Git pazar yerini veya pazar yeri adını atladığınızda yapılandırılmış tüm Git pazar yerlerini yeniler.
• plugin/list - geliştirme aşamasında; keşfedilen eklenti pazar yerlerini ve kurulum/kimlik doğrulama ilkesi meta verileri, pazar yeri yükleme hataları, öne çıkan eklenti kimlikleri ve yerel, Git, paket kayıt defteri veya uzak eklenti kaynağı meta verileri dâhil eklenti durumunu listeler. Özetler uzak version, yerel localVersion, yapılandırılmış açık/koyu simgeler ve mevcut uzak satırlar için null, WORKSPACE_SETTING ya da IMPLICIT_CANONICAL_APP olabilen installPolicySource değerini içerebilir. Bu yöntemi henüz üretim istemcilerinden çağırmayın.
• plugin/read - geliştirme aşamasında; pazar yeri yolu veya uzak pazar yeri adı ve eklenti adına göre tek bir eklentiyi; paketlenmiş becerileri, uygulamaları, MCP sunucu adlarını ve uzak katalog sağlıyorsa uzak eklenti shareUrl değerini içerecek biçimde okur. Bu yöntemi henüz üretim istemcilerinden çağırmayın.
• plugin/install - geliştirme aşamasında; pazar yeri yolundan veya uzak pazar yeri adından bir eklenti kurar. Bu yöntemi henüz üretim istemcilerinden çağırmayın.
• plugin/uninstall - geliştirme aşamasında; kurulu bir eklentiyi kaldırır. Bu yöntemi henüz üretim istemcilerinden çağırmayın.
• plugin/skill/read - uzak pazar yeri, eklenti kimliği ve beceri adına göre uzak eklenti becerisi Markdown metnini istek üzerine okur.
• app/installed - her uygulamanın geçerli etkin ve çağrılabilir durumları dâhil, kurulu uygulama çalışma zamanı durumunu okur.
• app/list - kullanılabilir uygulamaları (bağlayıcıları) erişilebilirlik/etkinlik meta verileri ve sayfalamayla listeler.
• app/read - belirli uygulama kimlikleri için meta verileri ve isteğe bağlı, yalnızca görüntülemeye yönelik araç özetlerini getirir.
• skills/config/write - becerileri yola göre etkinleştirir veya devre dışı bırakır.
• mcpServer/oauth/login - yapılandırılmış bir MCP sunucusu için OAuth oturumu açmayı başlatır; yetkilendirme URL'si döndürür ve tamamlandığında mcpServer/oauthLogin/completed yayınlar.
• tool/requestUserInput - bir araç çağrısı için kullanıcıya 1-3 kısa soru yöneltir (deneysel); sorular serbest biçimli bir seçenek için isOther ayarlayabilir.
• mcpServer/elicitation/request (sunucu isteği) - istemciden, bir MCP sunucusunun istediği yapılandırılmış form girdisini veya URL akışı onayını ister.
• item/permissions/requestApproval (sunucu isteği) - istemciden, yerleşik request_permissions aracının istediği ağ veya dosya sistemi izinlerinin bir alt kümesini vermesini ister.
• config/mcpServer/reload - MCP sunucu yapılandırmasını diskten yeniden yükler ve yüklü iş parçacıkları için yenileme kuyruğa alır.
• mcpServerStatus/list - MCP sunucularını, araçlarını, kaynaklarını ve kimlik doğrulama durumunu listeler (imleç + sınır sayfalaması). Tam veriler için detail: "full", kaynakları atlamak için detail: "toolsAndAuthOnly" kullanın.
• mcpServer/resource/read - başlatılmış bir MCP sunucusu üzerinden tek bir MCP kaynağını okur.
• mcpServer/tool/call - bir iş parçacığının yapılandırılmış MCP sunucusunda araç çağırır.
• mcpServer/startupStatus/updated (bildirim) - yapılandırılmış bir MCP sunucusunun başlangıç durumu, yüklü bir iş parçacığı için değiştiğinde yayınlanır.
• windowsSandbox/setupStart - elevated veya unelevated modu için Windows korumalı alan kurulumunu başlatır; hızla sonuç döndürür ve daha sonra windowsSandbox/setupCompleted yayınlar.
• feedback/upload - geri bildirim raporu gönderir (sınıflandırma + isteğe bağlı neden/günlükler + konuşma kimliği ve isteğe bağlı extraLogFiles ekleri).
• config/read - yapılandırma katmanlamasını çözümledikten sonra diskteki geçerli yapılandırmayı getirir.
• externalAgentConfig/detect - includeHome ve isteğe bağlı cwds ile taşınabilecek harici ajan yapıtlarını algılar; algılanan her öğe cwd içerir (ana dizin için null).
• externalAgentConfig/import - açık migrationItems değerlerini cwd ile ileterek seçilen harici ajan taşıma öğelerini uygular (ana dizin için null). Desteklenen öğe türleri yapılandırma, beceriler, AGENTS.md, eklentiler, MCP sunucu yapılandırması, alt ajanlar, kancalar, komutlar ve oturumları içerir; boş olmayan içe aktarmalar, çalışma tamamlanırken externalAgentConfig/import/progress ve externalAgentConfig/import/completed yayınlar. Eklenti ve oturum içe aktarmaları eşzamansız tamamlanabilir.
• config/value/write - kullanıcının diskteki config.toml dosyasına tek bir yapılandırma anahtarı/değeri yazar.
• config/batchWrite - yapılandırma düzenlemelerini kullanıcının diskteki config.toml dosyasına atomik olarak uygular.
• configRequirements/read - requirements.toml ve/veya MDM'den; tam yönetilen yapılandırma, izin listeleri, sabitlenmiş featureRequirements ve yerleşim/ağ gereksinimleri dâhil gereksinimleri getirir (hiçbirini ayarlamadıysanız null).
• fs/readFile, fs/writeFile, fs/createDirectory, fs/getMetadata, fs/readDirectory, fs/remove, fs/copy, fs/watch, fs/unwatch ve fs/changed (bildirim) - app-server v2 dosya sistemi API'si üzerinden mutlak dosya sistemi yollarında işlem yapar.

Eklenti özetleri bir source birleşimi içerir. Yerel eklentiler { "type": "local", "path": ... }, Git destekli pazar yeri girdileri { "type": "git", "url": ..., "path": ..., "refName": ..., "sha": ... }, paket kayıt defteri girdileri { "type": "npm", "package": ..., "version": ..., "registry": ... } ve uzak katalog girdileri { "type": "remote" } döndürür. Yalnızca uzak katalog girdileri için PluginMarketplaceEntry.path, null olabilir; bu eklentileri okurken veya kurarken marketplacePath yerine remoteMarketplaceName iletin.

Modeller

Modelleri listeleme (model/list)

Model veya kişilik seçicilerini oluşturmadan önce kullanılabilir modelleri ve yeteneklerini keşfetmek için model/list çağrısını yapın.

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

Her model girdisi şunları içerebilir:

• supportedReasoningEfforts - model için desteklenen efor seçenekleri.
• defaultReasoningEffort - istemciler için önerilen varsayılan efor.
• upgrade - istemcilerdeki geçiş istemleri için isteğe bağlı önerilen yükseltme modeli kimliği.
• upgradeInfo - istemcilerdeki geçiş istemleri için isteğe bağlı yükseltme meta verileri.
• hidden - modelin varsayılan seçici listesinden gizlenip gizlenmediği.
• inputModalities - model için desteklenen girdi türleri (örneğin text, image).
• supportsPersonality - modelin /personality gibi kişiliğe özgü talimatları destekleyip desteklemediği.
• isDefault - modelin önerilen varsayılan olup olmadığı.

model/list varsayılan olarak yalnızca seçicide görünen modelleri döndürür. Tam listeye ihtiyacınız varsa ve istemci tarafında hidden kullanarak filtrelemek istiyorsanız includeHidden: true değerini ayarlayın.

inputModalities eksik olduğunda (eski model katalogları), geriye dönük uyumluluk için bunu ["text", "image"] olarak değerlendirin.

Deneysel özellikleri listeleme (experimentalFeature/list)

Meta verileri ve yaşam döngüsü aşamalarıyla özellik bayraklarını keşfetmek için bu uç noktayı kullanın:

{ "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; beta, underDevelopment, stable, deprecated veya removed olabilir. Beta olmayan bayraklar için displayName, description ve announcement değerleri null olabilir.

Bir yürütme ortamını inceleme (deneysel)

Yapılandırılmış bir uzak ortamı, orada çalışmaya başlamadan önce incelemek için environment/info kullanın. Bu yöntem capabilities.experimentalApi = true gerektirir.

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

cwd, null olabilir. Mevcut olduğunda ortamın yerel yol söz dizimini kullanan kurallı bir file: URI'sidir. Bilinmeyen ortam kimlikleri ile bağlantı veya protokol hataları istek hataları döndürür.

İş parçacıkları

• thread/read, depolanan bir iş parçacığına abone olmadan onu okur; dönüşleri dâhil etmek için includeTurns değerini ayarlayın.
• thread/turns/list deneyseldir ve depolanan bir iş parçacığının dönüş geçmişini sürdürmeden sayfalar. Dönüş öğelerinin atlanacağını, özetleneceğini veya tamamen yükleneceğini seçmek için itemsView kullanın.
• thread/items/list deneyseldir ve kalıcı iş parçacığı öğelerini, isteğe bağlı olarak tek bir dönüşle sınırlayarak sayfalar.
• thread/list, imleçli sayfalamanın yanı sıra modelProviders, sourceKinds, archived, isPinned, cwd, useStateDbOnly, searchTerm ve deneysel parentThreadId ya da ancestorThreadId filtrelemesini destekler.
• thread/loaded/list, şu anda bellekte bulunan iş parçacığı kimliklerini döndürür.
• thread/archive, iş parçacığının kalıcı JSONL günlüğünü arşivlenmiş dizine taşır ve daha önce arşivlenmemiş, oluşturulmuş alt iş parçacığı günlüklarını arşivlemeyi dener.
• thread/delete, kalıcı etkin veya arşivlenmiş bir iş parçacığını ve oluşturduğu alt iş parçacıklarını kalıcı olarak siler.
• thread/metadata/update, kalıcı gitInfo ve isPinned dâhil depolanan iş parçacığı meta verilerine yama uygular.
• thread/unsubscribe, mevcut bağlantının yüklü bir iş parçacığı aboneliğini kaldırır ve hareketsizlik ek süresinden sonra thread/closed olayını tetikleyebilir.
• thread/unarchive, arşivlenmiş bir iş parçacığı çalıştırma kaydını etkin oturumlar dizinine geri yükler.
• thread/compact/start, sıkıştırmayı tetikler ve hemen {} döndürür.
• thread/rollback kullanımdan kaldırılmıştır. Bellek içi bağlamdan son N dönüşü çıkarır ve iş parçacığının kalıcı JSONL günlüğüne bir geri alma işaretçisi kaydeder.
• thread/inject_items, kullanıcı dönüşü başlatmadan ham Responses API öğelerini yüklü bir iş parçacığının model tarafından görülebilen geçmişine ekler.

Bir iş parçacığını başlatma veya sürdürme

Yeni bir Codex konuşmasına ihtiyaç duyduğunuzda yeni bir iş parçacığı başlatın.

{ "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 isteğe bağlıdır. app-server'ın iş parçacığı düzeyindeki metrikleri entegrasyonunuzun hizmet adıyla etiketlemesini istediğinizde bunu ayarlayın.

thread/start, thread/resume ve thread/fork, yüklenen talimat dosyası yollarından oluşan bir dizi olan instructionSources değerini döndürür. Uzak ortamlar dâhil her yol, kaynak ortamının yerel mutlak söz dizimini kullanır.

Deneysel istemciler, thread/start üzerindeki historyMode değerini "legacy" (varsayılan) veya "paginated" olarak ayarlayabilir. Sayfalı iş parçacığı oluşturma henüz desteklenmez ve JSON-RPC hatası -32601 döndürür. app-server mevcut sayfalı kayıtların özetlerini listeleyip okuyabilir; ancak sayfalı geçmiş desteklenene kadar tam geçmiş okumaları, dönüş sayfalama ve sürdürme işlemleri güvenli biçimde başarısız olur.

capabilities.experimentalApi özelliğini etkinleştiren beta istemcileri, eski sandbox alanı yerine permissions içinde adlandırılmış bir izin profili kimliği iletebilir. permissions ve sandbox değerlerini birlikte göndermeyin. Kullanılabilir profilleri ve yönetilen gereksinimlerin her birine izin verip vermediğini keşfetmek için proje cwd değeriyle permissionProfile/list kullanın.

thread.sessionId, mevcut canlı oturum ağacının kökünü tanımlar. Kök iş parçacıkları kendi iş parçacığı kimliklerini oturum kimliği olarak kullanır; çatallanmış iş parçacıkları geldikleri kökün oturum kimliğini korur. İstemciler oturum kimliğini iş parçacığı kimliğinden türetmek yerine thread.sessionId üzerinden okumalıdır.

Depolanan bir oturumu sürdürmek için daha önce kaydettiğiniz thread.id ile thread/resume çağrısını yapın. Yanıt biçimi thread/start ile aynıdır. Ayrıca thread/start tarafından desteklenen personality gibi yapılandırma geçersiz kılmalarını da iletebilirsiniz:

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

Bir iş parçacığını sürdürmek, tek başına thread.updatedAt değerini (veya çalıştırma dosyasının değiştirilme zamanını) güncellemez. Zaman damgası bir dönüş başlattığınızda güncellenir.

Etkin bir MCP sunucusunu yapılandırmada required olarak işaretlerseniz ve bu sunucu başlatılamazsa thread/start ile thread/resume, sunucu olmadan devam etmek yerine başarısız olur.

thread/start üzerindeki dynamicTools deneysel bir alandır (capabilities.experimentalApi = true gerektirir). Codex, bu dinamik araçları iş parçacığının çalıştırma kaydı meta verilerinde kalıcı hâle getirir ve yeni dinamik araçlar sağlamadığınızda thread/resume sırasında geri yükler.

Çalıştırma kaydında bulunan modelden farklı bir modelle sürdürürseniz Codex bir uyarı yayınlar ve sonraki dönüşte tek seferlik bir model değiştirme talimatı uygular.

Bir iş parçacığı hedefini yönetme

TUI içinde /goal tarafından gösterilen aynı kalıcı hedef durumunu yönetmek için thread/goal/set, thread/goal/get ve thread/goal/clear kullanın.

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

Hedef amaçları boş olamaz ve en fazla 4.000 karakter içerebilir. Yeni bir amaç sağlamak hedefi değiştirir ve kullanım hesabını sıfırlar. Mevcut sonlandırılmamış amacı sağlamak veya objective değerini atlamak, kullanım geçmişini koruyarak durumu ya da belirteç bütçesini günceller.

Depolanan bir oturumdan dallanmak için thread.id ile thread/fork çağrısını yapın. Bu işlem yeni bir iş parçacığı kimliği oluşturur ve bunun için thread/started bildirimi yayınlar. Geçmişi ilgili dönüş dâhil o noktaya kadar kopyalayıp sonraki dönüşleri atlamak için lastTurnId iletin:

{ "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, devam eden bir lastTurnId değerini reddeder. Kaynak iş parçacığı dönüşün ortasındayken bu alanı atlarsanız çatal, işaretsiz kısmi bir dönüşü tutmak yerine kesinti işaretçisi kaydeder.

Depolanan iş parçacığı listelerine eklemeden bellek içi bir çatal oluşturmak için ephemeral: true iletin:

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

Sayfalı iş parçacıklarının geçici çatalları ayrıca excludeTurns: true gerektirir. Bu alan deneyseldir ve capabilities.experimentalApi = true gerektirir.

Kullanıcıya gösterilen bir iş parçacığı başlığı ayarlandığında app-server; thread/list, thread/read, thread/resume, thread/unarchive ve thread/rollback yanıtlarında thread.name değerini doldurur. Bir başlık daha sonra ayarlanana kadar thread/start ve thread/fork, name değerini atlayabilir (veya null döndürebilir).

Depolanan bir iş parçacığını okuma (sürdürmeden)

Depolanan iş parçacığı verilerini almak ancak iş parçacığını sürdürmek veya olaylarına abone olmak istemediğinizde thread/read kullanın.

• includeTurns - true olduğunda yanıt, iş parçacığının dönüşlerini içerir; false olduğunda veya atlandığında yalnızca iş parçacığı özetini alırsınız.
• Döndürülen thread nesneleri çalışma zamanı status değerini içerir (notLoaded, idle, systemError veya activeFlags ile birlikte active).

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

thread/resume yönteminin aksine thread/read, iş parçacığını belleğe yüklemez veya thread/started yayınlamaz.

İş parçacığı dönüşlerini listeleme

thread/turns/list deneyseldir. Depolanan bir iş parçacığının dönüş geçmişini sürdürmeden sayfalamak için kullanın. Sonuçlar varsayılan olarak yeniden eskiye sıralanır; böylece istemciler nextCursor ile daha eski dönüşleri getirebilir. Yanıt ayrıca backwardsCursor içerir; önceki sayfanın ilk öğesinden daha yeni dönüşleri getirmek için bunu sortDirection: "asc" ile birlikte cursor olarak iletin.

itemsView, yanıtın ne kadar dönüş öğesi verisi içerdiğini denetler:

• notLoaded öğeleri atlar.
• summary özetlenmiş öğe verilerini döndürür ve atlandığında varsayılandır.
• full tam öğe verilerini döndürür.

{ "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 de deneyseldir. Kalıcı öğeleri iş parçacığını sürdürmeden sayfalar. Sonuçları tek bir dönüşle sınırlamak için turnId iletin veya öğeleri iş parçacığı genelinde sayfalamak için bunu atlayın. Etkin iş parçacığı deposu öğe sayfalamayı desteklemelidir; aksi takdirde sunucu desteklenmeyen yöntem hatası döndürür.

İş parçacıklarını listeleme (sayfalama ve filtrelerle)

thread/list, bir geçmiş kullanıcı arayüzü oluşturmanıza olanak tanır. Sonuçlar createdAt değerine göre varsayılan olarak yeniden eskiye sıralanır. Filtreler sayfalamadan önce uygulanır. Şunların herhangi bir birleşimini iletin:

• cursor - önceki bir yanıttan alınan opak dize; ilk sayfa için atlayın.
• limit - ayarlanmazsa sunucu makul bir sayfa boyutu kullanır.
• sortKey - created_at (varsayılan), updated_at veya recency_at.
• sortDirection - desc (varsayılan) veya asc.
• modelProviders - sonuçları belirli sağlayıcılarla sınırlar; ayarlanmamış, null veya boş bir dizi tüm sağlayıcıları içerir.
• sourceKinds - sonuçları belirli iş parçacığı kaynaklarıyla sınırlar. Atlandığında veya [] olduğunda sunucu varsayılan olarak yalnızca etkileşimli kaynakları kullanır: cli ve vscode.
• archived - true olduğunda yalnızca arşivlenmiş iş parçacıklarını listeler. false olduğunda veya atlandığında arşivlenmemiş iş parçacıklarını listeler (varsayılan).
• isPinned - sağlandığında yalnızca eşleşen kalıcı sabitleme durumuna sahip iş parçacıklarını döndürür. Sabitlenmiş ve sabitlenmemiş iş parçacıklarını döndürmek için atlayın.
• cwd - sonuçları, oturumun mevcut çalışma dizini bu yolla veya dizideki yollardan biriyle tam olarak eşleşen iş parçacıklarıyla sınırlar. Göreli yollar app-server işleminin çalışma dizininden çözümlenir.
• useStateDbOnly - true olduğunda, meta verileri onarmak için JSONL iş parçacığı günlüklerini taramadan durum veri tabanı sonuçlarını döndürür. Varsayılan tarama ve onarma davranışı için bunu atlayın veya false iletin.
• searchTerm - sonuçları, ayıklanan başlığı büyük/küçük harfe duyarlı bu metin parçasını içeren iş parçacıklarıyla sınırlar.
• parentThreadId - sonuçları belirtilen üst iş parçacığının doğrudan alt iş parçacıklarıyla sınırlar. Bu filtre deneyseldir ve capabilities.experimentalApi = true gerektirir.
• ancestorThreadId - sonuçları, belirtilen iş parçacığından herhangi bir derinlikte oluşturulmuş alt iş parçacıklarıyla sınırlar. Bu filtre deneyseldir ve capabilities.experimentalApi = true gerektirir; parentThreadId ile birleştirmeyin.

sourceKinds şu değerleri kabul eder:

• cli
• vscode
• exec
• appServer
• subAgent
• subAgentReview
• subAgentCompact
• subAgentThreadSpawn
• subAgentOther
• unknown

Örnek:

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

nextCursor değeri null olduğunda son sayfaya ulaşmışsınızdır.

Depolanan iş parçacığı meta verilerini güncelleme

İş parçacığını sürdürmeden depolanan iş parçacığı meta verilerine yama uygulamak için thread/metadata/update kullanın. İş parçacığını sabitlemek veya sabitlemesini kaldırmak için isPinned değerini ayarlayın ya da kalıcı Git meta verilerini değiştirmek için gitInfo değerini güncelleyin. Atlanan alanlar değişmeden kalır; açık null, depolanan Git meta veri değerini temizler.

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

İş parçacığı durum değişikliklerini izleme

Yüklü bir iş parçacığının çalışma zamanı durumu her değiştiğinde thread/status/changed yayınlanır. Yük, threadId ve yeni status değerini içerir.

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

Yüklü iş parçacıklarını listeleme

thread/loaded/list, şu anda bellekte yüklü olan iş parçacığı kimliklerini döndürür.

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

Yüklü bir iş parçacığının aboneliğini kaldırma

thread/unsubscribe, mevcut bağlantının bir iş parçacığı aboneliğini kaldırır. Yanıt durumu şunlardan biridir:

• Bağlantı aboneyse ve artık kaldırıldıysa unsubscribed.
• Bağlantı bu iş parçacığına abone değilse notSubscribed.
• İş parçacığı yüklü değilse notLoaded.

Bu son aboneyse sunucu, iş parçacığını hiçbir abonesi ve iş parçacığı etkinliği olmadan 30 dakika geçene kadar yüklü tutar. Ek süre dolduğunda app-server iş parçacığını bellekten kaldırır ve notLoaded durumuna bir thread/status/changed geçişiyle birlikte thread/closed yayınlar.

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

İş parçacığının süresi daha sonra dolarsa:

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

Bir iş parçacığını arşivleme

Kalıcı iş parçacığı günlüğünü (diskte JSONL dosyası olarak depolanır) arşivlenmiş oturumlar dizinine taşımak için thread/archive kullanın. Bir iş parçacığını arşivlemek, daha önce arşivlenmemiş ve onun tarafından oluşturulmuş alt iş parçacıklarını da arşivlemeyi dener.

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

Arşivlenen iş parçacıkları, archived: true iletmediğiniz sürece gelecekteki thread/list çağrılarında görünmez. Sunucu, gerçekten arşivlediği her iş parçacığı için bir thread/archived bildirimi yayımlar; oluşturulan bir alt öğe arşivlenemiyorsa istek, bu alt öğe için arşivlendi bildirimi olmadan da başarılı olabilir.

Bir iş parçacığını silme

Kalıcı hâle getirilmiş etkin veya arşivlenmiş bir iş parçacığını ve onun oluşturduğu alt iş parçacıklarını kalıcı olarak silmek için thread/delete kullanın. Sunucu, başarı yanıtını döndürmeden önce mevcut rollout dosyalarını ve ilişkili meta verileri kaldırır; eksik rollout dosyaları zaten silinmiş kabul edilir. Geçici kök iş parçacıkları silinemez.

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

Bir iş parçacığını arşivden çıkarma

Arşivlenmiş bir iş parçacığının rollout'unu yeniden etkin oturumlar dizinine taşımak için thread/unarchive kullanın.

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

İş parçacığı sıkıştırmasını tetikleme

Bir iş parçacığının geçmişini elle sıkıştırmayı tetiklemek için thread/compact/start kullanın. İstek, {} ile hemen döner.

App-server, aynı threadId üzerinde standart turn/* ve item/* bildirimleri olarak ilerleme yayımlar; buna bir contextCompaction öğesi yaşam döngüsü de dahildir (önce item/started, ardından item/completed).

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

İş parçacığında kabuk komutu çalıştırma

Bir iş parçacığına ait, kullanıcı tarafından başlatılan kabuk komutları için thread/shellCommand kullanın. İlerleme standart turn/* ve item/* bildirimleri üzerinden akarken istek, {} ile hemen döner.

Bu API, tam erişimle sandbox dışında çalışır ve iş parçacığının sandbox politikasını devralmaz. İstemciler bunu yalnızca kullanıcı tarafından açıkça başlatılan komutlar için sunmalıdır.

İş parçacığında zaten etkin bir tur varsa komut, o turda yardımcı bir eylem olarak çalışır ve biçimlendirilmiş çıktısı turun ileti akışına eklenir. İş parçacığı boştaysa app-server, kabuk komutu için bağımsız bir tur başlatır.

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

Arka plan terminallerini temizleme

Bir iş parçacığıyla ilişkili çalışan tüm arka plan terminallerini durdurmak için thread/backgroundTerminals/clean kullanın. Bu yöntem deneyseldir ve capabilities.experimentalApi = true gerektirir.

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

Yüklenmiş bir iş parçacığının çalışan arka plan terminallerini incelemek için thread/backgroundTerminals/list kullanın. İstek, standart cursor ve limit sayfalandırmasını destekler; döndürülen processId ise app-server işlem kimliğidir. Bu yöntem deneyseldir ve capabilities.experimentalApi = true gerektirir:

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

Tek bir arka plan terminalini durdurmak için ilgili processId ile thread/backgroundTerminals/terminate kullanın. Bu yöntem deneyseldir ve capabilities.experimentalApi = true gerektirir:

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

Son turları geri alma

thread/rollback kullanımdan kaldırılmıştır ve ileride kaldırılacaktır. Bellek içi bağlamdan son numTurns girdiyi kaldırır ve rollout günlüğüne bir geri alma işareti kaydeder. Döndürülen thread, geri alma işleminden sonra doldurulmuş turns içerir.

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

Turlar

input alanı bir öğe listesi kabul eder:

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

Yapılandırma ayarlarını tur bazında geçersiz kılabilirsiniz (model, efor, kişilik, cwd, sandbox politikası, özet). Belirtildiğinde bu ayarlar, aynı iş parçacığındaki sonraki turların varsayılanları olur. outputSchema yalnızca geçerli tura uygulanır. sandboxPolicy.type = "externalSandbox" için networkAccess değerini restricted veya enabled olarak ayarlayın; workspaceWrite için networkAccess boolean olarak kalır.

turn/start.collaborationMode için settings.developer_instructions: null, mod talimatlarını temizlemek yerine "seçilen modun yerleşik talimatlarını kullan" anlamına gelir.

Sandbox okuma erişimi (ReadOnlyAccess)

sandboxPolicy, açık okuma erişimi denetimlerini destekler:

• readOnly: isteğe bağlı access (varsayılan olarak { "type": "fullAccess" } veya kısıtlı kökler).
• workspaceWrite: isteğe bağlı readOnlyAccess (varsayılan olarak { "type": "fullAccess" } veya kısıtlı kökler).

Kısıtlı okuma erişiminin yapısı:

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

macOS'te includePlatformDefaults: true, okuma erişimi kısıtlı oturumlar için özenle seçilmiş, platformun varsayılan Seatbelt politikasını ekler. Bu, /System öğesinin tamamına geniş kapsamlı izin vermeden araç uyumluluğunu iyileştirir.

Örnekler:

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

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

Bir tur başlatma

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

Bir iş parçacığına öğe ekleme

Kullanıcı turu başlatmadan, önceden oluşturulmuş Responses API öğelerini yüklenmiş bir iş parçacığının istem geçmişine eklemek için thread/inject_items kullanın. Bu öğeler rollout'a kalıcı olarak kaydedilir ve sonraki model isteklerine dahil edilir.

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

Etkin bir turu yönlendirme

Devam eden etkin tura daha fazla kullanıcı girdisi eklemek için turn/steer kullanın.

• expectedTurnId öğesini dahil edin; etkin turun kimliğiyle eşleşmelidir.
• İş parçacığında etkin bir tur yoksa istek başarısız olur.
• turn/steer yeni bir turn/started bildirimi yayımlamaz.
• turn/steer, tur düzeyindeki geçersiz kılmaları (model, cwd, sandboxPolicy veya outputSchema) kabul etmez.

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

Bir tur başlatma (bir skill çağırma)

Metin girdisine $<skill-name> ekleyip yanında bir skill girdi öğesi sağlayarak bir skill'i açıkça çağırın.

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

Bir turu kesintiye uğratma

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

Başarılı olduğunda tur, status: "interrupted" ile tamamlanır.

İnceleme

review/start, bir iş parçacığı için Codex inceleyicisini çalıştırır ve inceleme öğelerini akış hâlinde iletir. Hedefler şunlardır:

• uncommittedChanges
• baseBranch (bir dala göre diff)
• commit (belirli bir commit'i inceleme)
• custom (serbest biçimli talimatlar)

İncelemeyi mevcut iş parçacığında çalıştırmak için delivery: "inline" (varsayılan), yeni bir inceleme iş parçacığı çatallamak içinse delivery: "detached" kullanın.

Örnek istek/yanıt:

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

Ayrılmış bir inceleme için "delivery": "detached" kullanın. Yanıtın yapısı aynıdır ancak reviewThreadId, yeni inceleme iş parçacığının kimliği olur (özgün threadId değerinden farklıdır). Sunucu ayrıca inceleme turunu akış hâlinde iletmeden önce bu yeni iş parçacığı için bir thread/started bildirimi yayımlar.

Codex, olağan turn/started bildirimini ve ardından enteredReviewMode öğesi içeren bir item/started yayımlar:

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

İnceleyici tamamladığında sunucu, nihai inceleme metnini içeren bir exitedReviewMode öğesiyle item/started ve item/completed yayımlar:

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

İstemcinizde inceleyici çıktısını işlemek için bu bildirimi kullanın.

İşlem yürütme

process/*, deneysel ve açık bir işlem denetimi API'sidir. capabilities.experimentalApi = true gerektirir ve Codex'in sandbox'ı dışında çalışır. Bunu yalnızca istemciniz yerel işlem denetimini bilinçli olarak sandbox olmadan sunuyorsa kullanın.

process/spawn ile bir işlem başlatıp bir processHandle sağlayın; ardından stdin, yeniden boyutlandırma ve sonlandırma isteklerinde bu tanıtıcıyı kullanın. Çıktı process/outputDelta bildirimleri, tamamlanma ise process/exited üzerinden akış hâlinde iletilir.

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

Girdi göndermek için deltaBase64, closeStdin veya her ikisiyle birlikte process/writeStdin kullanın. PTY yeniden boyutlandırma olayları için process/resizePty, çalışan bir işlemi sonlandırmak için process/kill kullanın.

Komut yürütme

command/exec, iş parçacığı oluşturmadan sunucu sandbox'ı altında tek bir komut (argv dizisi) çalıştırır.

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

Sunucu işlemini zaten sandbox içine alıyorsanız ve Codex'in kendi sandbox uygulamasını atlamasını istiyorsanız sandboxPolicy.type = "externalSandbox" kullanın. Harici sandbox modu için networkAccess değerini restricted (varsayılan) veya enabled olarak ayarlayın. readOnly ve workspaceWrite için yukarıda gösterilen aynı isteğe bağlı access / readOnlyAccess yapısını kullanın.

Notlar:

• Sunucu, boş command dizilerini reddeder.
• sandboxPolicy, turn/start tarafından kullanılan yapının aynısını kabul eder (örneğin dangerFullAccess, readOnly, workspaceWrite, externalSandbox).
• Belirtilmediğinde timeoutMs, sunucu varsayılanına geri döner.
• PTY destekli oturumlar için tty: true değerini ayarlayın; daha sonra command/exec/write, command/exec/resize veya command/exec/terminate kullanmayı planlıyorsanız processId kullanın.
• Komut çalışırken command/exec/outputDelta bildirimleri almak için streamStdoutStderr: true değerini ayarlayın.

Yönetici gereksinimlerini okuma (configRequirements/read)

requirements.toml ve/veya MDM'den yüklenen etkin yönetici gereksinimlerini incelemek için configRequirements/read kullanın.

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

Hiçbir gereksinim yapılandırılmadığında result.requirements, null olur. Desteklenen anahtar ve değerlerle ilgili ayrıntılar için requirements.toml belgelerine bakın.

Windows sandbox kurulumu (windowsSandbox/setupStart)

Özel Windows istemcileri, başlangıç denetimlerini engellemek yerine sandbox kurulumunu eşzamansız olarak tetikleyebilir.

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

App-server kurulumu arka planda başlatır ve daha sonra bir tamamlanma bildirimi yayımlar:

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

Modlar:

• elevated - yükseltilmiş Windows sandbox kurulum yolunu çalıştırır.
• unelevated - eski kurulum/ön kontrol yolunu çalıştırır.

Dosya sistemi

v2 dosya sistemi API'leri mutlak yollar üzerinde çalışır. Bir dosya veya dizin değiştikten sonra istemcinin UI durumunu geçersiz kılması gerektiğinde fs/watch kullanın.

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

Bir dosyanın izlenmesi, değiştirme veya yeniden adlandırma işlemleriyle iletilen güncellemeler dahil olmak üzere o dosya yolu için fs/changed yayımlar.

Olaylar

Olay bildirimleri; iş parçacığı yaşam döngüleri, tur yaşam döngüleri ve bunların içindeki öğeler için sunucu tarafından başlatılan akıştır. Bir iş parçacığını başlattıktan veya sürdürdükten sonra thread/started, thread/archived, thread/unarchived, thread/closed, thread/status/changed, turn/*, item/* ve serverRequest/resolved bildirimleri için etkin aktarım akışını okumayı sürdürün.

Bildirimlerden çıkma

İstemciler, initialize.params.capabilities.optOutNotificationMethods içinde tam yöntem adlarını göndererek bağlantı başına belirli bildirimleri engelleyebilir.

• Yalnızca tam eşleşme: item/agentMessage/delta yalnızca o yöntemi engeller.
• Bilinmeyen yöntem adları yok sayılır.
• Geçerli thread/*, turn/*, item/* ve ilişkili v2 bildirimlerine uygulanır.
• İsteklere, yanıtlara veya hatalara uygulanmaz.

Bulanık dosya arama olayları (deneysel)

Bulanık dosya arama oturumu API'si, sorgu başına bildirimler yayımlar:

• fuzzyFileSearch/sessionUpdated - etkin sorgunun güncel eşleşmelerini içeren { sessionId, query, files }.
• fuzzyFileSearch/sessionCompleted - ilgili sorgu için dizin oluşturma ve eşleştirme tamamlandığında bir kez { sessionId }.

Uyarı olayları

• configWarning - kurtarılabilir yapılandırma veya başlatma sorunları için { summary, details?, path?, range? }.
• warning - kritik olmayan çalışma zamanı uyarıları için { threadId?, message }.

Windows sandbox kurulum olayları

• windowsSandbox/setupCompleted - bir windowsSandbox/setupStart isteği tamamlandıktan sonra yayımlanan { mode, success, error }.

Tur olayları

• turn/started - tur kimliği, boş items ve status: "inProgress" içeren { turn }.
• turn/completed - turn.status değerinin completed, interrupted veya failed olduğu { turn }; başarısızlıklar { error: { message, codexErrorInfo?, additionalDetails? } } taşır.
• turn/diff/updated - turdaki her dosya değişikliğinin en son birleştirilmiş diff'ini içeren { threadId, turnId, diff }.
• turn/plan/updated - ajan planını her paylaştığında veya değiştirdiğinde { turnId, explanation?, plan }; her plan girdisi, status değeri pending, inProgress veya completed olan bir { step, status } öğesidir.
• hook/started ve hook/completed - bir yaşam döngüsü kancası başladığında ve nihai çalıştırma özeti hazır olduğunda { threadId, turnId?, run }.
• model/safetyBuffering/updated - yanıt geçici güvenlik arabelleğine girdiğinde { threadId, turnId, model, useCases, reasons, showBufferingUi, fasterModel }.
• model/rerouted - hizmet bir isteği başka bir modele yönlendirdiğinde { threadId, turnId, fromModel, toModel, reason }.
• model/verification - hizmet ek hesap doğrulaması gerektirdiğinde { threadId, turnId, verifications }.
• thread/tokenUsage/updated - etkin iş parçacığının kullanım güncellemeleri.

turn/diff/updated ve turn/plan/updated, öğe olayları akış hâlinde iletilse bile şu anda boş items dizileri içerir. Tur öğeleri için doğru kaynak olarak item/* bildirimlerini kullanın.

Öğeler

ThreadItem, tur yanıtlarında ve item/* bildirimlerinde taşınan etiketli birleşimdir. Yaygın öğe türleri şunlardır:

• userMessage - content alanının kullanıcı girdileri listesi (text, image veya localImage) olduğu {id, content}.
• agentMessage - birikmiş ajan yanıtını içeren {id, text, phase?}. Mevcut olduğunda phase, Responses API kablo değerlerini (commentary, final_answer) kullanır.
• plan - plan modunda önerilen plan metnini içeren {id, text}. item/completed içindeki son plan öğesini belirleyici kabul edin.
• reasoning - summary alanının akış hâlinde iletilen akıl yürütme özetlerini, content alanının ise ham akıl yürütme bloklarını tuttuğu {id, summary, content}.
• commandExecution - {id, command, cwd, status, commandActions, aggregatedOutput?, exitCode?, durationMs?}.
• fileChange - önerilen düzenlemeleri açıklayan {id, changes, status}; changes, {path, kind, diff} öğelerini listeler.
• mcpToolCall - {id, server, tool, status, arguments, appContext?, pluginId?, result?, error?}. Güvenilir MCP uygulamaları için appContext; connectorId, linkId, resourceUri, appName, templateId ve kararlı bağlayıcı actionName değerlerini içerebilir. Eski kalıcı öğelerde daha yeni meta veriler bulunmayabilir. Kullanımdan kaldırılmış üst düzey mcpAppResourceUri yerine appContext.resourceUri kullanın.
• dynamicToolCall - istemci tarafından yürütülen dinamik araç çağrıları için {id, tool, arguments, status, contentItems?, success?, durationMs?}.
• collabToolCall - {id, tool, status, senderThreadId, receiverThreadId?, newThreadId?, prompt?, agentStatus?}.
• webSearch - ajan tarafından gönderilen web arama istekleri için {id, query, action?}.
• imageView - ajan görüntü görüntüleyici aracını çağırdığında yayımlanan {id, path}.
• enteredReviewMode - inceleyici başladığında gönderilen {id, review}.
• exitedReviewMode - inceleyici tamamlandığında yayımlanan {id, review}.
• contextCompaction - Codex konuşma geçmişini sıkıştırdığında yayımlanan {id}.

webSearch.action için type eylemi; search (query?, queries?), openPage (url?) veya findInPage (url?, pattern?) olabilir.

App server, eski thread/compacted bildirimini kullanımdan kaldırmaktadır; bunun yerine contextCompaction öğesini kullanın.

Tüm öğeler iki ortak yaşam döngüsü olayı yayımlar:

• item/started - yeni bir iş birimi başladığında item öğesinin tamamını yayımlar; item.id, deltalar tarafından kullanılan itemId ile eşleşir.
• item/completed - iş tamamlandığında nihai item öğesini gönderir; bunu belirleyici durum olarak kabul edin.

Öğe deltaları

• item/agentMessage/delta - ajan iletisi için akış hâlinde iletilen metni ekler.
• item/plan/delta - önerilen plan metnini akış hâlinde iletir. Nihai plan öğesi, birleştirilmiş deltalarla tam olarak eşleşmeyebilir.
• item/reasoning/summaryTextDelta - okunabilir akıl yürütme özetlerini akış hâlinde iletir; yeni bir özet bölümü açıldığında summaryIndex artar.
• item/reasoning/summaryPartAdded - akıl yürütme özeti bölümleri arasındaki sınırı işaretler.
• item/reasoning/textDelta - ham akıl yürütme metnini akış hâlinde iletir (model destekliyorsa).
• item/commandExecution/outputDelta - bir komutun stdout/stderr çıktısını akış hâlinde iletir; deltaları sırayla ekleyin.
• item/fileChange/outputDelta - eski apply_patch metin çıktısı için kullanımdan kaldırılmış uyumluluk bildirimi. Güncel app-server sürümleri artık bunu yayımlamaz; fileChange öğelerini ve turn/diff/updated kullanın.

Hatalar

Bir tur başarısız olursa sunucu, { error: { message, codexErrorInfo?, additionalDetails? } } içeren bir error olayı yayımlar ve ardından turu status: "failed" ile tamamlar. Bir üst HTTP durumu mevcut olduğunda codexErrorInfo.httpStatusCode içinde görünür.

Yaygın codexErrorInfo değerleri şunlardır:

• ContextWindowExceeded
• UsageLimitExceeded
• HttpConnectionFailed (4xx/5xx üst hizmet hataları)
• ResponseStreamConnectionFailed
• ResponseStreamDisconnected
• ResponseTooManyFailedAttempts
• BadRequest, Unauthorized, SandboxError, InternalServerError, Other

Bir üst HTTP durumu mevcut olduğunda sunucu, ilgili codexErrorInfo varyantındaki httpStatusCode alanında bunu iletir.

Onaylar

Kullanıcının Codex ayarlarına bağlı olarak komut yürütme ve dosya değişiklikleri onay gerektirebilir. App-server, istemciye sunucu tarafından başlatılan bir JSON-RPC isteği gönderir; istemci de bir karar yüküyle yanıt verir.

• Komut yürütme kararları: accept, acceptForSession, decline, cancel veya { "acceptWithExecpolicyAmendment": { "execpolicy_amendment": ["cmd", "..."] } }.

• Dosya değişikliği kararları: accept, acceptForSession, decline, cancel.

• İstekler threadId ve turnId içerir; UI durumunu etkin konuşmayla sınırlandırmak için bunları kullanın.

• Sunucu işi sürdürür veya reddeder ve öğeyi item/completed ile sonlandırır.

Komut yürütme onayları

İleti sırası:

1. item/started; command, cwd ve diğer alanları içeren beklemedeki commandExecution öğesini gösterir.
2. item/commandExecution/requestApproval; itemId, threadId, turnId, isteğe bağlı reason, isteğe bağlı command, isteğe bağlı cwd, isteğe bağlı commandActions, isteğe bağlı proposedExecpolicyAmendment, isteğe bağlı networkApprovalContext ve isteğe bağlı availableDecisions içerir. initialize.params.capabilities.experimentalApi = true olduğunda yük, komut başına istenen sandbox erişimini açıklayan deneysel additionalPermissions alanını da içerebilir. additionalPermissions içindeki tüm dosya sistemi yolları kabloda mutlaktır.
3. İstemci, yukarıdaki komut yürütme onay kararlarından biriyle yanıt verir.
4. serverRequest/resolved, bekleyen isteğin yanıtlandığını veya temizlendiğini doğrular.
5. item/completed, status: completed | failed | declined içeren nihai commandExecution öğesini döndürür.

networkApprovalContext mevcut olduğunda istem, yönetilen ağ erişimi içindir (genel bir kabuk komutu onayı değildir). Geçerli v2 şeması hedef host ve protocol alanlarını sunar; istemciler ağa özgü bir istem göstermeli ve command alanının kullanıcı açısından anlamlı bir kabuk komutu önizlemesi olmasına güvenmemelidir.

Codex, eşzamanlı ağ onayı istemlerini hedefe göre (host, protokol ve port) gruplandırır. Bu nedenle app-server, aynı hedefe sıraya alınmış birden çok isteğin engelini kaldıran tek bir istem gönderebilir; aynı ana makinedeki farklı portlar ise ayrı değerlendirilir.

Dosya değişikliği onayları

İleti sırası:

1. item/started, önerilen changes ve status: "inProgress" alanlarını içeren bir fileChange öğesi yayımlar.
2. item/fileChange/requestApproval; itemId, threadId, turnId, isteğe bağlı reason ve isteğe bağlı grantRoot içerir.
3. İstemci, yukarıdaki dosya değişikliği onay kararlarından biriyle yanıt verir.
4. serverRequest/resolved, bekleyen isteğin yanıtlandığını veya temizlendiğini doğrular.
5. item/completed, status: completed | failed | declined içeren nihai fileChange öğesini döndürür.

tool/requestUserInput

İstemci item/tool/requestUserInput isteğine yanıt verdiğinde app-server, { threadId, requestId } içeren serverRequest/resolved yayımlar. Bekleyen istek, istemci yanıt vermeden önce tur başlangıcı, tur tamamlanması veya tur kesintisi nedeniyle temizlenirse sunucu bu temizleme için aynı bildirimi yayımlar.

İstek parametreleri, tamsayı milisaniye zaman aşımı olarak autoResolutionMs veya null içerir. Mevcut olduğunda ana makine istemcileri, kullanıcı yanıt vermezse bu süre sonunda istemi otomatik olarak çözümleyebilir.

İzin istekleri

Yerleşik request_permissions aracı; threadId, turnId, itemId, environmentId, cwd, isteğe bağlı reason ve istenen ağ veya dosya sistemi izinleriyle item/permissions/requestApproval gönderir. Yalnızca verilen alt kümeyi içeren permissions ile yanıt verin. İzni aynı oturumdaki sonraki turlar için kalıcı kılmak üzere scope değerini "session" olarak ayarlayın; turla sınırlı izin için bunu belirtmeyin veya "turn" kullanın. İstenmemiş izinler yok sayılır.

MCP sunucusu bilgi isteme istekleri

Bir MCP sunucusu, mcpServer/elicitation/request ile bir turu kesintiye uğratabilir. İstek; threadId, isteğe bağlı turnId, serverName ve şu istek yapılarından birini içerir:

• mode: "form" veya mode: "openai/form"; message ve requestedSchema ile birlikte.
• mode: "url"; message, url ve elicitationId ile birlikte.

action: "accept" ve istenen content ile ya da action: "decline" veya "cancel" ile birlikte content: null kullanarak yanıt verin. Ardından app-server serverRequest/resolved yayımlar. openai/form varyantını almak için initialize.params.capabilities.mcpServerOpenaiFormElicitation ile katılın.

Dinamik araç çağrıları (deneysel)

thread/start üzerindeki dynamicTools ve buna karşılık gelen item/tool/call istek veya yanıt akışı deneysel API'lerdir.

Dinamik araç adları ve ad alanı adları, Responses API adlandırma kısıtlamalarına uymalıdır. Yerleşik Codex araçlarının kullandığı ayrılmış ad alanı adlarından kaçının.

Bir tur sırasında dinamik bir araç çağrıldığında app-server şunları yayımlar:

1. item.type = "dynamicToolCall", status = "inProgress", ayrıca tool ve arguments içeren item/started.
2. İstemciye sunucu isteği olarak item/tool/call.
3. Döndürülen içerik öğelerini içeren istemci yanıt yükü.
4. item.type = "dynamicToolCall", nihai status ve döndürülen tüm contentItems veya success değerlerini içeren item/completed.

MCP araç çağrısı onayları (uygulamalar)

Uygulama (bağlayıcı) araç çağrıları da onay gerektirebilir. Bir uygulama araç çağrısının yan etkileri olduğunda sunucu, tool/requestUserInput ile ve Kabul Et, Reddet ve İptal gibi seçeneklerle onay isteyebilir. Yıkıcı araç ek açıklamaları, araç daha az ayrıcalıklı ipuçları da duyursa bile her zaman onayı tetikler. Kullanıcı reddeder veya iptal ederse ilgili mcpToolCall öğesi, aracı çalıştırmak yerine bir hatayla tamamlanır.

Skills

Kullanıcı metni girdisine $<skill-name> ekleyerek bir skill çağırın. Sunucunun adı çözümlemesi için modele güvenmek yerine skill talimatlarının tamamını eklemesi amacıyla bir skill girdi öğesi ekleyin (önerilir).

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

skill öğesini atlarsanız model yine de $<skill-name> işaretçisini ayrıştırıp skill'i bulmaya çalışır; bu da gecikmeyi artırabilir.

Örnek:

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

Kullanılabilir skill'leri getirmek için skills/list kullanın (isteğe bağlı olarak cwds ve forceReload ile sınırlandırılabilir). Ayrıca belirli cwd değerleri için ek mutlak yolları user kapsamı olarak taramak üzere perCwdExtraUserRoots ekleyebilirsiniz. App-server, cwd değeri cwds içinde bulunmayan girdileri yok sayar. skills/list, cwd başına önbelleğe alınmış bir sonucu yeniden kullanabilir; diskten yenilemek için forceReload: true değerini ayarlayın. Mevcut olduğunda sunucu, SKILL.json içinden interface ve dependencies değerlerini okur.

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

Sunucu ayrıca izlenen yerel skill dosyaları değiştiğinde skills/changed bildirimleri yayımlar. Bunu bir geçersiz kılma sinyali olarak değerlendirin ve gerektiğinde geçerli parametrelerinizle skills/list işlemini yeniden çalıştırın.

Bir skill'i yoluyla etkinleştirmek veya devre dışı bırakmak için:

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

Uygulamalar (bağlayıcılar)

En son commit edilmiş, kurulu uygulama çalışma zamanı anlık görüntüsünü okumak için app/installed kullanın. Her sonuç; uygulamanın id, runtimeName (veya null), etkin enabled durumu ve callable durumunu içerir. Bir uygulama yalnızca etkin yapılandırma onu etkinleştiriyorsa ve modelin görebildiği en az bir araç uygulama ve araç politikalarına uyuyorsa çağrılabilir.

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

Yüklenmiş bir iş parçacığının yapılandırması yerine genel yapılandırmayı kullanmak için threadId değerini belirtmeyin. Bağlayıcı çalışma zamanı anlık görüntüsünü okumadan önce yenilemek için forceRefresh: true değerini ayarlayın. Genel politika veya çalışma alanı politikası uygulama erişimini engellediğinde, gözlemlenen bir uygulama yine de enabled ve callable değerleri false olarak görünebilir.

Kullanılabilir uygulamaları getirmek için app/list kullanın. CLI/TUI içinde /apps kullanıcıya gösterilen seçicidir; özel istemcilerde doğrudan app/list çağırın. İstemcilerin kurulum/erişim ile yerel etkinlik durumunu ayırt edebilmesi için her girdi hem isAccessible (kullanıcının erişebildiği) hem de isEnabled (config.toml içinde etkin) alanını içerir. Uygulama girdileri isteğe bağlı branding, appMetadata ve labels alanlarını da içerebilir.

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

threadId sağlarsanız uygulama özellik geçidi (features.apps), o iş parçacığının yapılandırma anlık görüntüsünü kullanır. Belirtilmezse app-server en son genel yapılandırmayı kullanır.

app/list, hem erişilebilir uygulamalar hem de dizin uygulamaları yüklendikten sonra döner. Uygulama önbelleklerini atlayıp güncel verileri getirmek için forceRefetch: true değerini ayarlayın. Önbellek girdileri yalnızca yenilemeler başarılı olduğunda değiştirilir.

Sunucu ayrıca kaynaklardan biri (erişilebilir uygulamalar veya dizin uygulamaları) yüklenmeyi tamamladığında app/list/updated bildirimleri yayımlar. Her bildirim en son birleştirilmiş uygulama listesini içerir.

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

Uygulama kimliklerini zaten biliyor ve kurulu çalışma zamanı durumu yerine uygulama meta verilerine ihtiyaç duyuyorsanız app/read kullanın. En fazla 100 appIds iletin. Sunucu, yinelenen her kimliğin yalnızca ilk örneğini tutar ve bu sırayı hem apps hem de missingAppIds içinde korur. Bilinmeyen veya erişilemeyen uygulamalar, tüm isteğin başarısız olmasına neden olmadan missingAppIds içinde döndürülür.

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

Yalnızca görüntüleme amaçlı herkese açık araç özetleri istemek için includeTools: true değerini ayarlayın. Meta veri yanıtı, kurulu uygulama çalışma zamanı durumunu içermez veya bir araç çağrısını yetkilendirmez; etkin enabled ve callable durumunu denetlemek için app/installed kullanın.

Metin girdisine $<app-slug> ekleyip app://<id> yoluyla bir mention girdi öğesi sağlayarak bir uygulamayı çağırın (önerilir).

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

Uygulama ayarları için Config RPC örnekleri

config.toml içindeki uygulama denetimlerini incelemek veya güncellemek için config/read, config/value/write ve config/batchWrite kullanın.

Etkin uygulama yapılandırması yapısını (_default ve araç başına geçersiz kılmalar dahil) okuyun:

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

Uygulama başına bir değer bunu geçersiz kılmadığı sürece apps._default.approvals_reviewer, tüm uygulamaların inceleyicisini ayarlar. Her ikisi de belirtilmezse uygulama, üst düzey approvals_reviewer değerini devralır. apps._default.default_tools_approval_mode, uygulama veya araç bazında geçersiz kılması olmayan araçlar için yedek onay modunu ayarlar. Yönetilen onay modu gereksinimleri, araç onay modu ayarlarını geçersiz kılar.

Tek bir uygulama ayarını güncelleyin:

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

Birden çok uygulama düzenlemesini atomik olarak uygulayın:

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

Harici ajan yapılandırmasını algılama ve içe aktarma

Taşınabilecek harici ajan yapıtlarını keşfetmek için externalAgentConfig/detect kullanın, ardından seçilen girdileri externalAgentConfig/import öğesine iletin.

Algılama örneği:

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

İçe aktarma örneği:

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

İsteğe bağlı üst düzey source içe aktarma parametresi, seçilen geçiş öğelerini üreten ürünü etiketler.

Sunucu, öğe türleri tamamlandıkça externalAgentConfig/import/progress; tüm eşzamanlı ve arka plan içe aktarmaları tamamlandıktan sonra externalAgentConfig/import/completed yayımlar. Bu bildirimler, yanıttaki aynı importId değerini ve tür başına successes ile failures içeren itemTypeResults alanını kapsar. Tamamlanma, yanıtın hemen ardından veya arka plandaki uzak içe aktarmalar tamamlandıktan sonra gelebilir.

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

Önceden tamamlanmış içe aktarmaları okuyun:

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

Desteklenen itemType değerleri AGENTS_MD, CONFIG, SKILLS, PLUGINS, MCP_SERVER_CONFIG, SUBAGENTS, HOOKS, COMMANDS ve SESSIONS değerleridir. PLUGINS öğeleri için details.plugins, her marketplaceName değerini ve Codex'in taşımayı deneyebileceği pluginNames değerini listeler. Algılama yalnızca hâlâ yapılacak işi olan öğeleri döndürür. Örneğin AGENTS.md zaten mevcut ve boş değilse Codex, AGENTS geçişini atlar; skill içe aktarmaları da mevcut skill dizinlerinin üzerine yazmaz.

.claude/settings.json içinden eklentileri algılarken Codex, yapılandırılmış pazar kaynaklarını extraKnownMarketplaces içinden okur. enabledPlugins, claude-plugins-official kaynaklı eklentiler içeriyor ancak pazar kaynağı eksikse Codex, kaynak olarak anthropics/claude-plugins-official değerini çıkarır.

Kimlik doğrulama uç noktaları

JSON-RPC kimlik doğrulama/hesap yüzeyi, istek/yanıt yöntemlerinin yanı sıra sunucu tarafından başlatılan bildirimleri de sunar (id yoktur). Kimlik doğrulama durumunu belirlemek, oturum açmaları başlatmak veya iptal etmek, oturumu kapatmak, ChatGPT hız sınırlarını incelemek ve tükenen krediler ya da kullanım sınırları hakkında çalışma alanı sahiplerini bilgilendirmek için bunları kullanın.

Kimlik doğrulama modları

Codex şu kimlik doğrulama modlarını destekler. account/updated.authMode etkin modu gösterir ve mevcut olduğunda geçerli ChatGPT planType değerini içerir. account/read ayrıca hesap ve plan ayrıntılarını bildirir.

• API key (apikey) - çağıran taraf type: "apiKey" ile bir OpenAI API key sağlar ve Codex bunu API istekleri için saklar.
• ChatGPT tarafından yönetilen (chatgpt) - Codex, ChatGPT OAuth akışını yönetir, token'ları kalıcı olarak saklar ve otomatik yeniler. Tarayıcı akışı için type: "chatgpt", cihaz kodu akışı için type: "chatgptDeviceCode" ile başlayın.
• ChatGPT harici token'ları (chatgptAuthTokens) - deneyseldir ve kullanıcının ChatGPT kimlik doğrulama yaşam döngüsünü zaten yöneten ana makine uygulamalarına yöneliktir. Ana makine uygulaması doğrudan bir accessToken, chatgptAccountId ve isteğe bağlı chatgptPlanType sağlar; istendiğinde token'ı yenilemesi gerekir.
• Amazon Bedrock - account/read, Bedrock hesaplarını type: "amazonBedrock" olarak bildirir ve kimlik bilgilerinin Codex tarafından yönetilen bir Bedrock API key'den (credentialSource: "codexManaged") mi yoksa harici AWS kimlik bilgisi zincirinden (credentialSource: "awsManaged") mi geldiğini belirtir. account/updated.authMode, Codex tarafından yönetilen Bedrock API key'leri için bedrockApiKey kullanır.

API'ye genel bakış

• account/read - geçerli hesap bilgilerini getirir; isteğe bağlı olarak token'ları yeniler.
• account/login/start - oturum açmayı başlatır (apiKey, chatgpt, chatgptDeviceCode veya deneysel chatgptAuthTokens).
• account/login/completed (bildirim) - bir oturum açma denemesi tamamlandığında (başarıyla veya hatayla) yayımlanır.
• account/login/cancel - bekleyen ve yönetilen bir ChatGPT oturum açma işlemini loginId ile iptal eder.
• account/logout - oturumu kapatır; account/updated tetikler.
• account/updated (bildirim) - kimlik doğrulama modu her değiştiğinde yayımlanır (authMode: apikey, chatgpt, chatgptAuthTokens, agentIdentity, personalAccessToken, bedrockApiKey veya null) ve mevcut olduğunda planType içerir.
• account/chatgptAuthTokens/refresh (sunucu isteği) - bir yetkilendirme hatasından sonra haricen yönetilen güncel ChatGPT token'ları ister.
• account/rateLimits/read - ChatGPT hız sınırlarını getirir.
• account/rateLimits/updated (bildirim) - kullanıcının ChatGPT hız sınırları her değiştiğinde yayımlanır.
• account/sendAddCreditsNudgeEmail - ChatGPT'den, tükenen krediler veya ulaşılan kullanım sınırı hakkında çalışma alanı sahibine e-posta göndermesini ister.
• account/rateLimitResetCredit/consume - çağıran tarafından sağlanan bir idempotencyKey değeriyle kazanılmış bir hız sınırı sıfırlamasını kullanır.
• account/usage/read - ChatGPT hesabının token etkinliği özetlerini ve günlük dilimlerini getirir.
• account/workspaceMessages/read - mevcut olduğunda bildirim başlıkları dahil etkin çalışma alanı iletilerini getirir.
• mcpServer/oauthLogin/completed (bildirim) - bir mcpServer/oauth/login akışı tamamlandıktan sonra yayımlanır; yük { name, threadId, success, error? } içerir. threadId, uygulama kapsamlı veya eklenti OAuth akışları için null olabilir.
• mcpServer/startupStatus/updated (bildirim) - yapılandırılmış bir MCP sunucusunun başlangıç durumu değiştiğinde yayımlanır; yük { threadId, name, status, error, failureReason } içerir. Uygulama kapsamlı başlangıç için threadId, null olur. Başlangıç başarısız olduğunda failureReason: "reauthenticationRequired", saklanan OAuth kimlik bilgilerinin süresinin dolduğu ve yenilenemediği anlamına gelir; bu nedenle istemci sunucuyu yeniden bağlamayı önermelidir.

1) Kimlik doğrulama durumunu denetleme

İstek:

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

Yanıt örnekleri:

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

Alan notları:

• refreshToken (boolean): yönetilen ChatGPT modunda token yenilemeyi zorlamak için true olarak ayarlayın. Harici token modunda (chatgptAuthTokens) app-server bu bayrağı yok sayar.
• ChatGPT hesabının e-posta adresi olmadığında email, null olur.
• requiresOpenaiAuth etkin sağlayıcıyı yansıtır; false olduğunda Codex, OpenAI kimlik bilgileri olmadan çalışabilir.
• Amazon Bedrock, Codex tarafından yönetilen bir Bedrock API key kullandığında credentialSource: "codexManaged" bildirir. Harici AWS kimlik bilgisi yolu için credentialSource: "awsManaged" bildirir. Bu, seçilen kimlik bilgisi kaynağını tanımlar; AWS kimlik bilgisi zincirinin kimlik bilgilerini çözümleyebildiğini doğrulamaz.

2) API key ile oturum açma

1. Gönderin:

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

2. Beklenen:

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

3. Bildirimler:

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

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

3) ChatGPT ile oturum açma (tarayıcı akışı)

1. Başlatın:

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

Varsayılan olarak başarılı bir tarayıcı geri çağrısı, yerel bir başarı sayfasına yönlendirir. Kuruluş kurulumu gerekmediğinde barındırılan başarı sayfasını kullanmak için useHostedLoginSuccessPage: true değerini ayarlayın. Barındırılan başarı etkinleştirildiğinde appBrand, "codex" veya "chatgpt" olabilir; belirtilmeyen veya null değerleri varsayılan olarak "codex" olur.

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

2. authUrl adresini bir tarayıcıda açın; app-server yerel geri çağrıyı barındırır.
3. Bildirimleri bekleyin:

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

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

3b) ChatGPT ile oturum açma (cihaz kodu akışı)

İstemciniz oturum açma sürecini yönetiyorsa veya tarayıcı geri çağrısı kırılgansa bu akışı kullanın.

1. Başlatın:

   {
     "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. Kullanıcıya verificationUrl ve userCode gösterin; UX'i frontend yönetir.
3. Bildirimleri bekleyin:

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

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

3c) Haricen yönetilen ChatGPT token'larıyla oturum açma (chatgptAuthTokens)

Bu deneysel modu yalnızca bir ana makine uygulaması kullanıcının ChatGPT kimlik doğrulama yaşam döngüsünü yönetiyor ve token'ları doğrudan sağlıyorsa kullanın. İstemciler bu oturum açma türünü kullanmadan önce initialize sırasında capabilities.experimentalApi = true değerini ayarlamalıdır.

1. Gönderin:

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

2. Beklenen:

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

3. Bildirimler:

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

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

Sunucu bir 401 Unauthorized aldığında ana makine uygulamasından yenilenmiş token'lar isteyebilir:

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

Sunucu, başarılı bir yenileme yanıtından sonra özgün isteği yeniden dener. İstekler yaklaşık 10 saniye sonra zaman aşımına uğrar.

4) ChatGPT oturum açma işlemini iptal etme

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

5) Oturumu kapatma

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

6) Hız sınırları (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 }
  }
} }

Alan notları:

• rateLimits, geriye dönük uyumlu tek dilim görünümüdür.
• rateLimitsByLimitId (mevcut olduğunda), ölçümlenen limit_id anahtarına göre düzenlenen çok dilimli görünümdür (örneğin codex).
• limitId, ölçümlenen dilim tanımlayıcısıdır.
• limitName, dilim için isteğe bağlı ve kullanıcıya gösterilen etikettir.
• usedPercent, kota penceresindeki geçerli kullanımdır.
• windowDurationMins, kota penceresinin uzunluğudur.
• resetsAt, bir sonraki sıfırlamanın Unix zaman damgasıdır (saniye).
• Sunucu bir dilimle ilişkili ChatGPT planını döndürdüğünde planType dahil edilir.
• Sunucu kalan çalışma alanı kredisi ayrıntılarını döndürdüğünde credits dahil edilir.
• rateLimitReachedType, bir sınıra ulaşıldığında sunucu tarafından sınıflandırılan sınır durumunu tanımlar.
• Hizmet sağlıyorsa rateLimitResetCredits, kullanılabilir kazanılmış sıfırlama sayısını içerir; aksi hâlde null olur.
• Yalnızca sayı biliniyorsa rateLimitResetCredits.credits, null olur. Boş dizi, hizmetin ayrıntıları getirdiği ve kullanılabilir kredi döndürmediği anlamına gelir. Hizmet ayrıntı satırlarının sayısını sınırlayabileceğinden availableCount belirleyicidir.
• Her ayrıntı satırı; opak bir id, resetType, status, grantedAt, expiresAt (null olabilir), title (null olabilir) ve description (null olabilir) içerir.
• Bir sıfırlamayı kullandıktan sonra account/rateLimits/read getirin.

7) Token kullanımı (ChatGPT)

ChatGPT token etkinliği özet alanlarını ve isteğe bağlı günlük dilimleri getirmek için account/usage/read kullanın.

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

Alan notları:

• Hizmet ilgili metriği henüz döndürmediyse summary değerleri null olabilir.
• dailyUsageBuckets, null olabilir; mevcut olduğunda her dilim startDate ve tokens içerir.
• Uç nokta, Codex hizmetleri tarafından desteklenen kimlik doğrulaması gerektirir. ChatGPT, harici ChatGPT token'ları, ajan kimliği ve kişisel erişim token'ı kimlik doğrulaması çalışır; yalnızca API key ve Bedrock kimlik doğrulaması çalışmaz.

8) Kazanılmış hız sınırı sıfırlamaları (ChatGPT)

Kazanılmış bir sıfırlamayı kullanmak için account/rateLimitResetCredit/consume kullanın.

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

Alan notları:

• idempotencyKey boş olmamalıdır. Her mantıksal kullanma denemesi için bir UUID kullanın ve bu denemeyi yeniden denerken aynı değeri tekrar kullanın.
• creditId isteğe bağlıdır. Sağlandığında, account/rateLimits/read içinden alınmış boş olmayan opak bir kimlik olmalıdır. Belirtilmediğinde hizmet bir sonraki kullanılabilir krediyi seçer.
• reset, bir kredinin kullanıldığı anlamına gelir.
• alreadyRedeemed, aynı kullanma işleminin daha önce tamamlandığı anlamına gelir. Bunu idempotent başarı olarak değerlendirin ve hesap sınırlarını yenileyin.
• nothingToReset, sıfırlanabilecek uygun bir hız sınırı penceresi olmadığı anlamına gelir.
• noCredit, hesapta kullanılabilir kazanılmış sıfırlama kredisi olmadığı anlamına gelir.
• Güncellenmiş pencereleri bu yanıttan çıkarmak yerine bir sıfırlamayı kullandıktan sonra account/rateLimits/read getirin.

9) Bir sınır hakkında çalışma alanı sahibini bilgilendirme

Krediler tükendiğinde veya kullanım sınırına ulaşıldığında ChatGPT'den çalışma alanı sahibine e-posta göndermesini istemek için account/sendAddCreditsNudgeEmail kullanın.

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

Çalışma alanı kredileri tükendiğinde creditType: "credits", çalışma alanı kullanım sınırına ulaşıldığında creditType: "usage_limit" kullanın. Sahip yakın zamanda zaten bilgilendirildiyse yanıt durumu cooldown_active olur.

10) Çalışma alanı iletileri (ChatGPT)

Mevcut olduğunda bildirim başlıkları dahil olmak üzere geçerli çalışma alanının etkin iletilerini getirmek için account/workspaceMessages/read kullanın.

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