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üne başka bir makineden bağlanmanızı sağlar. 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 yerleştirin. Taşıyıcı belirteci 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 bağlantılar 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 sürecindeki 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:// değerini 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 mesajlarıyla çift yönlü iletişimi destekler (kablo üzerinde "jsonrpc":"2.0" üst bilgisi kullanılmaz).

Desteklenen aktarımlar:

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

--listen ws://IP:PORT ile çalıştırdığınızda aynı dinleyici, temel HTTP sistem durumu 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 verdiğinden 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, WebSocket el sıkışması sırasında kimlik bilgisini Authorization: Bearer <token> olarak sunar ve app-server, JSON-RPC initialize öncesinde kimlik doğrulamasını uygular.

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

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." mesajıyla reddeder. İstemciler, katlanarak artan bir gecikme ve rastgele sapmayla yeniden denemelidir.

Mesaj şeması

İstekler method, params ve id alanlarını içerir:

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

Yanıtlar id değerini result veya error ile yineler:

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

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

Bildirimler id alanını içermez ve yalnızca method ile params kullanır:

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

CLI'dan bir TypeScript şeması veya JSON Schema paketi oluşturabilirsiniz. Her çıktı, çalıştırdığınız Codex sürümüne özgüdür; dolayısıyla 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 tur başlatın, ardından etkin aktarım akışındaki bildirimleri okumayı sürdürün.

