Codex CLI 0.171.0: GPT-6.2 Sol Default, TUI Workspace, and Remote Exec

Codex CLI 0.171.0 makes GPT-6.2 Sol the default catalog model, enables the split-pane TUI workspace by default, adds codex exec --remote <ADDR> and /rc, and keeps permission profiles intact across directory changes. Verify active model IDs, switch back to GPT-6.2 Astra or custom API providers like BetterToken, disable the workspace if needed, and check remote execution prerequisites.

Contents
Codex CLI 0.171.0: GPT-6.2 Sol Default, TUI Workspace, and Remote Exec

Upgrading to Codex CLI 0.171.0 (released November 20, 2026) adds gpt-6.2-sol as the default catalog selection and turns the split-pane TUI workspace on by default. This affects anyone launching codex without a pinned model in config.toml, teams scripting codex exec, and developers routing Codex to custom API providers. Pin model = "gpt-6.2-astra" in your Codex config.toml to keep Astra, run codex features disable tui_workspace to restore the single-pane terminal layout, or configure pay-as-you-go GPT-6.2 API access below.

Routes to run GPT-6.2 Sol and Astra in Codex CLI 0.171.0

Before changing settings, choose how Codex authenticates and bills GPT-6.2 usage. Your sign-in route controls which model IDs work and whether ChatGPT-only features such as Codex cloud and /rc remote control stay available.

