# Полное руководство по Codex

> **Последняя проверка**: 2026-09-18 · 📄 По официальной документации (Codex CLI v0.155.0, выпуск 2026-09-17) · поведение профилей из 5.4 дополнительно проверено у нас локально (✅ codex-cli 0.155.0, изолированный HOME, запросы к модели не отправлялись)

## Кратко

| Параметр | Описание |
|---|---|
| Доступные модели | GPT ✅ (ветка Responses) · Claude ❌ · китайские модели ❌ (ветка Responses их не отдаёт) · Gemini ❌ |
| Протокол и Base URL | OpenAI Responses: `base_url = "https://api.qcode.cc/openai"` + `wire_api = "responses"` в config.toml |
| Где настраивается | `~/.codex/config.toml` (Windows: `%USERPROFILE%\.codex\`) |
| Официальная документация | [openai/codex](https://github.com/openai/codex) |

> 📖 Почему `base_url` для Codex отличается от `ANTHROPIC_BASE_URL` Claude? В чём разница между `/openai` и `/openai/v1`? См. [Точки доступа и форматы API](../getting-started/endpoints-and-api-paths).

Это **полное руководство по Codex CLI** для китайских разработчиков. Здесь вы найдёте пошаговую инструкцию по установке, настройке и использованию OpenAI Codex CLI, а также информацию о том, как получить недорогое и быстрое AI-программирование через QCode.cc. Независимо от того, впервые ли вы сталкиваетесь с AI-инструментами для программирования или уже используете Claude Code и хотите попробовать что-то новое — это руководство для вас.

---

## 1. Введение в Codex

### Что такое OpenAI Codex CLI？

[Codex CLI](https://github.com/openai/codex) — это **открытый AI-помощник для программирования в командной строке** от OpenAI (лицензия Apache 2.0), написанный на Rust и работающий прямо в терминале. Codex умеет:

- **Читать и понимать** структуру вашего репозитория
- **Редактировать файлы** и генерировать новый код
- **Выполнять команды** (запуск тестов, установка зависимостей и т.д.)
- **Автономно итерировать** до выполнения задачи

Ключевая философия Codex — это **автономный агент (Autonomous Agent)**: вы описываете задачу, Codex выполняет её в песочнице, а вы проверяете результат. Это дополняет **интерактивный диалоговый стиль** Claude Code.

### История развития Codex

Название «Codex» прошло через несколько этапов в продуктовой линейке OpenAI:

- **2021 год**：Изначальный Codex представлял собой тонко настроенную версию GPT-3 для кода и использовался в GitHub Copilot
- **2024 год**：OpenAI возродил бренд Codex, представив облачного асинхронного AI-программиста
- **2025-2026 годы**：Codex CLI превратился в зрелый локальный инструмент командной строки с переписыванием на Rust, поддержкой MCP, Skills, многопоточных агентов и других продвинутых функций

Сегодня Codex — это продукт с несколькими интерфейсами: **CLI инструмент командной строки** (основная тема статьи), **десктопное приложение для macOS**, **плагины для IDE**, а также **облачный агент**, встроенный в ChatGPT. Через QCode.cc используется версия CLI.

### Ключевые различия между Codex и Claude Code

| Измерение | Codex CLI | Claude Code |
|------|-----------|-------------|
| Стиль выполнения | Автономное выполнение с выдачей результата | Интерактивный диалог с пошаговым подтверждением |
| Открытый код | Полностью открытый (Apache 2.0) | Закрытый |
| Язык написания | Rust (быстрый запуск, низкое потребление ресурсов) | TypeScript |
| Безопасность песочницы | Встроенная песочница Landlock/seccomp | Подтверждение разрешений |
| Файл инструкций | `AGENTS.md` | `CLAUDE.md` |
| Облачный агент | Поддерживается (встроен в ChatGPT) | Не поддерживается |

Проще говоря: **Codex хорош для «бросания задач»** (дали чёткое задание — он выполнил сам), **Claude Code хорош для «парного программирования»** (обсуждаем и изменяем на ходу, подходит для исследовательских задач). Лучше всего использовать оба инструмента вместе.

### Почему стоит использовать Codex через QCode.cc？

По умолчанию Codex CLI требует OpenAI API Key или подписку ChatGPT, но в материковом Китае есть две проблемы:

1. **Сеть недоступна**：API OpenAI недоступен напрямую
2. **Высокая стоимость**：Официальные цены на токены GPT-5.3-Codex не низкие

Через QCode.cc вы получаете:

- **Низкую задержку через узлы Азиатско-Тихоокеанского региона**，без необходимости VPN или собственного прокси
- **Снижение стоимости до 80%**，значительная экономия по сравнению с официальными ценами
- **Общие квоты для Claude Code и Codex**，одна подписка для двух инструментов
- **Несколько доступных узлов** (глобальный Route 53 + резервы HK / US / EU), обеспечивающие стабильность соединения

---

## 2. Установка Codex CLI

### Системные требования

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

- **Операционная система**：macOS 12+, Ubuntu 20.04+, Windows 10+ (рекомендуется WSL2)
- **Node.js**：v22 LTS или выше (требуется для установки через npm)
- **Git**：2.x или выше (Codex использует Git для анализа репозитория)
- **Место на диске**：около 200 МБ (включая зависимости npm)

### Способ 1：Установка через npm (рекомендуется)

Это самый универсальный способ установки, подходящий для всех операционных систем:

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

> **Совет**：Если возникают проблемы с правами доступа, пользователи macOS/Linux могут добавить `sudo`，или использовать [nvm](https://github.com/nvm-sh/nvm) для управления Node.js и избежать проблем с правами.

> **Для пользователей из Китая**：Если скорость загрузки npm низкая, можно использовать зеркало Taobao:
> ```bash
> npm install -g @openai/codex --registry=https://registry.npmmirror.com
> ```

### Способ 2：Установка через Homebrew (macOS)

Пользователи macOS также могут установить через Homebrew:

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

Преимущество Homebrew — автоматическое управление зависимостями и обновлениями.

### Способ 3：Прямое скачивание бинарного файла (для опытных)

Скачайте предкомпилированный бинарный файл для вашей платформы со страницы [GitHub Releases](https://github.com/openai/codex/releases) и поместите его в каталог `PATH`. Этот способ не требует Node.js.

```bash
# Пример: скачивание и установка версии для Linux x64
wget https://github.com/openai/codex/releases/latest/download/codex-linux-x64
chmod +x codex-linux-x64
sudo mv codex-linux-x64 /usr/local/bin/codex
```

### Проверка установки

```bash
codex --version
```

Если выводится номер версии, установка прошла успешно. Не считайте цифру на этой странице «текущей последней» — смотрите [GitHub Releases](https://github.com/openai/codex/releases) и [npm `@openai/codex`](https://www.npmjs.com/package/@openai/codex), на машине — `codex --version`.

### Настройка автодополнения Shell (необязательно)

Codex поддерживает автодополнение в Shell — нажмите `Tab` при вводе команды для подсказок:

```bash
# Пользователи Zsh
echo 'eval "$(codex completion zsh)"' >> ~/.zshrc
source ~/.zshrc

# Пользователи Bash
echo 'eval "$(codex completion bash)"' >> ~/.bashrc
source ~/.bashrc
```

> Если Zsh выдаёт ошибку `command not found: compdef`，добавьте `autoload -Uz compinit && compinit` перед `eval`.

---

## 3. Настройка QCode.cc

Для подключения Codex CLI к сервису QCode.cc необходимо настроить два файла:

- `~/.codex/config.toml` — настройки конечной точки сервиса и модели
- `~/.codex/auth.json` — аутентификация по API-ключу

### Шаг 1：Создание каталога конфигурации

<div data-os="windows" markdown="1">

**Windows (PowerShell)：**

```powershell
mkdir $HOME\.codex
```

</div>

<div data-os="macos" markdown="1">

**macOS：**

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

</div>

<div data-os="linux" markdown="1">

**Linux：**

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

</div>

### Шаг 2：Создание config.toml

Запишите следующее содержимое в `~/.codex/config.toml`:

```toml
model_provider = "crs"
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
disable_response_storage = true
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"
```

**Описание полей config.toml:**

| Поле | Описание |
|------|------|
| `model_provider` | Название провайдера модели, здесь указано пользовательское `crs` |
| `model` | Модель по умолчанию. Для программирования рекомендуется `gpt-5.6-terra` |
| `model_reasoning_effort` | Уровень рассуждений: `low`, `medium`, `high`. Чем выше, тем точнее, но медленнее |
| `disable_response_storage` | Запретить хранение диалогов OpenAI (защита конфиденциальности) |
| `preferred_auth_method` | Метод аутентификации, установлен в `apikey` для использования API-ключа |
| `base_url` | Адрес точки доступа QCode.cc (в примере используется прямой IP в Шэньчжэне; другие варианты см. в [Точки доступа и форматы API](../getting-started/endpoints-and-api-paths)) |
| `wire_api` | Тип API-протокола, Codex использует `responses` |
| `requires_openai_auth` | Требуется передавать заголовок аутентификации в формате OpenAI |
| `env_key` | Имя переменной окружения, Codex читает API-ключ из этой переменной |

### Шаг 3：Создание auth.json

Запишите следующее содержимое в `~/.codex/auth.json`:

```json
{
  "OPENAI_API_KEY": "cr_xxxxxxxxxx"
}
```

> Замените `cr_xxxxxxxxxx` на ваш [API-ключ QCode.cc](https://qcode.cc/dashboard). Ключ начинается с `cr_`.

**Описание auth.json:**

- Этот файл предоставляет Codex API-ключ, эквивалентно установке переменной окружения `OPENAI_API_KEY`
- Рекомендуется установить права доступа к файлу `600` (только чтение/запись владельцем): `chmod 600 ~/.codex/auth.json`
- Если одновременно существуют `auth.json` и переменная окружения, приоритет имеет `auth.json`

### Шаг 4：Установка переменных окружения (необязательная альтернатива)

Если вы предпочитаете передавать ключ через переменные окружения (вместо `auth.json`), можно установить `CRS_OAI_KEY`:

<div data-os="windows" markdown="1">

**Windows (PowerShell)：**

```powershell
# Временная установка (текущая сессия)
$env:CRS_OAI_KEY = "cr_xxxxxxxxxx"

# Постоянная установка (в пользовательские переменные окружения)
[System.Environment]::SetEnvironmentVariable("CRS_OAI_KEY", "cr_xxxxxxxxxx", [System.EnvironmentVariableTarget]::User)
```

</div>

<div data-os="macos" markdown="1">

**macOS：**

```bash
# Временная установка
export CRS_OAI_KEY="cr_xxxxxxxxxx"

# Постоянная установка
echo 'export CRS_OAI_KEY="cr_xxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc
```

</div>

<div data-os="linux" markdown="1">

**Linux：**

```bash
# Временная установка
export CRS_OAI_KEY="cr_xxxxxxxxxx"

# Постоянная установка (Bash)
echo 'export CRS_OAI_KEY="cr_xxxxxxxxxx"' >> ~/.bashrc
source ~/.bashrc

# Постоянная установка (Zsh)
echo 'export CRS_OAI_KEY="cr_xxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc
```

</div>

При использовании переменных окружения установите `OPENAI_API_KEY` в `auth.json` в значение `null`:

```json
{
  "OPENAI_API_KEY": null
}
```

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

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

| Модель | Описание | Рекомендуемые сценарии |
|------|------|----------|
| **`gpt-5.5`** | Новейший флагман, контекст 1M | Максимальные возможности (рекомендуется ★) |
| **`gpt-5.4`** 🔥 | Новейшее поколение GPT, контекст 1M | Ежедневные сложные задачи (рекомендуется) |
| `gpt-5.6-mini` | Облегчённая версия, контекст 272K, быстрая | Лёгкие задачи / цена-качество |
| `gpt-5.6-terra` | Codex 5.3, оптимизирована для кода | Программирование / Codex CLI (рекомендуется) |

> Все модели **разделяют** квоту подписки QCode.cc с Claude Code. Переключение модели не требует дополнительной оплаты.

---

## 4. Базовое руководство по использованию

### 4.1 Запуск Codex

Откройте терминал, перейдите в каталог вашего проекта и выполните:

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

Codex запустит интерактивный интерфейс терминала (TUI), где вы можете вводить команды на естественном языке. Интерфейс состоит из следующих частей:

- **Верхняя панель состояния**：показывает текущую модель, режим подтверждения, состояние песочницы
- **Основная область**：ответы AI и журнал операций
- **Нижнее поле ввода**：место для ввода ваших команд

Вы также можете указать задачу непосредственно в командной строке (неинтерактивный режим), что подходит для вызова из скриптов:

```bash
# Интерактивный запуск
codex

# Неинтерактивный режим: выполнение одной задачи с выходом
codex "Просмотрите структуру проекта и дайте мне обзор"

# Задача с изображением
codex -i screenshot.png "Исправьте проблему с UI, показанную на скриншоте"

# Указание модели
codex -m gpt-5.4 "Рефакторинг обработки ошибок в модуле аутентификации"
```

### 4.2 Первое задание: попросите Codex написать функцию

Начнём с простого примера. Запустите Codex в каталоге проекта и введите:

```text
Напишите функцию на Python, которая принимает список строк и возвращает самую длинную строку. Если несколько строк одинаковой длины, верните первую. Сохраните в файл utils.py.
```

Codex выполнит следующие шаги:

1. **Планирование**：анализ ваших требований, разработка плана реализации
2. **Генерация кода**：создание файла `utils.py` и запись функции
3. **Запрос подтверждения**：в режиме по умолчанию Codex покажет предстоящие изменения файла и дождётся вашего подтверждения

Вы увидите примерно такое приглашение:

```text
Codex wants to create file: utils.py
─────────────────────────────────────
+ def find_longest(strings: list[str]) -> str:
+     """Возвращает самую длинную строку из списка, первую при наличии нескольких."""
+     if not strings:
+         raise ValueError("Список не может быть пустым")
+     return max(strings, key=len)

Accept? [y/n]
```

Введите `y` для подтверждения, и Codex запишет код в файл.

Далее вы можете давать дополнительные команды, Codex будет сохранять контекст в той же сессии:

```text
Напишите модульный тест для этой функции с использованием pytest
```

Codex автоматически прочитает созданный ранее файл `utils.py` и сгенерирует соответствующий тестовый файл.

### 4.3 Понимание режима выполнения в песочнице Codex

Это одна из важнейших функций безопасности Codex. Codex выполняет команды в **песочнице** с тремя уровнями безопасности:

| Режим песочницы | Чтение файлов | Запись файлов | Выполнение команд | Сетевой доступ |
|----------|---------|---------|---------|---------|
| `read-only` | Разрешено | Требует подтверждения | Требует подтверждения | Требует подтверждения |
| `workspace-write` (по умолчанию) | Разрешено | Разрешено в рабочей области | Разрешено в рабочей области | Запрещено по умолчанию |
| `danger-full-access` | Разрешено | Полностью разрешено | Полностью разрешено | Разрешено |

Режим `workspace-write` по умолчанию — лучший выбор для повседневной разработки: Codex может свободно читать/писать файлы и выполнять команды в каталоге проекта, но не может обращаться к файлам или сети за пределами проекта.

**Если вашей задаче требуется сетевой доступ** (например, `npm install`), можно временно включить сетевой доступ:

```bash
codex -c 'sandbox_workspace_write.network_access=true' "Установить зависимости и запустить тесты"
```

### 4.4 Проверка и принятие изменений Codex

Изменения файлов Codex выполняются в соответствии с **политикой подтверждения (Approval Policy)**. По умолчанию:

- **Редактирование файлов**：показывается diff и ожидается ваше подтверждение
- **Shell-команды**：показывается содержимое команды и ожидается ваше подтверждение

Когда Codex предлагает изменения, вы можете:

- **Принять (y)**：применить изменения
- **Отклонить (n)**：пропустить это изменение
- **Посмотреть детали**：внимательно изучить diff перед принятием решения

> **Совет**：Используйте команду `/diff` чтобы в любой момент просмотреть все применённые изменения в текущей сессии.

### 4.5 Полезные приёмы взаимодействия

**Ссылка на файлы**：введите `@` и имя файла, Codex автоматически прочитает содержимое этого файла:

```text
Просмотрите @src/app.py и оптимизируйте обработку ошибок
```

**Выполнение Shell-команд**：начав с `!` можно напрямую выполнить команду, вывод будет передан Codex:

```text
!cat error.log
Проанализируйте приведённый выше журнал ошибок и найдите первопричину
```

**Добавление команд**：во время работы Codex нажмите `Enter` для вставки новой команды, `Tab` для постановки в очередь следующего раунда команд.

**Возврат к редактированию**：при пустом поле ввода дважды нажмите `Esc` чтобы вернуться к предыдущему сообщению для редактирования и повторной отправки. Продолжайте нажимать `Esc` для возврата к более ранним сообщениям, затем нажмите `Enter` чтобы ответвиться в новую линию диалога из этой точки.

**Передача через конвейер**：можно передать вывод других команд через конвейер для анализа Codex:

```bash
# Анализ последних git-изменений
git diff HEAD~3 | codex "Проверьте эти изменения и найдите потенциальные проблемы"

# Анализ журнала ошибок
cat /var/log/app/error.log | codex "Проанализируйте корневые причины этих ошибок"

# Проверка PR
gh pr diff 42 | codex "Проверьте качество кода и безопасность этого PR"
```

**Горячие клавиши**:

| Клавиша | Функция |
|--------|------|
| `Tab` | Автодополнение пути к файлу (используется с `@`) |
| `Enter` | Вставить новую команду во время работы Codex |
| `Tab` | Поставить в очередь следующий раунд команд во время работы Codex |
| `Esc` x 2 | Вернуться к предыдущему сообщению для редактирования |
| `Ctrl+C` | Отменить текущую операцию |

**Команды со слэшем**:

| Команда | Описание |
|------|------|
| `/help` | Показать справку |
| `/mode` | Переключить режим подтверждения |
| `/diff` | Показать все изменения |
| `/mcp` | Показать подключённые MCP-серверы |
| `/status` | Показать состояние текущей сессии |
| `/compact` | Сжать историю диалога для экономии токенов |
| `/permissions` | Просмотр и изменение настроек разрешений |
| `/review` | Проверка кода |

---

## 5. Расширенная настройка

### 5.1 Пользовательские файлы инструкций (AGENTS.md)

Codex поддерживает файл `AGENTS.md` для предоставления AI контекста проекта и рабочих правил, аналогично файлу `CLAUDE.md` в Claude Code.

**Инструкции уровня проекта**：создайте `AGENTS.md` в корневом каталоге проекта:

```markdown
# AGENTS.md

## Описание проекта
Это бэкенд-проект на FastAPI с базой данных PostgreSQL.

## Стандарты кодирования
- Все функции должны иметь аннотации типов
- Новые API-эндпоинты требуют синхронного написания тестов
- Перед коммитом запускайте `make lint` для проверки стиля

## Команды тестирования
- Модульные тесты：`pytest tests/unit/`
- Интеграционные тесты：`pytest tests/integration/`
- Проверка кода：`make lint`
```

**Глобальные инструкции**：создайте глобальные правила по умолчанию в `~/.codex/AGENTS.md`, все проекты будут их наследовать:

```markdown
# Глобальные инструкции

- Всегда общайтесь на китайском языке
- Комментарии к коду пишите на английском
- Предпочитайте функциональный стиль программирования
- Сгенерированный код должен содержать обработку ошибок
```

**Переопределение в подкаталогах**：создание `AGENTS.override.md` в определённом каталоге переопределит правила выше:

```markdown
# services/payments/AGENTS.override.md

- Все изменения в этом каталоге должны записываться в журнал аудита
- Расчёты сумм используют тип Decimal, не числа с плавающей точкой
```

Codex ищет файлы инструкций в следующем порядке: `AGENTS.override.md` > `AGENTS.md` > запасной файл из конфигурации. Общий размер объединённых инструкций по умолчанию ограничен 32 КБ, можно изменить через `project_doc_max_bytes`.

### 5.2 Настройка режима подтверждения (Approval Mode)

Три режима подтверждения Codex подходят для разных сценариев использования:

#### Режим Suggest (наиболее безопасный)

**Все операции требуют вашего ручного подтверждения**，включая редактирование файлов и выполнение команд. Подходит для этапа обучения или проверки чувствительного кода.

```bash
codex --approval-mode suggest
```

#### Режим Auto-Edit (рекомендуется для повседневного использования)

**Редактирование файлов выполняется автоматически, выполнение команд всё ещё требует подтверждения**. Хороший баланс между эффективностью и безопасностью.

```bash
codex --approval-mode auto-edit
```

#### Режим Full-Auto (полностью автономный)

**Все операции выполняются автоматически** без какого-либо подтверждения. Рекомендуется использовать только в изолированных средах (Docker-контейнеры, CI/CD).

> 🔴 **Флаг `--full-auto` удалён.** Используйте `--sandbox workspace-write`:

```bash
codex --sandbox workspace-write
```

> **Предупреждение безопасности**: `--sandbox workspace-write` сохраняет защиту песочницы (ограничение рабочей областью). Если нужен полностью неограниченный доступ, используйте `--dangerously-bypass-approvals-and-sandbox`, но в неизолированных средах это **настоятельно не рекомендуется**.

**Автоматически проверяемые подтверждения** (`--approve-for-me`, добавлено в 0.147.0 / 2026-08-07): Codex сам проверяет и одобряет низкорисковые действия перед выполнением — середина между «спрашивать на каждом шаге» и «полностью без подтверждений».

```bash
codex --approve-for-me
```

> ⚠️ Флаги Codex меняются быстро (`--full-auto` — пример удалённого). **Ориентируйтесь на вывод `codex --help`**, а не на список флагов из какого-либо документа, включая эту страницу.

**Настройка режима по умолчанию в config.toml**:

```toml
# Рекомендуется для личной разработки
approval_policy = "on-request"
sandbox_mode = "workspace-write"
```

**Переключение режима в сессии**：команда `/mode` позволяет переключаться без перезапуска:

```text
/mode suggest      # Переключиться в режим suggest
/mode auto-edit    # Переключиться в режим auto-edit
/mode full-auto    # Переключиться в режим full-auto
```

#### Рекомендуемые конфигурации для разных сценариев

| Сценарий | Режим подтверждения | Режим песочницы |
|------|---------|---------|
| Личная повседневная разработка | `auto-edit` | `workspace-write` |
| Общая командная среда | `suggest` | `workspace-write` |
| CI/CD конвейер | `full-auto` | `workspace-write` |
| Обучение и эксперименты | `suggest` | `workspace-write` |
| Одноразовые скриптовые задачи | `full-auto` | `danger-full-access` |

### 5.3 Настройка MCP-серверов

Codex поддерживает [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), позволяющий подключать внешние инструменты для расширения возможностей.

**Добавление MCP-сервера через командную строку**:

```bash
codex mcp add my-server -- npx -y @some/mcp-server --config /path/to/config.json
```

**Настройка через config.toml**:

```toml
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "ghp_your_token" }
```

После настройки перезапустите Codex и используйте команду `/mcp` для просмотра подключённых серверов. Инструменты MCP автоматически появятся в списке доступных инструментов Codex наравне со встроенными.

**Codex как MCP-сервер**：Codex также может работать в обратном режиме как MCP-сервер, вызываться другими AI-агентами. Это очень полезно при построении систем с несколькими агентами.

### 5.4 Настройка профилей (управление множеством сред)

Если для разных проектов нужны разные настройки (рабочее и личное), используйте профили. **Начиная с Codex 0.134.0 старые таблицы `[profiles.<имя>]` внутри `config.toml` больше не действуют** — теперь на профиль приходится отдельный файл: `~/.codex/<имя>.config.toml`. Ниже три блока — полная новая форма:

```toml
# ~/.codex/config.toml - default config (top-level keys only; no [profiles.x] tables)
model_provider = "crs"
model = "gpt-5.6-terra"

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

