# Переменные окружения

> ⚡ Ещё не настроили? Одна команда: `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, так и для официальных SDK Anthropic (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 | `base_url` в конфигурации `~/.codex` | `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` для определения вышестоящего сервера; он берёт `base_url` из конфигурационного файла `~/.codex` (до `/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` и соседние id — см. [китайские семейства моделей](/docs/usage/cn-models)
- **Изображения**: `gpt-image-2` (точка доступа `https://api.qcode.cc/qcode-img/v1`)

> **Длина контекста Claude Code**: по умолчанию окно **200K**; опциональный **контекст 1M** поддерживают `claude-opus-5`, `claude-sonnet-5`, `claude-fable-5`, `claude-opus-4-8` и `claude-sonnet-4-6`.

## 3. Где задавать

Место установки переменной окружения определяет её область действия. Три распространённых способа:

**① Файл конфигурации шелла (постоянно, глобально)** — впишите её в `~/.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` у Codex CLI или панель настроек плагина редактора. Такие настройки применяются только к этому инструменту.

**Постоянно 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_ваш_ключ"
```

> **Замечание о приоритете**: переменные окружения, считанные при запуске процесса, имеют приоритет над файлами конфигурации. После редактирования файла шелла выполните `source` или откройте новый терминал; если одна и та же переменная задана в нескольких местах, побеждает та, которую процесс фактически унаследовал.

## 4. 🇨🇳 Примечание для пользователей из КНР

Пользователям из материкового Китая рекомендуется заменить хост в BASE_URL с `api.qcode.cc` на `asia.qcode.cc` (узел в Гонконге, географически ближайший, минимальная задержка):

```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` — сеть, endpoint и ключ полностью готовы. `401` — ключ недействителен или не передан (проверьте, что префикс `cr_` скопирован целиком); `404` — обычно неверный префикс пути. Важно: запрос **без ключа** вернёт HTML-страницу-заглушку (HTTP 200), а не ошибку — если вы её видите, ключ не был передан. Полные curl-тесты: [Endpoints & API Paths](/docs/getting-started/endpoints-and-api-paths).

Выполните end-to-end тест с настоящим ключом:

```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` читать список моделей шлюза (по умолчанию выключено: шлюзы с общим ключом могут показать недоступные модели). С QCode в списке появятся **id семейства Claude** (отбираются только имена, содержащие `claude` / `anthropic`); **китайские модели там не появятся** — для них по-прежнему нужен `ANTHROPIC_MODEL` / `ANTHROPIC_DEFAULT_MODEL` |
| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` | Срезает заголовок `anthropic-beta` и бета-поля инструментов. Включайте, если шлюз отвечает 400 `Unexpected value(s) … anthropic-beta` |
| `CLAUDE_CODE_DISABLE_ARTIFACT=1` | Отключает инструмент Artifact (после включения ни один интерфейс его не вернёт). В Claude Code 2.1.265–2.1.267 схема этого инструмента отвергалась строгими шлюзами целиком (400); официальное исправление — апгрейд на ≥2.1.268, переменная служит временной мерой |
| `CLAUDE_CODE_ATTRIBUTION_HEADER=0` | Официальный смысл: убирает блок attribution в начале system prompt (версию клиента и отпечаток промпта). **Эффект отключения мы не проверяли**, рекомендацией это не является — решайте после чтения официальной страницы |

---

> 💡 Ещё нет ключа или хотите разобраться в тарификации по моделям? Загляните на [страницу цен QCode.cc](https://qcode.cc/pricing) и выберите подходящий план.