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

From installation and config to AGENTS.md, CI/CD, and advanced tips — each guide walks from "why this happens" to "how to fix it, step by step," covering the full Codex CLI lifecycle.

⬇01 · INSTALL

Install Codex CLI

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

Read guide → 🪟

Windows Install Guide

WSL2 (recommended), PowerShell, and Git Bash — plus WSL2 proxy passthrough, script execution policy, and EPERM errors.

Windows guide → ↑

Update to Latest

One command to upgrade Codex CLI, check version numbers, pin CI versions, and 2026 config migration notes.

▸02 · USAGE

Login & first run

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

Read guide → 🔑

API Key Setup Guide

Where to get a key, codex login vs env variable, multi-account direnv management, and emergency key revocation steps.

Configure auth → ⚙03 · CONFIG

Configure config.toml

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

Read guide → 🔒

Sandbox & Approval Modes

suggest vs auto-edit vs full-auto: when to use each mode and safe CI/CD configuration.

↻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 → 🤖

vs GitHub Copilot

Feature differences, pricing, autonomous tasks vs inline completion: which tool suits which developer.

See comparison → 💡

What is Codex CLI?

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

⭐

Review 2026

Honest take: pros, cons, benchmarks, and competitor comparisons — is it worth it? Rated 4.1 / 5.

💰

Pricing & Costs

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

🤖

Model Selection Guide

o4-mini vs GPT-4.1 vs o3 compared — pick the right model per task and cut costs by 80%.

⚡

Codex vs Cursor

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

🔀

Codex vs Aider

Open source vs official — model flexibility and auto-commit behavior compared.

📝

AGENTS.md Guide

Give Codex persistent project memory. Generate with /init, learn the structure and nested monorepo patterns.

⚙️

CI/CD Integration

Drive GitHub Actions with codex exec: auto-generate changelogs, AI code review, and test completion.

▶

codex exec Guide

Non-interactive mode deep dive: syntax, exit codes, approval modes, GitHub Actions & GitLab CI examples.

💡

Tips & Advanced Usage

Effective prompt patterns, model selection strategy, context management, daily workflows, and common pitfalls.

🦙

Ollama & Local Models

Configure Codex CLI with Qwen2.5-Coder, DeepSeek-Coder, and other local models — offline, zero cost, data stays on your machine.

📋

50+ Prompt Examples

Refactoring, test generation, bug fixing, docs, CI/CD automation — battle-tested prompt templates, copy-paste ready.

🌿

Git Workflow Automation

Auto-generate Conventional Commits messages, draft PR descriptions, AI code review — end-to-end intelligent Git workflow.

🐍

Python Developer Guide

Configure AGENTS.md for Python projects, auto-generate pytest tests, fix mypy errors, Django/FastAPI scenarios covered.

⚡

JavaScript/TypeScript Guide

React component generation, TypeScript error fixing, Vitest test automation, Next.js App Router, Node.js/Bun backend — all covered.

📂

Multi-File & Large Codebases

Context window management, .codexignore config, Monorepo support (Turborepo/Nx), incremental refactoring strategies and case studies.

🔐

Security & Privacy Guide

Does Codex upload your code? Sandbox mechanism, API key security, enterprise privacy config, and Ollama local deployment option.

🔍

Debugging Guide

--verbose mode, CODEX_LOG_LEVEL log levels, --dry-run preview, and step-by-step fixes for 5 common failure patterns.

♻️

Refactoring Guide

5-step safe refactoring workflow, extract/rename/split patterns, TypeScript migration, TDD refactoring — with prompt templates.

🐹

Go Developer Guide

AGENTS.md for Go projects, table-driven test generation, go vet/staticcheck fixes, interface refactoring, concurrency patterns, and GitHub Actions CI.

⚡TOOL · Free tool

Network Risk Detector

Check your IP ban risk, WebRTC leak, and OpenAI reachability in one click — with copy-paste fix commands.

Run check →

Not here?

Search your exact error

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

Free online tool

⚡ Check your network ban risk before you start

Many Codex issues come from a bad network environment. This tool gives you a 30-second diagnosis:

IP risk rating: residential / datacenter / China direct
WebRTC real IP leak: spotted even through a proxy
OpenAI API reachability: live connectivity and latency test
Copy-paste fix commands: for every issue found

⚡ Run check → Proxy setup guide

Network check · sample result

✓ Exit IP: 203.0.113.x Residential

✓ Location: Japan · NTT Communications

✓ WebRTC: No leak detected

✓ OpenAI API: reachable (138ms)

✓ Timezone: Asia/Tokyo consistent

Risk score: 8/100 — Low risk

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