Environment & Login
Emergency Manual

Symptom Quick Check + Problem Map

Symptom Quick Check: Pinpoint your problem in 30 seconds

Problem Map: All environment issues have 4 root causes

Claude Code and Codex "environment issues" seem diverse, but only have 4 root causes. Recognize the root cause, and all following chapters will map and fix them here.

Two Tools, One Mental Model

Good news: The environment architecture of the two tools is highly isomorphic. Learn the methodology once, apply it to both.

Full comparison table in Chapter 13. All conclusions on this page are verified against official docs 2026-07 edition, sources are in footnotes of each section.

Five diagnostic layers

Check executable/version, environment variable names, authentication, loaded configuration, and the actual network endpoint. Multiple installations or proxy variables are not automatically wrong. Never print credential files or full environment values. Use Claude /status for loaded sources; do not assume an undocumented Codex /debug-config exists.

codex --version
claude --version
# Variable names only (macOS / Linux / WSL)
env | cut -d= -f1 | sort | grep -iE 'anthropic|claude|codex|openai|proxy' || true

依据：Codex configuration · Claude settings

Claude Code · Authentication

Managed settings precede CLI --settings, local project, shared project and user settings. Environment precedence is decided per key; arrays have exceptions. Authentication includes subscriptions, Console, API credentials, cloud providers and enterprise gateways. Desktop/cloud do not simply inherit CLI helpers.

Authentication →

依据：Official reference

Claude Code · Configuration

Managed settings precede CLI --settings, local project, shared project and user settings. Environment precedence is decided per key; arrays have exceptions. Authentication includes subscriptions, Console, API credentials, cloud providers and enterprise gateways. Desktop/cloud do not simply inherit CLI helpers.

Configuration →

依据：Official reference

Claude Code · Troubleshooting

Managed settings precede CLI --settings, local project, shared project and user settings. Environment precedence is decided per key; arrays have exceptions. Authentication includes subscriptions, Console, API credentials, cloud providers and enterprise gateways. Desktop/cloud do not simply inherit CLI helpers.

Troubleshooting →

依据：Official reference

Codex · Authentication

Use the dedicated configuration chapter for provider IDs, authentication, endpoints, mutual exclusions and migration. Official ChatGPT login, API usage and gateway credentials are different paths with different access and billing.

Authentication →

依据：Official reference

Codex · Configuration

Use the dedicated configuration chapter for provider IDs, authentication, endpoints, mutual exclusions and migration. Official ChatGPT login, API usage and gateway credentials are different paths with different access and billing.

Configuration →

依据：Official reference

Codex · Troubleshooting

Use the dedicated configuration chapter for provider IDs, authentication, endpoints, mutual exclusions and migration. Official ChatGPT login, API usage and gateway credentials are different paths with different access and billing.

Troubleshooting →

依据：Official reference

Playbook A · Shared Computer / Inheriting a Pre-configured Machine

The most frequent failure scene: You are a Claude Pro user, sitting at a computer someone else used, and hitting walls of errors. The root cause is almost always the same: The previous user's credentials and env vars are still alive, and their priority is higher than your login.

The 3 Pre-Checks (Do this before configuring)

1. Check Env Vars and RC Residue: Run Chapter 01 Health Check script, focusing on L2 output —— export ANTHROPIC_API_KEY / ANTHROPIC_BASE_URL (proxy config) / OPENAI_API_KEY in someone else's rc file are ticking time bombs.
2. Check Credential Ownership: Run claude into session and /status to see whose account is logged in; same for codex login status. If it's someone else's, /logout / codex logout first.
3. Check Global Config Pollution: Check if ~/.claude/CLAUDE.md, ~/.claude/settings.json, ~/.codex/config.toml, ~/.codex/AGENTS.md contain someone else's preferences or instructions —— these will directly impact all your conversations.

Choose Solution Based on Sharing Level

Running Multiple Config Profiles on One System Account (Isolation Solution)

# ~/.zshrc —— Independent config dir + dedicated command for each person/account
# Claude Code: CLAUDE_CONFIG_DIR dictates where "home" is
alias claude-me='CLAUDE_CONFIG_DIR="$HOME/.claude-me" claude'
alias claude-work='CLAUDE_CONFIG_DIR="$HOME/.claude-work" claude'
# Codex: CODEX_HOME similarly
alias codex-me='CODEX_HOME="$HOME/.codex-me" codex'
alias codex-work='CODEX_HOME="$HOME/.codex-work" codex'

• On first use, each directory walks through its own login; credentials, history, and configs are completely isolated. No more logging in and out repeatedly;
• Anti-mixup trick: Use /color in different account sessions to change UI theme colors, instantly recognizing "who I am right now" (community madewithlove solution);
• Note that Claude Code also has a global state file ~/.claude.json (MCP, etc.), which follows the directory if CLAUDE_CONFIG_DIR is set —— stop manually touching the one in the default location.

References: Running multiple Claude accounts without logging out (madewithlove) · Two Claude accounts on one Windows PC (Josh Grossman) · codex-multi-auth (community tool)