```toml
# ~/.codex/work.config.toml
model = "gpt-5.4"
model_reasoning_effort = "high"
```

```toml
# ~/.codex/personal.config.toml
model = "gpt-5.6-mini"
model_reasoning_effort = "medium"
```

Запуск с профилем:

```bash
codex --profile work "Рефакторинг модуля аутентификации"
codex --profile personal "Написать небольшой скрипт"
```

✅ Три поведения ниже **проверены на нашей машине** (codex-cli 0.155.0, linux-x86_64, изолированный HOME, запросы к модели не отправлялись) — именно на них и сыпятся ошибки:

- Если оставить старую таблицу и передать `--profile`, будет **жёсткая ошибка**, а не молчаливое игнорирование:

  ```text
  Error loading config.toml: --profile `work` cannot be used while ~/.codex/config.toml contains legacy `profile = "work"` or `[profiles.work]` config; move those settings into ~/.codex/work.config.toml and remove the legacy profile selector/table.
  ```

- Селектор верхнего уровня `profile = "work"` тоже упразднён:

  ```text
  Error: legacy `profile = "work"` config is no longer supported; use `--profile work` with `work.config.toml` instead
  ```
- **Без `--profile` оставшиеся таблицы `[profiles.*]` вообще не участвуют в разрешении конфига** — `codex doctor` по-прежнему показывает `config.toml parse ok` и берёт значения верхнего уровня. «Нет ошибки» ≠ «сработало», поэтому при переезде удалите старые таблицы.

