feat: Codex as an OpenAI-compatible API — use your ChatGPT subscription

services/codex_api.py is the mirror image of claude-code-api: it wraps the local
`codex` CLI so anything speaking the OpenAI chat API can drive your ChatGPT/Codex
subscription. No API key — auth is whatever `codex login` established.

    POST /v1/chat/completions   GET /v1/models   GET /health

Wired end to end: a `codex` service on :8010 (aios start codex), a chat target
and dashboard chip/panel, an entry in the hub's own /v1/models, the interconnect
URL for other agents, and option 2 in the setup wizard next to the Claude
subscription — so both subscription routes are offered before any API key is.

Three real bugs found by testing it against the live CLI rather than assuming:

- Passing a model name that the account can't use makes codex exit 1 with
  "model is not supported". The bridge now sends no -m at all unless explicitly
  asked, letting codex use whatever it's configured for.
- Codex is a *workspace* agent. Pointed at the AIOS repo with -C it answered
  every question with "Ready. What would you like me to work on in <repo>?"
  instead of the question. It now runs in a neutral scratch dir, overridable
  with AIOS_CODEX_WORKDIR when repo context is actually wanted.
- The big one: on Windows `codex` resolves to codex.CMD, and cmd.exe mangles
  newlines inside an argv argument — so every multi-line prompt (i.e. every real
  one, since system+user get flattened) silently arrived truncated and produced
  a generic greeting. The prompt is now piped via stdin with "-", which is
  correct on both platforms.

Uses --output-last-message rather than scraping stdout, because codex streams
reasoning, tool calls and token counts to the terminal and the final answer
can't be reliably picked out of that.

Verified live: healthy on :8010, correct answers to both a factual and a coding
question through the bridge, and through the hub after restart —
"`zip()` pairs items from multiple iterables into tuples, stopping when the
shortest is exhausted."

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: ZD Studios

README.md

@@ -2,7 +2,7 @@
 
 # 🧠 The AI OS
 
-### Nine open-source AI projects. One operating system. One Control Room.
+### Ten open-source AI projects. One operating system. One Control Room.
 
 <p align="center">
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-8B5CF6?style=for-the-badge" alt="MIT License"></a>
@@ -24,6 +24,7 @@
   <img src="https://img.shields.io/badge/+_Caveman-say_less-A16207?style=flat-square" alt="Caveman">
   <img src="https://img.shields.io/badge/+_Ponytail-build_less-DB2777?style=flat-square" alt="Ponytail">
   <img src="https://img.shields.io/badge/+_Ruflo-314_MCP_tools-7C3AED?style=flat-square" alt="Ruflo">
