Codex CLI 0.164.0: config.toml и QCode

Codex CLI 0.164.0 (2026-10-23): установка, config.toml и auth.json для QCode.cc, ключи /presets, /model и /permissions, AGENTS.md и MCP.

Нужен API-ключ? Зарегистрироваться →·Эндпоинты и Base URL →

Последняя проверка: 2026-10-26 · 📄 По официальной документации (последний стабильный Codex CLI v0.164.0, выпуск 2026-10-23; в этот раз заново проверены параметры config, изменения команд в 0.164.0 и способы установки) · поведение профилей из 5.4 дополнительно проверено у нас локально (✅ codex-cli 0.155.0, изолированный HOME, запросы к модели не отправлялись)

Кратко¶

📖 Почему base_url для Codex отличается от ANTHROPIC_BASE_URL Claude? В чём разница между /openai и /openai/v1? См. Точки доступа и форматы API.

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

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

Что такое OpenAI Codex CLI?¶

Codex CLI — это открытый 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 хорош для «бросания задач» (дали чёткое задание — он выполнил сам), Claude Code хорош для «парного программирования» (обсуждаем и изменяем на ходу, подходит для исследовательских задач). Лучше всего использовать оба инструмента вместе.

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

По умолчанию Codex CLI требует API-ключ OpenAI или подписку ChatGPT, а в материковом Китае API OpenAI напрямую недоступен.

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

• Один ключ для Claude, GPT и популярных китайских моделей: Codex работает с моделями GPT, Claude Code — с Claude, и оба используют один и тот же API-ключ QCode
• Несколько точек доступа: api.qcode.cc — глобальный вход, us.qcode.cc — для Северной Америки и Европы, asia.qcode.cc — для Азии; пользователям из материкового Китая рекомендуем asia.qcode.cc, собственный прокси не нужен
• Оплату по токенам, цены по моделям указаны на qcode.cc/models
• Общую квоту тарифа для Claude Code и Codex, один тариф подходит для обоих инструментов

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 (рекомендуется)¶

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

npm install -g @openai/codex

Совет: Если возникают проблемы с правами доступа, пользователи macOS/Linux могут добавить sudo, или использовать nvm для управления Node.js и избежать проблем с правами.

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

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

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

brew install --cask codex

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

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

Скачайте готовый бинарный файл для вашей платформы со страницы GitHub Releases и поместите его в каталог из PATH. Этот способ не зависит от Node.js. По состоянию на 2026-10-26 последний стабильный выпуск — v0.164.0 (опубликован 2026-10-23); при проверке 2026-10-15 на странице была v0.162.1 (опубликована 2026-10-09). Файлы названы по платформам: например, codex-x86_64-unknown-linux-musl.tar.gz для Linux x64, codex-aarch64-apple-darwin.tar.gz для macOS на чипах Apple и codex-x86_64-pc-windows-msvc.exe для Windows x64.

# Пример: скачать и установить версию для Linux x64
curl -fsSLO https://github.com/openai/codex/releases/latest/download/codex-x86_64-unknown-linux-musl.tar.gz
tar -xzf codex-x86_64-unknown-linux-musl.tar.gz
sudo mv codex-x86_64-unknown-linux-musl /usr/local/bin/codex

Способ 4: Официальный установочный скрипт (macOS / Linux)¶

В официальной документации OpenAI по Codex (по состоянию на 2026-10-26) есть и самостоятельный установщик:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

После установки проверьте результат командой codex --version.

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

codex --version

Если выводится номер версии, установка прошла успешно. Не считайте цифру на этой странице «текущей последней» — смотрите GitHub Releases и npm @openai/codex, на машине — codex --version.

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

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

# Пользователи 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: Создание каталога конфигурации¶

mkdir $HOME\.codex

mkdir -p ~/.codex

mkdir -p ~/.codex

Шаг 2: Создание config.toml¶

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

model_provider = "qcode"
model = "gpt-6.1-sol"
model_reasoning_effort = "high"

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

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

Шаг 3: Создание auth.json¶

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

{
  "OPENAI_API_KEY": "cr_xxxxxxxxxx"
}