Кроме того, `--profile` действует только для «рантаймовых» подкоманд (`codex`, `exec`, `review`, `resume`, `queue`, `archive`, `delete`, `unarchive`, `fork`, `mcp`, `sandbox`, `debug prompt-input`); с `doctor` он выдаёт `--profile only applies to runtime commands ...`. Файл профиля — слой выше пользовательского конфига и ниже проектного и командной строки, см. 5.6.

### 5.5 Неинтерактивный режим (скрипты и автоматизация)

Codex можно использовать не только интерактивно, но и как неинтерактивный инструмент в скриптах и CI/CD конвейерах. Просто передайте параметр prompt:

```bash
# Базовое использование: выполнить задачу и выйти
codex "Добавить инструкции по установке в README.md"

# Full-Auto + неинтерактивность: полностью автономное выполнение
codex --sandbox workspace-write "Запустить набор тестов, исправить все упавшие тесты"

# Вывести transcript в файл (для аудита)
codex --sandbox workspace-write --transcript output.jsonl "Рефакторинг модуля обработки ошибок"
```

**Использование Codex в CI/CD**:

```yaml
# Пример GitHub Actions
- name: Auto-fix lint errors
  run: |
    npx @openai/codex --sandbox workspace-write "Запустить eslint --fix для исправления всех lint-ошибок, затем сделать коммит"
  env:
    CRS_OAI_KEY: ${{ secrets.QCODE_API_KEY }}
```