+  <img src="https://img.shields.io/badge/+_Codex-ChatGPT_sub-10A37F?style=flat-square" alt="Codex">
 </p>
 
 **[Install](#-install-one-line)** · **[Control Room](#-the-control-room)** · **[Architecture](#️-architecture)** · **[Commands](#️-command-reference)** · **[Full docs](README.aios.md)** · **[Website](https://zdstudios.github.io/AIOS/)**
@@ -32,7 +33,7 @@
 
 ---
 
-**The AI OS** takes nine independent open-source AI projects and makes them work as **one auto-configured
+**The AI OS** takes ten independent open-source AI projects and makes them work as **one auto-configured
 system** you drive from a single command — **`aios`** — and a single web **Control Room** where you can
 **talk to everything and have the agents talk to each other**.
 
@@ -42,7 +43,7 @@ together, mounts your shared skills, and adds **OpenUI** generative-UI context t
 
 > You can't fuse three runtimes and multiple package managers into a single file — that would just break
 > everything. So "one file" here means **one control surface** (`aios`) + **one dashboard** (the Hub) over
-> nine real, unmodified projects. It installs, configures, wires, runs, tests, and debugs all of them.
+> ten real, unmodified projects. It installs, configures, wires, runs, tests, and debugs all of them.
 
 <div align="center">
 
@@ -115,6 +116,7 @@ aios url                 # open the Control Room
 | **openclaw** | Multi-channel messaging gateway + plugin host | `18789` | [openclaw.ai](https://github.com/openclaw/openclaw) |
 | **CrewAI** | Multi-agent orchestration — role-based crews | `4788` | [crewaiinc/crewai](https://github.com/crewaiinc/crewai) |
 | **claude-code** | Claude Code as an OpenAI-compatible API | `8000` | [codingworkflow/claude-code-api](https://github.com/codingworkflow/claude-code-api) |
+| **Codex** | OpenAI Codex CLI as an OpenAI-compatible API — your ChatGPT sub, no API key | `8010` | [openai/codex](https://github.com/openai/codex) |
 | **LifeOS** | Shared identity + skills mounted into the agents | — | [danielmiessler/LifeOS](https://github.com/danielmiessler/LifeOS) |
 
 Plus the integrations that glue it together — these aren't services, they're mounted into every agent:

aios.config.example.yaml

@@ -29,6 +29,11 @@ services:
   claudecode:              # claude-code-api — Claude Code as an OpenAI-compatible API (6th agent)
     enabled: true
     port: 8000
+  codex:                   # ChatGPT/Codex via the local `codex` CLI (no API key)
+    enabled: true
+    port: 8010
+    model: ""              # blank = whatever codex itself is configured to use
+    sandbox: read-only     # read-only | workspace-write | danger-full-access
   openclaw_proxy:          # frame-stripping proxy so openclaw's control-UI embeds in the hub
     enabled: true
     port: 8791
@@ -100,6 +105,7 @@ health:
   openclaw: http://127.0.0.1:18789/
   crewai: http://127.0.0.1:4788/health
   claudecode: http://127.0.0.1:8000/health
+  codex: http://127.0.0.1:8010/health
   openclaw_proxy: http://127.0.0.1:8791/
   hermes_proxy: http://127.0.0.1:8792/
   hub: http://127.0.0.1:8787/health

aios.py

@@ -340,6 +340,8 @@ def child_env(extra: dict | None = None) -> dict:
     "gemini": "GEMINI_API_KEY",
     # Claude Pro/Max via claude-code-api (OpenAI-compatible; auth is the Claude CLI login).
     "claudecode": "OPENAI_API_KEY",
+    # ChatGPT/Codex via the local codex CLI (auth is `codex login`, no API key).
+    "codex": "OPENAI_API_KEY",
 }
 PASSTHROUGH_KEYS = [
     "OPENROUTER_API_KEY", "ANTHROPIC_API_KEY", "OPENAI_API_KEY",
@@ -436,6 +438,22 @@ def service_specs(cfg: dict) -> dict:
             "health": cfg_get(cfg, "health.claudecode", f"http://127.0.0.1:{port}/health"),
             "tool": "uv",
         }
+    # Codex CLI as an OpenAI-compatible API (mirror of claude-code-api). Pure
+    # stdlib, so it runs on the same interpreter as aios itself.
+    if cfg_get(cfg, "services.codex.enabled", True):
+        cxp = int(cfg_get(cfg, "services.codex.port", 8010))
+        specs["codex"] = {
+            "enabled": True,
+            "cwd": ROOT,
+            "cmd": [sys.executable, str(ROOT / "services" / "codex_api.py")],
+            "port": cxp,
+            "health": cfg_get(cfg, "health.codex", f"http://127.0.0.1:{cxp}/health"),
+            "tool": "python",
+            "env": {"AIOS_CODEX_PORT": str(cxp),
+                    "AIOS_CODEX_MODEL": str(cfg_get(cfg, "services.codex.model", "")),
+                    "AIOS_CODEX_SANDBOX": str(cfg_get(cfg, "services.codex.sandbox", "read-only"))},
+        }
+
     # Frame-stripping reverse proxies so openclaw + hermes control-UIs embed in the hub.
     if cl and cfg_get(cfg, "services.openclaw_proxy.enabled", True):
         pport = int(cfg_get(cfg, "services.openclaw_proxy.port", 8791))
@@ -488,7 +506,7 @@ def service_specs(cfg: dict) -> dict:
 
 
 START_ORDER = ["opencode", "hermes", "hermes-gateway", "hermes-proxy", "openclaw",
-               "openclaw-proxy", "crewai", "claudecode", "hub"]
+               "openclaw-proxy", "crewai", "claudecode", "codex", "hub"]
 
 
 def openclaw_env() -> dict:
@@ -519,6 +537,7 @@ def interconnect_env(cfg: dict) -> dict:
         "AIOS_CREWAI_URL": f"http://127.0.0.1:{crp}",
         "AIOS_CREWAI_PORT": str(crp),
         "AIOS_CLAUDECODE_URL": f"http://127.0.0.1:{ccp}",
+        "AIOS_CODEX_URL": f"http://127.0.0.1:{cfg_get(cfg, 'services.codex.port', 8010)}",
         "AIOS_OPENCLAWPROXY_URL": f"http://127.0.0.1:{pxp}/",
         "AIOS_HERMESPROXY_URL": f"http://127.0.0.1:{hxp}/",
         "AIOS_OPENCLAWOS_URL": f"http://127.0.0.1:{clp}/plugins/openclawos/",
@@ -897,15 +916,16 @@ def _wizard_env(args):
     elif interactive:
         say(f"\n  {C.B}How should the agents talk to a model?{C.R}")
         say(f"    {C.CYN}1{C.R}  Claude Pro/Max subscription  {C.GRY}— no API key, no per-token cost{C.R}")
-        say(f"    {C.CYN}2{C.R}  OpenRouter                   {C.GRY}— one key, most models{C.R}")
-        say(f"    {C.CYN}3{C.R}  Anthropic API key")
-        say(f"    {C.CYN}4{C.R}  OpenAI API key")
-        say(f"    {C.CYN}5{C.R}  Google Gemini API key")
+        say(f"    {C.CYN}2{C.R}  ChatGPT / Codex subscription {C.GRY}— via the local codex CLI{C.R}")
+        say(f"    {C.CYN}3{C.R}  OpenRouter                   {C.GRY}— one key, most models{C.R}")
+        say(f"    {C.CYN}4{C.R}  Anthropic API key")
+        say(f"    {C.CYN}5{C.R}  OpenAI API key")
+        say(f"    {C.CYN}6{C.R}  Google Gemini API key")
         say(f"    {C.GRY}s{C.R}  skip for now")
-        choice = input(f"  Choice [1-5/s] ({data['AIOS_LLM_PROVIDER']}): ").strip().lower()
+        choice = input(f"  Choice [1-6/s] ({data['AIOS_LLM_PROVIDER']}): ").strip().lower()
 
-        by_num = {"1": "claude", "2": "openrouter", "3": "anthropic",
-                  "4": "openai", "5": "gemini", "s": "skip"}
+        by_num = {"1": "claude", "2": "codex", "3": "openrouter", "4": "anthropic",
+                  "5": "openai", "6": "gemini", "s": "skip"}
         prov = by_num.get(choice, choice or data["AIOS_LLM_PROVIDER"])
 
         if prov in ("skip", "none", "s"):
@@ -938,6 +958,21 @@ def _wizard_env(args):
                         warn(f"could not launch the login: {e}")
                 else:
                     say(f"  {C.GRY}Run `aios claude-login` when you're ready.{C.R}")
+        elif prov in ("codex", "chatgpt", "openai-codex"):
+            cxp = cfg_get(load_config(), "services.codex.port", 8010)
+            data["AIOS_LLM_PROVIDER"] = "codex"
+            data["AIOS_LLM_BASE_URL"] = f"http://127.0.0.1:{cxp}/v1"
+            data["AIOS_LLM_API_KEY"] = "sk-aios-codex"     # placeholder; auth is the CLI
+            data["AIOS_DEFAULT_MODEL"] = "codex"
+            ok("using your ChatGPT/Codex subscription via the codex CLI")
+            cx = find_tool("codex")
+            if not cx:
+                warn("the `codex` CLI isn't installed yet — install it with:")
+                say(f"    {C.B}npm install -g @openai/codex{C.R}")
+                say(f"    {C.GRY}then run `codex login` to authorise your account.{C.R}")
+            else:
+                ok(f"found the codex CLI ({cx})")
+                say(f"  {C.GRY}If it isn't logged in yet, run `codex login`.{C.R}")
         else:
             data["AIOS_LLM_PROVIDER"] = prov
             data.pop("AIOS_LLM_BASE_URL", None)  # don't leave a stale claude-code URL
@@ -2517,7 +2552,7 @@ def _print_urls(cfg):
     ("Agents & updates", ["updates", "update", "claude-login", "ruflo", "attach", "migrate", "wire"]),
     ("Advanced", ["test", "debug", "autostart", "install-cli", "bootstrap", "uninstall"]),
 ]
-TAGLINE = "Nine open-source AI projects. One operating system."
+TAGLINE = "Ten open-source AI projects. One operating system."
 
 
 class AiosParser(argparse.ArgumentParser):

aios_hub.py

@@ -101,6 +101,7 @@ def run_aios(*a, background=False):
     "openclaw": os.environ.get("AIOS_OPENCLAW_URL", "http://127.0.0.1:18789"),
     "crewai": os.environ.get("AIOS_CREWAI_URL", "http://127.0.0.1:4788"),
     "claudecode": os.environ.get("AIOS_CLAUDECODE_URL", "http://127.0.0.1:8000"),
+    "codex": os.environ.get("AIOS_CODEX_URL", "http://127.0.0.1:8010"),
     "openclaw-os": os.environ.get("AIOS_OPENCLAWOS_URL", "http://127.0.0.1:18789/plugins/openclawos/"),
 }
 CLAUDECODE = os.environ.get("AIOS_CLAUDECODE_URL", "http://127.0.0.1:8000").rstrip("/")
@@ -118,7 +119,7 @@ def read_system_prompt() -> str:
 
 
 # Chat "targets" the AIOS API exposes as OpenAI-style models.
-TARGETS = ["brain", "team", "swarm", "opencode", "crewai", "claudecode", "fabric", "all"]
+TARGETS = ["brain", "team", "swarm", "opencode", "crewai", "claudecode", "codex", "fabric", "all"]
 
 MEMORY_FILE = ROOT / ".aios" / "memory.json"
 USAGE_FILE = ROOT / ".aios" / "usage.json"
@@ -371,6 +372,24 @@ def ask_opencode(message: str) -> str:
         return f"⚠️ opencode error: {e}"
 
 
+def ask_codex(message: str, history: list | None = None) -> str:
+    """Codex CLI through its OpenAI-compatible bridge (services/codex_api.py)."""
+    base = os.environ.get("AIOS_CODEX_URL", "http://127.0.0.1:8010").rstrip("/")
+    msgs = (history or []) + [{"role": "user", "content": message}]
+    try:
+        d = post_json(base + "/v1/chat/completions",
+                      {"model": "codex", "messages": msgs}, timeout=620)
+        return (d.get("choices") or [{}])[0].get("message", {}).get("content", "") or             "(codex returned nothing)"
+    except urllib.error.HTTPError as e:
+        try:
+            return "⚠️ " + json.loads(e.read()).get("error", {}).get("message", str(e))
+        except Exception:
+            return f"⚠️ codex error: {e}"
+    except Exception as e:
+        return (f"⚠️ codex-api not reachable ({e}). Start it with `aios start codex`, "
+                f"and make sure the `codex` CLI is installed and logged in.")
+
+
 def ask_claudecode(message: str, history: list | None = None) -> str:
     """Call claude-code-api's OpenAI-compatible endpoint."""
     msgs = (history or []) + [{"role": "user", "content": message}]
@@ -682,6 +701,9 @@ def route(target: str, message: str, history: list | None = None) -> str:
         return ask_opencode(message)
     if target in ("claudecode", "claude-code"):
         return ask_claudecode(message, history)
+    if target == "codex":
+        act("agent", "Handing off to Codex…")
+        return ask_codex(message, history)
     if target == "fabric":
         # "pattern: text"  →  run that fabric pattern; else summarize by default.
         pat, _, txt = message.partition(":")
@@ -1184,6 +1206,7 @@ def claude_status() -> dict:
     "opencode": "writing/editing/running code, repos, technical build tasks",
     "crewai": "multi-step research or workflows that benefit from a crew of roles",
     "claudecode": "Claude Code — coding with the Claude Code CLI",
+    "codex": "OpenAI Codex — coding via your ChatGPT/Codex subscription",
 }
 
 

docs/dashboard.html

@@ -236,6 +236,7 @@
     <button class="nav" data-v="openclaw" data-svc="openclaw" onclick="nav('openclaw')"><span class="ic">🦞</span> openclaw <span class="dot"></span></button>
     <button class="nav" data-v="crewai" data-svc="crewai" onclick="nav('crewai')"><span class="ic">👥</span> CrewAI <span class="dot"></span></button>
     <button class="nav" data-v="claudecode" data-svc="claudecode" onclick="nav('claudecode')"><span class="ic">◈</span> claude-code <span class="dot"></span></button>
+    <button class="nav" data-v="codex" data-svc="codex" onclick="nav('codex')"><span class="ic">⌁</span> Codex <span class="dot"></span></button>
 
     <div class="sec">Dashboards</div>
     <button class="nav" data-v="openclawos" data-svc="openclaw-os" onclick="nav('openclawos')"><span class="ic">🪟</span> openclaw-os <span class="dot"></span></button>
@@ -280,6 +281,7 @@
             <button class="chip" data-t="crewai">👥 CrewAI</button>
             <button class="chip" data-t="opencode">⌨️ opencode</button>
             <button class="chip" data-t="claudecode">◈ claude-code</button>
+            <button class="chip" data-t="codex" title="OpenAI Codex via your ChatGPT subscription">⌁ Codex</button>
             <button class="chip" data-t="swarm" title="Big task: decompose across specialist agents running in parallel">🐝 Swarm</button>
             <button class="chip" data-t="fabric" title="Run a Fabric pattern (type: pattern: your text)">🧵 Fabric</button>
             <button class="chip" data-t="all">🌐 All</button>
@@ -313,6 +315,8 @@
     <!-- INFO AGENTS (opencode / crewai / claude-code) -->
     <div id="opencode" class="view"><div class="vhead"><h2>⌨️ opencode</h2><span class="sub">coding-agent engine</span></div><div class="vbody pad" id="opencodeBody"></div></div>
     <div id="crewai" class="view"><div class="vhead"><h2>👥 CrewAI</h2><span class="sub">multi-agent crews</span></div><div class="vbody pad" id="crewaiBody"></div></div>
+    <div id="codex" class="view"><div class="vhead"><h2>⌁ Codex</h2><span class="sub">OpenAI Codex via your ChatGPT subscription</span></div><div class="vbody pad" id="codexBody"></div></div>
+
     <div id="claudecode" class="view"><div class="vhead"><h2>◈ claude-code</h2><span class="sub">Claude Code as an OpenAI-compatible API</span></div><div class="vbody pad" id="claudecodeBody"></div></div>
 
     <!-- CANVAS (generative UI any agent can edit) -->
@@ -669,8 +673,8 @@ <h3 style="margin-top:26px;font-size:1rem;display:flex;align-items:center;gap:8p
     const same=(typeof u==='string')&&(u.startsWith('/')||u.startsWith(location.origin));
     if(AIOS_TOKEN&&same){o.headers=Object.assign({'Authorization':'Bearer '+AIOS_TOKEN},o.headers||{});}
     return _f(u,o);};})();
