# 环境变量配置

> ⚡ 还没接入？一条命令完成全部配置：`curl -fsSL https://qcode.cc/install/claude-code.sh | bash`（Windows：`irm https://qcode.cc/install/claude-code.ps1 | iex`）。详见 [一键配置脚本](/docs/getting-started/one-click-install)。

绝大多数 AI 编程工具都通过**环境变量**来决定「连哪个服务、用哪把密钥」。把这两类信息指向 QCode.cc，工具就会把请求发到我们这里。本页讲清楚要设哪些变量、在哪里设、以及怎么验证。

> 📖 还不清楚 `BASE_URL` 该填 `/api` 还是别的前缀？四个接入域怎么选？先看 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)。还没装好工具？见 [安装教程](/docs/getting-started/installation)。

## 1. 核心两个变量（Claude Code & Anthropic SDK）

接入 Claude 系模型只需要两个环境变量：

```bash
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_你的密钥"
```

- **`ANTHROPIC_BASE_URL`** —— 接入地址，填到 `/api` 前缀为止。SDK 会自动在后面拼 `/v1/messages`。
- **`ANTHROPIC_AUTH_TOKEN`** —— 你的 QCode.cc 密钥，以 `cr_` 开头，在 [QCode.cc 控制台](https://qcode.cc/dashboard) 创建。

> **关于 `AUTH_TOKEN`**：这是本服务的约定 —— 中转密钥统一放在 `ANTHROPIC_AUTH_TOKEN`（而不是官方直连用的 `ANTHROPIC_API_KEY`）。Claude Code 会把它作为 Bearer 令牌发出。如果你的工具只认 `ANTHROPIC_API_KEY`，把同一把 `cr_` 密钥填进去也能用。

> **⚠️ 末尾不要带斜杠**：填 `https://api.qcode.cc/api`，**不要**写成 `https://api.qcode.cc/api/`。SDK 会自动拼 `/v1/messages`，多一个斜杠会变成 `//v1/messages` 导致 404。

这两个变量对 Claude Code 和直接使用 Anthropic 官方 SDK（Python / TypeScript）都适用 —— SDK 同样读取 `ANTHROPIC_BASE_URL`，或在构造客户端时传 `base_url=`。

## 2. 各工具对照表

不同工具读取不同的环境变量。按你用的工具对号入座：

| 工具 | 环境变量 | 填写值 |
|------|---------|--------|
| Claude Code | `ANTHROPIC_BASE_URL`<br>`ANTHROPIC_AUTH_TOKEN` | `https://api.qcode.cc/api`<br>`cr_你的密钥` |
| Anthropic SDK（Python/JS） | `ANTHROPIC_BASE_URL`<br>`ANTHROPIC_AUTH_TOKEN` | `https://api.qcode.cc/api`<br>`cr_你的密钥` |
| Codex CLI | 通过 `~/.codex` 配置中的 `base_url` | `https://api.qcode.cc/openai` |
| OpenAI 兼容工具 | `OPENAI_BASE_URL`<br>`OPENAI_API_KEY` | `https://api.qcode.cc/openai/v1`<br>`cr_你的密钥` |
| Gemini / Antigravity | base URL | `https://api.qcode.cc/gemini` |

几点说明：

- **Codex CLI** 不读 `OPENAI_BASE_URL` 来定位上游，它走 `~/.codex` 配置文件里的 `base_url`（填到 `/openai`，走 OpenAI Responses 协议）。详细写法见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)。
- **OpenAI 兼容工具**（OpenAI 官方 SDK、LangChain、各类通用客户端）认 `OPENAI_BASE_URL` 和 `OPENAI_API_KEY`，base 填到 `/openai/v1`。
- **Gemini / Antigravity**：base 填到 `/gemini` 即可，SDK 自己会拼 `/v1beta/`。同一把 `cr_` 密钥通用。

> **同一把密钥三协议通用**：你的 `cr_` 密钥不区分协议 —— 走 `/api` 是 Anthropic，走 `/openai/v1` 是 OpenAI，走 `/gemini` 是 Google Gemini。换工具只需换 BASE_URL，密钥不用换。

### 可用模型一览

填好接入后，按工具协议选模型名（更多细节见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)）：

- **Claude 系**（日常默认 5 系）：`claude-sonnet-5`（1M，平衡档）、`claude-opus-5`（1M，当前旗舰）、`claude-fable-5`（1M，顶配）、`claude-sonnet-4-6` / `claude-opus-4-8` / `claude-opus-4-7`（仍在售的上一代）、`claude-haiku-4-5`（200K）
- **GPT 系**：`gpt-5.6-terra`（推荐）、`gpt-5.6-sol`、`gpt-5.6-luna`、`gpt-5.5`、`gpt-5.4`、`gpt-5.6-mini`、`gpt-5.6-nano`
- **Gemini 系**：`gemini-2.5-pro`、`gemini-3.5-flash`、`gemini-2.5-flash`
- **国产**（GLM / Kimi / DeepSeek / Qwen）：`glm-5.3`、`kimi-k3`、`deepseek-v4-pro`、`qwen3.8-max` 等，见 [国产模型接入](/docs/usage/cn-models)
- **图像**：`gpt-image-2`（接入点 `https://api.qcode.cc/qcode-img/v1`）

> **Claude Code 上下文长度**：Claude Code 默认窗口为 **200K**；**1M 上下文**为可选开关，`claude-opus-5`、`claude-sonnet-5`、`claude-fable-5`、`claude-opus-4-8`、`claude-sonnet-4-6` 支持。

## 3. 在哪里设置

环境变量的设置位置决定了它的作用范围。三种常见方式：

