การใช้งาน Codex Harness: วิธีที่ OpenAI สร้าง App Server

• OpenAI ได้สร้างและเปิดให้ใช้งานสถาปัตยกรรม App Server แบบมาตรฐานและโปรโตคอล JSON-RPC เพื่อให้สามารถผสานรวม Codex เข้ากับผลิตภัณฑ์ของตนเองได้
• ในช่วงแรกเริ่มจาก TUI harness ที่เน้น CLI เป็นศูนย์กลาง แต่ภายหลังได้นำ โปรโตคอล JSON-RPC มาใช้ ทำให้ไคลเอนต์หลายประเภท เช่น IDE, เว็บ, แอปโลคัล สามารถใช้ agent loop เดียวกันร่วมกันได้
• App Server คือโปรเซสที่รันระยะยาวซึ่งโฮสต์ไลบรารีแกนกลางของ Codex และเปิดประสบการณ์เอเจนต์ทั้งหมดให้ไคลเอนต์ใช้งาน ไม่ว่าจะเป็น การจัดการวงจรชีวิตของเธรด, การตั้งค่า/การยืนยันตัวตน และการรันเครื่องมือ
• ด้วย conversation primitives สามอย่าง ได้แก่ item, turn และ thread จึงสามารถจัดโครงสร้างปฏิสัมพันธ์ที่ซับซ้อนของ agent loop และสร้าง UI ที่สมบูรณ์ได้
• ใช้ harness เดียวกันซ้ำได้บนหลายพื้นผิว เช่น VS Code, JetBrains, Xcode, แอปเดสก์ท็อป และเว็บรันไทม์ พร้อมรองรับ client bindings หลายภาษา เช่น Go, Python, TypeScript, Swift และ Kotlin
• ยังมีวิธีผสานรวมทางเลือกอย่าง MCP server, โหมด CLI และ TypeScript SDK แต่ App Server ได้กลายเป็นมาตรฐานการผสานรวมหลัก
• OpenAI จะคง App Server ไว้เป็น เส้นทางหลักสำหรับการผสานรวม Codex และสนับสนุนให้ทุกคนนำ Codex ไปเชื่อมกับเวิร์กโฟลว์ของตนเองผ่านรีโพซิทอรี CLI แบบโอเพนซอร์ส

---

พื้นหลังเบื้องต้นของ App Server

• ในช่วงแรกเป็นวิธีที่ใช้ได้จริงเพื่อ นำ Codex harness กลับมาใช้ซ้ำ ในหลายผลิตภัณฑ์ แต่ค่อยๆ พัฒนาเป็น โปรโตคอลมาตรฐาน
• Codex CLI เริ่มต้นจาก TUI (terminal user interface) และเมื่อสร้างส่วนขยาย VS Code ก็จำเป็นต้องมีวิธีรัน harness เดียวกันบน UI ของ IDE
  • จึงต้องรองรับรูปแบบปฏิสัมพันธ์ที่หลากหลายซึ่งเกินกว่าคำขอ/คำตอบ เช่น การสำรวจ workspace, การสตรีมความคืบหน้าของการให้เหตุผล, การแสดง diff
• ตอนแรกมีความพยายาม เปิด Codex เป็น MCP server แต่ยากที่จะรักษา semantics ของ MCP ให้อยู่ในรูปแบบที่เหมาะกับ VS Code
• ทางเลือกที่ใช้คือการนำ โปรโตคอล JSON-RPC ที่สะท้อนลูปของ TUI มาใช้ ซึ่งกลายเป็นเวอร์ชันแรกอย่างไม่เป็นทางการของ App Server
  • ในเวลานั้นไม่ได้คาดว่าจะมีไคลเอนต์อื่นมาพึ่งพา จึงไม่ได้ออกแบบให้เป็น API ที่เสถียร
