Menjalankan Codex CLI sebagai worker di osFoundry

Di akhir panduan ini, sebuah agen di aplikasi desktop osFoundry memakai cli:codex:agent sebagai modelnya. Saat ada pekerjaan yang sampai ke agen itu, aplikasi menjalankan codex exec di Mac Anda dengan login ChatGPT Anda sendiri. Run tersebut berlangsung di folder yang sudah Anda izinkan. Apa yang dilaporkan Codex, yaitu reasoning-nya, perintah yang dijalankannya, dan pesan akhirnya, muncul sebagai baris-baris di run osFoundry. Tidak ada API key OpenAI yang terlibat sama sekali.

Siapa mengerjakan apa

	Codex CLI	osFoundry
Login	Login ChatGPT miliknya sendiri (codex login), disimpan oleh Codex	Tidak pernah melihatnya. Menghapus CODEX_API_KEY, OPENAI_API_KEY, dan OPENAI_BASE_URL dari environment proses anak agar run tetap memakai langganan
Panggilan model	Langsung ke OpenAI dari proses codex	Mencatat biaya sebagai 0.0 (langganan, tidak dihitung per pemakaian)
Tool	Shell dan pengeditan file miliknya sendiri, di dalam folder kerja	Tool miliknya sendiri (misalnya memory_search), disajikan dari bridge MCP loopback di 127.0.0.1, hanya saat git worktree mengisolasi run
Persetujuan	Tidak ada selama run: exec bersifat non-interaktif, approval_policy="never"	Setiap panggilan tool lewat bridge melewati orchestrator::execute_tool dan gerbang kebijakannya
Output	Satu event JSON per item yang selesai di stdout (--json)	Mengubah setiap event menjadi baris progres atau teks jawaban; menyimpan ekor stderr untuk error
File Anda	Dibaca dan ditulis di folder atau worktree	Memilih folder: repositori di surface Code, atau kalau tidak ada, folder lokal pertama yang Anda izinkan

Penyiapan

1. Instal Codex CLI dan login sekali. osFoundry mencari binary-nya di PATH, di ~/.codex/bin, dan di dalam /Applications/Codex.app (instalasi lewat cask menaruhnya di Contents/Resources/codex, tempat which codex tidak menemukan apa pun).

   codex login

1. Buka ikon kunci di header (tooltip-nya berbunyi API Keys (BYOK)), lalu pindah ke tab External AI (AI eksternal). Baris Codex menampilkan Installed, badge No live stream, dan id model otonom. Codex tidak punya id chat, jadi hanya satu id yang muncul:

   Codex   Installed   No live stream   Enabled
   cli:codex:agent (autonomous)
   osFoundry tools require git-worktree isolation for Codex (it trades its
   own sandbox for git safety). Point it at a git repo folder.

Contoh: Claude Code dan Codex di tab External AI

Kalau Anda belum login, tombol Sign in membuka terminal yang menjalankan codex login.

1. Klik Verify sign-in (verifikasi login). Tombol ini menjalankan satu completion kecil lewat builder yang sama dengan yang dipakai run sungguhan:

   codex exec "Reply with the single word: ok" \
     --json --skip-git-repo-check --ignore-user-config --ignore-rules \
     -s read-only -c 'approval_policy="never"'

--ignore-rules hanya ditambahkan bila codex exec --help mencantumkannya. osFoundry bertanya langsung ke binary karena build lama menolak flag itu dan membuat seluruh run gagal.

1. Beri agen sebuah folder. Tambahkan satu di Settings → Local Folders. Jika Anda juga ingin Codex bisa menjangkau tool milik osFoundry, jadikan folder itu repositori git, lalu di surface Code klik Enable for this workspace. Setelah itu setiap run mendapat branch dan salinan kerjanya sendiri.

2. Buka agen di Studio dan atur Model Preference. Pemilihnya mencantumkan Codex di bagian CLI agents sebagai cli:codex:agent (provider "External AI (subscription)"). Atur Runtime Role ke worker jika agen harus mengambil langkah-langkah worker.

Saat pekerjaan diserahkan, perintahnya terlihat seperti ini. Tanpa worktree, sandbox milik Codex sendiri tetap dipakai:

codex exec "<system prompt>

User: <task>" \
  --json --skip-git-repo-check --ignore-user-config --ignore-rules \
  -C /path/to/folder -s workspace-write -c 'approval_policy="never"'

Dengan worktree, flag sandbox diganti dan bridge dipasang:

codex exec "<system prompt>