**Codex SDK**：Если нужно вызывать Codex из своей программы, можно использовать официальный SDK для программного вызова, встраивая Codex в собственные инструменты разработки или рабочие процессы.

### 5.6 Приоритет конфигурации

Когда несколько источников конфигурации конфликтуют, Codex разрешает их в следующем порядке приоритета (от высшего к низшему):

1. **Аргументы командной строки** (`--model`, `-c` и т.д.)
2. **Конфигурация проекта** (`.codex/config.toml`, от корня проекта до текущего каталога, ближайший приоритетнее; загружается только для доверенной папки, а ключи `model_provider`, `model_providers`, `profile` и `profiles` в проектном слое Codex игнорирует)
3. **Файл профиля** (`~/.codex/<name>.config.toml`, который выбирает `--profile <name>`)
4. **Конфигурация пользователя** (`~/.codex/config.toml`)
5. **Системная конфигурация** (`/etc/codex/config.toml`, для Unix-систем)
6. **Встроенные значения по умолчанию**

Понимание этого приоритета помогает точно контролировать поведение на разных уровнях. Например, установите общие значения по умолчанию в `~/.codex/config.toml`, переопределите конкретные настройки в `.codex/config.toml` проекта, и используйте аргументы командной строки для разовых корректировок.

---

## 6. Сравнение Claude Code и Codex

