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

Пошаговое руководство по установке, настройке и использованию OpenAI Codex CLI вместе с QCode.cc для недорогого и быстрого AI-программирования.

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

Кратко¶

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

Это полное руководство по Codex CLI для китайских разработчиков. Здесь вы найдёте пошаговую инструкцию по установке, настройке и использованию OpenAI Codex CLI, а также информацию о том, как получить недорогое и быстрое AI-программирование через 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 требует 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 (рекомендуется)¶

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

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.

# Пример: скачивание и установка версии для 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

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

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 = "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:

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

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

{
  "OPENAI_API_KEY": "cr_xxxxxxxxxx"
}

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

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

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

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

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

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

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

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

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

# Временная установка
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

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

{
  "OPENAI_API_KEY": null
}

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

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

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

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

4.1 Запуск Codex¶

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

cd /path/to/your/project
codex

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

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

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

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

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

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

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

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). По умолчанию:

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

Когда 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"

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

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

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 Настройка режима подтверждения (Approval Mode)¶

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

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

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

codex --approval-mode suggest

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

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

codex --approval-mode auto-edit

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

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

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

codex --sandbox workspace-write

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

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

codex --approve-for-me

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

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

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

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

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

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

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 = "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"

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

# ~/.codex/personal.config.toml
model = "gpt-5.6-mini"
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 конвейерах. Просто передайте параметр prompt:

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

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

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

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

# Пример 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.

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: автономное исправление тестов¶

Классический сценарий для режима Full-Auto — 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 --config-dump

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

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

Решение:

1. Проверьте формат ключа (должен начинаться с cr_)
2. Убедитесь, что ключ в auth.json записан целиком (без лишних пробелов и переносов строк)
3. Если используете переменную окружения, проверьте, что её имя — CRS_OAI_KEY (совпадает с env_key в config.toml)
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-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

Могут ли 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