Ö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ığı: Kullanıcı ile Codex ajanı arasındaki konuşma. İş parçacıkları turları içerir.
• Tur: Tek bir kullanıcı isteği ve bunu izleyen ajan çalışması. Turlar öğeleri içerir ve artımlı güncellemeleri akış hâlinde iletir.
• Öğe: Bir girdi veya çıktı birimi (kullanıcı mesajı, ajan mesajı, 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ı tur API'leriyle yönetin ve ilerlemeyi tur bildirimleriyle akış hâlinde alın.

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

• Her bağlantı için 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ışmasından önce o bağlantıda gönderilen 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ı yapın.
• Bir tur başlatın: Hedef threadId ve kullanıcı girdisiyle turn/start çağrısı yapın. İsteğe bağlı alanlar modeli, kişiliği, cwd değerini, korumalı alan ilkesini ve daha fazlasını geçersiz kılar.
• Etkin bir turu yönlendirin: Yeni bir tur oluşturmadan, o anda devam eden tura kullanıcı girdisi eklemek için turn/steer çağrısı yapın.
• Olayları akış hâlinde alın: turn/start sonrasında stdout üzerindeki bildirimleri okumayı sürdürün: thread/archived, thread/unarchived, item/started, item/completed, item/agentMessage/delta, araç ilerlemesi ve diğer güncellemeler.
• Turu tamamlayın: Model tamamlandığında veya bir turn/interrupt iptalinden sonra sunucu, nihai durumla birlikte turn/completed yayınlar.

Başlatma

İstemciler, bir aktarım bağlantısında başka bir yöntemi çağırmadan önce bağlantı başına tek bir initialize isteği göndermeli, ardından bir initialized bildirimiyle bunu 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 ayarlayın.

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

• optOutNotificationMethods - bu bağlantı için bastırılacak bildirim yöntemlerinin tam adları. Eşleştirme tamdır (joker karakter veya ön ek yoktur); bilinmeyen adlar kabul edilir ve yok sayılır.
• requestAttestation - sunucunun başlattığı attestation/generate isteğine katılımı etkinleştirir. Üst hizmet tasdiki 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 değişkenini göndermesine izin verir.

Önemli: İstemcinizi OpenAI Compliance Logs Platform için 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'ye katılım

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 katılmadan deneysel bir yöntem veya alan gönderirse app-server bunu şu hatayla reddeder:

<descriptor> requires experimentalApi capability

API'ye genel bakış

• thread/start - yeni bir iş parçacığı oluşturur; thread/started yayınlar ve sizi o iş parçacığının tur/öğe olaylarına otomatik olarak abone eder.
• thread/resume - mevcut bir iş parçacığını kimliğiyle yeniden açar; böylece sonraki turn/start çağrıları ona 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 tur dâhil o tura kadar kopyalayıp sonraki turları 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ğiyle okur; tam tur geçmişini döndürmek için includeTurns ayarlayın. Döndürülen thread nesneleri çalışma zamanı status değerini içerir.
• thread/list - depolanan iş parçacığı günlüklerinde sayfalar hâlinde gezinir; imleç tabanlı sayfalamanın yanı sıra modelProviders, sourceKinds, archived, isPinned, cwd, useStateDbOnly, searchTerm ve deneysel parentThreadId veya ancestorThreadId filtrelerini destekler. Döndürülen thread nesneleri çalışma zamanı status değerini içerir.
• thread/turns/list - deneyseldir; depolanan bir iş parçacığının tur geçmişinde, onu sürdürmeden sayfalar hâlinde gezinir. itemsView, tur öğelerinin atlanmasını, özetlenmesini veya tamamen yüklenmesini denetler.
• thread/items/list - deneyseldir; kalıcı iş parçacığı öğelerinde, isteğe bağlı olarak tek bir turnId ile sınırlandırılmış biçimde sayfalar hâlinde gezinir. Etkin iş parçacığı deposu öğe sayfalamasını desteklemelidir.
• thread/loaded/list - şu anda belleğe yüklenmiş iş parçacığı kimliklerini listeler.
• thread/name/set - yüklenmiş bir iş parçacığının veya kalıcı bir rollout'un kullanıcıya yönelik 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 geçerli hedefini okur.
• thread/goal/clear - hedefi 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şiv dizinine taşır ve henüz 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ığının tur/öğe olayları aboneliğini kaldırır. Bu son aboneyse sunucu, abonesiz geçen hareketsizlik ek süresinden sonra iş parçacığını bellekten kaldırır ve thread/closed yayınlar.
• thread/unarchive - arşivlenmiş bir iş parçacığı rollout'unu 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üklenmiş 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ığı için konuşma geçmişi sıkıştırmasını tetikler; ilerleme turn/* ve item/* bildirimleriyle akış hâlinde iletilirken hemen {} döndürür.
• thread/shellCommand - bir iş parçacığına karşı kullanıcı tarafından başlatılan bir kabuk komutu çalıştırır. Bu, korumalı alanın dışında tam erişimle çalışır ve iş parçacığının korumalı alan ilkesini devralmaz.
• thread/backgroundTerminals/clean - bir iş parçacığının çalışan tüm arka plan terminallerini durdurur (deneysel; capabilities.experimentalApi gerektirir).
• thread/backgroundTerminals/list - yüklenmiş bir iş parçacığının çalışan arka plan terminallerini listeler (deneysel; capabilities.experimentalApi gerektirir).
• thread/backgroundTerminals/terminate - app-server processId değerine göre çalışan bir arka plan terminalini sonlandırır (deneysel; capabilities.experimentalApi gerektirir).
• thread/rollback - kullanım dışıdır; son N turu bellek içi bağlamdan çıkarır ve kalıcı bir geri alma işaretçisi kaydeder; güncellenmiş thread değerini döndürür.
• turn/start - bir iş parçacığına kullanıcı girdisi veya bağımsız araç çıktısı 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 - bir kullanıcı turu başlatmadan, ham Responses API öğelerini yüklenmiş 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 turuna kullanıcı girdisi ekler; kabul edilen turnId değerini döndürür.
• turn/interrupt - devam eden bir turun iptalini ister; başarı {} değeridir ve tur 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ığı/tur başlatmadan sunucu korumalı alanında tek bir komut çalıştırır.
• command/exec/write - çalışan bir command/exec oturumuna stdin baytlarını yazar veya stdin öğesini 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ış hâlindeki bir command/exec oturumundan base64 kodlu stdout/stderr parçaları için yayınlanır.
• process/spawn - Codex'in korumalı alanı dışında açık bir süreç oturumu başlatır (deneysel; capabilities.experimentalApi gerektirir).
• process/writeStdin - çalışan bir process/spawn oturumuna stdin baytları yazar veya stdin'i kapatır (deneysel).
• process/resizePty - PTY destekli, çalışan bir süreç oturumunu yeniden boyutlandırır (deneysel).
• process/kill - çalışan bir süreç oturumunu sonlandırır (deneysel).
• process/outputDelta ve process/exited (bildirim) - süreç çıktısının akışı ve süreç çıkış durumu için yayınlanır (deneysel).
• model/list - kullanılabilir modelleri; çaba seçenekleri, isteğe bağlı upgrade ve inputModalities ile listeler (hidden: true içeren girdileri dâhil etmek için includeHidden: true ayarlayın).
• modelProvider/capabilities/read - model/sağlayıcı birleşimleri için sağlayıcı yetenek sınırlarını okur.
• experimentalFeature/list - yaşam döngüsü aşaması meta verileri ve imleç sayfalamasıyla özellik bayraklarını 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 - deneyseldir; yapılandırılmış bir yürütme ortamına bağlanır ve kabuğunu, varsayılan çalışma diziniyle birlikte döndürür.
• permissionProfile/list - beta izin profillerini ve etkin gereksinimlerin bunlara izin verip vermediğini imleç sayfalamasıyla 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 süreç 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şfedilmiş 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 kalıcı olarak kaydeder.
• marketplace/remove - yapılandırılmış bir pazar yerini ve varsa 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 tüm yapılandırılmış Git pazar yerlerini yeniler.
• plugin/list - geliştirme aşamasındadır; kurulum/kimlik doğrulama ilkesi meta verileri, pazar yeri yükleme hataları, öne çıkan eklenti kimlikleri ve yerel, Git, paket kayıt sistemi ya da uzak eklenti kaynağı meta verileri dâhil olmak üzere keşfedilen eklenti pazar yerlerini ve eklenti durumunu listeler. Özetler uzak version, yerel localVersion, yapılandırılmış açık/koyu simgeler ve geçerli uzak satırlar için null, WORKSPACE_SETTING veya 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ındadır; 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 bir 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ındadır; bir pazar yeri yolundan veya uzak pazar yeri adından eklenti kurar. Bu yöntemi henüz üretim istemcilerinden çağırmayın.
• plugin/uninstall - geliştirme aşamasındadır; 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 becerisinin Markdown içeriğini isteğe bağlı olarak okur.
• app/installed - her uygulamanın etkin olarak etkinleştirilmiş ve çağrılabilir durumları dâhil olmak üzere kurulu uygulamanın ç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üleme amaçlı 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üklenmiş iş parçacıkları için yenileme işlemini 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 veri 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üklenmiş 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 döner ve daha sonra windowsSandbox/setupCompleted yayınlar.
• feedback/upload - bir 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 katmanlarını çözümledikten sonra diskteki etkin 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 (ana dizin için null) içerir.
• externalAgentConfig/import - açık migrationItems değerlerini cwd (ana dizin için null) ile ileterek seçilen harici ajan taşıma öğelerini uygular. Desteklenen öğe türleri arasında yapılandırma, beceriler, AGENTS.md, eklentiler, MCP sunucu yapılandırması, alt ajanlar, kancalar, komutlar ve oturumlar bulunur; boş olmayan içe aktarımlar çalışma tamamlanırken externalAgentConfig/import/progress ve externalAgentConfig/import/completed yayınlar. Eklenti ve oturum içe aktarımları zaman uyumsuz tamamlanabilir.
• config/value/write - tek bir yapılandırma anahtarını/değerini kullanıcının disk üzerindeki config.toml dosyasına yazar.
• config/batchWrite - yapılandırma düzenlemelerini kullanıcının disk üzerindeki config.toml dosyasına atomik olarak uygular.
• configRequirements/read - requirements.toml ve/veya MDM'den tam yönetilen yapılandırma, izin verilenler listeleri, sabitlenmiş featureRequirements ve ağ gereksinimleri (ya da herhangi birini ayarlamadıysanız null) dâhil gereksinimleri getirir.
• 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ı üzerinde 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 sistemi 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ı 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 çaba seçenekleri.
• defaultReasoningEffort - istemciler için önerilen varsayılan çaba.
• 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 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 dışı bayraklarda displayName, description ve announcement, null olabilir.

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

Orada çalışmaya başlamadan önce yapılandırılmış bir uzak ortamı incelemek için environment/info kullanın. 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 bu, ortamın yerel yol söz dizimini kullanan standart 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ığını ona abone olmadan okur; turları dâhil etmek için includeTurns ayarlayın.
• thread/turns/list deneyseldir ve depolanan bir iş parçacığının tur geçmişinde onu sürdürmeden sayfalar hâlinde gezinir. Tur öğelerinin atlanmasını, özetlenmesini veya tamamen yüklenmesini seçmek için itemsView kullanın.
• thread/items/list deneyseldir ve isteğe bağlı olarak tek bir turla sınırlandırılmış kalıcı iş parçacığı öğelerinde sayfalar hâlinde gezinir.
• thread/list; imleç sayfalamasının yanı sıra modelProviders, sourceKinds, archived, isPinned, cwd, useStateDbOnly, searchTerm ve deneysel parentThreadId veya 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şiv dizinine taşır ve henüz arşivlenmemiş, oluşturulmuş alt iş parçacığı günlüklerini 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, depolanmış iş parçacığı meta verilerine yama uygular.
• thread/unsubscribe, geçerli bağlantının yüklenmiş bir iş parçacığı aboneliğini kaldırır ve bir hareketsizlik ek süresinden sonra thread/closed tetikleyebilir.
• thread/unarchive, arşivlenmiş bir iş parçacığı rollout'unu etkin oturumlar dizinine geri yükler.
• thread/compact/start, sıkıştırmayı tetikler ve hemen {} döndürür.
• thread/rollback kullanım dışıdır. Son N turu bellek içi bağlamdan çıkarır ve iş parçacığının kalıcı JSONL günlüğüne bir geri alma işaretçisi kaydeder.
• thread/inject_items, bir kullanıcı turu başlatmadan ham Responses API öğelerini yüklenmiş 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 ihtiyacınız olduğunda 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üklenmiş 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. Sayfalanmış iş parçacığı oluşturma henüz desteklenmez ve JSON-RPC hatası -32601 döndürür. app-server mevcut sayfalanmış kayıtların özetlerini listeleyip okuyabilir ancak sayfalanmış geçmiş desteklenene kadar tam geçmiş okumaları, tur sayfalaması ve sürdürme işlemleri güvenli biçimde başarısız olur.

capabilities.experimentalApi yeteneğine katılan beta istemcileri, eski sandbox alanı yerine permissions içinde adlandırılmış bir izin profili kimliği iletebilir. permissions ile 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, geçerli canlı oturum ağacının kökünü tanımlar. Kök iş parçacıkları oturum kimliği olarak kendi iş parçacığı kimliklerini 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 değeriyle thread/resume çağrısı yapın. Yanıt biçimi thread/start ile eşleşir. personality gibi, thread/start tarafından desteklenen aynı 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 rollout dosyasının değiştirilme zamanını) güncellemez. Zaman damgası bir tur başlattığınızda güncellenir.