-  const ROLES={opencode:"coding engine",hermes:"autonomous agent",openclaw:"channel gateway",crewai:"multi-agent crews",claudecode:"Claude Code API","openclaw-os":"dashboard",hub:"brain + interconnect"};
-  const ICON={opencode:"⌨️",hermes:"☤",openclaw:"🦞",crewai:"👥",claudecode:"◈","openclaw-os":"🪟",hub:"◆",brain:"◆",team:"✦",all:"🌐"};
+  const ROLES={opencode:"coding engine",hermes:"autonomous agent",openclaw:"channel gateway",crewai:"multi-agent crews",claudecode:"Claude Code API",codex:"Codex (ChatGPT sub)","openclaw-os":"dashboard",hub:"brain + interconnect"};
+  const ICON={opencode:"⌨️",hermes:"☤",openclaw:"🦞",crewai:"👥",claudecode:"◈",codex:"⌁","openclaw-os":"🪟",hub:"◆",brain:"◆",team:"✦",all:"🌐"};
   let target="brain", peers={}, svc={}, history=[];
 
   // ── themes (applied as CSS vars from JS → enables the theme store) ──
@@ -750,6 +754,7 @@ <h3 style="margin-top:26px;font-size:1rem;display:flex;align-items:center;gap:8p
     if(v==='openclaw')frame('clawFrame','clawNew',peers['openclaw-embed']||peers.openclaw);
     if(v==='opencode')agentPanel('opencode','opencodeBody','The headless coding-agent engine. Chat with it from the Chat tab (target “opencode”) or call its HTTP API/SDK.',peers.opencode);
     if(v==='crewai')agentPanel('crewai','crewaiBody','Role-based multi-agent crews. Chat with it from the Chat tab (target “CrewAI”). It can call the other agents via the hub.',peers.crewai);
+    if(v==='codex')agentPanel('codex','codexBody','OpenAI Codex, wrapped as an OpenAI-compatible API by <span class="mono">services/codex_api.py</span>. Auth is your <span class="mono">codex login</span> — no API key. Chat with it here (target <b>Codex</b>) or POST to <span class="mono">'+(peers.codex||'http://127.0.0.1:8010')+'/v1</span>.',peers.codex);
     if(v==='claudecode')agentPanel('claudecode','claudecodeBody','Claude Code exposed as an OpenAI-compatible API. Chat with it (target “claude-code”), or point any tool at <span class="mono">'+(peers.claudecode||'http://127.0.0.1:8000')+'/v1</span>. Needs the <span class="mono">claude</span> CLI installed + authenticated.',peers.claudecode);
     if(v==='automations')loadSchedules();
     if(v==='canvas')loadCanvas();