Contents
  1. 1. Prerequisites & Terminal Network Configuration
  2. Terminal Proxy Setup (Crucial for CLI)
  3. Method A: Desktop App (Recommended for Beginners)
  4. Method B: Terminal CLI (Recommended for Engineers)
  5. 2. Authentication & OAuth Sign-in
  6. 3. Verification & First Ping
  7. 4. The 3 Sanity Checkpoints
  8. 5. Troubleshooting & Edge Cases
  9. 6. Best Practice: Protect Your Codebase from Day One

The Beginner's Guide to Codex: Desktop App & Terminal CLI Setup Walkthrough

Among modern AI programming assistants, OpenAI's Codex stands out for its strong architectural reasoning and autonomous engineering capabilities, whether packaged as a standalone desktop application or running inside your terminal as a CLI.

However, newcomers often hit roadblocks early in the setup process. Complex prerequisites, connection timeouts, or missing environment variables can cause frustration before writing a single line of code.

In reality, running Codex successfully comes down to three fundamental actions: installing the binary, authenticating your account, and verifying bidirectional communication.

Codex 3 Sanity Checkpoints

This guide covers both the Desktop and CLI workflows, along with practical troubleshooting steps and essential terminal configuration.

1. Prerequisites & Terminal Network Configuration

Before initiating installation, ensure your environment can reliably reach chatgpt.com.

Terminal Proxy Setup (Crucial for CLI)

A frequent pitfall for developers in restricted network environments is that terminal sessions do not automatically inherit system-level graphical proxy configurations.

If your browser can access ChatGPT but your terminal installation script hangs, explicitly route traffic through your local proxy port (e.g., standard Clash/v2ray port 7890):

macOS / Linux:

export http_proxy="http://127.0.0.1:7890"
export https_proxy="http://127.0.0.1:7890"
export all_proxy="socks5://127.0.0.1:7890"

# Verify connectivity
curl -I https://chatgpt.com/codex

Windows PowerShell:

$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"

A returned HTTP 200 or 301 status confirms that the terminal tunnel is active.

If you prefer a clean graphical user interface without managing shell environments:

  1. Navigate to the official download page: https://chatgpt.com/codex;
  2. Download the installer for your operating system (macOS .dmg or Windows .exe);
  3. Double-click the installer and follow the on-screen prompts.

The desktop app mirrors familiar messaging interfaces, offering an accessible starting point.

For developers who spend most of their time in Neovim, Tmux, or integrated VS Code terminals, the CLI provides tighter file system integration and faster iteration.

macOS & Linux: Run the official automated shell script:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows: Launch PowerShell as Administrator (do not use legacy cmd.exe) and run:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Once installation finishes, restart your terminal session to ensure your environment reloads the updated $PATH.

2. Authentication & OAuth Sign-in

Once installed, link your OpenAI account:

  1. Desktop App: Launch the app and click "Sign In." Your default browser will open automatically. Complete authentication and click Authorize.

  2. Terminal CLI: Execute the startup command:

    codex

    Codex spins up a temporary local callback server and opens the browser authorization portal. Once you approve access on the web page, the terminal captures the authentication token and prints Authentication successful.

3. Verification & First Ping

To ensure the end-to-end toolchain is sound, avoid asking Codex to refactor an entire codebase immediately. Instead, run a minimal ping test.

Desktop App: In the bottom message input, simply type:

Hello

Terminal CLI: Do not launch the CLI directly inside a mission-critical project repository during initial testing. Create an isolated sandbox directory first:

mkdir codex-test
cd codex-test
codex

Inside the interactive prompt, type:

Hello

If the model streams back a coherent greeting, your local binary runtime, network proxy route, OAuth authorization, and API streaming pipeline are all functioning properly.

4. The 3 Sanity Checkpoints

Keep these criteria in mind when diagnosing setup issues:

  1. Installed: The desktop icon opens, or executing codex --version in terminal outputs valid version information.
  2. Authenticated: The browser confirms login and the terminal releases its authorization listener.
  3. Responsive: Sending a simple greeting returns a real-time streaming completion.

5. Troubleshooting & Edge Cases

  • command not found: codex: Your shell has not refreshed its path cache. Restart the terminal or check whether ~/.local/bin (or similar install paths) exists in your PATH configuration.
  • Windows irm is not recognized: You are running the legacy Command Prompt (cmd.exe). Switch to Windows PowerShell.
  • Infinite Loading on Login Page: Confirm that your proxy allows local loopback traffic (127.0.0.1), as the OAuth flow requires the browser to pass the token back to a local port.
  • Install Script Stalls at 0%: Terminal traffic is being blocked. Revisit Section 1 to export your HTTP proxy settings.

6. Best Practice: Protect Your Codebase from Day One

When introducing Codex to an existing repository, start with a read-only exploration prompt before authorizing file modifications:

Review the project structure and dependencies in package.json.
Provide a high-level summary of what this application does and outline its core modules.
Do NOT modify, create, or delete any files during this step.

Allowing the agent to describe its mental model first helps verify its context before making real code edits, avoiding unexpected repository churn.