# 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](https://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:

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

```powershell
# 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

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

### Codex

```bash
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

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

### Codex

```powershell
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:

```powershell
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](https://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:

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

| Flag | Description |
|------|------|
| `--key <cr_...>` | API key; when provided, skips the interactive prompt |
| `--domain <api\|asia\|us\|eu>` | Pin the endpoint, skipping the latency test |
| `--model <id>` | (codex.sh only) Set the default model, skipping the picker |
| `--lang <zh\|en>` | Interface language; follows the system locale by default |
| `--target <app\|cli>` | (codex only) Config only / also install the CLI; asks interactively by default |
| `--yes` / `-y` | Accept the default for every confirmation |
| `--no-install` | Write configuration only, don't install Node / CLI |
| `--no-verify` | Skip connectivity verification |
| `--help` | Show all flags |

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

```powershell
& ([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

| Tool / platform | Written to | Rollback |
|------|------|------|
| Claude Code (macOS/Linux) | The `# >>> qcode.cc claude-code >>>` managed block in `~/.zshrc` or `~/.bashrc` | Delete the entire managed block, or restore from the `.bak.<timestamp>` backup in the same directory |
| Claude Code (Windows) | 3 user-level environment variables | Restore the previous values from `%USERPROFILE%\.qcode\backup-*.json` |
| Codex (all platforms) | `~/.codex/config.toml` + `~/.codex/auth.json` | Restore from the `.bak.<timestamp>` backup in the same directory |

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](https://qcode.cc/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](https://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](https://qcode.cc/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