Замените cr_xxxxxxxxxx на ваш API-ключ QCode.cc. Ключ начинается с cr_.

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

• Этот файл предоставляет Codex API-ключ (при requires_openai_auth = true Codex читает из него OPENAI_API_KEY)
• Рекомендуется установить права доступа к файлу 600 (только чтение/запись владельцем): chmod 600 ~/.codex/auth.json

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

Чтобы передавать ключ через переменную окружения, замените в [model_providers.qcode] строку requires_openai_auth = true на env_key = "QCODE_API_KEY" и экспортируйте эту переменную. Выберите только один из двух вариантов: в официальной документации сказано, что при requires_openai_auth = true Codex игнорирует env_key. Полная конфигурация для варианта с переменной окружения:

model_provider = "qcode"
model = "gpt-6.1-sol"
model_reasoning_effort = "high"

[model_providers.qcode]
name = "qcode"
base_url = "https://api.qcode.cc/openai"
wire_api = "responses"
env_key = "QCODE_API_KEY"

Затем задайте переменную окружения:

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

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

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

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

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

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

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

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

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

QCode сейчас не предоставляет gpt-6-luna / gpt-5.6-luna. Используйте другие модели GPT (gpt-6.1-sol / gpt-6.1-terra / gpt-6-sol / gpt-5.6-terra).

Claude Code и Codex используют один и тот же API-ключ QCode, для смены модели ничего дополнительно подключать не нужно. QCode тарифицирует по токенам, цены по моделям указаны на qcode.cc/models.

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

4.1 Запуск Codex¶

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

cd /path/to/your/project
codex

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

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

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

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

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

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

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

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

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

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

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

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

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

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 будет сохранять контекст в той же сессии:

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

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

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

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

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

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

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

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

Изменения файлов Codex выполняются в соответствии с политикой подтверждения (Approval Policy). Согласно официальной документации (по состоянию на 2026-10-26), в Git-репозитории по умолчанию используется предустановка «запись в рабочую область + подтверждение по запросу»:

• Правки файлов и команды внутри рабочей области: выполняются автоматически
• Запись за пределами рабочей области, доступ в сеть и подобные действия: показываются вам и ждут подтверждения
• Каталоги вне Git: по умолчанию только чтение, поэтому перед любыми изменениями Codex спрашивает

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

4.6 Изменения команд в Codex CLI 0.164.0 (2026-10-23)¶

Codex CLI 0.164.0 выпущен 2026-10-23. В официальных примечаниях к релизу перечислены следующие изменения, связанные с командами и конфигурацией:

• Сохраняйте повторно используемые промпты и слэш-команды в десяти пронумерованных слотах /presets; клавиатурное меню открывает их быстро.
• Задавайте модель, интенсивность рассуждений, скорость и профили разрешений прямо в аргументах /model и /permissions.
• Аутентифицируйте корпоративные MCP-подключения через подходящие разрешения аккаунта Codex или отдельный вход, включая OAuth-клиенты, которым нужен секрет.
• Маскируйте учётные данные в поддерживаемых удалённых командах Bash и сессиях снимков Zsh, включая учётные данные пользовательских провайдеров.

Ключи, которые используются в конфигурации выше, по-прежнему есть в официальном справочнике конфигурации, проверенном 2026-10-26: model_provider, [model_providers.<id>], base_url, wire_api, requires_openai_auth. Команды установки в официальном README, проверенном в тот же день, не изменились: npm install -g @openai/codex, brew install --cask codex или curl -fsSL https://chatgpt.com/codex/install.sh | sh.

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

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

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

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

# AGENTS.md

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

## Стандарты кодирования

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

## Команды тестирования

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

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

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

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

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

# services/payments/AGENTS.override.md

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

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

5.2 Настройка подтверждений и песочницы¶

Защита в Codex состоит из двух слоёв: режим песочницы определяет, что Codex технически может делать (куда писать, можно ли выходить в сеть), а политика подтверждений — когда он обязан сначала спросить вас. По состоянию на 2026-10-26, согласно официальной документации OpenAI, ими управляют два параметра командной строки:

Типичные сочетания (официальная документация):