Etkinleştirilmiş 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ığı rollout meta verilerinde kalıcı olarak saklar ve yeni dinamik araçlar sağlamadığınızda thread/resume sırasında geri yükler.

Rollout'ta kayıtlı modelden farklı bir modelle sürdürürseniz Codex bir uyarı yayınlar ve sonraki turda tek seferlik bir model değiştirme talimatı uygular.

İş parçacığı hedefini yönetme

TUI'da /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. Geçerli, sonlandırılmamış amacı sağlamak veya objective alanını atlamak, kullanım geçmişini korurken durumu ya da belirteç bütçesini günceller.

Depolanan bir oturumdan dallanmak için thread.id ile thread/fork çağrısı 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 tur dâhil o tura kadar kopyalayıp sonraki turları 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ığı turun ortasındayken alanı atlarsanız çatal, işaretlenmemiş kısmi bir turu korumak yerine bir 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
    }
  }
}

Sayfalanmış 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 yönelik bir iş parçacığı başlığı ayarlandığında app-server; thread/list, thread/read, thread/resume, thread/unarchive ve thread/rollback yanıtlarındaki thread.name değerini doldurur. Daha sonra bir başlık 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 istediğiniz ancak iş parçacığını sürdürmek veya olaylarına abone olmak istemediğiniz durumlarda thread/read kullanın.

