agent0ai · vivenstrix · Feb 12, 2026
diff --git a/README.md b/README.md
@@ -15,7 +15,8 @@
 [Installation](./docs/setup/installation.md) •
 [How to update](./docs/setup/installation.md#how-to-update-agent-zero) <br>
 [Development Setup](./docs/setup/dev-setup.md) •
-[Usage](./docs/guides/usage.md)
+[Usage](./docs/guides/usage.md) •
+[Codex Subscription](./docs/guides/codex-subscription.md)
 
 Or see DeepWiki generated documentation:
 
@@ -155,6 +156,7 @@ docker run -p 50001:80 agent0ai/agent-zero
 |-------|-------------|
 | [Installation](./docs/setup/installation.md) | Installation, setup and configuration |
 | [Usage](./docs/guides/usage.md) | Basic and advanced usage |
+| [Codex Subscription](./docs/guides/codex-subscription.md) | Connect ChatGPT subscription, select per-role Codex models, and verify setup |
 | [Guides](./docs/guides/) | Step-by-step guides: Usage, Projects, API Integration, MCP Setup, A2A Setup |
 | [Development Setup](./docs/setup/dev-setup.md) | Development and customization |
 | [WebSocket Infrastructure](./docs/developer/websockets.md) | Real-time WebSocket handlers, client APIs, filtering semantics, envelopes |

diff --git a/agent.py b/agent.py
@@ -730,6 +730,8 @@ def get_chat_model(self):
             self.config.chat_model.provider,
             self.config.chat_model.name,
             model_config=self.config.chat_model,
+            a0_role="chat",
+            a0_context_id=self.context.id,
             **self.config.chat_model.build_kwargs(),
         )
 
@@ -738,6 +740,8 @@ def get_utility_model(self):
             self.config.utility_model.provider,
             self.config.utility_model.name,
             model_config=self.config.utility_model,
+            a0_role="utility",
+            a0_context_id=self.context.id,
             **self.config.utility_model.build_kwargs(),
         )
 
@@ -746,6 +750,8 @@ def get_browser_model(self):
             self.config.browser_model.provider,
             self.config.browser_model.name,
             model_config=self.config.browser_model,
+            a0_role="browser",
+            a0_context_id=self.context.id,
             **self.config.browser_model.build_kwargs(),
         )
 

diff --git a/conf/model_providers.yaml b/conf/model_providers.yaml
@@ -30,6 +30,9 @@ chat:
   cometapi:
     name: CometAPI
     litellm_provider: cometapi
+  codex:
+    name: Codex (ChatGPT subscription)
+    litellm_provider: codex
   deepseek:
     name: DeepSeek
     litellm_provider: deepseek

diff --git a/docs/README.md b/docs/README.md
@@ -13,6 +13,7 @@ Welcome to the Agent Zero documentation hub. Whether you're getting started or d
 ## User Guides
 
 - **[Usage Guide](guides/usage.md):** Comprehensive guide to Agent Zero's features and capabilities.
+- **[Codex Subscription Guide](guides/codex-subscription.md):** Use ChatGPT subscription via Codex CLI with global login and per-role model selection.
 - **[Projects Tutorial](guides/projects.md):** Learn to create isolated workspaces with dedicated context and memory.
 - **[API Integration](guides/api-integration.md):** Add external APIs without writing code.
 - **[MCP Setup](guides/mcp-setup.md):** Configure Model Context Protocol servers.
