4. veljače 2026.

Otključavanje Codex harnessa: 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), proširenju IDE⁠(otvara se u novom prozoru) i novoj aplikaciji Codex za macOS. Ispod poklopca, sve ih pokreće isti Codex sustav—petlja agenta i logika koja je temelj svih Codex iskustava. Koja je kritična poveznica između njih? Codex App Server⁠(otvara se u novom prozoru), dvosmjerni JSON-RPC¹ API prilagođen klijentima

U ovoj objavi predstavit ćemo Codex App Server; podijelit ćemo dosadašnja saznanja o najboljim načinima uvođenja mogućnosti Codexa u vaš proizvod kako biste svojim korisnicima pomogli da unaprijede svoje radne procese. Obradit ćemo arhitekturu i protokol App Servera te načine integriranja s različitim Codex sučeljima, kao i savjete za iskorištavanje Codexa, bez obzira na to želite li Codex pretvoriti u recenzenta koda, SRE agenta ili asistenta za kodiranje.

Podrijetlo App Servera

Prije nego što se upustimo u arhitekturu, korisno je upoznati se s pozadinom App Servera. U početku je App Server bio praktičan način ponovne upotrebe Codex harnessa u različitim proizvodima, koji je s vremenom postupno prerastao u naš standardni protokol.

Codex CLI započeo je kao TUI (terminal user interface), što znači da se Codexu pristupa putem terminala. Kad smo izgradili proširenje za VS Code (način interakcije s Codex agentima koji je više prilagođen IDE-u), trebali smo način da koristimo isti harness kako bismo iz IDE UI-ja pokretali istu petlju rada agenta bez ponovne implementacije. To je značilo podršku za bogate obrasce interakcije izvan modela zahtjev/odgovor, poput istraživanja radnog prostora, streaminga napretka tijekom rada agenta i generiranja diffova. Najprije smo eksperimentirali s izlaganjem Codexa kao MCP poslužitelja⁠(otvara se u novom prozoru), ali se održavanje MCP semantike na način koji ima smisla za VS Code pokazalo zahtjevnim. Umjesto toga, uveli smo protokol JSON-RPC koji je preslikavao TUI petlju, a koji je postao neslužbena prva verzija⁠(otvara se u novom prozoru) App Servera. U to vrijeme nismo očekivali da će drugi klijenti ovisiti o App Serveru, pa on nije bio dizajniran kao stabilan API.

Kako je tijekom sljedećih nekoliko mjeseci raslo usvajanje Codexa, interni timovi i vanjski partneri poželjeli su mogućnost ugradnje istog harnessa u vlastite proizvode kako bi ubrzali radne procese razvoja softvera svojih korisnika. Primjerice, JetBrains i Xcode željeli su iskustvo rada s agentom na razini IDE-ova, dok je desktop aplikacija Codex trebala orkestrirati velik broj Codex agenata paralelno. Ti su zahtjevi potaknuli dizajn platformskog sloja na koji se s vremenom mogu sigurno osloniti i naši proizvodi i partnerske integracije. Morala je biti jednostavna za integraciju i dizajnirana tako da zadrži kompatibilnost s postojećim klijentima, kako bismo mogli razvijati protokol bez njihovog narušavanja.

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

Unutar Codex harnessa

Najprije, usredotočimo se na ono što se nalazi unutar Codex harnessa i kako ga Codex App Server izlaže klijentima. U našem posljednjem Codex blogu, raščlanili smo temeljnu petlju rada agenta koja orkestrira interakciju između korisnika, modela i alata. Ovo je osnovna logika Codex harnessa, ali cjelokupno iskustvo rada s agentom uključuje i više od toga:

1. Životni ciklus i postojanost threada. Thread je Codex razgovor između korisnika i agenta. Codex stvara, nastavlja, grana i arhivira threadove te čuva povijest događaja kako bi se klijenti mogli ponovno povezati i prikazati dosljednu vremensku liniju.

2. Konfiguracija i autentifikacija Codex učitava konfiguraciju, upravlja zadanim postavkama i pokreće tijekove provjere autentičnosti kao što je „Prijava pomoću ChatGPT‑a“, uključujući stanje vjerodajnica.

3. Izvršavanje alata i proširenja Codex izvršava shell/datotečne alate u sandboxu i povezuje integracije poput MCP poslužitelja i vještina kako bi mogle sudjelovati u petlji agenta prema dosljednom modelu pravila.