• includeTurns - true olduğunda yanıt iş parçacığının turlarını 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 (notLoaded, idle, systemError veya activeFlags ile active) içerir.

{ "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 aksine thread/read, iş parçacığını belleğe yüklemez veya thread/started yayınlamaz.

İş parçacığı turlarını listeleme

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

itemsView, yanıtın ne kadar tur öğesi verisi içereceğ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. İş parçacığını sürdürmeden kalıcı öğelerde sayfalar hâlinde gezinir. Sonuçları tek bir turla sınırlamak için turnId iletin veya iş parçacığı genelinde öğeleri sayfalamak için bunu atlayın. Etkin iş parçacığı deposu öğe sayfalamasını 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ızı sağlar. Sonuçlar varsayılan olarak createdAt ölçütüne göre en yeniden en 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 boyutunu varsayılan olarak 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 durumundaki iş parçacıklarını döndürür. Sabitlenmiş ve sabitlenmemiş iş parçacıklarını döndürmek için bunu atlayın.
• cwd - sonuçları, oturumun geçerli çalışma dizini bu yolla veya bir dizideki yollardan biriyle tam olarak eşleşen iş parçacıklarıyla sınırlar. Göreli yollar app-server sürecinin çalışma dizininden çözümlenir.
• useStateDbOnly - true olduğunda, meta verileri onarmak için JSONL iş parçacığı günlüklerini taramadan durum veritabanı sonuçlarını döndürür. Varsayılan tara ve onar 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ı, verilen ü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ı, verilen 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 birlikte kullanmayın.

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, 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 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ça belirtilen null, depolanan bir 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ığı durumu değişikliklerini izleme

thread/status/changed, yüklenmiş bir iş parçacığının çalışma zamanı durumu her değiştiğinde 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üklenmiş iş parçacıklarını listeleme

thread/loaded/list, şu anda belleğe yüklenmiş iş parçacığı kimliklerini döndürür.

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

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

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

• Bağlantı aboneyken artık kaldırılmışsa unsubscribed.
• Bağlantı bu iş parçacığına abone değilse notSubscribed.
• İş parçacığı yüklenmemişse notLoaded.

Bu son aboneyse sunucu, iş parçacığını hiç abonesi ve hiçbir iş parçacığı etkinliği olmadan 30 dakika geçene kadar yüklü tutar. Ek süre sona erdiğinde 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 saklanır) arşivlenmiş oturumlar dizinine taşımak için thread/archive kullanın. Bir iş parçacığını arşivlemek, henüz arşivlenmemiş, 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" } }