• เมื่อการนำ Codex ไปใช้ขยายวงกว้างขึ้น ทั้งทีมภายในและพาร์ตเนอร์ภายนอก (เช่น JetBrains, Xcode) ต้องการความสามารถในการฝัง harness ลงในผลิตภัณฑ์ของตนเอง
  • จึงต้องออกแบบ platform surface ที่สามารถพัฒนาโปรโตคอลต่อไปได้โดยยัง คงความเข้ากันได้ย้อนหลัง

โครงสร้างภายในของ Codex harness

• Codex core คือทั้งไลบรารีที่รวมโค้ดเอเจนต์ทั้งหมด และรันไทม์ที่รัน agent loop พร้อมจัดการความคงอยู่ของ Codex thread (การสนทนา) หนึ่งรายการ
• นอกเหนือจาก agent loop หลัก ยังมีพื้นที่ความสามารถสำคัญอีกสามส่วน:
  • วงจรชีวิตและความคงอยู่ของเธรด: สร้าง, เรียกคืน, fork, เก็บถาวรเธรด และรักษาบันทึกเหตุการณ์ไว้เพื่อให้ไคลเอนต์เชื่อมต่อใหม่และเรนเดอร์ไทม์ไลน์ที่สอดคล้องกันได้
  • การตั้งค่าและการยืนยันตัวตน: โหลดการกำหนดค่า, จัดการค่าเริ่มต้น, จัดการสถานะข้อมูลรับรอง และรันโฟลว์ยืนยันตัวตนอย่าง "เข้าสู่ระบบด้วย ChatGPT"
  • การรันและการขยายเครื่องมือ: รันเครื่องมือ shell/ไฟล์ใน sandbox และเชื่อมการผสานรวมอย่าง MCP server และ skills เข้ากับ agent loop ภายใต้โมเดลนโยบายที่สอดคล้องกัน

สถาปัตยกรรม App Server

• App Server คือทั้ง โปรโตคอล JSON-RPC ระหว่างไคลเอนต์กับเซิร์ฟเวอร์ และโปรเซสที่รันระยะยาวซึ่งโฮสต์ Codex core thread
• มีองค์ประกอบหลักสี่ส่วน:
  • stdio reader: ทำหน้าที่อ่านอินพุตจากไคลเอนต์
  • Codex message processor: สื่อสารโดยตรงกับแต่ละ core session เพื่อส่งคำขอจากไคลเอนต์และรับอัปเดตกลับมา
  • thread manager: เริ่มหนึ่ง core session สำหรับแต่ละ thread
  • core thread: รัน agent loop จริง
• คำขอหนึ่งรายการจากไคลเอนต์อาจทำให้เกิดอัปเดตเหตุการณ์จำนวนมาก และเหตุการณ์ย่อยเหล่านี้ช่วยให้สร้าง UI ที่สมบูรณ์ ได้
• stdio reader และ Codex message processor ทำหน้าที่เป็น ชั้นแปลงข้อมูล ที่แปลงคำขอ JSON-RPC ของไคลเอนต์ให้เป็นงานของ Codex core และแปลงสตรีมเหตุการณ์ภายในให้เป็นการแจ้งเตือน JSON-RPC ที่เสถียรและพร้อมใช้งานใน UI
• โปรโตคอล JSON-RPC ระหว่างไคลเอนต์กับ App Server เป็นแบบ สองทางเต็มรูปแบบ
  • เมื่อเอเจนต์ต้องการอินพุต เช่น การอนุมัติ เซิร์ฟเวอร์สามารถเริ่มคำขอเองได้ และพัก turn ไว้จนกว่าไคลเอนต์จะตอบกลับ

Conversation primitives

• แกนสำคัญของการออกแบบ API สำหรับ agent loop คือปฏิสัมพันธ์ระหว่างผู้ใช้กับเอเจนต์ไม่ได้เป็นเพียงคำขอ/คำตอบแบบง่าย แต่ดำเนินไปเป็น ชุดงานที่มีโครงสร้าง
• มี primitive หลักสามอย่าง:

