# Быстрый старт Codex

> ⚡ **Рекомендуем установку в один клик** — `curl -fsSL https://qcode.cc/install/codex.sh | bash` (в Windows: `irm https://qcode.cc/install/codex.ps1 | iex`) поставит CLI, запишет конфигурацию `~/.codex` и проверит связь. См. [Скрипт установки в один клик](/docs/getting-started/one-click-install). Если хотите настроить вручную — читайте дальше.

Если вы уже пользуетесь Claude Code, это руководство запустит у вас Codex CLI за **5 минут**. Оба инструмента делят квоту тарифа QCode.cc и используют один и тот же API-ключ, так что после настройки можно свободно переключаться между ними.

Если аккаунта QCode.cc ещё нет, сначала [зарегистрируйтесь и выберите тариф](https://qcode.cc/pricing).

---

## Требования

Перед началом убедитесь, что окружение соответствует требованиям:

| Требование | Версия | Как проверить |
|-------------|---------|-------------|
| Node.js | v22 или новее | `node --version` |
| npm | v10 или новее | `npm --version` |
| Git | Любая | `git --version` |
| ОС | macOS / Linux / Windows (WSL) | - |
| Ключ QCode.cc | API-ключ, начинающийся с `cr_` | [Консоль](https://qcode.cc/dashboard) |

> **Примечание**: песочница уровня ядра у Codex работает лучше всего на Linux. macOS и Windows WSL тоже полностью поддерживаются, хотя часть возможностей песочницы там может быть ограничена.

---

## Шаг 1: Установка Codex CLI

Выберите один из способов:

### Вариант A: глобальная установка через npm (рекомендуется)

```bash
npm install -g @openai/codex

# Пользователи из Китая могут ускорить установку через зеркало Taobao
npm install -g @openai/codex --registry=https://registry.npmmirror.com
```

### Вариант B: Homebrew (macOS)

```bash
brew install --cask codex
```

### Вариант C: сборка из исходников

```bash
git clone https://github.com/openai/codex.git
cd codex
cargo build --release
cp target/release/codex ~/.local/bin/
```

Проверьте установку:

```bash
codex --version
# выведет версию (доверяйте `codex --version` на своей машине, а не устаревшему числу из интернета)
```

---

## Шаг 2: Настройка QCode.cc

### 2.1 Создайте каталог конфигурации

```bash
mkdir -p ~/.codex
```

### 2.2 Запишите config.toml

Создайте `~/.codex/config.toml`:

```toml
model_provider = "crs"
model = "gpt-6-sol"
model_reasoning_effort = "high"
preferred_auth_method = "apikey"

[model_providers.crs]
name = "crs"
base_url = "https://api.qcode.cc/openai"
wire_api = "responses"
requires_openai_auth = true
env_key = "CRS_OAI_KEY"
```

Справка по полям:

| Поле | Описание |
|-------|------|
| `model_provider` | Использовать собственного провайдера `crs` |
| `model` | Модель по умолчанию, рекомендуется `gpt-6-sol`; см. «Доступные модели» ниже |
| `model_reasoning_effort` | Глубина рассуждений: `low` / `medium` / `high` |
| `base_url` | Азиатско-Тихоокеанский эндпоинт QCode.cc |
| `wire_api` | Протокол API, укажите `responses` |
| `env_key` | Имя переменной окружения с API-ключом |

### 2.3 Создайте auth.json

Создайте `~/.codex/auth.json`:

```json
{
  "OPENAI_API_KEY": "cr_your_key_here"
}
```

> Замените `cr_your_key_here` на API-ключ из вашей [консоли QCode.cc](https://qcode.cc/dashboard).

### 2.4 Задайте переменные окружения

Альтернатива `auth.json` (достаточно одного из способов):

```bash
# Временно (только текущая сессия терминала)
export CRS_OAI_KEY="cr_your_key_here"

# Постоянно (для Bash)
echo 'export CRS_OAI_KEY="cr_your_key_here"' >> ~/.bashrc
source ~/.bashrc

# Постоянно (для Zsh)
echo 'export CRS_OAI_KEY="cr_your_key_here"' >> ~/.zshrc
source ~/.zshrc
```

> **Подсказка**: это тот же ключ, что и для Claude Code. Если вы уже пользуетесь Claude Code, ключ лежит в том же месте в [консоли](https://qcode.cc/dashboard).

---

## Шаг 3: Проверка настройки

Запустите простую задачу, чтобы проверить соединение:

```bash
codex "print hello world"
```

Если Codex нормально стартовал и вернул ответ, настройка выполнена успешно.

### Чек-лист

- Codex запускается без ошибок
- Запросы к API идут через QCode.cc (нет сетевых таймаутов)
- Модель отвечает корректно (понимает ваши инструкции)

Если что-то не работает, перейдите в раздел [Частые вопросы](#faq).

---

## Шаг 4: Первая настоящая задача

Попробуем реальный сценарий, чтобы почувствовать возможности Codex. Перейдите в каталог проекта:

```bash
cd /path/to/your/project
```

### Пример 1: анализ структуры проекта

```bash
codex "Проанализируй структуру каталогов и технологический стек этого проекта и дай краткий обзор"
```

### Пример 2: генерация кода

```bash
codex "Создай файл utils/date-formatter.ts со следующими возможностями:
  1. Форматирование даты в вид YYYY-MM-DD
  2. Подсчёт количества дней между двумя датами
  3. Определение, является ли дата рабочим днём
  4. Полные JSDoc-комментарии и модульные тесты для каждой функции"
```

### Пример 3: массовые изменения

```bash
codex "Преобразуй все файлы .js в src/ в .ts и добавь аннотации типов"
```

Codex автономно выполнит задачу в песочнице, а затем покажет сводку изменений для проверки.

---

## Три режима прав

В Codex есть три режима прав, регулирующих степень автоматизации:

### suggest (режим предложений)

```bash
codex --suggest "Отрефактори модуль auth"
```

- Только анализирует и предлагает — **никакие файлы не меняет**
- Предложенные изменения вы применяете сами
- Подходит для: изучения кода, оценки подходов

### auto-edit (режим автоправок)

```bash
codex --auto-edit "Добавь обработку ошибок"
```

- **Правит файлы автоматически**, но перед выполнением команд спрашивает подтверждение
- Подходит для: повседневной разработки (рекомендуемый режим по умолчанию)

### Полностью автоматический (`--sandbox workspace-write`)

```bash
codex --sandbox workspace-write "Запусти тесты и исправь все падения"
```

- Автоматически правит файлы и выполняет команды, **подтверждения не требуются**
- Все операции идут внутри песочницы и не затрагивают вашу систему
- Подходит для: интеграции в CI/CD, массовых задач

> Режим по умолчанию можно задать и в `config.toml`: `approval_mode = "auto-edit"`

---

## Справочник команд

| Команда | Описание |
|---------|------|
| `codex "ваша инструкция"` | Запустить Codex с задачей |
| `codex --model gpt-6-sol` | Указать модель |
| `codex --sandbox workspace-write "инструкция"` | Полностью автоматический режим |
| `codex --suggest "инструкция"` | Только предложения, без выполнения |
| `codex --auto-edit "инструкция"` | Автоправки, команды с подтверждением |
| `codex --version` | Показать версию |
| `codex --help` | Показать справку |

### Доступные модели

Через QCode.cc доступны следующие модели:

| Модель | Описание | Для чего рекомендуется |
|-------|------|-----------------|
| `gpt-6-sol` | Флагман GPT-6, контекст 1.05M | Код / сложные задачи (рекомендуется ★) |
| `gpt-6-luna` | Быстрая и недорогая | Простые задачи |
| `gpt-6-astra` | Старший уровень GPT-6, высокая цена | Максимальные возможности |
| `gpt-5.6-terra` | Флагман GPT-5.6 | Код / сложные задачи |
| `gpt-5.6-sol` | Флагманское семейство GPT-5.6 | Максимальные возможности |

---

## Конфигурация проекта: AGENTS.md

Создайте в корне проекта файл `AGENTS.md`, чтобы задать поведение Codex в этом проекте — по аналогии с `CLAUDE.md` у Claude Code:

```markdown
# AGENTS.md

- Использовать строгий режим TypeScript
- Стиль кода — ESLint + Prettier
- Фреймворк тестов: Vitest
- Перед коммитом выполнять `npm run lint && npm test`
- Файлы компонентов именовать в PascalCase
```

> Подробнее о настройке — [Руководство по AGENTS.md](/docs/usage/agents-md).

---

## Совместное использование с Claude Code

Поскольку оба инструмента делят квоту QCode.cc, лучшая практика — использовать их вместе:

```bash
# Терминал 1: анализируем проблему в Claude Code
$ claude
> Где узкое место по производительности? Помоги разобрать подход.

# Терминал 2: массово выполняем в Codex
$ codex "По этому плану оптимизируй все запросы к базе в src/api/:
  1. Добавь кеширование запросов
  2. Устрани N+1 запросы
  3. Добавь комментарии с рекомендациями по индексам"
```

> Больше схем совместной работы — в статье [Codex vs Claude Code](/docs/getting-started/codex-vs-claude-code).

---

## Следующие шаги

Настройка завершена — можно начинать работать с Codex. Рекомендуем прочитать:

- [Руководство по AGENTS.md](/docs/usage/agents-md) -- настроить поведение Codex в проекте
- [Codex vs Claude Code](/docs/getting-started/codex-vs-claude-code) -- понять различия и как их сочетать
- [Настройка интеграции с Codex](/docs/ide/codex) -- полный справочник по настройке (включая подробные шаги для Windows и других ОС)
- [Приёмы работы в CLI](/docs/usage/cli-tips) -- приёмы повышения продуктивности

---

## Частые вопросы

### Q: Установка падает с `npm ERR! EACCES`

**Причина**: недостаточно прав на каталог глобальной установки npm.

**Решение**:

```bash
# Вариант A: через sudo (не рекомендуется на постоянной основе)
sudo npm install -g @openai/codex

# Вариант B: настроить npm на пользовательский каталог (рекомендуется)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @openai/codex
```

### Q: Появляется `API key not found` или ошибка аутентификации

**Что проверить**:

1. Ключ в `~/.codex/auth.json` начинается с `cr_`
2. Переменная окружения `CRS_OAI_KEY` задана: `echo $CRS_OAI_KEY`
3. Ключ не истёк: проверьте в [консоли QCode.cc](https://qcode.cc/dashboard)
4. Имя `env_key` в `config.toml` написано верно

### Q: Таймаут соединения или сетевая ошибка

**Что проверить**:

1. `base_url` указан как `https://api.qcode.cc/openai`
2. Проверьте связь: `curl -I https://api.qcode.cc`
3. Если основной эндпоинт недоступен, попробуйте резервный:
   - Резервный эндпоинт: `https://asia.qcode.cc/openai`

### Q: Ключ для Codex тот же, что и для Claude Code?

**Да**. Оба используют один API-ключ QCode.cc и общую квоту. Отдельный ключ не нужен.

### Q: Работает ли это в Windows?

**Да**, но мы рекомендуем WSL (Windows Subsystem for Linux). Нативная поддержка Windows тоже улучшается. Подробные шаги для Windows — в [Настройке интеграции с Codex](/docs/ide/codex).