# 一键配置脚本

用一条命令完成从零到可用：脚本自动测速选择最快接入域、引导输入密钥、写入配置、按需安装 Node.js 与 CLI，最后发一条最小请求验证连通。**先选你的操作系统**：

> 📖 运行前请先在 [QCode.cc 控制台](https://qcode.cc/dashboard) 准备好 `cr_` 开头的 API 密钥；脚本运行中会提示粘贴（输入不回显）。

## 界面语言

脚本会跟随系统语言自动选择**中文**或**英文**。也可以显式指定：

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

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

中文是默认值，原有命令不受影响；`codex` 同理。

## 🍎 macOS / 🐧 Linux

打开终端，粘贴运行（不需要 sudo）：

### Claude Code

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

### Codex

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

配置写入 shell 配置文件（`~/.zshrc` / `~/.bashrc` 托管块）或 `~/.codex/`；缺 Node.js 时用 nvm 装在用户目录。

## 🪟 Windows

**原生 PowerShell 即可——不需要 WSL，不需要管理员权限。** 打开「Windows 终端」或 PowerShell，粘贴运行：

### Claude Code

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

### Codex

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

### 没有 irm，或被执行策略拦下？

脚本本身已经会为**本次运行**自动放宽执行策略（不改动你的用户级 / 机器级设置），并优先调用
`npm.cmd` 而不是受策略限制的 `npm.ps1`。以下几种情况另有走法：

**① 在 CMD（命令提示符）里，或提示 `irm` 不是内部或外部命令**

`irm` 是 PowerShell 的命令，CMD 里不认。这一条在 CMD 和 PowerShell 里都能跑：

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

**② 想双击运行，或 `iex` 被安全策略挡下**

下载 `.cmd` 引导脚本后双击，或在 CMD 里运行：

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

Windows 10 1803+ 自带 `curl.exe`。`.cmd` 会自动选用 PowerShell 7（若已安装）、强制 TLS 1.2，
并在结束时停住窗口，双击不会一闪而过。指定英文界面：`"%TEMP%\qcode.cmd" en`。
Codex 把上面的 `claude-code` 换成 `codex` 即可。

**③ 希望以后新开的 PowerShell 里跑 `claude` / `codex` 也不被拦**

脚本的放宽只对本次会话有效。执行一次下面这条（**不需要管理员权限**，只影响你自己）：

```powershell
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
```

Windows 版说明：

- 配置写入**用户级环境变量**（Codex 写 `%USERPROFILE%\.codex\`），旧值自动备份到 `%USERPROFILE%\.qcode\`
- 缺 Node.js 时用 winget 安装 LTS；没有 winget 会给出 [nodejs.org](https://nodejs.org/) 手动安装指引
- 配置完成后，**新开的** PowerShell / 终端自动生效；VS Code 等编辑器需要重启一次
- 如果提示脚本被执行策略拦截，先执行 `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser` 再重试

## Codex：桌面 App 还是 CLI

运行 `codex.sh` / `codex.ps1` 时会先问你要在哪个客户端里用：

1. **Codex 桌面版 App**（默认，直接回车）—— 只写配置文件，**不检测也不安装 Node.js / CLI**
2. **Codex CLI** —— 同时对 App 生效，会按需安装 Node.js 与 Codex CLI

只用桌面 App 的话选 1，全程不碰 Node；以后想用 CLI 时重跑脚本选 2 即可。
非交互指定：`--target app` / `--target cli`（Windows：`-Target app` / `-Target cli`）。

> ⚠️ `~/.codex/config.toml` 是**整体覆盖**写入的。你原有的 MCP server、profile、
> `approval_policy` 等自定义配置不会被保留 —— 脚本会明确提示，并把原文件备份为同目录的
> `.bak.时间戳`，请从备份里手动合并回来。

## 脚本做了什么

1. **测速选域** —— 对 api / asia / us 三个接入域各发一次轻量请求，推荐最快项（可手动改选）
2. **写入配置** —— Claude Code：macOS/Linux 写 shell 托管块、Windows 写用户级环境变量；Codex：写 `~/.codex/config.toml` + `auth.json`（默认模型现场可选，推荐 `gpt-6-sol`）
3. **安装环境**（可跳过）—— 检测 Node.js ≥ 20，缺失时用 nvm（macOS/Linux）或 winget（Windows）安装 LTS，再 `npm install -g` 安装 CLI；全程用户目录
4. **连通验证** —— 用你的密钥发一条最小请求，失败时按 HTTP 状态码给出定向排错提示
5. **写前备份** —— 所有被修改的文件先备份为 `.bak.时间戳`；Windows 旧环境变量备份到 `%USERPROFILE%\.qcode\`
6. **密钥清洗** —— 自动去掉粘贴时带入的首尾引号、空白与中文全角引号；密钥中间仍含非法字符时直接拒绝并提示重新复制，不会把错值写进配置

## 非交互模式（CI / 免确认）

macOS / Linux：

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

| 参数 | 说明 |
|------|------|
| `--key <cr_...>` | API 密钥，提供后跳过交互输入 |
| `--domain <api\|asia\|us>` | 指定接入域，跳过测速 |
| `--model <id>` | Codex：指定默认模型，跳过选单；Claude Code：固定默认模型（写入 `ANTHROPIC_MODEL`），不传则沿用 Claude Code 自带的默认模型并随其升级 |
| `--lang <zh\|en>` | 界面语言，缺省跟随系统 locale |
| `--target <app\|cli>` | （仅 codex）只写配置 / 同时装 CLI，缺省交互询问 |
| `--yes` / `-y` | 所有确认取默认值 |
| `--no-install` | 只写配置，不安装 Node / CLI |
| `--no-verify` | 跳过连通验证 |
| `--help` | 查看全部参数 |

Windows 带参调用（参数与上表对应：`-Key`、`-Domain`、`-Model`、`-Lang`、`-Target`、`-Yes`、`-NoInstall`、`-NoVerify`）：

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

（`codex.ps1` 同理）

## 写入了哪些文件 / 如何回滚

| 工具 / 平台 | 写入位置 | 回滚方式 |
|------|------|------|
| Claude Code（macOS/Linux）| `~/.zshrc` 或 `~/.bashrc` 中的 `# >>> qcode.cc claude-code >>>` 托管块 | 删除整个托管块，或用同目录 `.bak.时间戳` 备份还原 |
| Claude Code（Windows）| 用户级环境变量 ×4（`ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN` / `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` / `CLAUDE_CODE_AUTO_MODE_SERVER`；带 `-Model` 时另写 `ANTHROPIC_MODEL`） | 用 `%USERPROFILE%\.qcode\backup-*.json` 中的旧值还原 |
| Codex（全平台）| `~/.codex/config.toml` + `~/.codex/auth.json` | 用同目录 `.bak.时间戳` 备份还原 |

重跑脚本总是安全的：托管块原地更新，配置文件先备份再覆盖。

## 常见问题

- **验证返回 401** —— 密钥无效或过期：到 [控制台](https://qcode.cc/dashboard) 核对（确认 `cr_` 前缀完整复制）后重跑脚本
- **验证返回 404** —— 接入地址错误：Claude Code 的 BASE_URL 应为 `https://{域}/api`、Codex 为 `https://{域}/openai`，且末尾不带斜杠
- **网络超时** —— 重跑脚本换一个接入域（如 `--domain asia`）；各域实时状态见 [probe.qcode.cc](https://probe.qcode.cc/)
- **Windows 上装完找不到 claude / codex 命令** —— 重开一个新的 PowerShell 窗口（PATH 在新会话才刷新）
- **不想让脚本装 Node** —— 加 `--no-install`（Windows：`-NoInstall`），只写配置
- **想先看脚本内容** —— 直接打开 <https://qcode.cc/install/claude-code.sh> 阅读源码；脚本不需要 sudo / 管理员权限，不写任何系统目录
- **提示「API 密钥含有非法字符」** —— 复制时把引号、空格或中文标点一起粘进来了。脚本会自动去掉首尾的引号和空白，但中间夹杂的字符仍会被拒绝；到 [控制台](https://qcode.cc/dashboard) 重新复制一次即可
- **提示「检测到你在用 sudo 运行本脚本」** —— 本脚本**不需要 sudo**。用 sudo 会把配置写进 root 的家目录，你自己的终端里读不到；去掉 sudo 重新运行
- **看到「配置已写入，但验证未通过」** —— 配置文件本身已经写好，只是最后那次连通测试没成功。按提示里的状态码排查（401 核对密钥 / 404 检查地址 / 超时换接入域），修好后重跑脚本
- **Codex 越用越慢、反复出现「Reconnecting… / stream disconnected」** —— 多半是会话里积了很多截图/图片：Codex 每一轮都会把整段对话（含全部图片）重新上传，几十张截图就是每次几十 MB，网络稍慢就传不完。用 `/new` 开一个新会话（把要继续的任务用几句话交代一下）即可恢复；会话已经很大时不要用 `/compact`（压缩请求本身也要把整段历史上传一次）。以后同一会话里少贴截图，或先缩小再贴