Если коротко: **Claude Code — интерактивное парное программирование, Codex — автономное выполнение задач.** Claude Code подходит для исследовательской отладки, сложного рефакторинга и разбора архитектуры; Codex — для чётко сформулированной разработки, массовых миграций и автоматизации CI/CD. Файлы инструкций — `CLAUDE.md` и `AGENTS.md`, оба полностью поддерживают MCP и **используют одну квоту тарифа QCode.cc**, поэтому переключение ничего не стоит.

Полное сравнение по 13 параметрам (модель исполнения, длина контекста, песочница, мультиагентность, открытость кода и другие) → [Codex vs Claude Code](/docs/getting-started/codex-vs-claude-code).

---

## 7. Практические примеры

Ниже — несколько реальных сценариев работы с Codex. В каждом примере есть конкретная команда и ожидаемый результат.

### Пример 1: разобраться в новом проекте

Когда вы получаете незнакомую кодовую базу:

```bash
cd /path/to/new/project
codex
```

В интерактивном режиме:

```text
Чем занимается этот проект? Проанализируй структуру каталогов, основные модули,
технологический стек и нарисуй компактную схему архитектуры (ASCII art).
```

Codex просканирует файлы проекта, разберёт файлы зависимостей (`package.json`, `requirements.txt`, `go.mod` и другие), прочитает ключевые точки входа и выдаст общий обзор проекта.