User: <task>" \
  --json --skip-git-repo-check --ignore-user-config --ignore-rules \
  -C /path/to/worktree \
  --dangerously-bypass-approvals-and-sandbox \
  -c 'mcp_servers.osfoundry.url="http://127.0.0.1:<port>/mcp"' \
  -c 'mcp_servers.osfoundry.http_headers={Authorization="Bearer <per-run token>"}'

Codex tidak punya flag untuk menambahkan system prompt, jadi osFoundry menaruh system prompt agen di depan percakapan, dipisahkan oleh satu baris kosong. Giliran-giliran sebelumnya menyusul sebagai transkrip User: / Assistant:.

Sebuah run

Contoh. Berikut baris-baris event yang ditulis Codex dan baris-baris yang ditampilkan osFoundry dari event tersebut. Teksnya hanya ilustrasi, tetapi tipe event dan format barisnya sesuai dengan yang dipetakan oleh kode.

$ codex exec … --json
{"type":"item.completed","item":{"type":"reasoning","text":"Check what the tests cover first."}}
{"type":"item.completed","item":{"type":"mcp_tool_call","server":"osfoundry","tool":"memory_search"}}
{"type":"item.completed","item":{"type":"command_execution","command":"npm test"}}
{"type":"item.completed","item":{"type":"file_change","path":"src/date.ts","change":"edit"}}
{"type":"item.completed","item":{"type":"agent_message","text":"Fixed the off-by-one in parseRange; 42 tests pass."}}
{"type":"turn.completed","usage":{"input_tokens":…,"cached_input_tokens":…,"output_tokens":…}}

osFoundry run
  Thinking: Check what the tests cover first.
  Using memory_search…
  Using shell — npm test
  Edited src/date.ts
  Fixed the off-by-one in parseRange; 42 tests pass.

Codex menyebut tool bridge dalam dua field, server dan tool, sehingga barisnya menampilkan memory_search tanpa awalan mcp__osfoundry__. Jawaban datang sebagai item agent_message utuh, bukan per token. Baris progres muncul satu per satu selagi Codex masih bekerja. Teks setiap pesan baru muncul setelah Codex selesai menulis pesan itu. Jumlah token diambil dari turn.completed, dan di situ input_tokens tidak mencakup bagian yang di-cache, jadi osFoundry menambahkan kembali cached_input_tokens untuk mendapatkan ukuran konteks.

Di mana batasnya

Tidak ada mode chat cli:codex. Konfigurasi Codex tidak punya sakelar untuk mematikan tool shell-nya, jadi "completion tanpa tool" lewat Codex tetap saja agen yang memegang shell. osFoundry menolak id chat itu alih-alih menjalankannya diam-diam: "codex has no tool-less chat mode — use 'cli:codex:agent' for an autonomous run instead."

-s adalah sandbox untuk filesystem dan perintah. workspace-write membatasi di mana Codex boleh menulis dan apa yang bisa dilakukan perintahnya. Flag ini tidak membatasi tool mana yang boleh dipanggil model, dan Codex tidak punya padanan --disallowedTools. Karena itu, saat Anda menambahkan Codex ke sebuah channel, panel Add agent menyebutkan bahwa cakupan tool tidak bisa ditegakkan pada harness ini.

Tool osFoundry membutuhkan worktree. Dalam exec non-interaktif, Codex membatalkan setiap panggilan tool MCP kecuali persetujuan dan sandbox sama-sama di-bypass. Mode persetujuan per tool, proyek tepercaya, dan approval_policy="never" semuanya tetap membatalkan. Jadi aplikasi melakukan satu pertukaran saja: ia melepas sandbox OS milik Codex hanya bila isolasi git menggantikan posisinya. Tanpa worktree, run tetap memakai -s workspace-write, bridge tidak dipasang, dan satu baris di run memberitahukan hal itu.

Setup Codex pribadi Anda tidak ikut campur. --ignore-user-config melewati ~/.codex/config.toml, sehingga server MCP yang Anda konfigurasi untuk diri sendiri tidak ikut masuk ke run osFoundry. Autentikasi tetap dimuat dari CODEX_HOME. --ignore-rules juga menjauhkan file execpolicy .rules.

Setiap run punya batas waktu nyata: 1.800 detik untuk run otonom, 300 detik untuk probe login. Saat waktunya habis, proses anak dilepas dan dimatikan.

Selanjutnya

Arahkan agen ke repositori git kecil, aktifkan agen kode untuk workspace tersebut, lalu beri tugas yang membutuhkan perintah shell sekaligus sesuatu dari memori osFoundry. Dengan begitu Anda bisa melihat Using shell dan Using memory_search… muncul di run yang sama. Halaman agen Studio menunjukkan letak Model Preference, dan build desktop tersedia di halaman unduhan.