archived: true iletmediğiniz sürece arşivlenmiş iş parçacıkları sonraki 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ınlar; oluşturulmuş bir alt iş parçacığı arşivlenemezse istek yine de o alt iş parçacığı için arşivleme bildirimi olmadan başarılı olabilir.

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

Kalıcı olarak saklanan 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ş olarak değerlendirilir. 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ığı 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 bilgisi 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": {} }

Bir iş parçacığı kabuk komutunu çalıştırma

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

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.

Yürütme süresini milisaniye cinsinden sınırlamak için timeoutMs değerini ayarlayın. Bu değerin atlanması veya null geçirilmesi, varsayılan bir saatlik süreyi kullanır. 0 anında zaman aşımı ister; negatif değerler reddedilir. Zaman aşımı, anlık RPC alındı onayını geciktirmez.

{ "method": "thread/shellCommand", "id": 26, "params": { "threadId": "thr_b", "command": "git status --short", "timeoutMs": 10000 } }
{ "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 ve döndürülen processId, 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 } }

Bir arka plan terminalini durdurmak için söz konusu 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 silinecektir. 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 alanını 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ı her tur için 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ıtlanmış kökler).
• workspaceWrite: isteğe bağlı readOnlyAccess (varsayılan olarak { "type": "fullAccess" } veya kısıtlanmış kökler).

Kısıtlanmış okuma erişimi yapısı:

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

macOS'te includePlatformDefaults: true, kısıtlı okuma oturumları için özenle seçilmiş, platformun varsayılan Seatbelt politikasını ekler. Bu, /System kapsamının tamamına geniş ölçüde 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 } } }

İstemcinizin çalıştırdığı bir aracın çıktısıyla tur başlatmak için boş olmayan bir name, isteğe bağlı bir namespace ve içerik öğelerinden oluşan bir output dizesi veya dizisiyle birlikte toolOutput geçirin. input değerini boş bir dizi olarak ayarlayın; boş olmayan kullanıcı girdisini toolOutput ile birleştiremezsiniz.

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

Çıktı, konuşmada araç çıktısı olarak kalır ve bildirimlerle kalıcı geçmişte bir functionCallOutput öğesi olarak görünür. Normal bir tur zaten etkinse Codex, çıktıyı bu tur için sıraya alır.

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