### Пример 2: код-ревью

```bash
codex "Проверь все изменения последнего git commit в каталоге src/. Обрати внимание на:
1. потенциальные баги (разыменование null, граничные условия)
2. риски безопасности (SQL-инъекции, XSS, зашитые в код секреты)
3. проблемы производительности (N+1 запросы, лишние циклы)
Укажи конкретные места в коде и предложи исправления."
```

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

```bash
codex --sandbox workspace-write "Замени все вызовы print() во всех Python-файлах проекта на модуль logging.
Требования:
1. добавить import logging в начало каждого файла
2. создать logger = logging.getLogger(__name__)
3. заменить print() на logger.info()
4. сохранить исходные строки форматирования
5. после замены запустить pytest и убедиться, что ничего не сломано"
```

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

### Пример 4: написать полный набор тестов

```bash
codex "Напиши полный набор модульных тестов для src/services/user_service.py. Требования:
1. использовать pytest + pytest-mock
2. покрыть все публичные методы
3. включить и обычные, и исключительные сценарии
4. замокать внешние зависимости (базу данных, HTTP-запросы)
5. сохранить файл тестов в tests/unit/test_user_service.py
6. запустить тесты и убедиться, что все проходят"
```

### Пример 5: автономное исправление тестов

Классический сценарий для режима Full-Auto — Codex сам чинит падающие тесты:

```bash
codex --sandbox workspace-write "Запусти все тесты. Если какие-то падают:
1. проанализируй причину падения
2. исправь код (а не тест)
3. перезапусти тесты
4. повторяй эти шаги, пока все тесты не пройдут
В конце дай краткую сводку исправлений."
```

### Пример 6: сверстать UI по макету

```bash
codex -i design.png "Свёрстай эту страницу по макету на React + Tailwind CSS.
Требования:
1. адаптивная вёрстка (с поддержкой мобильных)
2. попиксельное соответствие макету
3. разумное разбиение на компоненты
4. базовые состояния взаимодействия (hover, focus)"
```

### Пример 7: миграция базы данных

```bash
codex "Нужно добавить в таблицу users поле avatar_url (varchar 500, nullable).
Сделай:
1. скрипт миграции Alembic
2. обнови модель SQLAlchemy
3. обнови соответствующую схему Pydantic
4. обнови функции CRUD
5. добавь соответствующие эндпоинты API (GET/PUT)
6. выполни миграцию и убедись, что она прошла успешно"
```

### Пример 8: автогенерация Changelog в CI/CD

```bash
codex --sandbox workspace-write "Проанализируй все git commit с момента прошлого release tag,
раскатегорируй их по соглашению conventional commits
и сформируй обновление для CHANGELOG.md.
Включи: новые возможности, исправления багов, ломающие изменения, прочие улучшения."
```

