4. februar 2026.

Otključavanje Codex sistema: kako smo izgradili App Server

Celia Chen, članica tehničkog osoblja

Učitavanje…

OpenAI-jev agent za kodiranje Codex dostupan je na mnogo različitih platformi: web aplikaciji⁠(otvara se u novom prozoru), CLI-ju⁠(otvara se u novom prozoru), IDE ekstenziji⁠(otvara se u novom prozoru) i novoj Codex macOS aplikaciji. Ispod haube, sve pokreće isti Codex harness—petlja agenta i logika koja je osnova svih Codex iskustava. Koja je kritična veza između njih? Codex App Server⁠(otvara se u novom prozoru), klijentu prilagođen, dvosmjerni JSON-RPC¹ API.

U ovom postu ćemo predstaviti Codex App Server i podijeliti naša dosadašnja saznanja o najboljim načinima kako integrirati mogućnosti Codex-a u vaš proizvod kako biste pomogli korisnicima da unaprijede svoje radne tokove. Obradit ćemo arhitekturu i protokol App Servera i kako se integriše s različitim Codex površinama, kao i savjete za korištenje Codexa, bilo da želite pretvoriti Codex u recenzenta koda, SRE agenta ili asistenta za kodiranje.

Porijeklo aplikacijskog servera

Prije nego što zaronimo u arhitekturu, korisno je znati pozadinsku priču o App Serveru. U početku je App Server bio praktičan način za ponovnu upotrebu Codex harnessa kroz proizvode, što je postepeno evoluiralo u naš standardni protokol.

Codex CLI je započeo kao TUI (terminalni korisnički interfejs), što znači da se Codexu pristupa putem terminala. Kada smo razvili VS Code ekstenziju (prilagođeniju IDE-u za interakciju s Codex agentima), trebali smo način da koristimo isti okvir kako bismo pokretali istu petlju agenta iz IDE korisničkog interfejsa bez ponovne implementacije. To je značilo podržavanje bogatih obrazaca interakcije izvan request/response, kao što su istraživanje radnog prostora, strimovanje napretka dok agent rezonuje i emitovanje razlika. Prvo smo eksperimentisali s izlaganjem Codexa kao MCP servera⁠(otvara se u novom prozoru), ali se održavanje MCP semantike na način koji je imao smisla za VS Code pokazalo izazovnim. Umjesto toga, uveli smo JSON-RPC protokol koji je odražavao TUI petlju, što je postalo nezvanična prva verzija⁠(otvara se u novom prozoru) aplikacijskog servera. U to vrijeme nismo očekivali da će drugi klijenti zavisiti od App Servera, pa nije bio dizajniran kao stabilan API.

Kako je usvajanje Codexa raslo tokom narednih nekoliko mjeseci, interni timovi i vanjski partneri željeli su mogućnost da ugrade isti alat u svoje proizvode kako bi ubrzali radne tokove razvoja softvera svojih korisnika. Na primjer, JetBrains i Xcode su željeli iskustvo agenta na nivou IDE-a, dok je Codex desktop aplikacija trebala orkestrirati mnoge Codex agente istovremeno. Ti zahtjevi su nas potaknuli da dizajniramo površinu platforme na koju se i naši proizvodi i integracije partnera mogu sigurno oslanjati tokom vremena. Trebalo je biti lako integrirati i unatrag kompatibilno, što znači da smo mogli razvijati protokol bez narušavanja postojećih klijenata.

Zatim ćemo objasniti kako smo osmislili arhitekturu i protokol kako bi različiti klijenti mogli koristiti isti sistem.

Unutar Codex harnesa

Prvo, hajde da se detaljno osvrnemo na ono što se nalazi unutar Codex harnessa i kako ga Codex App Server predstavlja klijentima. U našem posljednjem Codex blogu, razložili smo osnovnu petlju agenta koja upravlja interakcijom između korisnika, modela i alata. Ovo je osnovna logika Codex harnessa, ali postoji još toga u potpunom iskustvu agenta:

1. Životni ciklus niti i postojanost. Nit je razgovor u Codexu između korisnika i agenta. Codex kreira, nastavlja, forkuje i arhivira niti, te čuva historiju događaja kako bi se klijenti mogli ponovo povezati i prikazati dosljednu vremensku liniju.

2. Konfiguracija i autentifikacija. Codex učitava konfiguraciju, upravlja podrazumijevanim postavkama i pokreće tokove autentifikacije kao što je „Prijava s ChatGPT‑om“, uključujući stanje vjerodajnica.

3. Izvršavanje alata i proširenja. Codex izvršava shell/file alate u sandboxu i povezuje integracije poput MCP servera i vještina kako bi mogli sudjelovati u agentovoj petlji prema dosljednom modelu politika.

Sva logika agenta koju smo ovdje spomenuli, uključujući osnovnu petlju agenta, nalazi se u dijelu Codex CLI koda koji se zove „Codex core⁠(otvara se u novom prozoru).” Codex core je i biblioteka u kojoj se nalazi sav kod agenta i izvršno okruženje koje se može pokrenuti da izvršava petlju agenta i upravlja postojanošću jedne Codex niti (razgovora).

Da bi bio koristan, Codex harness mora biti dostupan korisnicima. Tu dolazi do izražaja App Server.

Dijagram pod nazivom „App server process flow“. Klijent šalje JSON-RPC poruke stdio čitaču, koji prosljeđuje zahtjeve procesoru poruka Codex. Procesor komunicira s upraviteljem niti i osnovnom niti putem niti za pretragu, rukohvata niti, podnesenih zahtjeva i događaja/ažuriranja, a zatim vraća odgovore klijentu.

App Server je i JSON-RPC protokol između klijenta i servera, kao i dugotrajan proces koji hostuje osnovne niti Codexa. Kao što možemo vidjeti iz gornjeg dijagrama, proces App Servera ima četiri glavne komponente: stdio čitač, Codex procesor poruka, upravitelj niti i osnovne niti. Upravitelj niti pokreće jednu osnovnu sesiju za svaku nit, a zatim Codex procesor poruka direktno komunicira sa svakom osnovnom sesijom kako bi podnosio zahtjeve klijenata i primao ažuriranja.

Jedan zahtjev klijenta može rezultirati mnogim ažuriranjima događaja, a upravo ti detaljni događaji omogućavaju nam da izgradimo bogat korisnički interfejs na vrhu App Servera. Nadalje, stdio čitač i Codex procesor poruka djeluju kao prevodilački sloj između klijenta i osnovnih niti Codex-a. Oni prevode klijentske JSON-RPC zahtjeve u osnovne operacije Codex jezgre, slušaju interni tok događaja Codex jezgre, a zatim te događaje niskog nivoa transformišu u mali skup stabilnih, za korisnički interfejs spremnih JSON-RPC obavještenja.

JSON-RPC protokol između klijenta i App Servera je potpuno dvosmjeran. Tipična nit sadrži zahtjev klijenta i mnogo obavještenja servera. Osim toga, server može pokrenuti zahtjeve kada agentu treba unos, kao što je odobrenje, i zatim pauzirati radnju dok klijent ne odgovori.

Osnovni elementi konverzacije

Zatim ćemo razložiti osnovne elemente razgovora, građevne blokove protokola App Servera. Dizajniranje API-ja za petlju agenta je izazovno jer interakcija između korisnika i agenta nije jednostavan zahtjev/odgovor. Jedan korisnički zahtjev može se razviti u strukturirani niz radnji koje klijent treba vjerno predstaviti: korisnikov unos, agentov postepeni napredak, artefakti nastali usput (npr., razlike). Da bismo taj tok interakcije učinili jednostavnim za integraciju i otpornim kroz korisničke interfejse, odlučili smo se za tri osnovna primitiva s jasnim granicama i životnim ciklusima:

1. Stavka: Stavka je osnovna jedinica ulaza/izlaza u Codexu. Stavke su tipizirane (npr., poruka korisnika, poruka agenta, izvršavanje alata, zahtjev za odobrenje, diff) i svaka ima jasan životni ciklus:

item/started kada stavka započne
opcionalni item/*/delta događaji kao tokovi sadržaja (za tipove stavki za strimovanje)
item/completed kada se stavka završi sa svojim završnim opterećenjem

Ovaj životni ciklus omogućava klijentima da odmah započnu renderovanje na started, strimuju inkrementalna ažuriranja na delta i završe na completed.

2. Potez: Potez je jedna jedinica rada agenta koju pokreće unos korisnika. Počinje kada klijent pošalje unos (na primjer, „pokreni testove i sažmi neuspjehe“) i završava kada agent završi s generisanjem izlaza za taj unos. Potez sadrži niz stavki koje predstavljaju međukorake i izlaze proizvedene tokom procesa.

3. Niz: Niz je trajni kontejner za tekuću Codex sesiju između korisnika i agenta. Sadrži više koraka. Teme se mogu kreirati, nastaviti, razgranati i arhivirati. Istorija niti se čuva kako bi se klijenti mogli ponovo povezati i prikazati dosljedan vremenski slijed.

Sada ćemo pogledati pojednostavljeni razgovor između klijenta i agenta, gdje je razgovor predstavljen primitivima:

Dijagram označen kao „Client-server protocol message flow: Initialization handshake.” Klijent šalje zahtjev za inicijalizaciju s clientInfo na server. Server odgovara događajem rezultata koji sadrži niz userAgent “my_client/1.0.”

Na početku razgovora, klijent i server moraju uspostaviti initialize rukovanje. Klijent mora poslati jedan initialize zahtjev prije bilo koje druge metode, a server to potvrđuje odgovorom. Ovo daje serveru priliku da reklamira svoje mogućnosti i omogućava objema stranama da se dogovore o verzioniranju protokola, funkcionalnim zastavicama i podrazumijevanim postavkama prije nego što stvarni posao počne. Evo primjera payloada iz OpenAI-jeve VS Code ekstenzije:

JSON

1{
2  "method": "initialize",
3  "id": 0,
4  "params": {
5    "clientInfo": {
6      "name": "codex_vscode",
7      "title": "Codex VS Code Extension",
8      "version": "0.1.0"
9    }
10  }
11}

Ovo je ono što server vraća:

JSON

1{
2  "id": 0,
3  "result": {
4    "userAgent": "codex_vscode/0.94.0-alpha.7 (Mac OS 26.2.0; arm64) vscode/2.4.22 (codex_vscode; 0.1.0)"
5  }
6}

Dijagram pod nazivom „Tok poruka klijent-server protokola: životni ciklus niti i turna.” Klijent šalje zahtjeve thread/start i turn/start na server. Server emituje događaje—thread/started, turn/started, item/started i item/completed—prikazujući potez u kojem je korisnička poruka „pokreni testove i sažmi greške.”

Kada klijent uputi novi zahtjev, prvo će kreirati nit, a zatim okret. Server će poslati obavijesti o napretku (thread/started i turn/started). Također će vratiti unose koje registrira kao stavke, poput korisničke poruke ovdje.

Dijagram pod nazivom „Tok poruka klijent-server protokola: Izvršavanje alata s opcionalnim odobrenjem.” Tokom poziva alata, server emituje item/started, a zatim item/commandExecution/requestApproval s razlogom („pokreni testove“). Klijent vraća događaj odobrenja (dozvoli/odbijanje). Server zatim emituje item/completed, prikazujući izvršenje naredbe ("pnpm test").

Pozivi alata se također vraćaju klijentu kao stavke. Osim toga, server može tražiti odobrenje klijenta prije nego što pokrene radnju slanjem zahtjeva servera. Odobrenje će pauzirati potez dok klijent ne odgovori sa „dozvoli“ ili „odbij“. Ovako izgleda tok odobravanja u ekstenziji VS Code:

Upit za dozvolu u interfejsu sa tamnom temom koji pita: „Da li želite da mi dozvolite da pokrenem pnpm test za ovaj radni prostor?“ Navodi opcije: 1) Da, 2) Da i ne pitajte ponovo za komande koje počinju s pnpm test, i 3) Ne, s dugmetom 'Submit' na dnu.

Dijagram pod nazivom „Tok poruka protokola klijent-server: Tok poruka agenta za streaming.” Server prenosi poruku asistenta u dijelovima: item/started, dva događaja agentMessage/delta (“izvršena 3 testa.”, „sve je prošlo”), zatim stavka/završena. Potez se završava sa turn/completed.

Na kraju, server šalje poruku agenta i zatim završava potez sa turn/completed. Delta događaji toka poruka agenta šalju dijelove poruke nazad dok se poruka ne završi sa item/completed.

Poruke u dijagramu su pojednostavljene radi lakšeg čitanja. Ako želite vidjeti JSON za cijeli potez, možete pokrenuti testni klijent iz Codex CLI repozitorija:

Bash

1codex debug app-server send-message-v2 "run tests and summarize failures"

Integracija sa klijentima

Sada, hajde da pogledamo kako različite klijentske površine integrišu Codex putem App Servera. Obradit ćemo tri obrasca: lokalne aplikacije i IDE-ove, Codex web runtime i TUI.

Dijagram pod nazivom „Codex klijenti integrirani s Codex harnessom putem aplikacijskog servera.“ Klijenti prve strane (Codex Desktop App, TUI/CLI, Web Runtime) i integracije trećih strana (JetBrains IDE-ovi, VS Code, Xcode) komuniciraju s Codex harness putem JSON-RPC poziva.

U sva tri slučaja, transport je JSON-RPC preko stdio (JSONL). JSON-RPC olakšava izradu klijentskih veza na jeziku po vašem izboru. Codex površine i partnerske integracije su implementirale klijente App Servera na jezicima kao što su Go, Python, TypeScript, Swift i Kotlin. Za TypeScript, možete generisati definicije direktno iz Rust protokola pokretanjem:

Bash

1codex app-server generate-ts

Za druge jezike, možete generirati paket JSON šeme i unijeti ga u vaš preferirani generator koda pokretanjem:

Bash

1codex app-server generate-json-schema

Lokalne aplikacije & IDE-ovi

Snimak ekrana VS Code-a sa pokrenutom ekstenzijom Codex. Otvorena je testna datoteka za Rust, a ispod nje Codex panel opisuje pokretanje samo fmt i cargo test -p codex-app-server, izvještavajući da su formatiranje i testovi u toku dok se čeka konačni rezultat prolaz/pad.

Lokalni klijenti obično pakiraju ili preuzimaju binarnu datoteku specifičnu za platformu za App Server, pokreću je kao dugotrajni podređeni proces i održavaju otvoren dvosmjerni stdio kanal za JSON-RPC. U našoj VS Code ekstenziji i Desktop aplikaciji, na primjer, isporučeni artefakt uključuje platformi specifični Codex binarni fajl i fiksiran je na testiranu verziju tako da klijent uvijek pokreće tačno one bitove koje smo testirali.

Nije svaka integracija u mogućnosti često isporučivati ažuriranja za klijente. Neki partneri, poput Xcode-a, razdvajaju cikluse izdanja održavajući klijenta stabilnim i omogućavajući mu da po potrebi upućuje na noviju binarnu datoteku App Servera. Na taj način mogu usvojiti poboljšanja na strani servera (na primjer, bolju automatsku kompakciju u Codex jezgri ili novopodržane konfiguracijske ključeve) i uvoditi ispravke grešaka bez čekanja na izdanje klijenta. Površina JSON-RPC App Servera je dizajnirana da bude unazad kompatibilna, tako da stariji klijenti mogu sigurno komunicirati s novijim serverima.

Codex Web

Codex Web koristi Codex harness, ali ga pokreće u kontejnerskom okruženju. Radnik obezbjeđuje kontejner sa preuzetim radnim prostorom, pokreće binarnu datoteku App Servera unutar njega i održava dugotrajni JSON-RPC preko stdio² kanala. Web aplikacija (koja radi u kartici korisnikovog preglednika) komunicira s Codex backendom putem HTTP-a i SSE-a, koji prenose događaje zadataka koje generira radnik. Ovo održava korisnički interfejs na strani pretraživača laganim, a istovremeno nam omogućava konzistentno izvršno okruženje na desktopu i internetu.

Pošto su web sesije prolazne (kartice se zatvaraju, mreže se prekidaju), web aplikacija ne može biti izvor istine za dugotrajne zadatke. Čuvanje stanja i napretka na serveru znači da rad može da se nastavi čak i ako kartica nestane. Protokol za streaming i sačuvane sesije niti omogućavaju lako ponovno povezivanje nove sesije, nastavak tamo gdje je prekinuto i nadoknadu bez ponovnog uspostavljanja stanja u klijentu.

TUI/Codex CLI

Snimak ekrana terminala na kojem je pokrenut Codex CLI. Prikazuje OpenAI Codex baner s modelom gpt-5.2-codex srednje, korisnička komanda „objasni mi app server“, i status „U radu“. Ispod se pojavljuje prijedlog: „napišite testove za @filename“, s opcijama za prečice.

Historijski gledano, TUI je bio 'nativni' klijent koji se izvršavao u istom procesu kao petlja agenta i direktno je komunicirao s Rust jezgrenim tipovima umjesto s protokolom aplikacijskog servera. To je omogućilo brzu ranu iteraciju, ali je također učinilo TUI površinom za posebne slučajeve.

Sada kada App Server postoji, planiramo refaktorisati TUI⁠(otvara se u novom prozoru) kako bi ga koristio i ponašao se kao bilo koji drugi klijent: pokrenuti child proces App Servera, koristiti JSON-RPC preko stdio i prikazati iste strimujuće događaje i odobrenja. Ovo omogućava radne tokove u kojima se TUI može povezati s Codex serverom koji radi na udaljenoj mašini, držeći agenta blizu računarskih resursa i nastavljajući rad čak i ako laptop pređe u stanje mirovanja ili se prekine veza, dok istovremeno isporučuje ažuriranja uživo i lokalne kontrole.

Odabir pravog protokola

Codex App Server će biti prvorazredna metoda integracije koju ćemo održavati ubuduće, ali postoje i druge metode s ograničenijom funkcionalnošću. Podrazumijevano bismo preporučili da klijenti koriste Codex App Server za integraciju s Codexom, ali vrijedi razmotriti različite metode integracije i razumjeti njihove prednosti i nedostatke. U nastavku su najčešći načini za upravljanje Codex-om i kada bi svaki mogao biti dobar izbor.

JSON-RPC protokoli

Codex kao MCP server

Pokrenite codex mcp-server⁠(otvara se u novom prozoru) i povežite se s bilo kojim MCP klijentom koji podržava stdio servere (npr. OpenAI Agents SDK⁠(otvara se u novom prozoru)). Ovo je dobar izbor ako već imate radni tok zasnovan na MCP-u i želite koristiti Codex kao alat koji se može pozvati. Nedostatak je u tome što dobijate samo ono što MCP izlaže, pa se interakcije specifične za Codex koje se oslanjaju na bogatiju semantiku sesije (npr., ažuriranja diff-a) možda neće čisto mapirati kroz MCP krajnje tačke.

Protokoli za povezivanje agenata između različitih provajdera

Neki ekosistemi nude prenosivi interfejs koji može ciljati više pružalaca modela i okruženja za izvršavanje. Ovo može biti dobar izbor ako želite jednu apstrakciju koja koordinira više agenata. Kompromis je u tome što ovi protokoli često konvergiraju na zajednički podskup mogućnosti, što može otežati predstavljanje bogatijih interakcija, posebno kada su važni semantika alata i sesije specifične za pružatelja usluga. Ovaj prostor se brzo razvija, i očekujemo da će se pojaviti uobičajeniji standardi kako budemo utvrđivali najbolje primitive za predstavljanje radnih procesa agenata u stvarnom svijetu (vještine⁠(otvara se u novom prozoru) su dobar primjer za to).

Codex App Server

Odaberite App Server kada želite da se kompletan Codex harness prikaže kao stabilan tok događaja prilagođen korisničkom interfejsu. Dobijate punu funkcionalnost petlje agenta i druge prateće funkcije kao što su prijava pomoću ChatGPT‑a, otkrivanje modela i upravljanje konfiguracijom. Glavni trošak je integracijski rad, jer trebate izgraditi klijentsko vezivanje za JSON-RPC na svom jeziku. U praksi, međutim, Codex može obaviti veliki dio teškog posla ako mu dostavite JSON šemu i dokumentaciju. Mnogi timovi s kojima smo radili brzo su uspjeli napraviti funkcionalnu integraciju koristeći Codex.

Drugi načini za integraciju Codex

Codex Exec⁠(otvara se u novom prozoru)

Lagani, skriptabilni CLI režim za jednokratne zadatke i CI pokretanja. Odlično odgovara za automatizaciju i cjevovode gdje želite da jedna naredba bude izvršena do kraja bez interakcije, strimuje strukturirani izlaz za logove i završi sa jasnim signalom uspjeha ili neuspjeha.

Codex SDK⁠(otvara se u novom prozoru)

TypeScript biblioteka za programsko upravljanje lokalnim Codex agentima iz vaše aplikacije. Najbolje je kada želite izvorni interfejs biblioteke za alate i radne tokove na strani servera, bez potrebe za izgradnjom zasebnog JSON-RPC klijenta. Budući da je isporučen ranije od App Servera, trenutno podržava manje jezika i manju površinu funkcionalnosti. Ako postoji interes programera, mogli bismo dodati dodatne SDK-ove koji obuhvataju protokol App Servera kako bi timovi mogli pokriti veći dio površine harnesa bez pisanja JSON-RPC veza.

Nastavit ćemo s ovim

U ovom postu podijelili smo kako pristupamo dizajniranju novog standarda za interakciju s agentima i kako pretvoriti Codex harness u stabilan i klijentima prilagođen protokol. Obradili smo kako App Server izlaže Codex jezgro, omogućava klijentima da upravljaju kompletnom petljom agenta i pokreće širok spektar površina, uključujući TUI, lokalne IDE integracije i web runtime.

Ako ti je ovo dalo ideje za integraciju Codex-a u tvoje radne tokove, vrijedi isprobati App Server. Sav izvorni kod nalazi se u Codex CLI repozitoriju⁠(otvara se u novom prozoru) otvorenog koda. Slobodno podijelite svoje povratne informacije i zahtjeve za funkcionalnosti. Uzbuđeni smo što ćemo čuti od vas i nastaviti činiti agente pristupačnijima svima.

Autor

Celia Chen

Priznanja

Posebna zahvala Michaelu Bolinu, Owenu Linu, Ericu Trautu i Rasmusu Rygaardu, koji su doprinijeli ovom postu, kao i cijelom Codex timu koji je radio na App Serveru.

Fusnote

1
Koristimo varijantu „JSON‑RPC lite“: zadržava oblik zahtjeva/odgovora/obavijesti, ali izostavlja "jsonrpc": "2.0" zaglavlje i je uokvireno kao JSONL preko stdio umjesto strogog JSON‑RPC 2.0.
2
„stdio” se odnosi na stdin/stdout aplikacijskog servera unutar kontejnera. U hostovanim postavkama, ti tokovi se često tuneliraju preko trajne mrežne veze (npr., WebSocket-slične) do kontejnerskog runtime-a—tako da se ponaša kao stdio čak i ako nije doslovna lokalna cijev.

Nastavite čitati

Prikažite sve

Izgradnja poreskih agenata koji se sami poboljšavaju uz Codex

Inženjering27. maj 2026.

Izgradnja sigurnog i efikasnog sandboxa za omogućavanje Codexa na Windowsu

Inženjering13. maj 2026.

Odakle su došli goblini

Inženjering5. maj 2026.