Bir 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 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 alanını ekleyin; etkin tur 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 (beceri çağırma)

Metin girdisine $<skill-name> ekleyerek ve yanına bir skill girdi öğesi koyarak bir beceriyi 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ışla iletir. Hedefler şunlardır:

• uncommittedChanges
• baseBranch (bir dala göre fark)
• 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çin 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 aynı yapıdadır ancak reviewThreadId, yeni inceleme iş parçacığının kimliği olur (asıl threadId değerinden farklıdır). Sunucu ayrıca inceleme turunu akışla 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 bildirimini akışla iletir:

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

İnceleyici tamamladığında sunucu, nihai inceleme metnini içeren bir exitedReviewMode öğesi barındıran item/started ve item/completed bildirimlerini 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 sandbox'ının dışında çalışır. Bunu yalnızca istemciniz yerel işlem denetimini bilerek sandbox olmadan sunuyorsa kullanın.

process/spawn ile bir işlem başlatıp processHandle sağlayın; ardından bu tanıtıcıyı stdin, yeniden boyutlandırma ve sonlandırma istekleri için kullanın. Çıktı process/outputDelta bildirimleri, tamamlanma ise process/exited üzerinden akışla 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, bir 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 zorlaması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).
• Atlandığında timeoutMs, sunucu varsayılanına geri döner.
• PTY destekli oturumlar için tty: true değerini; ardından command/exec/write, command/exec/resize veya command/exec/terminate kullanmayı planlıyorsanız processId değerini ayarlayın.
• Komut çalışırken command/exec/outputDelta bildirimlerini 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 anahtarlar ve değerler hakkında 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 denetim 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 de dahil olmak üzere söz konusu 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ı okumaya devam edin.

Bildirimleri devre dışı bırakma

İ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 bu 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, her sorgu için bildirimler yayımlar:

• fuzzyFileSearch/sessionUpdated - etkin sorgunun geçerli eşleşmelerini içeren { sessionId, query, files }.
• fuzzyFileSearch/sessionCompleted - bu sorgu için indeksleme ve eşleştirme tamamlandığında { sessionId }.

Uyarı olayları

• configWarning - kurtarılabilir yapılandırma veya başlatma sorunları için { summary, details?, path?, range? }.
• warning - ölümcül 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 tüm dosya değişikliklerinin en son birleştirilmiş farkını 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 - eşzamanlı bir yaşam döngüsü kancası başladığında ve nihai çalıştırma özeti hazır olduğunda { threadId, turnId?, run }. Bu bildirimler eşzamansız kancalar için yayımlanmaz.
• model/safetyBuffering/updated - bir yanıt geçici güvenlik tamponlamasına 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ışla iletilse bile şu anda boş items dizileri içerir. Tur öğeleri için doğruluk kaynağı 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 (text, image veya localImage) listesi olduğu {id, content}.
• functionCallOutput - turn/start.toolOutput aracılığıyla sağlanan bağımsız araç çıktısı için {id, name, namespace, output}. namespace, null olabilir.
• 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 kaynağındaki son plan öğesini belirleyici kabul edin.
• reasoning - summary alanının akışla 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ında appContext; connectorId, linkId, resourceUri, appName, templateId ve kararlı bağlayıcı actionName değerlerini içerebilir. Daha eski kalıcı öğelerde 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 yapılan 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 çalışma birimi başladığında item öğesinin tamamını yayımlar; item.id, deltaların kullandığı itemId ile eşleşir.
• item/completed - çalışma tamamlandığında son item öğesini gönderir; bunu belirleyici durum olarak kabul edin.

Öğe deltaları

• item/agentMessage/delta - ajan iletisi için akışla iletilen metni sona ekler.
• item/plan/delta - önerilen plan metnini akışla iletir. Son plan öğesi, birleştirilmiş deltalarla tam olarak aynı olmayabilir.
• item/reasoning/summaryTextDelta - okunabilir akıl yürütme özetlerini akışla 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ışla iletir (model destekliyorsa).
• item/commandExecution/outputDelta - bir komutun stdout/stderr çıktısını akışla iletir; deltaları sırayla sona 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. Üst kaynak 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 kaynak hataları)
• ResponseStreamConnectionFailed
• ResponseStreamDisconnected
• ResponseTooManyFailedAttempts
• BadRequest, Unauthorized, SandboxError, InternalServerError, Other