---

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

### Файл конфигурации не найден

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

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

1. Проверьте, существует ли каталог конфигурации: `ls ~/.codex/`
2. Убедитесь, что оба файла `config.toml` и `auth.json` на месте
3. Проверьте синтаксис TOML в `config.toml` (частые ошибки: пропущенные кавычки, опечатки)
4. Посмотрите фактически загруженную конфигурацию: `codex --config-dump`

### Ошибка аутентификации по API Key

**Проблема**: сообщение `401 Unauthorized` или «API Key недействителен».

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

1. Проверьте формат ключа (должен начинаться с `cr_`)
2. Убедитесь, что ключ в `auth.json` записан целиком (без лишних пробелов и переносов строк)
3. Если используете переменную окружения, проверьте, что её имя — `CRS_OAI_KEY` (совпадает с `env_key` в `config.toml`)
4. Войдите в [консоль QCode.cc](https://qcode.cc/dashboard) и проверьте статус ключа и остаток квоты

### Проблемы с сетевым подключением

**Проблема**: не удаётся подключиться к сервису QCode.cc, таймаут или отказ в соединении.

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

1. Проверьте сеть: `curl -I https://api.qcode.cc`
2. Убедитесь, что `base_url` указан верно (должен быть `https://api.qcode.cc/openai`)
3. Попробуйте резервные узлы:
   - Азиатский резерв: `https://asia.qcode.cc/openai`
4. Если используете корпоративный прокси или VPN, убедитесь, что они не блокируют HTTPS-запросы

### Какую модель выбрать

**Проблема**: непонятно, какую модель использовать.

**Рекомендации**:

| Ваша задача | Рекомендуемая модель | Почему |
|---------|---------|------|
| Программирование | `gpt-5.6-terra` | оптимизирована под код |
| Сложные задачи | `gpt-5.4` | сильная общая модель, контекст 1M |
| Лёгкие задачи | `gpt-5.6-mini` | меньше расход квоты |
| Максимальные возможности | `gpt-5.5` | новейший флагман |

Модель по умолчанию задаётся в `config.toml`, но её можно переключить и разово:

```bash
codex -m gpt-5.4 "Разберись в этом сложном баге с конкурентностью"
```

### Ограничения песочницы мешают выполнить команду

**Проблема**: команды, которые пытается выполнить Codex, отклоняются песочницей.

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

1. Если это сетевая операция (например, `npm install`), временно откройте сеть:
   ```bash
   codex -c 'sandbox_workspace_write.network_access=true' "Установи зависимости"
   ```
2. Если нужно писать файлы вне каталога проекта, временно расширьте область записи:
   ```bash
   codex --sandbox danger-full-access "Сохрани вывод в /tmp/result.txt"
   ```
3. Прямо в сессии командой `/permissions` можно посмотреть и изменить текущие разрешения

### Как считается стоимость

**Проблема**: как рассчитываются расходы Codex и Claude Code?

**Пояснение**:

- Codex и Claude Code **используют общую квоту тарифа QCode.cc**
- Один тариф обслуживает оба инструмента одновременно
- Стоимость считается по фактическому расходу токенов, а не по инструменту
- В режиме Full-Auto Codex автономно проходит несколько итераций, поэтому расход токенов на одну задачу может быть выше — зато экономится время разработчика
- Расход текущей сессии удобно смотреть командой `/cost`, а общий расход квоты — в [консоли QCode.cc](https://qcode.cc/dashboard)

### Могут ли AGENTS.md и CLAUDE.md сосуществовать?

**Да.** Если проект используется и Codex, и Claude Code:

- Codex читает только `AGENTS.md` и игнорирует `CLAUDE.md`
- Claude Code читает только `CLAUDE.md` и игнорирует `AGENTS.md`
- Они не мешают друг другу — для каждого инструмента можно вести свой файл инструкций
- Основные правила (команды тестирования, стиль кода и т. п.) стоит держать согласованными в обоих файлах

---

## 10. Связанная документация

- [Настройка переменных окружения](/docs/getting-started/environment) — переменные окружения для Claude Code
- [Быстрый старт](/docs/getting-started/quick-start) — краткое руководство по Claude Code
- [Интеграция с Aider](/docs/ide/aider) — настройка ещё одного open-source AI-ассистента
- [Приёмы работы в CLI](/docs/usage/cli-tips) — продвинутые приёмы командной строки Claude Code