• Item

  • หน่วยพื้นฐานของ อินพุต/เอาต์พุต ใน Codex
  • มีการระบุประเภท เช่น ข้อความผู้ใช้, ข้อความเอเจนต์, การรันเครื่องมือ, คำขออนุมัติ, diff เป็นต้น
  • มีวงจรชีวิตชัดเจน: item/started → item/*/delta แบบเลือกได้ (สตรีม) → item/completed (payload สุดท้าย)
  • ไคลเอนต์สามารถเริ่มเรนเดอร์ได้ทันทีที่ started, สตรีมอัปเดตแบบค่อยเป็นค่อยไปที่ delta, และจบสมบูรณ์ที่ completed

• Turn

  • หนึ่งหน่วยของงานเอเจนต์ ที่เริ่มจากอินพุตของผู้ใช้
  • ตัวอย่าง: เมื่อไคลเอนต์ส่ง "run tests and summarize failures" จะเป็นการเริ่ม turn และ turn จะสิ้นสุดเมื่อเอเจนต์สร้างเอาต์พุตเสร็จ
  • หนึ่ง turn จะมีชุดของ item ที่แสดงขั้นตอนระหว่างทางและผลลัพธ์

• Thread

  • คอนเทนเนอร์แบบถาวร สำหรับ Codex session ที่กำลังดำเนินอยู่ระหว่างผู้ใช้กับเอเจนต์
  • มีหลาย turn และสามารถสร้าง, เรียกคืน, fork, เก็บถาวรได้
  • บันทึกของ thread ถูกเก็บรักษาไว้อย่างต่อเนื่อง ทำให้ไคลเอนต์เชื่อมต่อใหม่และเรนเดอร์ไทม์ไลน์เดิมได้อย่างสอดคล้อง

ลำดับการสนทนาระหว่างไคลเอนต์กับเซิร์ฟเวอร์

• เมื่อเริ่มการสนทนา ไคลเอนต์และเซิร์ฟเวอร์ต้องตั้งค่า handshake initialize
  • ไคลเอนต์ต้องส่งคำขอ initialize เพียงครั้งเดียวก่อนเมธอดอื่น และเซิร์ฟเวอร์ตอบกลับเพื่อยืนยัน
  • ทั้งสองฝ่ายตกลงกันเรื่องการกำหนดเวอร์ชันของโปรโตคอล, feature flags และค่าเริ่มต้น
• เมื่อมีคำขอใหม่ เซิร์ฟเวอร์จะสร้าง thread แล้วสร้าง turn จากนั้นส่งการแจ้งเตือน thread/started และ turn/started
• การเรียกใช้เครื่องมือ ก็ถูกส่งไปยังไคลเอนต์ในรูปของ item เช่นกัน และเซิร์ฟเวอร์สามารถขออนุมัติให้รันงานได้
  • เมื่อมีคำขออนุมัติ turn จะถูกพักไว้จนกว่าไคลเอนต์จะตอบว่า "อนุญาต" หรือ "ปฏิเสธ"
• เซิร์ฟเวอร์ส่งข้อความเอเจนต์และจบ turn ด้วย turn/completed
  • เหตุการณ์ delta ของข้อความเอเจนต์ จะสตรีมบางส่วนของข้อความ ก่อนจะปิดท้ายอย่างสมบูรณ์ด้วย item/completed
• หากต้องการดู JSON ของทั้ง turn สามารถรันคำสั่ง codex debug app-server send-message-v2 "run tests and summarize failures" ได้

รูปแบบการผสานรวมกับไคลเอนต์

• แอปโลคัลและ IDE

  • วิธีขนส่งคือ JSON-RPC (JSONL) ผ่าน stdio
  • ไคลเอนต์โลคัลจะบันเดิลหรือนำเข้า App Server binary ตามแพลตฟอร์ม แล้วรันเป็น subprocess ระยะยาว
  • ในส่วนขยาย VS Code และแอปเดสก์ท็อป จะรวม Codex binary ตามแพลตฟอร์ม ไว้ในอาร์ติแฟกต์สำหรับแจกจ่าย และล็อกไว้กับเวอร์ชันที่ผ่านการทดสอบแล้ว
  • มีการติดตั้งใช้งาน App Server client แล้วในหลายภาษา เช่น Go, Python, TypeScript, Swift และ Kotlin
    • TypeScript: สร้าง definition ได้โดยตรงด้วยคำสั่ง codex app-server generate-ts
    • ภาษาอื่น: สร้าง JSON schema bundle ด้วยคำสั่ง codex app-server generate-json-schema แล้วป้อนให้ code generator
  • พาร์ตเนอร์อย่าง Xcode แยกรอบการออกรุ่นโดย คงไคลเอนต์ให้เสถียร และชี้ไปยัง App Server binary ล่าสุด
    • ทำให้ปล่อยการปรับปรุงฝั่งเซิร์ฟเวอร์ (เช่น auto-compaction ที่ดีขึ้น, คีย์การกำหนดค่าใหม่) และการแก้บั๊กได้โดยไม่ต้องรอรีลีสไคลเอนต์
    • เนื่องจาก JSON-RPC surface รองรับความเข้ากันได้ย้อนหลัง ไคลเอนต์รุ่นเก่าจึงสื่อสารกับเซิร์ฟเวอร์รุ่นใหม่ได้อย่างปลอดภัย

• Codex เว็บรันไทม์

  • รันใน สภาพแวดล้อมคอนเทนเนอร์
  • worker จะ provision คอนเทนเนอร์พร้อม workspace ที่เช็กเอาต์แล้ว รัน App Server binary ภายใน และคงช่องทาง JSON-RPC ผ่าน stdio
  • เว็บแอป (เบราว์เซอร์ของผู้ใช้) สื่อสารกับ Codex backend ผ่าน HTTP และ SSE เพื่อสตรีมเหตุการณ์ของงาน
  • ช่วยให้ UI ฝั่งเบราว์เซอร์มีน้ำหนักเบา ขณะเดียวกันก็ให้ รันไทม์ที่สอดคล้องกัน ทั้งบนเดสก์ท็อปและเว็บ
  • เนื่องจากเว็บเซสชันมีอายุสั้น (ปิดแท็บ, เครือข่ายหลุด) ฝั่งเซิร์ฟเวอร์จึงเก็บสถานะและความคืบหน้าไว้
    • แม้แท็บจะหายไป งานก็ยังทำต่อได้ และเซสชันใหม่สามารถเชื่อมต่อกลับมาเพื่อทำต่อจากจุดเดิมได้ง่าย

• แผนรีแฟกเตอร์ TUI

  • TUI เดิมเป็นไคลเอนต์แบบ "native" ที่รันอยู่ในโปรเซสเดียวกับ agent loop และสื่อสารกับ Rust core types โดยตรง ไม่ใช่ผ่านโปรโตคอล App Server
  • มีแผนจะรีแฟกเตอร์ TUI ให้ทำงานเหมือนไคลเอนต์อื่นโดยใช้ App Server
    • สามารถเชื่อมต่อกับ Codex server ที่กำลังรันอยู่บนเครื่องระยะไกลได้
    • ทำให้เอเจนต์ ผูกกับโครงสร้างพื้นฐานการประมวลผลอย่างใกล้ชิด และยังทำงานต่อได้แม้โน้ตบุ๊กเข้าสลีปหรือการเชื่อมต่อหลุด
    • พร้อมทั้งยังให้ live update และความสามารถในการควบคุมจากเครื่องโลคัลต่อไป

การเลือกโปรโตคอลที่เหมาะสม

• แม้ App Server จะเป็นวิธีผสานรวมหลัก แต่ก็ยังมีทางเลือกที่ฟีเจอร์จำกัดกว่าด้วย

• MCP server

  • รัน codex mcp-server แล้วเชื่อมต่อจาก MCP client ใดก็ได้ที่รองรับ stdio server (เช่น OpenAI Agents SDK)
  • เหมาะเมื่อมี เวิร์กโฟลว์ที่ใช้ MCP อยู่แล้ว และต้องการใช้ Codex เป็นเครื่องมือที่เรียกได้
  • ข้อเสีย: ใช้ได้เฉพาะสิ่งที่ MCP รองรับ และปฏิสัมพันธ์เฉพาะของ Codex อย่างการอัปเดต diff อาจจับคู่ได้ไม่ลื่นไหล

• Portable interfaces

  • เหมาะเมื่อจำเป็นต้องมี abstraction เดียวสำหรับผู้ให้บริการโมเดลและรันไทม์หลายราย
  • ข้อเสีย: มักจะลงเอยที่ ชุดความสามารถร่วมขั้นต่ำ ทำให้ยากต่อการแสดงปฏิสัมพันธ์ที่สมบูรณ์
  • พื้นที่นี้กำลังพัฒนาอย่างรวดเร็ว และคาดว่าจะมีมาตรฐานร่วมเพิ่มขึ้นอีก (เช่น agentskills.io)

• App Server

  • เปิด Codex harness แบบเต็มผ่าน สตรีมเหตุการณ์ที่เสถียรและเป็นมิตรกับ UI
  • นอกเหนือจากความสามารถเต็มรูปแบบของ agent loop ยังใช้งานฟังก์ชันสนับสนุนอย่างการเข้าสู่ระบบด้วย ChatGPT, การค้นหาโมเดล และการจัดการการกำหนดค่าได้ด้วย
  • ต้นทุนหลักคือ ต้องสร้าง JSON-RPC bindings ฝั่งไคลเอนต์ ในภาษาที่ใช้งาน
    • หากมี JSON schema และเอกสารประกอบ Codex สามารถช่วยจัดการงานที่ซับซ้อนได้มาก ทำให้หลายทีมผสานรวมได้อย่างรวดเร็ว

• โหมด CLI

  • โหมดแบบสคริปต์น้ำหนักเบาสำหรับงานครั้งเดียวและ การรัน CI
  • รันคำสั่งเดียวแบบไม่โต้ตอบ สตรีมเอาต์พุตแบบมีโครงสร้าง และจบด้วยสัญญาณสำเร็จ/ล้มเหลวที่ชัดเจน
  • เหมาะกับงานอัตโนมัติและ pipeline

• TypeScript SDK

  • ไลบรารี TypeScript สำหรับควบคุม Codex agent แบบโลคัลภายในแอปพลิเคชันของตนเองด้วยโปรแกรม
  • เหมาะเมื่อจำเป็นต้องใช้อินเทอร์เฟซไลบรารีแบบ native โดยไม่ต้องสร้าง JSON-RPC client แยก
  • เปิดตัวก่อน App Server จึงรองรับภาษาน้อยกว่าและมีขอบเขตการใช้งานแคบกว่า
  • มีความเป็นไปได้ที่จะมี SDK เพิ่มเติมที่ครอบโปรโตคอล App Server ตามความสนใจของนักพัฒนา

แผนในอนาคต

• App Server เปิดเผย Codex core ให้ไคลเอนต์สามารถขับเคลื่อน agent loop แบบเต็มได้ และรองรับ พื้นผิวการใช้งานอย่างกว้างขวาง รวมถึง TUI, การผสานรวมกับ IDE แบบโลคัล และเว็บรันไทม์
• ซอร์สโค้ดทั้งหมดเปิดเผยอยู่ในรีโพซิทอรีโอเพนซอร์สของ Codex CLI
• ยินดีรับคำขอฟีเจอร์และความคิดเห็น และมีแผนจะ ปรับปรุงอย่างต่อเนื่อง เพื่อให้ใช้งานเอเจนต์ได้ง่ายยิ่งขึ้น

• เอกสารทางการของ Codex App Server