Üst kaynak HTTP durumu mevcut olduğunda sunucu, bunu ilgili codexErrorInfo varyantındaki httpStatusCode alanında 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 alanlarını içerir; UI durumunu etkin konuşmayla sınırlamak için bunları kullanın.

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

Komut yürütme onayları

İletilerin 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 alanlarını 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ı kablo üzerinde mutlaktır.
3. İstemci, yukarıdaki komut yürütme onayı kararlarından biriyle yanıt verir.
4. serverRequest/resolved, beklemedeki 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ı için anlamlı bir kabuk komutu önizlemesi olmasına güvenmemelidir.

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

Dosya değişikliği onayları

İletilerin 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 alanlarını içerir.
3. İstemci, yukarıdaki dosya değişikliği onayı kararlarından biriyle yanıt verir.
4. serverRequest/resolved, beklemedeki 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 bildirimini yayımlar. Beklemedeki istek, istemci yanıt vermeden önce tur başlangıcı, tur tamamlanması veya tur kesintisi nedeniyle temizlenirse sunucu bu temizlik 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 söz konusu aralıktan sonra 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 birlikte 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; tur kapsamlı bir izin için bunu atlayın 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:

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

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

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

thread/start üzerindeki dynamicTools ve buna karşılık gelen item/tool/call istek ya da 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 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 ve Kabul et, Reddet ve İptal gibi seçeneklerle onay isteyebilir. Araç daha düşük ayrıcalık ipuçları da bildirse bile yıkıcı araç açıklamaları her zaman onayı tetikler. Kullanıcı reddeder veya iptal ederse ilgili mcpToolCall öğesi, araç çalıştırılmadan bir hatayla tamamlanır.

Beceriler

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

{
  "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şaretini ayrıştırıp beceriyi bulmayı dener; bu da gecikmeyi artırabilir.

Örnek:

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

Kullanılabilir becerileri getirmek için skills/list kullanın (isteğe bağlı olarak forceReload ile cwds kapsamına alınabilir). Belirli cwd değerleri için ek mutlak yolları user kapsamında taramak üzere perCwdExtraUserRoots alanını da 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 alanlarını 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 beceri 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 beceriyi yoluna göre 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)

Kaydedilmiş en son yüklü 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ştirdiğinde ve modele görünür en az bir araç, uygulama ve araç politikalarına uyduğunda ç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 atlayın. 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ısını yapın. İstemcilerin kurulum/erişim ile yerel etkin durumu ayırt edebilmesi için her girdi hem isAccessible (kullanıcı tarafından kullanılabilir) hem de isEnabled (config.toml içinde etkin) alanları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), söz konusu iş parçacığının yapılandırma anlık görüntüsünü kullanır. Atlandığında 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üklemeyi her 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 yüklü çalışma zamanı durumu yerine uygulama meta verilerine ihtiyaç duyuyorsanız app/read kullanın. En fazla 100 appIds geçirin. Sunucu, tekrarlanan her kimliğin yalnızca ilk geçtiği yeri tutar ve bu sırayı hem apps hem de missingAppIds içinde korur. Bilinmeyen veya erişilemeyen uygulamalar, isteğin tamamı başarısız 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ç özetlerini istemek için includeTools: true değerini ayarlayın. Meta veri yanıtı, yüklü uygulamanın çalışma zamanı durumunu içermez veya bir araç çağrısına yetki vermez; etkin enabled ve callable durumunu denetlemek için app/installed kullanın.

Metin girdisine $<app-slug> ekleyerek ve app://<id> yoluna sahip bir mention girdi öğesi (önerilir) ekleyerek bir uygulamayı çağırın.

