Why does Codex keep showing Reconnecting?

Most Reconnecting loops are network or proxy problems — Codex cannot reach OpenAI. Set HTTPS_PROXY, HTTP_PROXY and ALL_PROXY to your local proxy (e.g. http://127.0.0.1:7890). Codex does not support socks5, so convert it to an http proxy. A smaller share are version bugs; update to the latest release and restart all sessions.

Where is the Codex config file?

It lives at ~/.codex/config.toml (Windows: %USERPROFILE%\.codex\config.toml). Key fields include model and model_provider, plus [model_providers. ] for custom providers. Auth is stored in auth.json in the same folder.

OpenAI Codex CLI · Field Guide

Turn Reconnecting into ● connected

Q: How do I install the Codex CLI?

Install Node.js 18 or later, then run npm install -g @openai/codex. On macOS/Linux you can also use the official script: curl -fsSL https://chatgpt.com/codex/install.sh | sh. Verify with codex --version. The package name is @openai/codex — installing plain codex pulls an unrelated 2012 project.

Q: Do I have to pay to use the Codex CLI?

The CLI itself is free and open source, but calling the model requires a ChatGPT subscription (Plus and up) or an OpenAI API key. Signing in with ChatGPT reuses your plan; an API key is billed by usage.

From install and login to editing config.toml — and the bug everyone hits, the endless reconnect loop. Every newcomer trap, explained, with commands you can copy.

Install Codex → Fix Reconnecting

Copy-paste commands macOS / Windows / Linux Kept up to date

zsh — codex

Guide index

Find your answer by problem

The 8 things newcomers search for most — each walks from "why this happens" to "how to fix it, step by step."

⬇01 · INSTALL

Install Codex CLI

npm / official script / Homebrew, Node version requirements, and the wrong-package mistake everyone makes.

Read guide → ▸02 · USAGE

Login & first run

ChatGPT login vs API key, your first prompt, approval and sandbox modes, and AGENTS.md memory.

Read guide → ⚙03 · CONFIG

Configure config.toml

Model, provider, third-party API endpoints, context window — every core key with a full example.

Read guide → ↻04 · TOP ISSUE

Stuck on Reconnecting

Work through the reconnect loop: proxy, socks5, auth conflicts, the VS Code extension, WSL2 and bugs.

Troubleshoot → ⚑05 · PROXY

Proxy & restricted networks

Why a proxy is required behind firewalls, how to set it in the terminal vs VS Code, and faster npm mirrors.

See setup → ⚠06 · ERRORS

Common errors

401 auth failures, 429 rate limits, port 1455 in use, headless login — a quick lookup table.

Look it up → ⌘07 · COMMANDS

Commands & slash commands

codex / exec flags, /model, /approvals, /init and the permission & sandbox modes explained.

Read guide → ⚖08 · COMPARE

vs Claude Code

2026 pricing, context windows, SWE-bench scores and which tool fits which job — and how to run both.

See comparison → 💡

What is Codex CLI?

Core features, how it differs from ChatGPT, and real-world use cases.

💰

Pricing & Costs

Free tier, API billing details, and money-saving tips explained.

⚡

Codex vs Cursor

Deep comparison of both AI coding tools — find your best fit.

Not here?

Search your exact error

Paste the raw terminal error + "codex" into a search engine, then come back to the errors table.

Most frequent issue

Why does Codex keep Reconnecting?

Eight times out of ten Codex isn't broken — it simply can't reach OpenAI. Reconnect failures usually come from one of these, in priority order:

No / wrong proxy: behind a firewall you must set HTTPS_PROXY.
socks5 proxy: Codex doesn't read socks5 — convert it to http.
OAuth vs API key conflict: both present at once is unstable.
VS Code extension / WSL2: separate proxy; WSL doesn't inherit Windows proxy.
Version bug: known issues on some builds — update to latest.

Full checklist →

~/.zshrc or ~/.codex/config.toml

# 1) set for the current shell (most common)
export HTTPS_PROXY="http://127.0.0.1:7890"
export HTTP_PROXY="http://127.0.0.1:7890"
export ALL_PROXY="http://127.0.0.1:7890"

# 2) verify the proxy works
$ curl -I https://api.openai.com/v1

# 3) reconnect
$ codex

30-second start

Shortest path: install → log in → go

STEP 01

Install

$ npm i -g @openai/codex

Needs Node ≥ 18. Note the @openai/ scope.

STEP 02

Log in

$ codex
# sign in with ChatGPT

Or codex login --with-api-key.

STEP 03

Run it

› fix the error on the login page

Just describe the task in plain language.

FAQ

The questions newcomers ask first

How do I install the Codex CLI?

Install Node.js 18+ then run npm install -g @openai/codex; on macOS/Linux you can also use curl -fsSL https://chatgpt.com/codex/install.sh | sh. Verify with codex --version. It must be @openai/codex — plain codex is an unrelated 2012 package.

Why does it keep showing Reconnecting?

Almost always a network/proxy issue. Behind a firewall Codex can't reach OpenAI, so set HTTPS_PROXY to a local proxy — and not socks5 (convert to http). See the Reconnecting checklist.

Do I have to pay?

The CLI is free and open source, but the model needs a ChatGPT subscription (Plus and up) or an OpenAI API key. ChatGPT login reuses your plan; an API key bills per token.

Where is config.toml and how do I change the model?

At ~/.codex/config.toml (Windows: %USERPROFILE%\.codex\config.toml). Set model = "gpt-5.3-codex" for the default, or switch in-session with /model. See the config guide.

Codex or Claude Code — which should I pick?

In short: Codex is cheaper, edges ahead on benchmarks, and suits high-volume automation; Claude Code is rated higher for quality, context-heavy and security-sensitive work. Many teams run both. See the comparison.

Start here

Still stuck reconnecting? Fix the network first

90% of newcomer issues are just three things: the wrong package, no proxy, or an auth conflict. Walk the guide once and it usually runs.

Fix Reconnecting → Installation guide