🔴 Формы --full-auto, --suggest, --auto-edit и --approval-mode, которые встречаются в старых руководствах, в текущем официальном списке параметров отсутствуют. Если нужна автономная запись файлов, используйте --sandbox workspace-write; для неинтерактивных запусков — codex exec --sandbox workspace-write.

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

Значения по умолчанию в config.toml:

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

approval_policy принимает on-request, never или таблицу granular, которая делит запросы по категориям. В официальной документации сказано, что approval_policy = "untrusted" больше не поддерживается; если эта строка осталась в старой конфигурации, клиент может не запуститься — удалите её.

Переключение во время сеанса: команда /permissions позволяет без перезапуска переключаться между предустановкой по умолчанию и режимом только для чтения.

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

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

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

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

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

Настройка через config.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. Ниже три блока — полная новая форма:

# ~/.codex/config.toml - default config (top-level keys only; no [profiles.x] tables)
model_provider = "qcode"
model = "gpt-6-sol"

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

# ~/.codex/work.config.toml
model = "gpt-6-sol"
model_reasoning_effort = "high"

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

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

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 конвейерах: команда codex exec выполняет задачу и завершается (по официальной документации, она работает неинтерактивно и выводит результат в stdout или JSONL).

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

# Разрешить запись в рабочую область: полностью автономное выполнение
codex exec --sandbox workspace-write "Запустить набор тестов, исправить все упавшие тесты"

# Вывод потоком событий JSONL (для аудита или последующей обработки)
codex exec --json "Рефакторинг модуля обработки ошибок"

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

# Пример GitHub Actions

- name: Auto-fix lint errors
  run: |
    # Вариант с переменной окружения: в config.toml используется env_key, без requires_openai_auth
    mkdir -p ~/.codex
    cat > ~/.codex/config.toml <<'EOF'
    model_provider = "qcode"
    model = "gpt-6.1-sol"

    [model_providers.qcode]
    name = "qcode"
    base_url = "https://api.qcode.cc/openai"
    wire_api = "responses"
    env_key = "QCODE_API_KEY"
    EOF
    npx @openai/codex exec --sandbox workspace-write "Запустить eslint --fix для исправления всех lint-ошибок, затем сделать коммит"
  env:
    QCODE_API_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.

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

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

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

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

cd /path/to/new/project
codex

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

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

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

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

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

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

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

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

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

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

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

Классический сценарий полной автономности — Codex сам чинит падающие тесты:

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

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

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

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

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

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

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 doctor, чтобы получить диагностический отчёт об установке, конфигурации и аутентификации

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

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

Решение:

1. Проверьте формат ключа (должен начинаться с cr_)
2. Убедитесь, что ключ в auth.json записан целиком (без лишних пробелов и переносов строк)
3. Если используете вариант с переменной окружения, проверьте, что в провайдере указано env_key = "QCODE_API_KEY", нет requires_openai_auth = true, а переменная экспортирована
4. Войдите в консоль QCode.cc и проверьте статус ключа и остаток квоты

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

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

Решение:

1. Проверьте сеть: curl -I https://api.qcode.cc
2. Убедитесь, что base_url указан верно (должен быть https://api.qcode.cc/openai)

3. Попробуйте другую точку доступа:

4. Азиатская точка доступа: https://asia.qcode.cc/openai

5. Если используете корпоративный прокси или VPN, убедитесь, что они не блокируют HTTPS-запросы

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

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

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

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

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

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

Проблема: команды, которые пытается выполнить 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
• Один тариф обслуживает оба инструмента одновременно
• Стоимость считается по фактическому расходу токенов, а не по инструменту
• Когда Codex автономно проходит несколько итераций, расход токенов на одну задачу может быть выше — зато экономится время разработчика
• QCode тарифицирует по токенам, цены по моделям указаны на qcode.cc/models, а расход можно смотреть в консоли QCode.cc

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

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

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

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

• Настройка переменных окружения — переменные окружения для Claude Code
• Быстрый старт — краткое руководство по Claude Code
• Интеграция с Aider — настройка ещё одного open-source AI-ассистента
• Приёмы работы в CLI — продвинутые приёмы командной строки Claude Code

Enterprise →