{
  "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 geçersiz kılmadığı sürece apps._default.approvals_reviewer, tüm uygulamalar için inceleyiciyi ayarlar. Her ikisi de atlandığında uygulama, üst düzey approvals_reviewer değerini devralır. apps._default.default_tools_approval_mode, uygulama veya araç başına geçersiz kılma bulunmayan 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 geçirin.

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 taşıma öğ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 ise 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ıttan hemen sonra veya uzaktaki arka plan içe aktarmaları tamamlandıktan sonra gerçekleşebilir.

{ "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, Codex'in taşımayı deneyebileceği her marketplaceName ve pluginNames değerini listeler. Algılama yalnızca hâlâ yapılacak işi olan öğeleri döndürür. Örneğin Codex, AGENTS.md zaten mevcutsa ve boş değilse AGENTS taşımasını atlar; beceri içe aktarmaları da mevcut beceri dizinlerinin üzerine yazmaz.

Codex, .claude/settings.json içindeki eklentileri algılarken yapılandırılmış marketplace kaynaklarını extraKnownMarketplaces içinden okur. enabledPlugins, claude-plugins-official kaynaklı eklentiler içeriyor ancak marketplace 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çma işlemlerini 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ı için tasarlanmıştır. 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 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 girişimi tamamlandığında (başarıyla veya hatayla) yayımlanır.
• account/login/cancel - beklemedeki, yönetilen 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 yeni 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 - tükenen krediler veya ulaşılan kullanım sınırı hakkında çalışma alanı sahibine e-posta göndermesini ChatGPT'den ister.
• account/rateLimitResetCredit/consume - çağıran tarafından sağlanan idempotencyKey değerini kullanarak kazanılmış bir hız sınırı sıfırlamasını tüketir.
• 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. threadId, uygulama kapsamlı başlangıç için null olur. Başlangıç başarısız olduğunda failureReason: "reauthenticationRequired", saklanan OAuth kimlik bilgilerinin süresinin dolduğunu ve yenilenemediğini belirtir; bu durumda istemci sunucuya yeniden bağlanmayı ö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 yenilemesini zorlamak için true olarak ayarlayın. Harici token modunda (chatgptAuthTokens) app-server bu bayrağı yok sayar.
• ChatGPT hesabının e-posta adresi yoksa 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"
     }
   }

Başarılı bir tarayıcı geri çağrısı, varsayılan olarak yerel bir başarı sayfasına yönlendirir. Kuruluş kurulumu gerekli değilse barındırılan başarı sayfasını kullanmak için useHostedLoginSuccessPage: true değerini ayarlayın. Barındırılan başarı etkin olduğunda appBrand, "codex" veya "chatgpt" olabilir; atlanan ya da null değerleri varsayılan olarak "codex" kullanır.

   {
     "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ı güvenilir değilse 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 değerlerini gösterin; UX'ten frontend sorumludur.
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 asıl 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çülen limit_id değerine göre anahtarlanmış çoklu dilim görünümüdür (örneğin codex).
• limitId, ölçülen dilim tanımlayıcısıdır.
• limitName, dilim için isteğe bağlı ve kullanıcıya gösterilen bir etikettir.
• usedPercent, kota penceresi içindeki geçerli kullanımdır.
• windowDurationMins, kota penceresinin uzunluğudur.
• resetsAt, sonraki sıfırlama için Unix zaman damgasıdır (saniye).
• Sunucu bir dilimle ilişkili ChatGPT planını döndürdüğünde planType eklenir.
• Sunucu kalan çalışma alanı kredisi ayrıntılarını döndürdüğünde credits eklenir.
• rateLimitReachedType, bir sınıra ulaşıldığında sunucu tarafından sınıflandırılan sınır durumunu tanımlar.
• Hizmet sağladığında rateLimitResetCredits, kullanılabilir kazanılmış sıfırlama sayısını içerir; aksi takdirde null olur.
• Yalnızca sayı biliniyorsa rateLimitResetCredits.credits, null olur. Boş bir dizi, hizmetin ayrıntıları getirdiği ve kullanılabilir kredi döndürmediği anlamına gelir. Hizmet ayrıntı satırlarını sınırlayabildiğ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ı tükettikten 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 söz konusu metriği 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ı tüketmek 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 kullanım girişimi için bir UUID kullanın ve bu girişimi yeniden denerken aynı değeri tekrar kullanın.
• creditId isteğe bağlıdır. Sağlandığında account/rateLimits/read kaynağından alınmış, boş olmayan opak bir kimlik olmalıdır. Atlandığında hizmet, kullanılabilir sonraki krediyi seçer.
• reset, bir kredinin tüketildiği anlamına gelir.
• alreadyRedeemed, aynı kullanım işleminin daha önce tamamlandığı anlamına gelir. Bunu eşgüçlü bir 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ı tükettikten 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 çalışma alanı sahibine e-posta göndermesini ChatGPT'den 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 ise 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 }
] } }