Sva logika agenta koju smo ovdje spomenuli, uključujući osnovnu petlju agenta, nalazi se u dijelu kodne baze Codex CLI-ja koji se zove „Codex core⁠(otvara se u novom prozoru)“. Codex core istodobno je biblioteka u kojoj se nalazi sav kȏd agenta i runtime koji se može pokrenuti za izvršavanje petlje rada agenta i upravljanje postojanošću jednog Codex threada (razgovora).

Da bi bio koristan, Codex harness mora biti dostupan klijentima. Tu na scenu stupa App Server.

Dijagram s naslovom „App server process flow.” Klijent šalje JSON-RPC poruke u stdio reader, koji prosljeđuje zahtjeve u Codex message processor. Procesor komunicira s thread managerom i core threadom putem dohvaćanja threadova, thread handlea, poslanih zahtjeva te događaja i ažuriranja, a zatim vraća odgovore klijentu.

App Server istodobno je JSON-RPC protokol između klijenta i poslužitelja i dugotrajni proces koji pokreće Codex core threadove. Kao što se vidi na gornjem dijagramu, App Server proces ima četiri glavne komponente: stdio reader, Codex message processor, thread manager i core threads. Thread manager pokreće jednu core sesiju za svaki thread, a Codex message processor zatim izravno komunicira sa svakom core sesijom kako bi slao zahtjeve klijenta i primao ažuriranja.

Jedan zahtjev klijenta može rezultirati velikim brojem ažuriranja događaja, a upravo ti detaljni događaji omogućuju izgradnju bogatog korisničkog sučelja povrh App Servera. Nadalje, stdio reader i Codex message processor služe kao prevoditeljski sloj između klijenta i Codex core threadova. Oni prevode JSON-RPC zahtjeve klijenta u Codex core operacije, slušaju interni tok događaja Codex corea te niskorazinske događaje pretvaraju u mali skup stabilnih JSON-RPC notifikacija namijenjenih UI-ju.

Protokol JSON-RPC između klijenta i poslužitelja aplikacije potpuno je dvosmjeran. Tipični thread sadrži zahtjev klijenta i brojne obavijesti poslužitelja. Osim toga, poslužitelj može inicirati zahtjeve kad je agentu potreban unos, primjerice odobrenje, te zatim pauzirati turn dok klijent ne odgovori.

Osnovni elementi razgovora

Zatim ćemo raščlaniti osnovne elemente razgovora, gradivne blokove protokola App Servera. Dizajniranje API-ja za petlju agenta je izazovno jer interakcija između korisnika i agenta nije jednostavna razmjena zahtjeva i odgovora. Jedan korisnički zahtjev može se razviti u strukturirani slijed radnji koje klijent treba vjerno prikazati: korisnikov unos, agentov postupni napredak, artefakti nastali usput (npr. razlike). Kako bismo taj tijek interakcije učinili jednostavnim za integraciju i otpornim u različitim korisničkim sučeljima, odlučili smo se za tri osnovna elementa s jasnim granicama i životnim ciklusima:

1. Item: Item je atomska jedinica ulaza/izlaza u Codexu. Itemi su tipizirani (npr. user message, agent message, tool execution, approval request, diff) i svaki ima jasno definiran životni ciklus:.

