One-Click Setup Script

One command to fully configure Claude Code / Codex: latency-based endpoint selection, config writing, CLI installation and connectivity verification — no sudo / admin rights required

One-Click Setup Script¶

Go from zero to working with a single command: the script picks the fastest endpoint via a latency test, prompts you for your API key, writes the configuration, installs Node.js and the CLI if needed, then sends a minimal request to verify connectivity. Start by picking your operating system:

📖 Before running, grab your API key (starting with cr_) from the QCode.cc dashboard; the script will prompt you to paste it (input is not echoed).

Interface language¶

The scripts follow your system language and switch between English and Chinese automatically. To force one explicitly:

# macOS / Linux
curl -fsSL https://qcode.cc/install/claude-code.sh | bash -s -- --lang zh

# Windows PowerShell
$env:QCODE_LANG='zh'; irm https://qcode.cc/install/claude-code.ps1 | iex

Chinese is the default when your system locale is Chinese; the plain commands above are unaffected. The same applies to codex.

🍎 macOS / 🐧 Linux¶

Open a terminal and paste (no sudo needed):

Claude Code¶

curl -fsSL https://qcode.cc/install/claude-code.sh | bash

Codex¶

curl -fsSL https://qcode.cc/install/codex.sh | bash

Configuration is written to your shell config file (a managed block in ~/.zshrc / ~/.bashrc) or ~/.codex/; if Node.js is missing, it is installed into your home directory via nvm.

🪟 Windows¶

Native PowerShell is all you need — no WSL, no administrator rights. Open Windows Terminal or PowerShell and paste:

Claude Code¶

irm https://qcode.cc/install/claude-code.ps1 | iex

Codex¶

irm https://qcode.cc/install/codex.ps1 | iex

No irm, or blocked by the execution policy?¶

The scripts already relax the execution policy for the current run only (your user-level and machine-level settings are left untouched), and prefer npm.cmd over the policy-restricted npm.ps1. For the remaining cases:

1. In CMD (Command Prompt), or if you get "irm is not recognized"

irm is a PowerShell command and does not exist in CMD. This one works in both:

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://qcode.cc/install/claude-code.ps1 | iex"

2. To run it by double-clicking, or if iex is blocked by policy

Download the .cmd bootstrapper, then double-click it or run it from CMD:

curl -fsSL https://qcode.cc/install/claude-code.cmd -o "%TEMP%\qcode.cmd" && "%TEMP%\qcode.cmd"

Windows 10 1803+ ships curl.exe. The .cmd picks PowerShell 7 when available, forces TLS 1.2, and keeps the window open at the end so a double-click never flashes past. For a Chinese UI: "%TEMP%\qcode.cmd" zh. For Codex, replace claude-code with codex.

3. So that claude / codex also run unblocked in future PowerShell sessions

The relaxation above only covers the current session. Run this once — no administrator rights required, it only affects your own account:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Windows-specific notes:

• Configuration is written to user-level environment variables (Codex writes to %USERPROFILE%\.codex\); previous values are automatically backed up to %USERPROFILE%\.qcode\
• If Node.js is missing, the LTS release is installed via winget; without winget, you'll get instructions for manual installation from nodejs.org
• Once setup completes, newly opened PowerShell / terminal windows pick up the config automatically; editors like VS Code need one restart
• If the script is blocked by the execution policy, run Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser first, then retry

Codex: desktop App or CLI¶

codex.sh / codex.ps1 first asks which client you plan to use:

1. Codex desktop App (default, just press Enter) — writes the config files only; Node.js and the CLI are neither checked nor installed
2. Codex CLI — also applies to the App; installs Node.js and the Codex CLI as needed

If you only use the desktop App, pick 1 and Node is never touched. Re-run the script and pick 2 whenever you later want the CLI. Non-interactive: --target app / --target cli (Windows: -Target app / -Target cli).

⚠️ ~/.codex/config.toml is overwritten as a whole. Your existing MCP servers, profiles and approval_policy are not preserved — the script says so explicitly and backs the original up as .bak.<timestamp> in the same directory. Merge them back manually from that backup.

What the script does¶

1. Latency-based endpoint selection — sends one lightweight request to each of the four endpoints (api / asia / us / eu) and recommends the fastest (you can override the choice)
2. Write configuration — Claude Code: a managed shell block on macOS/Linux, user-level environment variables on Windows; Codex: ~/.codex/config.toml + auth.json (default model chosen interactively, gpt-5.6-terra recommended)
3. Install the environment (skippable) — checks for Node.js ≥ 20, installs the LTS release via nvm (macOS/Linux) or winget (Windows) if missing, then installs the CLI with npm install -g; everything stays in your user directory
4. Verify connectivity — sends a minimal request with your key, and on failure gives targeted troubleshooting hints based on the HTTP status code
5. Back up before writing — every modified file is first backed up as .bak.<timestamp>; on Windows, previous environment variables are backed up to %USERPROFILE%\.qcode\
6. Key sanitising — surrounding quotes, whitespace and full-width punctuation pasted along with the key are stripped automatically; a key with invalid characters in the middle is rejected outright rather than written into your config

Non-interactive mode (CI / no prompts)¶

macOS / Linux:

curl -fsSL https://qcode.cc/install/claude-code.sh | bash -s -- --key cr_xxx --yes

Windows with parameters (matching the table above: -Key, -Domain, -Model, -Lang, -Target, -Yes, -NoInstall, -NoVerify):

& ([scriptblock]::Create((irm https://qcode.cc/install/claude-code.ps1))) -Key cr_xxx -Yes

(Same pattern for codex.ps1.)

What files are written / how to roll back¶

Re-running the script is always safe: the managed block is updated in place, and config files are backed up before being overwritten.

FAQ¶

• Verification returns 401 — invalid or expired key: check it in the dashboard (make sure the cr_ prefix was copied in full), then re-run the script
• Verification returns 404 — wrong endpoint URL: the BASE_URL should be https://{domain}/api for Claude Code and https://{domain}/openai for Codex, with no trailing slash
• Network timeout — re-run the script with a different endpoint (e.g. --domain asia); live status for each endpoint is at probe.qcode.cc
• claude / codex command not found after installing on Windows — open a new PowerShell window (PATH only refreshes in new sessions)
• Don't want the script to install Node — add --no-install (Windows: -NoInstall) to write configuration only
• Want to inspect the script first — open https://qcode.cc/install/claude-code.sh and read the source; the script needs no sudo / administrator rights and never writes to system directories
• "The API key contains invalid characters" — quotes, spaces or smart punctuation were pasted along with the key. The script strips surrounding quotes and whitespace automatically, but characters in the middle are still rejected; copy it again from the dashboard
• "You are running this script with sudo" — the script does not need sudo. Running it with sudo writes the config into root's home directory, where your own shell will never read it; re-run without sudo
• "Config was written, but verification did not pass" — the configuration files are already in place; only the final connectivity check failed. Follow the status code in the message (401 → recheck the key, 404 → check the address, timeout → try another endpoint), then re-run