OpenAI shipped Codex CLI 0.168 and 0.169 on November 13, 2026. Together they add a new terminal workspace with side-chat tabs, a model provider picker, a diagnostic ZIP shortcut and a safer default for codex exec.
This guide shows you how to update, which config.toml lines turn each feature on, and what the new --trust rule means for your scripts.
- Update: run
npm install -g @openai/codex@0.169.0, then check withcodex --version. - Side chats: set
tui_workspace = trueunder[features]to get side-chat tabs next to the main chat. Saved local side chats come back after a restart. - Providers: add or edit custom model providers from the terminal and pick a default for new chats under Sessions, then Model providers.
- Security:
codex execnow keeps project config and MCP servers off in untrusted folders. Pass--trustto save trust. - Extras: Ctrl+S saves a diagnostic ZIP, animated GIF image generation, audio attachments and OSC 777 notifications.
What’s New in Codex CLI 0.168 and 0.169
Both versions landed on the same day. Version 0.168 brought the workspace and the provider list. Version 0.169 polished the workspace, added search to the agent command center and fixed the trust gap in codex exec.
If you are new to Codex, start with my OpenAI Codex guide first. Here is everything that changed, in one table.
| Feature | Version | How to use it |
|---|---|---|
| Side conversation beside the main chat | 0.168 | features.tui_workspace |
| Multiple side-chat tabs (keyboard or mouse) | 0.169 | Same workspace, opt-in |
| Saved local side chats reopen after restart | 0.169 | Automatic in the workspace |
| Pane zoom | 0.168 | Leader key, then z |
| Browse providers and set a default | 0.168 | Sessions, then Model providers |
| Add or edit custom providers from the terminal | 0.169 | Also offered during sign-in |
| Device-code sign-in for supported gateways | 0.169 | During provider sign-in |
| Search older tasks in the agent command center | 0.169 | Matches task name, prompt preview or folder |
| Collapse turn details in the transcript | 0.169 | Full-screen transcript view |
| Diagnostic ZIP | 0.169 | Ctrl+S in the report editor |
| Opt-in Cloud connection (images, model, reasoning effort, archive and restore) | 0.169 | macOS and Linux |
| Animated GIF generation and editing | 0.168 | features.image_generation_animation |
| Audio attachments | 0.168 | Audio-capable models only |
| OSC 777 notifications | 0.168 | tui.notification_method = "osc777" |
| Image previews in tmux (Ghostty, Kitty) | 0.168 | tmux allow-passthrough all |
features.multi_agent deprecated |
0.168 | Use agents.enabled |
Untrusted folders stay locked in codex exec |
0.169 | Add --trust to save trust |
How to Update Codex CLI
The changelog lists an npm install command for each release. The steps below work on macOS, Linux and Windows.
- Close running sessions. Quit any open Codex terminal sessions so the binary is not in use.
- Install the new version. Run
npm install -g @openai/codex@0.169.0. Use@latestinstead of the version number if you always want the newest build. - Check the version. Run
codex --versionand confirm it prints 0.169.0 or newer. - Back up your config. Copy
~/.codex/config.tomlbefore you change it. A typo in TOML can stop Codex from starting. - Remove deprecated keys. If your config sets
multi_agentunder[features], swap it foragents.enabled(shown below).
npm install -g @openai/codex@0.169.0
codex --version
Note: If you installed Codex with Homebrew or another package manager, upgrade it with that same tool. Mixing npm and Homebrew installs can leave an old binary first on your PATH.
How to Turn On Side-Chat Tabs
Codex already had the /side slash command. It opens a short-lived side chat forked from your current chat, so you can ask a quick question without derailing the main task.
The new terminal workspace puts that side conversation in its own pane next to the main chat. In 0.169 you can open several side chats as tabs.
Step 1: Enable the workspace flag
The workspace is opt-in. Add this to ~/.codex/config.toml and restart Codex.
[features]
tui_workspace = true
Step 2: Open and use side chats
- Start a side chat. Type
/sidein the main chat. You can add a question inline, for example/side Check whether this plan has an obvious risk. - Switch tabs. Move between side-chat tabs with the keyboard or click them with the mouse.
- Resize panes. Drag the divider between the main chat and the side pane.
- Zoom a pane. Press your leader key, then z, to zoom the focused pane.
- Come back later. Saved local side chats reopen after you restart Codex, so you do not lose a useful thread.
Tip: The leader key is set in /keymap, and its default was Ctrl+X when it arrived in 0.163. Run /keymap to check or change yours before you try the zoom shortcut.
What side chats are good for
- Quick checks: ask “what does this error mean?” while the main task keeps its context clean.
- Plan reviews: ask a second opinion on a plan before you approve it.
- Research: look up an API or flag without filling the main transcript.
A side chat keeps its transcript separate from the parent. You cannot open a side chat inside another side chat, and it is not available during review mode.
How to Add a Custom Model Provider
Version 0.168 added a model provider list under Sessions, then Model providers, where you can set the default provider for new chats. Version 0.169 lets you add or edit custom providers from the terminal, including during sign-in.
You can also set providers up by hand in config.toml. Here are the main keys from the official config reference.
| Key | What it does |
|---|---|
model_provider |
The default provider ID. Defaults to openai. |
name |
Display name for the provider. |
base_url |
The API base URL. |
env_key |
Environment variable that holds the API key. |
auth table |
A command that prints a token. Do not combine it with env_key. |
wire_api |
Protocol. responses is the only value and the default. |
http_headers |
Static headers sent with each request. |
request_max_retries |
HTTP retry count. Default 4. |
Example: OpenRouter
OpenRouter’s own Codex guide recommends a command-based auth block. With a plain env_key, Codex does not fetch the OpenRouter model catalog, and non-OpenAI models show an “Unknown model” warning.
- Set your key. On macOS or Linux, add
export OPENROUTER_API_KEY="sk-or-..."to your shell profile. On Windows, runsetx OPENROUTER_API_KEY "sk-or-..."and restart Codex fully. - Add the provider. Paste the block below into
~/.codex/config.toml. - Pick the model. Set
modelto a model ID from OpenRouter. The example uses the one in OpenRouter’s guide. - Confirm. Start Codex and run
/statusto see the active model and provider.
model_provider = "openrouter"
model = "~openai/gpt-sol-latest"
[model_providers.openrouter]
name = "openrouter"
base_url = "https://openrouter.ai/api/v1"
[model_providers.openrouter.auth]
command = "sh"
args = ["-c", "echo $OPENROUTER_API_KEY"]
On Windows, swap the auth block for this one:
[model_providers.openrouter.auth]
command = "powershell"
args = ["-NoProfile", "-Command", "Write-Output $env:OPENROUTER_API_KEY"]
For pricing and free models, see my OpenRouter guide.
Example: Ollama (local)
Ollama and LM Studio are built-in providers. Their IDs (ollama, lmstudio, openai) are reserved, so you cannot redefine them. The simplest route is the --oss flag.
# config.toml
oss_provider = "ollama" # or "lmstudio"
Then run codex --oss. If oss_provider is unset, Codex asks you which local provider to use. You can also pick one per run with --local-provider.
If you prefer a custom entry, give it a new ID. This is the example from the official docs:
[model_providers.local_ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"
Need a model to run? My list of the best Ollama models covers good picks by GPU size.
Warning: Profiles changed earlier this year. Since Codex 0.134.0, [profiles.<name>] tables and the top-level profile = "..." selector are no longer supported. Use a separate file such as ~/.codex/deep-review.config.toml and run codex --profile deep-review.
The New Trust Rule for codex exec
This is the change most likely to affect CI scripts. Codex only loads project-level .codex/ layers, such as .codex/config.toml and project MCP servers, when a folder is trusted.
Version 0.169 closes a gap here. codex exec now keeps project config and MCP servers disabled in untrusted folders, even with --sandbox workspace-write.
Why it matters
- Cloned repos: a repo you just cloned could ship a
.codex/config.tomlthat adds an MCP server or changes settings. - Headless runs:
codex execruns without a person watching, so a silent config change is riskier. - Clear intent: you now trust a folder on purpose, not by accident.
How to trust a folder
- Check the repo first. Read any
.codex/folder andAGENTS.mdin the project before you trust it. - Run once with trust. Add
--trusttocodex execorcodex review. This saves trust for the project. - Or set it in config. Add a
projectsentry in your user-level config, as below.
codex exec --trust "run the test suite and fix failures"
# ~/.codex/config.toml
[projects."/home/you/code/my-app"]
trust_level = "trusted" # or "untrusted"
Warning: Do not add --trust to a CI job that runs on pull requests from forks. Anyone could then add a project config or MCP server that your runner would load.
Other New Features Worth Knowing
Search older tasks in the agent command center
The agent command center (/agents or codex agents) now has search. It matches the task name, the prompt preview or the working folder. My agent command center guide covers the rest of that view.
Ctrl+S diagnostic ZIP
In the terminal report editor (part of the /feedback flow), press Ctrl+S to save a diagnostic ZIP on your own machine. It works even when uploads are disabled, which helps on locked-down company laptops.
Opt-in Cloud connection
On macOS and Linux, the opt-in Cloud connection now lets you:
- Send images to Cloud conversations.
- Pick a model and reasoning effort for the Cloud task.
- Archive or restore Cloud conversations.
Cloud tasks use your plan’s Codex limits. See my Codex usage limits guide before you move heavy work there.
Animated GIFs and audio
Turn on animated GIF generation and editing with one flag. Audio-capable models can also receive attached recordings, with no flag needed.
[features]
image_generation_animation = true
OSC 777 notifications
If your terminal supports OSC 777 desktop notifications, you can now pick them. Set it under the [tui] table:
[tui]
notification_method = "osc777"
multi_agent is now agents.enabled
features.multi_agent is deprecated. Codex warns you if it is set and points you to agents.enabled, which defaults to true. To switch subagent tools off:
[agents]
enabled = false
A Sample config.toml With Everything
Here is one file that turns on the new features and adds OpenRouter as an extra provider. Keep model_provider on openai if you want OpenAI as the default.
model_provider = "openai"
[features]
tui_workspace = true
image_generation_animation = true
[tui]
notification_method = "osc777"
[agents]
enabled = true
[model_providers.openrouter]
name = "openrouter"
base_url = "https://openrouter.ai/api/v1"
[model_providers.openrouter.auth]
command = "sh"
args = ["-c", "echo $OPENROUTER_API_KEY"]
[projects."/home/you/code/my-app"]
trust_level = "trusted"
One TOML rule to remember: top-level keys like model_provider must sit above the first [table] header. If you put them lower, TOML treats them as part of the table above.
My Take
Side-chat tabs are the headline, and they fix a real habit. Most of us open a second terminal just to ask a quick question, and now that lives in one window with saved history.
The --trust change is the one I would act on today. If your scripts depend on a project .codex/config.toml, they may quietly lose those settings until you trust the folder. Comparing tools? My Codex vs Claude Code post covers how the two compare.
Troubleshooting: Common Problems and Fixes
- No side pane after enabling the flag: check that
tui_workspace = truesits under[features], then fully restart Codex. Runcodex --versionto confirm you are on 0.168 or newer. - Only one side chat, no tabs: multiple tabs came in 0.169. Update with
npm install -g @openai/codex@0.169.0. - Zoom shortcut does nothing: your leader key may be different. Open
/keymapto see the current binding. - Project MCP servers stopped loading in exec: the folder is untrusted. Review it, then run once with
--trustor add atrust_levelentry. - “Unknown model” warning with OpenRouter: you are using
env_key. Switch to theauthcommand block so Codex can fetch the model catalog. - Your custom Ollama block does not work: check that you did not try to redefine
ollama,lmstudiooropenai. Use a new ID likelocal_ollama. - Warning about multi_agent: delete
multi_agentfrom[features]and use[agents]withenabledinstead. - Images do not show in tmux: on Ghostty or Kitty, set tmux
allow-passthroughtoall. - Profile stopped working:
[profiles]tables were removed in 0.134.0. Move the settings to a<name>.config.tomlfile.
Frequently Asked Questions
When were Codex CLI 0.168 and 0.169 released?
Both were released on November 13, 2026, according to the official Codex changelog.
Are side-chat tabs on by default?
No. The terminal workspace is opt-in. Add tui_workspace = true under [features] in config.toml and restart Codex.
Do side chats survive a restart?
Yes, saved local side chats can be reopened after you restart Codex, starting with version 0.169.
Can I use Codex CLI with OpenRouter or Ollama?
Yes. Add OpenRouter as a custom entry under [model_providers]. Ollama is built in, so set oss_provider = "ollama" and run codex --oss.
What does the trust flag do?
It saves project trust when you run codex exec or codex review. Without trust, project config and MCP servers stay disabled in that folder.
Where does the Ctrl+S diagnostic ZIP go?
It is saved on your own machine from the terminal report editor. It works even when feedback uploads are disabled.
Is features.multi_agent removed?
It is deprecated, not removed. Codex warns you when it is set and points you to agents.enabled, which is the setting to use now.