item/started kad item započinje
neobavezni događaji item/*/delta dok sadržaj pristiže kao tok (za streaming tipove itema)
item/completed kad se item dovrši sa svojim završnim payloadom

Ovaj životni ciklus omogućuje klijentima da započnu prikaz odmah na started, da streamaju postupna ažuriranja na delta te da dovrše prikaz na completed.

2. Turn: turn je jedna jedinica rada agenta pokrenuta korisničkim unosom. Započinje kad klijent pošalje unos (primjerice „run tests and summarize failures”) i završava kad agent dovrši izradu izlaza za taj unos. Turn sadrži niz itema koji predstavljaju međukorake i izlaze koji pritom nastaju.

3. Thread: thread je postojani spremnik za trajnu Codex sesiju između korisnika i agenta Sadrži više turnova. Threadovi se mogu stvarati, nastavljati, granati i arhivirati. Povijest threada se čuva kako bi se klijenti mogli ponovno povezati i prikazati dosljednu vremensku liniju.

Zatim ćemo pogledati pojednostavljeni razgovor između klijenta i agenta, pri čemu je razgovor predstavljen osnovnim elementima:

Dijagram s oznakom „Client-server protocol message flow: Initialization handshake.” Klijent poslužitelju šalje zahtjev initialize s clientInfo. Poslužitelj odgovara result eventom koji sadrži userAgent string „my_client/1.0”.

Na početku razgovora klijent i poslužitelj moraju uspostaviti initialize handshake. Klijent mora poslati jedan zahtjev initialize prije bilo koje druge metode, a poslužitelj to potvrđuje odgovorom. Time se poslužitelju daje prilika da objavi svoje mogućnosti te da se obje strane usuglase oko verzije protokola, značajki koje se uključuju ili isključuju, i zadanih postavki prije nego što započne stvarni rad. Evo primjera payloada iz OpenAI proširenja za VS Code:

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}

Ovako izgleda odgovor poslužitelja:

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 s naslovom „Tijek poruka protokola klijent – poslužitelj: životni ciklus threadova i turnova.” Klijent poslužitelju šalje zahtjeve thread/start i turn/start. Poslužitelj emitira događaje thread/started, turn/started, item/started i item/completed, koji prikazuju turn u kojem je korisnička poruka „pokreni testove i sažmi neuspjehe”.

Kad klijent pošalje novi zahtjev, najprije će se stvoriti thread, a zatim turn. Poslužitelj će zatim poslati obavijesti o napretku (thread/started i turn/started). Također će vratiti unose koje prepoznaje kao iteme, poput korisničke poruke ovdje.

Dijagram s naslovom „Client-server protocol message flow: Tool execution with optional approval.” Tijekom poziva alata poslužitelj emitira item/started, zatim item/commandExecution/requestApproval s razlogom („run tests”). Klijent vraća događaj odobrenja (allow/deny). Nakon toga poslužitelj emitira item/completed koji prikazuje izvršenje naredbe („pnpm test”).

Pozivi alata također se šalju natrag klijentu kao itemi. Osim toga, prije nego što može izvršiti neku radnju, poslužitelj traži odobrenje klijenta slanjem zahtjeva s poslužitelja. Odobrenje pauzira turn dok klijent ne odgovori s „allow” ili „deny”. Ovako izgleda tijek odobravanja u proširenju za VS Code:

Upit za dopuštenje u sučelju s tamnom temom koji pita: „Do you want to allow me to run pnpm test for this workspace?” Prikazuje opcije: 1) Yes, 2) Yes and don’t ask again for commands starting with pnpm test i 3) Ne, s gumbom „Submit” na dnu.

Dijagram s naslovom „Client-server protocol message flow: Streaming agent message flow.” Poslužitelj streama poruku asistenta u dijelovima: item/started, dva događaja agentMessage/delta („ran 3 tests.”, „all passed”), zatim item/completed. Turn završava s turn/completed.

Na kraju, poslužitelj šalje poruku agenta i završava turn s turn/completed. Delta događaji poruka agenta vraćaju dijelove poruke sve dok se poruka ne finalizira s item/completed.

Poruke u dijagramu su pojednostavljene radi bolje čitljivosti. Ako želite vidjeti JSON za cijeli turn, možete pokrenuti testni klijent iz repozitorija Codex CLI:

Bash

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

Integracija s klijentima

Sad ćemo pogledati kako različite klijentske površine ugrađuju Codex putem App Servera. Obuhvatit ćemo tri obrasca: lokalne aplikacije i IDE-ove, Codex web runtime i TUI.

Dijagram s naslovom „Codex clients integrated with Codex harness via app server.” Klijenti prve strane (Codex desktop aplikacija, TUI/CLI, Web Runtime) i integracije trećih strana (JetBrains IDE-ovi, VS Code, Xcode) komuniciraju s Codex harnessom putem JSON-RPC poziva.

U sva tri slučaja prijenos se odvija putem JSON-RPC-a preko stdio-a (JSONL). JSON-RPC olakšava izradu klijentskih vezivanja u programskom jeziku po vašem izboru. Codex površine i partnerske integracije implementirale su App Server klijente u jezicima kao što su Go, Python, TypeScript, Swift i Kotlin. Za TypeScript možete generirati definicije izravno iz Rust protokola pokretanjem:

Bash

1codex app-server generate-ts

Za druge jezike generirajte paket JSON sheme i proslijedite ga u svoj preferirani generator koda pokretanjem:

Bash

1codex app-server generate-json-schema

Lokalne aplikacije i IDE-ovi

Snimka zaslona VS Codea s pokrenutim proširenjem Codex. Otvorena je Rust testna datoteka, a ispod nje panel Codex opisuje pokretanje samo fmt i cargo test -p codex-app-server te izvještava da su formatiranje i testovi u tijeku, dok se čeka konačni rezultat prolaz/pad.

Lokalni klijenti obično paketiraju ili dohvaćaju binarnu datoteku App Servera specifičnu za platformu, pokreću je kao dugotrajni podređeni proces i drže otvoren dvosmjerni stdio kanal za JSON-RPC. Primjerice, u našem proširenju za VS Code i u desktop aplikaciji isporučeni artefakt uključuje binarnu datoteku Codexa specifičnu za platformu i prikvačen je na testiranu verziju kako bi klijent uvijek pokretao točno onu verziju koda koju smo validirali.

Nije svaka integracija u mogućnosti često isporučivati ažuriranja za klijente. Neki partneri, poput Xcodea, odvajaju cikluse izdanja tako da klijent ostaje stabilan i omogućuju mu da se po potrebi usmjeri na noviju binarnu datoteku App Servera. Na taj način mogu usvojiti poboljšanja na strani poslužitelja (npr. bolje automatsko sažimanje u Codex jezgri ili novopodržane konfiguracijske ključeve) i uvoditi ispravke pogrešaka bez čekanja na izdanje klijenta. JSON-RPC sloj App Servera dizajniran je tako da zadrži kompatibilnost sa starijim klijentima, pa stariji klijenti mogu sigurno komunicirati s novijim poslužiteljima.

Codex Web

Snimka zaslona web-sučelja Codexa koja prikazuje ažuriranje s naslovom „Update login success message”. Lijevi panel sažima promjene, testove i izmijenjene datoteke, dok desni panel prikazuje diff koda za login.rs s ažuriranim formuliranjem poruke o uspješnoj prijavi.

Codex Web koristi Codex harness, ali ga pokreće u okruženju koje koristi kontejnere. Radnik priprema kontejner s preuzetim radnim prostorom, u njemu pokreće binarnu datoteku App Servera i održava dugotrajni JSON-RPC kanal preko stdio². Web-aplikacija (koja se izvršava u kartici korisnikova preglednika) komunicira s poslužiteljskom stranom Codexa putem HTTP-a i SSE-a, koji streama događaje zadataka koje proizvodi radnik. Time se korisničko sučelje na strani preglednika održava laganim, a istodobno dobivamo dosljedno okruženje za izvršavanje na desktopu i webu.

Budući da su web-sesije prolazne (kartice se zatvaraju, mrežne veze pucaju), web-aplikacija ne može biti pouzdan izvor za dugotrajne zadatke. Zadržavanje stanja i napretka na poslužitelju znači da se rad nastavlja čak i ako kartica nestane. Streaming protokol i spremljene sesije threada omogućuju da se nova sesija jednostavno ponovno poveže, nastavi ondje gdje je stala i nadoknadi propušteno bez ponovne izgradnje stanja na strani klijenta.

TUI/Codex CLI

Snimka zaslona terminala u kojem se pokreće Codex CLI. Prikazuje banner OpenAI Codex s modelom gpt-5.2-codex medium, korisnička naredba „explain app server to me” i status „Working”. Ispod se pojavljuje prijedlog „write tests for @filename”, uz ponuđene opcije prečaca.

Povijesno gledano, TUI je bio „izvorni“ klijent koji se izvršavao u istom procesu kao i petlja agenta te je izravno komunicirao s osnovnim tipovima u Rustu, umjesto s protokolom poslužitelja aplikacije. To je omogućilo brzu ranu iteraciju, ali je TUI također učinilo posebnim sučeljem.

Sad kad postoji App Server ji, planiramo refaktorirati TUI⁠(otvara se u novom prozoru) tako da ga koristi i da se ponaša kao svaki drugi klijent: pokrene podređeni proces App Servera, komunicira putem JSON-RPC-a preko stdio-a te prikazuje iste streaming događaje i odobrenja. Ovo omogućuje radne tijekove u kojima se TUI može povezati s Codex poslužiteljem koji radi na udaljenom računalu, zadržavajući agenta blizu računalnih resursa i omogućujući nastavak rada čak i ako prijenosno računalo prijeđe u stanje mirovanja ili se odspoji, uz istodobnu isporuku ažuriranja uživo i lokalnih kontrola.

Odabir pravog protokola

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

JSON-RPC protokoli

Codex kao MCP poslužitelj

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

Protokoli za upravljanje agentima između različitih pružatelja usluga

Neki ekosustavi nude prenosivo sučelje koje može ciljati više pružatelja modela i izvršnih okruženja. To može biti dobar izbor ako želite jednu apstrakciju koja koordinira više agenata. Nedostatak je u tome što se ti protokoli često svode na zajednički podskup mogućnosti, što može otežati prikaz bogatijih interakcija, osobito kada su važne semantike alata i sesija specifične za pojedinog pružatelja. Ovo se područje brzo razvija i očekujemo da će se pojaviti više zajedničkih standarda kako budemo utvrđivali najbolje osnovne elemente za prikaz stvarnih radnih tokova agenata (skills⁠(otvara se u novom prozoru) je dobar primjer).

Codex App Server

Odaberite App Server kad želite da se puni Codex harness izloži kao stabilan tok događaja prilagođen korisničkom sučelju. Dobivate punu funkcionalnost petlje agenta i druge podržavajuće značajke kao što su prijava putem ChatGPT‑a, otkrivanje modela i upravljanje konfiguracijom. Glavni trošak je integracijski rad, jer trebate izraditi klijentsko povezivanje za JSON-RPC u svom jeziku. U praksi, međutim, Codex može obaviti velik dio teškog posla ako mu date JSON shemu i dokumentaciju. Mnogi timovi s kojima smo radili uspjeli su brzo uspostaviti funkcionalnu integraciju koristeći Codex.

Drugi načini za ugradnju Codexa

Codex Exec⁠(otvara se u novom prozoru)

Lagani, skriptabilni CLI način rada za jednokratne zadatke i CI pokretanja. Dobar je izbor za automatizaciju i cjevovode u kojima želite jednom naredbom izvršiti zadatak do kraja bez interakcije, emitirati strukturirani izlaz za zapise i završiti s jasnim signalom uspjeha ili neuspjeha.

Codex SDK⁠(otvara se u novom prozoru)

TypeScript biblioteka za programsko upravljanje lokalnim Codex agentima iz vlastite aplikacije. Najprikladnija je kad želite izvorno programsko sučelje za poslužiteljske alate i radne tokove bez izgradnje zasebnog JSON-RPC klijenta. Budući da je isporučena ranije od App Servera, trenutačno podržava manje jezika i manji opseg funkcionalnosti. Ako postoji interes razvojnih programera, mogli bismo dodati dodatne SDK-ove koji obavijaju protokol App Servera kako bi timovi mogli pokriti veći opseg Codex harnessa bez pisanja vlastitih JSON-RPC vezivanja.

Idemo dalje

U ovoj objavi podijelili smo kako pristupamo dizajniranju novog standarda za interakciju s agentima i kako Codex harness pretvaramo u stabilan protokol prilagođen klijentima. Objasnili smo kako App Server izlaže Codex core, omogućuje klijentima upravljanje cjelokupnom petljom rada agenta te pokreće širok raspon površina, uključujući TUI, lokalne IDE integracije i web runtime.

Ako vam je ovo potaknulo ideje za integraciju Codexa u vaše radne tokove, vrijedi isprobati App Server. Sav izvorni kôd nalazi se u otvorenom repozitoriju⁠(otvara se u novom prozoru) Codex CLI-ja. Slobodno podijelite povratne informacije i prijedloge značajki. Veselimo se vašim dojmovima i nastavku rada na tome da agenti budu dostupniji svima.

Autor

Celia Chen

Priznanja

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

Bilješke

1
Koristimo varijantu „JSON-RPC lite”: zadržava oblik zahtjev/odgovor/notifikacija, ali izostavlja zaglavlje "jsonrpc": "2.0" te je uokvirena kao JSONL preko stdio-a, a ne kao strogi JSON-RPC 2.0.
2
„stdio” se odnosi na stdin/stdout App Servera unutar kontejnera. U poslužiteljskim okruženjima ti se tokovi često prenose putem postojane mrežne veze (npr. nalik WebSocketu) prema izvršnom okruženju kontejnera, tako da se ponašaju kao stdio čak i kada nisu doslovni lokalni pipe.

Nastavite čitati

Prikaži sve

Razvoj poreznih agenata koji se sami poboljšavaju uz Codex

Inženjerstvo27. svi 2026.

Izgradnja sigurnog, učinkovitog sandboxa za omogućavanje Codexa u sustavu Windows

Inženjerstvo13. svi 2026.

Odakle su došli goblini

Inženjerstvo5. svi 2026.