@@ -86,6 +87,7 @@ Welcome to the Agent Zero documentation hub. Whether you're getting started or d
     - [Voice Interface](guides/usage.md#voice-interface)
     - [Memory Management](guides/usage.md#memory-management)
     - [Backup & Restore](guides/usage.md#backup--restore)
+  - [Codex Subscription Guide](guides/codex-subscription.md)
   - [Projects Tutorial](guides/projects.md)
   - [API Integration](guides/api-integration.md)
   - [MCP Setup](guides/mcp-setup.md)

diff --git a/docs/guides/codex-subscription.md b/docs/guides/codex-subscription.md
@@ -0,0 +1,149 @@
+# Codex (ChatGPT Subscription) Guide
+
+This guide explains how to use Agent Zero with your ChatGPT subscription through the `Codex (ChatGPT subscription)` provider.
+
+## What This Integration Does
+
+- Uses local `codex` CLI authentication (your ChatGPT account), not OpenAI API billing.
+- Supports independent model selection for:
+  - Chat model
+  - Utility model
+  - Browser model
+- Keeps embedding model unchanged (embedding does not use Codex subscription mode).
+- Uses one global login, then lets you choose different models per role.
+
+## Prerequisites
+
+- `codex` CLI is installed and available in PATH.
+- You can run:
+
+```bash
+codex --version
+codex login status
+```
+
+- Agent Zero is running and you can open the Web UI settings.
+
+## UI Walkthrough
+
+### 1. Open Agent Settings
+
+- Go to **Settings → Agent Settings**.
+- You should see sections for `Chat Model`, `Utility model`, `Web Browser Model`, and `ChatGPT Subscription`.
+
+![Agent settings overview](../res/setup/codex/agent-settings-overview.svg)
+
+### 2. Connect Your ChatGPT Subscription (Global Login)
+
+- Open **ChatGPT Subscription** section.
+- Click **Connect ChatGPT**.
+- Complete authentication in the browser window opened by the login flow.
+- Click **Check Status** and confirm:
+  - Installed: `yes`
+  - Logged in: `yes`
+  - Login flow: `completed`
+- Click **Refresh Models** to fetch available Codex models for your account.
+
+![Subscription login panel](../res/setup/codex/subscription-panel.svg)
+
+> [!NOTE]
+> This login is global and shared by all Codex-backed roles. You do not log in separately for Chat/Utility/Browser.
+
+### 3. Set Providers and Models Per Role
+
+For each section below, set provider to `Codex (ChatGPT subscription)`:
+
+- **Chat Model**
+- **Utility model**
+- **Web Browser Model**
+
+Then choose model name independently per role. Example:
+
+- Chat model: `gpt-5.2-codex`
+- Utility model: `gpt-5.1-codex-mini`
+- Browser model: `gpt-5.2`
+
+Click **Save**.
+
+![Per-role model selectors](../res/setup/codex/per-role-models.svg)
+
+## How It Works Internally
+
+- Agent Zero runs Codex through local CLI (`codex exec --json`) for Chat/Utility/Browser roles.
+- A single ChatGPT login is reused globally.
+- Each role stores its own model setting (`chat_model_name`, `util_model_name`, `browser_model_name`).
+- Codex sessions are resumed per chat context and per role:
+  - New chat starts fresh Codex thread(s).
+  - Existing chat resumes relevant Codex thread for that role.
+- If Codex fails on a call, Agent Zero attempts a temporary per-call fallback to the previous non-Codex provider for that role and shows a warning banner.
+- Saved provider remains `codex` unless you change it manually.
+
+## Verify It Works (Checklist)
+
+### A. UI Verification
+
+- [ ] Chat role shows selected Chat model name correctly.
+- [ ] Utility role shows selected Utility model name correctly.
+- [ ] Browser role shows selected Browser model name correctly.
+- [ ] Reopening Settings still shows all three chosen values.
+
+### B. Backend Verification
+
+Run:
+
+```bash
+cd agent-zero
+./.venv/bin/python - <<'PY'
+from python.helpers import settings
+s=settings.get_settings()
+print("chat:", s["chat_model_name"])
+print("util:", s["util_model_name"])
+print("browser:", s["browser_model_name"])
+PY
+```
+
+Expected: values match what you selected in UI for each role.
+
+### C. Functional Verification
+
+- Send a normal chat prompt and confirm response arrives.
+- Trigger at least one utility-style task (summarization/memory operations) and verify no model misformat loop.
+- Trigger browser-use task and verify browser path still works.
+
+## Security Notes
+
+> [!CAUTION]
+> This setup can run Codex in unrestricted full-auto mode (`--dangerously-bypass-approvals-and-sandbox`), which can execute commands without additional sandbox/approval prompts. Use only in trusted environments.
+
+> [!IMPORTANT]
+> ChatGPT subscription login is not an API key replacement for non-Codex providers. If you switch back to OpenAI/OpenRouter/etc, configure API keys as usual.
+
+## Common Issues
+
+### UI shows the same model for all three roles
+
+- First verify backend values (command above).
+- If backend values are different, update to the latest UI patch and hard-refresh browser.
+- If mismatch persists, reopen settings after save and check model text fields again.
+
+### Codex status says not connected
+
+- Confirm `codex` is installed on the same machine/container where Agent Zero backend runs.
+- Run `codex login status` in terminal.
+- Return to **ChatGPT Subscription** and click **Check Status**.
+
+### No model list appears
+
+- Ensure login is completed first.
+- Click **Refresh Models**.
+- If still empty/unverified, use manual model entry (exact model ID) and re-check diagnostics in status panel.
+
+## Recommended Team Documentation Practice
+
+If you maintain a fork/team deployment:
+
+1. Keep this guide (`docs/guides/codex-subscription.md`) as the detailed source of truth.
+2. Keep README concise with a link to this guide.
+3. Add short troubleshooting bullets in `docs/guides/troubleshooting.md`.
+4. When UI changes, update screenshots in `docs/res/setup/codex/`.
+
diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md
@@ -14,6 +14,36 @@ This page addresses frequently asked questions (FAQ) and provides troubleshootin
 **4. Does ChatGPT Plus include API access?**
 - No. ChatGPT Plus does not include API credits. You must provide an OpenAI API key in Settings.
 
+**4a. Can I use ChatGPT subscription without OpenAI API billing?**
+- Yes, by using the `Codex (ChatGPT subscription)` provider for Chat/Utility/Browser roles.
+- This provider relies on your local `codex` login status instead of API keys.
+- Use **Settings → Agent Settings → ChatGPT Subscription** to connect/disconnect and verify status.
+
+**4b. Codex provider is selected but calls fail. What should I check?**
+- Verify `codex` is installed and available on PATH.
+- Run `codex login status` locally and confirm it reports logged in.
+- In Agent Zero Settings, check Codex status diagnostics for the selected role.
+- If Codex fails, Agent Zero can temporarily fallback to previous non-codex provider and show a warning banner.
+- If you enabled unrestricted full-auto for Codex, make sure you trust the execution environment.
+
+**4c. UI shows the same Codex model in Chat/Utility/Browser, but backend values are different.**
+- Confirm saved values with:
+  ```bash
+  cd agent-zero
+  ./.venv/bin/python - <<'PY'
+  from python.helpers import settings
+  s=settings.get_settings()
+  print("chat:", s["chat_model_name"])
+  print("util:", s["util_model_name"])
+  print("browser:", s["browser_model_name"])
+  PY
+  ```
+- If backend is correct, update to latest frontend patch and hard-refresh browser.
+- Reopen Settings and verify each role field shows its own value.
+
+**4d. Where is the full setup guide for ChatGPT subscription mode?**
+- See [Codex Subscription Guide](codex-subscription.md) for login flow, model selection, screenshots, and verification checklist.
+
 **5. Where is chat history stored?**
 - Chat history lives at `/a0/usr/chats/` inside the container.
 

diff --git a/docs/res/setup/codex/README.md b/docs/res/setup/codex/README.md
@@ -0,0 +1,16 @@
+# Codex Guide Images
+
+This folder contains visual assets for the Codex subscription setup guide:
+
+- `agent-settings-overview.svg`
+- `subscription-panel.svg`
+- `per-role-models.svg`
+
+These are placeholder illustrations so docs render cleanly in all environments.
+
+If you want real product screenshots, replace these files (or add PNG files and update links in `docs/guides/codex-subscription.md`) using captures from:
+
+1. Agent Settings overview
+2. ChatGPT Subscription connection panel
+3. Per-role model selection (Chat / Utility / Browser)
+
diff --git a/docs/res/setup/codex/agent-settings-overview.svg b/docs/res/setup/codex/agent-settings-overview.svg
diff --git a/docs/res/setup/codex/per-role-models.svg b/docs/res/setup/codex/per-role-models.svg
diff --git a/docs/res/setup/codex/subscription-panel.svg b/docs/res/setup/codex/subscription-panel.svg
diff --git a/docs/setup/installation.md b/docs/setup/installation.md
@@ -295,6 +295,31 @@ Configure API keys for various service providers directly within the Web UI. Cli
 > [!NOTE]
 > **OpenAI API vs Plus subscription:** A ChatGPT Plus subscription does not include API credits. You must provide a separate API key for OpenAI usage in Agent Zero.
 
+> [!NOTE]
+> **Codex provider (ChatGPT subscription):** The `Codex (ChatGPT subscription)` provider uses your local `codex` login instead of OpenAI API keys.  
+> In the Settings panel, use **Agent Settings → ChatGPT Subscription** to connect and verify login status.
+
+> [!CAUTION]
+> **Codex execution mode:** If Codex is configured with unrestricted full-auto, it may execute commands without sandbox/approval prompts. Use this mode only in trusted environments.
+
+### Codex (ChatGPT subscription) quick setup
+
+Use this when you want Agent Zero to run through your ChatGPT subscription instead of OpenAI API billing.
+
+1. Open **Settings → Agent Settings → ChatGPT Subscription**.
+2. Click **Connect ChatGPT** and finish login in browser.
+3. Click **Check Status** (must show logged in) and **Refresh Models**.
+4. In each model section (`Chat`, `Utility`, `Web Browser`), set provider to `Codex (ChatGPT subscription)`.
+5. Choose model name per role and click **Save**.
+
+![Codex setup flow](../res/setup/codex/subscription-panel.svg)
+
+> [!NOTE]
+> Login is global, but model selection is per role. You can run different models for Chat, Utility, and Browser.
+
+> [!TIP]
+> See the full walkthrough, screenshots, verification checklist, and internals in [Codex Subscription Guide](../guides/codex-subscription.md).
+
 > [!TIP]
 > For OpenAI-compatible providers (e.g., custom gateways or Z.AI/GLM), add the API key under **External Services → Other OpenAI-compatible API keys**, then select **OpenAI Compatible** as the provider in model settings.