**① Shell 配置文件（持久，全局）** —— 写进 `~/.zshrc`（macOS / zsh）或 `~/.bashrc`（Linux / bash），每开一个终端都自动生效：

```bash
echo 'export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="cr_你的密钥"' >> ~/.zshrc
source ~/.zshrc
```

bash 用户把 `~/.zshrc` 换成 `~/.bashrc` 即可。

**② 项目级 `.env`（持久，按项目）** —— 在项目根目录放一个 `.env` 文件，只对该项目生效，方便不同项目用不同密钥：

```bash
ANTHROPIC_BASE_URL=https://api.qcode.cc/api
ANTHROPIC_AUTH_TOKEN=cr_你的密钥
```

> `.env` 含密钥，记得加进 `.gitignore`，不要提交到代码仓库。

**③ 工具自带的设置（按工具）** —— 部分工具有自己的配置文件或界面，例如 Codex CLI 的 `~/.codex`、各编辑器插件的设置面板。这类设置只对该工具生效。

**持久 vs 临时**：上面三种都是**持久**设置。如果只想在**当前终端会话**临时试一下，直接 `export`（macOS/Linux）或 `$env:`（Windows PowerShell）即可，关掉终端就失效：

```bash
# macOS / Linux 临时设置
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_你的密钥"
```

```powershell
# Windows PowerShell 临时设置
$env:ANTHROPIC_BASE_URL = "https://api.qcode.cc/api"
$env:ANTHROPIC_AUTH_TOKEN = "cr_你的密钥"
```

> **优先级提示**：进程启动时读取的环境变量优先于配置文件。改了 shell 配置后记得 `source` 或重开终端；多处都设了同一个变量时，以进程实际继承到的那一个为准。

## 4. 🇨🇳 中国大陆提示

中国大陆用户建议把 BASE_URL 的域名从 `api.qcode.cc` 换成 `asia.qcode.cc`（亚洲节点，HK/JP 就近，地理就近、延迟最低）：

```bash
export ANTHROPIC_BASE_URL="https://asia.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_你的密钥"
```

其它协议同理：OpenAI 兼容工具填 `https://asia.qcode.cc/openai/v1`，Codex 填 `https://asia.qcode.cc/openai`，Gemini 填 `https://asia.qcode.cc/gemini`。四个接入域业务能力完全一致，同一把密钥随意切换，`asia` 不稳时切回 `api.qcode.cc`（全球 Route 53 路由）。详见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)。

## 5. 验证

设完变量，先确认值正确：

```bash
echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN
```

再用 curl 确认接入地址可达（**不带密钥**，只验路径和网络）：

```bash
curl -s -o /dev/null -w '%{http_code}' \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  https://api.qcode.cc/v1/models
# → 200 = 网络、路径、密钥全部就绪
```

**解读**：返回 `200` 说明网络、接入地址和密钥全部就绪。返回 `401` 说明密钥无效或没传对（核对 `cr_` 前缀是否完整）；返回 `404` 多半是路径前缀写错。注意：**不带密钥**访问接入点会得到一个 HTML 介绍页（HTTP 200）而不是报错——看到介绍页说明请求没带上密钥。完整的 curl 自测见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)。

带上真实密钥跑一次端到端：

```bash
curl -X POST https://api.qcode.cc/api/v1/messages \
  -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":64,"messages":[{"role":"user","content":"ping"}]}'
```

返回正常的 JSON 响应，就说明环境变量配置完成、可以开工了。

> 想看自己每一次请求的模型、上下文长度和用量？所有接入域的请求都会上报到 [probe.qcode.cc](https://probe.qcode.cc)，输入你的 `cr_` 密钥即可查看。

## 6. 接入网关时的常用变量

Claude Code 连第三方网关（包括 QCode）时，这几个官方变量常用。定义与出处：[官方环境变量列表](https://code.claude.com/docs/en/env-vars) 与 [网关连接文档](https://code.claude.com/docs/en/llm-gateway-connect)（2026-09-18 查阅）：

| 变量 | 什么时候用 |
|---|---|
| `ANTHROPIC_DEFAULT_MODEL` | 设置**新会话的默认模型**（2.1.236 起，2026-08-19）。与 `ANTHROPIC_MODEL` 的区别：`/model` 会话内的选择会覆盖它、且跨重启保持；`ANTHROPIC_MODEL` 则是每次启动强制生效 |
| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` | 让 `/model` 选择器读取网关的模型列表（官方默认关，因为共享 Key 的网关可能列出你无权用的模型）。接 QCode 时列表里出现的是 **Claude 系 id**（官方只收录名字含 `claude` / `anthropic` 的模型）；**国产模型不会出现**，用国产仍需设 `ANTHROPIC_MODEL` / `ANTHROPIC_DEFAULT_MODEL` |
| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` | 剥掉 `anthropic-beta` 请求头与 beta 工具字段。网关报 `Unexpected value(s) … anthropic-beta` 类 400 时开 |
| `CLAUDE_CODE_DISABLE_ARTIFACT=1` | 关掉 Artifact 工具（设置后任何配置界面都打不开它）。Claude Code 2.1.265–2.1.267 发出的工具 schema 会被严格校验的网关整请求拒绝（400），官方修复是升级到 ≥2.1.268；来不及升级时可先用本变量止血 |
| `CLAUDE_CODE_ATTRIBUTION_HEADER=0` | 官方定义：去掉 system prompt 开头的 attribution 块（客户端版本与 prompt 指纹）。**是否建议关闭我们未实测**，也不构成推荐——先读官方页再决定 |

---

> 💡 还没有密钥，或想了解各模型的计费？看看 [QCode.cc 价格页](https://qcode.cc/pricing) 选一个适合的方案。