Playbook B · Switching Computers / Multi-Machine Roaming

Core principle in one sentence: Configs travel with you, credentials login fresh per machine, history stays put. Figure out "what to take, what to leave", and swapping machines takes 10 minutes.

What to Take, What to Leave (Dual Tool Comparison)

New Machine 10-Minute Standard Procedure

New Machine 10-Minute Standard Procedure

# 1. Install (Official native channels, do not mix with npm)
curl -fsSL https://claude.ai/install.sh | bash        # Claude Code
npm install -g @openai/codex                          # Codex (or brew install codex)

# 2. Restore Configs (dotfiles method)
git clone git@github.com:your_name/dotfiles.git ~/dotfiles
ln -s ~/dotfiles/claude ~/.claude                     # Or export CLAUDE_CONFIG_DIR=~/dotfiles/claude
ln -s ~/dotfiles/codex ~/.codex                       # Or export CODEX_HOME=~/dotfiles/codex

# 3. Login once for each (NEVER copy credentials)
claude          # Browser OAuth → /status to verify account and Login method
codex login     # Browser OAuth → codex login status to verify

# 4. Final Health Check
claude doctor && bash ai-env-check.sh

References: Official ~/.claude Directory Guide · anthropics/claude-code#36693 (Multi-machine sync discussion)

Playbook C · SSH / Containers / Headless / CI

In environments without a browser, logging in requires a different approach. The official recommended paths for the two tools differ, so do not mix them up.

Claude Code: Three Paths

1. SSH/WSL2/Container Interactive Use: Run claude normally, copy the OAuth URL from the terminal into your local browser to complete login, then paste the code back into the terminal (if pasting fails, use claude auth login to read from stdin).
2. CI / Scripts (Subscription Quota): Run claude setup-token locally to generate a 1-year OAuth token, store it in CI Secrets, and set CLAUDE_CODE_OAUTH_TOKEN in the execution environment. Note that --bare mode ignores this; for bare scenarios, use ANTHROPIC_API_KEY or apiKeyHelper instead.
3. CI (API Billing): Just use the ANTHROPIC_API_KEY environment variable —— simplest, but uses pay-as-you-go billing.

Codex: Three Official Methods by Priority

1. Device Code (Preferred): codex login --device-auth, enter the one-time code in any local browser. Workspace admins might need to enable device code permissions first.
2. Copy auth.json (Official Fallback): Log in on a machine with a browser, then securely copy ~/.codex/auth.json to the target machine (scp / docker cp). If local credentials are in the keychain instead of a file, set cli_auth_credentials_store to file and re-login first.
3. SSH Port Forwarding: ssh -L 1455:localhost:1455 user@remote then run codex login on the remote machine; the local browser handles the standard flow.

Codex CI Long-term Auth (Official auth.json Renewal Loop)

The official way to run CI using ChatGPT subscription quota —— leveraging Codex's mechanism to automatically refresh the token and write back to auth.json during runtime:

1. Run codex login (file storage) on a trusted machine, store the generated auth.json into CI Secrets management;
2. For each task: Restore auth.json → Run Codex (token goes stale if not refreshed for ~8 days, auto-renews during runtime) → Write back the refreshed auth.json to Secrets;
3. Red lines: Do not share the same auth.json across concurrent tasks; Do not overwrite with the original old file every time; If the refresh chain breaks, go back to a trusted machine to re-login and seed a new one. For self-hosted runners, just providing a persistent CODEX_HOME is easier.

Company Network (Proxy / Private CA) Quick Lookup

Sources: Official Authentication (setup-token) · Official Codex CI/CD auth (2026-07 Edition)

Case Studies: From Symptoms to Root Causes

Four high-frequency real-world scenarios, walking through the 5-Layer Diagnostic Method from start to finish. Understand these four, and you can solve most "voodoo problems" yourself —— note how far the error text is from the actual root cause in each case.

Case I · "I'm a Pro subscriber, but it says organization disabled"

Case II · "VS Code extension keeps saying Invalid API key, but terminal is fine"

Case III · "Woke up and all parallel sessions demand re-login"

Case IV · "Codex ran stable in CI for a week, suddenly 401 across the board"

Case Basis: Official troubleshoot-install / authentication docs, anthropics/claude-code#12204, Codex CI/CD auth official guide (2026-07 verified); Machine and persona details are adapted for scenarios, but diagnostic paths and root causes represent real mechanisms.

Recoverable diagnostics and resets

Save errors, versions, effective configuration, and redacted logs. Reauthenticate only when evidence points to credentials. Do not erase entire configuration directories: partial backups cannot restore all sessions, skills, and state.

If isolation is needed, identify actual custom paths, make a complete timestamped copy, and verify readability. Preserve originals and change one confirmed item at a time. A failed reset does not prove a server-side cause.

Dual Tool Concept Map + Resource Index

One Table to Bridge Both Tools

Resource Index (Sorted by Reliability)