RouteAccount and authBilling unitCodex 0.171.0 support and limitsBest when
ChatGPT subscription (codex login)ChatGPT account via browser sign-inPlan usage allowance (shared across local messages and cloud chats)Supports Codex cloud and /rc remote control; ChatGPT Pro 200 adds Ultrafast with SolYou already have an eligible ChatGPT plan and want cloud or remote-control features
OpenAI API directOpenAI Platform account + API keyPer 1M tokens (USD)Uses gpt-6.2-sol and gpt-6.2-astra; no cloud-based features, and /rc remote control is unavailable with API key authYou want direct OpenAI billing and API-organization data policies
BetterToken API gatewayBetterToken account + API keyPay-as-you-go balance per model unitListed gpt-6.2-sol and gpt-6.2-astra over OpenAI Responses (https://www.bettertoken.ai/v1); paid balance does not reset monthlyYou want pay-as-you-go multi-model API access without a ChatGPT subscription

Configure Codex CLI 0.171.0 with BetterToken

BetterToken is a multi-model API access layer with pay-as-you-go billing, not an official OpenAI product. As of 2026-11-21, BetterToken lists both gpt-6.2-sol and gpt-6.2-astra on its current pricing page over the OpenAI Responses protocol (https://www.bettertoken.ai/v1). See the Codex API overview for a summary of Codex compatibility.

Register a BetterToken account and create your API key in the BetterToken console. Using file-based API key authentication in auth.json replaces official ChatGPT sign-in, so ChatGPT-only features such as /rc remote control and ChatGPT Pro 200 Ultrafast are unavailable under this mode. To keep your official ChatGPT login intact alongside a third-party provider, follow BetterToken’s official-login preservation guide instead of editing auth.json.

Fully quit Codex CLI and Codex App before editing files, because both clients share config.toml and auth.json in the same Codex directory ($CODEX_HOME if set, otherwise ~/.codex on macOS/Linux or %USERPROFILE%\.codex on Windows; see Codex CLI vs Codex App vs VS Code Extension). Back up both config.toml and auth.json from that active directory to a private location, and create config.toml if it is missing.

In config.toml, update any existing model_provider, model, or cli_auth_credentials_store root keys in place, and add only the keys that are missing before any [tables]. If [model_providers.bettertoken] already exists, merge these fields into that existing table rather than adding a duplicate table header; otherwise add the table below, keeping unrelated settings intact per the BetterToken Codex setup guide:

model_provider = "bettertoken"
model = "gpt-6.2-sol"
cli_auth_credentials_store = "file"

[model_providers.bettertoken]
name = "BetterToken"
base_url = "https://www.bettertoken.ai/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false

Swap model to "gpt-6.2-astra" whenever you want Astra by default. Remove env_key and experimental_bearer_token from [model_providers.bettertoken] when using file authentication.

Next, write auth.json in that same resolved Codex directory. On macOS or Linux with Bash and Python 3, run the snippet below to enter your key without echoing it; it aborts without modifying auth.json if key entry is cancelled or empty, and creates the replacement file with owner-only (0600) permissions before writing the key. On native Windows, follow the documented auth.json file-auth steps (auth_mode set to "apikey" and OPENAI_API_KEY set to your key) in your active Codex directory ($CODEX_HOME or %USERPROFILE%\.codex) from the BetterToken Codex setup guide:

CODEX_DIR="${CODEX_HOME:-$HOME/.codex}"
mkdir -p "$CODEX_DIR"
if IFS= read -rs BETTERTOKEN_API_KEY && [ -n "$BETTERTOKEN_API_KEY" ]; then
  export BETTERTOKEN_API_KEY CODEX_DIR
  python3 -c 'import json, os, pathlib, tempfile
dir_path = pathlib.Path(os.environ["CODEX_DIR"])
fd, tmp_name = tempfile.mkstemp(prefix=".auth.", dir=dir_path)
try:
    os.fchmod(fd, 0o600)
    with os.fdopen(fd, "w", encoding="utf-8") as fh:
        json.dump({"auth_mode": "apikey", "OPENAI_API_KEY": os.environ["BETTERTOKEN_API_KEY"]}, fh, indent=2)
        fh.write("\n")
    os.replace(tmp_name, dir_path / "auth.json")
except Exception:
    os.unlink(tmp_name)
    raise'
  unset BETTERTOKEN_API_KEY
else
  echo "API key entry cancelled or empty; auth.json was not changed." >&2
fi

If you have Node.js installed and prefer automated setup, the BetterToken Codex documentation also provides curl -fsSL "https://www.bettertoken.ai/install-codex-provider.sh" | bash for macOS and Linux, plus a PowerShell installer (install-codex-provider.ps1) for Windows. Compare the generated config.toml and auth.json against the manual settings above before starting Codex.

To verify the setup, start a fresh codex session, run /status to confirm the Model (gpt-6.2-sol) and Model provider lines, and send a short prompt. A normal reply confirms the Responses connection.

If you prefer OpenAI’s own route instead, install or upgrade to 0.171.0 with npm install -g @openai/codex@0.171.0 (or start from an existing 0.171.0 installation) and confirm codex --version includes 0.171.0. Then run codex login for ChatGPT subscription access, or sign in with an OpenAI API key following OpenAI’s Codex authentication reference. Teams weighing subscription limits against API billing can review ChatGPT and Codex shared allowance planning.

Create a BetterToken account

Verify the GPT-6.2 Sol default and select Astra or another model

In PR #62106, Codex CLI 0.171.0 adds gpt-6.2-sol and gpt-6.2-astra to the bundled, Amazon Bedrock, and Vertex catalogs and makes gpt-6.2-sol the default catalog selection (priority: 1). It also increases gpt-6.1-sol’s catalog context window to 500,000 tokens.

In the 0.171.0 bundled catalog (codex-rs/models-manager/models.json), gpt-6.2-sol lists a 500,000-token context window and gpt-6.2-astra lists a 272,000-token context window, both with default_reasoning_level set to "low". On OpenAI’s API documentation as of 2026-11-21, both GPT-6.2 Sol and GPT-6.2 Astra support a 1,050,000-token context window (922,000 max input, 128,000 max output) and reject reasoning effort none.

Whether upgrading changes your active model depends on your configuration and active catalog (codex-rs/models-manager/src/manager.rs):

  • If model is unset in config.toml, get_default_model picks the default from the active catalog (default_model_from_available). When your session uses the bundled 0.171.0 catalog, that default is gpt-6.2-sol.
  • If model is explicitly set in your user config.toml (or a trusted project’s .codex/config.toml), Codex preserves that model unless provider fallback is enabled and replaces an unavailable model.

Inspect the catalog bundled with your installed binary:

codex debug models --bundled

Inside an interactive TUI session, run /status to check the Model line (and Model provider, when set). To switch models without editing config.toml, run /model inside the TUI or pass --model / -m on launch:

codex -m gpt-6.2-astra
codex exec -m gpt-6.2-astra "Audit the auth middleware for race conditions"

To make gpt-6.2-astra (or an older model such as gpt-6.1-sol) your persistent default, update or add model = "gpt-6.2-astra" at the root of $CODEX_HOME/config.toml (default ~/.codex/config.toml), above all [tables], and restart Codex.

As of 2026-11-21, OpenAI’s published Standard API text-token list prices for requests up to 272K input tokens are $2 input / $10 output per 1M tokens for GPT-6.2 Sol and $8 input / $40 output per 1M tokens for GPT-6.2 Astra. For requests with more than 272K input tokens on either model, input and cache rates double and output costs 1.5 times the short-context rate for the full request. Start with Sol for everyday coding and switch to Astra when a multi-file task needs deeper reasoning; see GPT-6 Astra vs Sol vs Luna for a fuller selection framework. OpenAI’s Ultrafast mode with Sol is a ChatGPT Pro 200 subscription feature (and on the OpenAI API, Ultrafast costs 3 times the Standard rate through February 28, 2027), not a default custom-gateway setting.

Map catalog names to actual model IDs on custom providers

Codex displays human-readable names like GPT-6.2-Sol and GPT-6.2-Astra in the picker, while each provider expects its own wire model ID.

ProviderGPT-6.2 Sol IDGPT-6.2 Astra IDNotes
OpenAI API (direct)gpt-6.2-solgpt-6.2-astraMatches Codex bundled catalog slugs
BetterToken (https://www.bettertoken.ai/v1)gpt-6.2-solgpt-6.2-astraVerified on BetterToken as of 2026-11-21 over OpenAI Responses (openai-response), plus openai and anthropic endpoint types
Amazon Bedrockopenai.gpt-6.2-solopenai.gpt-6.2-astraCatalog normalization also recognizes Bedrock Runtime cross-region IDs global.openai.gpt-6.2-astra and us.openai.gpt-6.2-astra
Google Vertex AIgpt-6.2-solgpt-6.2-astraAdded to the built-in GCP catalog in PR #62106
Other custom model_providerProvider-definedProvider-definedPin exact model = "..." in config.toml

When model is omitted in config.toml, Codex resolves the default from the active catalog rather than inferring a custom gateway’s naming convention. If your custom model_provider uses vendor-prefixed or aliased model IDs that differ from the bundled catalog slugs, requests can fail until you pin the exact model = "..." ID your gateway expects at the root of config.toml (never inside [projects."<path>"], which stores project trust_level).

TUI workspace on by default: what changed and how to turn it off

PR #61352 promotes the tui_workspace feature to Stable with default_enabled: true. Upgrading changes what opens beside your main conversation in the terminal:

  • Document previews (PR #61888, PR #61889): Opening transcript file links renders read-only Markdown tabs in the sidebar, with search, keyboard/mouse selection, offline Markdown copying, and Tab / Shift+Tab plus Enter link navigation.
  • Image previews (PR #61919): PNG, JPEG, GIF, and WebP links open as sidebar image previews with format and dimension labels, falling back to text when terminal graphics are unavailable. Completed, saved generated images appear after the assistant’s answer with a clickable Generated image label.
  • Subagent transcripts (PR #62157): Selecting a subagent from the sidebar opens a watch-only reader tab alongside the parent conversation instead of replacing your active chat.

Dismissing a sidebar view depends on what is focused:

  • In a document preview, press Esc to close the preview.
  • In a subagent transcript reader, press Esc to return to the subagent list with the same agent selected, or use the sidebar’s close button or close shortcut to dismiss the tab.

To turn the TUI workspace off for a single session, launch Codex with --disable:

codex --disable tui_workspace

To disable tui_workspace permanently in $CODEX_HOME/config.toml, run:

codex features disable tui_workspace

Or set the flag manually in $CODEX_HOME/config.toml:

[features]
tui_workspace = false

Start a new codex session to confirm the workspace sidebar stays off. Disabling tui_workspace turns off the sidebar and its preview tabs as a unit.

Remote execution with codex exec --remote vs TUI /rc and /remote

Codex CLI 0.171.0 adds two distinct remote features:

  • codex exec --remote <ADDR> runs a noninteractive turn against an already-running codex app-server.
  • /rc (alias /remote) manages device remote control for the managed local background server from inside the TUI.

codex exec --remote <ADDR> syntax, transport, and limits

PR #61707 lets codex exec attach to an existing app server using ws://host:port, wss://host:port, unix:// (default Unix socket), or unix://PATH.

Same-host or SSH port-forwarded example (loopback): Plain WebSocket listeners on ws://127.0.0.1:PORT are appropriate only for localhost or an SSH port-forwarded tunnel. Start the server on that host:

codex app-server --listen ws://127.0.0.1:4500

Then run codex exec on the same host (or over an SSH tunnel forwarding port 4500):

codex exec --remote ws://127.0.0.1:4500 "Run the test suite and summarize failures"

Separate host or CI runner (authenticated wss://): Non-loopback WebSocket listeners allow unauthenticated connections by default during rollout, and codex app-server itself listens on ws:// (see OpenAI’s app-server documentation). Before exposing an app server to another machine or CI runner, enable WebSocket authentication on the server (prefer --ws-token-file over passing raw tokens on the command line) and put TLS termination in front of it so clients connect over wss://:

# On the app-server host (behind a TLS reverse proxy exposing wss://remote-host:4500)
codex app-server --listen ws://127.0.0.1:4500 \
  --ws-auth capability-token \
  --ws-token-file /absolute/path/to/app-server-token

On the client or CI runner, pass the matching bearer token via an environment variable name with --remote-auth-token-env. In human output, codex exec --remote prints thread id: <UUID> to stderr; with --json, it emits a thread.started JSONL event ("type": "thread.started") containing thread_id. Substitute the UUID returned by your first run when resuming that thread:

if IFS= read -rs CODEX_REMOTE_TOKEN && [ -n "$CODEX_REMOTE_TOKEN" ]; then
  export CODEX_REMOTE_TOKEN

  # Start a new noninteractive turn (capture thread_id from the thread.started JSONL event)
  codex exec --remote wss://remote-host:4500 \
    --remote-auth-token-env CODEX_REMOTE_TOKEN \
    --json "Run the test suite and summarize failures"

  # Resume syntax example: replace <THREAD_UUID> with the thread_id returned above
  codex exec --remote wss://remote-host:4500 \
    --remote-auth-token-env CODEX_REMOTE_TOKEN \
    resume <THREAD_UUID> "Fix the failing parser test"

  unset CODEX_REMOTE_TOKEN
else
  echo "Remote token entry cancelled or empty." >&2
fi

You can place --remote and --remote-auth-token-env before or after exec; passing conflicting endpoints in both places fails with `codex exec` received conflicting remote server endpoints. Expect three strict constraints verified in 0.171.0 (codex-rs/exec/src/remote.rs):

  1. Server owns the agent config: Passing agent-configuration overrides such as -m/--model, -s/--sandbox, -C/--cd, -c overrides, -i/--image, -p/--profile, --add-dir, --output-schema, --ephemeral, or --worktree fails with "--remote currently supports only prompt, resume by UUID, and output options; configure the agent on the server".
  2. UUID-only resume: exec --remote resume rejects --last, --all, --image, or a non-UUID target with "remote resume requires a thread UUID".
  3. No concurrent turn: Targeting a thread whose status is already active fails with "remote thread already has an active turn".

/rc and /remote in the TUI

PR #62121 adds /rc (and /remote) inside the TUI to enable or disable remote control for the managed local background server. When enabled, the menu verifies that remoteControlEnabled saved to app-server-daemon/settings.json for the next restart and reports if saving failed; selecting Add device displays a manual pairing code. You can open /rc while viewing a cloud session, and its changes apply only to local sessions.

Check three prerequisites before relying on /rc:

  • The managed local background server must be running; otherwise remote-control actions fail with "Remote control requires the local background server."
  • You must be signed in with ChatGPT. API key auth is rejected with "Sign in with ChatGPT to manage remote control."
  • Enterprise administrators can block it globally by setting allow_remote_control = false in managed requirements.toml, which produces "Remote control is disabled by managed requirements."

Outside the TUI (such as over SSH), use codex remote-control start, codex remote-control stop, and codex remote-control pair as documented in OpenAI’s CLI reference.

Permission profiles across directory changes and other 0.171.0 fixes

Yes, your active permission profile stays intact when you change working directories in 0.171.0. In rust-v0.170.0, a directory-only update with a rebindable project-root write policy could re-derive a legacy permission profile from the legacy sandbox policy (codex-rs/core/src/session/session.rs).

PR #61195 removes that legacy rebuild branch so the active permission profile, its active selection, and its profile workspace roots remain preserved while runtime workspace roots update to the new directory. In the PR’s workspace-write regression check, ordinary files in the new workspace remain writable while writes to .git/config and the previous workspace stay denied; custom named profiles continue to follow their own configured roots and rules. If you maintain restricted network or filesystem profiles for package installs, review Codex sandbox permission profiles to verify your domain and write rules.

Three other fixes in rust-v0.171.0 reduce friction in daily CLI workflows:

  • Session switching keeps unsent text (PR #61216): Drafts, queued follow-ups, and interrupted input remain attached to their original threads when you switch or resume sessions.
  • Enterprise MCP sign-in without refresh tokens (PR #62129): Fixes MCP authentication for enterprise identity providers that issue ID tokens without refresh tokens.
  • Active-turn steering and approvals (PR #61820, PR #61801): Steering an active turn keeps earlier edits in aggregate diffs, and late completion events no longer cancel approvals for a newer turn.

Ready to optimize your LLM workflow?

Join thousands of developers building faster, smarter, and more cost-effective AI applications with BetterToken.

Get Started for Free