Codex полный туториал

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

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

一、Введение в 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，одна подписка для двух инструментов
• Несколько доступных узлов（основной узел Азиатско-Тихоокеанского региона, Гонконг, Шэньчжэнь），гарантирующие стабильность соединения

二、Установка 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 openai-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

Если вы видите номер версии (например, 0.114.0), установка прошла успешно.

Текущая последняя версия：v0.114.0 (2026-03-11), поддерживает систему Skills, движок Hooks, протокол MCP и другие новые функции.

Настройка автодополнения 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.

三、Настройка 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.3-codex-spark"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.crs]
name = "crs"
base_url = "https://asia.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.1 Запуск Codex¶

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

cd /path/to/your/project
codex

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

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

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

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

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

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

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

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.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).

codex --full-auto
# Эквивалентно: --approval-mode full-auto --sandbox workspace-write

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

Настройка режима по умолчанию в 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 Настройка профилей (управление множеством сред)¶

Если вы используете разные конфигурации в разных проектах (например, один API-ключ для рабочих проектов, другой для личных), можно использовать функцию Profile:

# ~/.codex/config.toml

# Конфигурация по умолчанию
model_provider = "crs"
model = "gpt-5.3-codex-spark"

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

# Profile для рабочих проектов
[profiles.work]
model = "gpt-5.1-codex-max"
model_reasoning_effort = "high"

# Profile для личных проектов (экономия)
[profiles.personal]
model = "gpt-5.2-codex"
model_reasoning_effort = "medium"

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

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

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

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

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

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

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

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

# Пример GitHub Actions

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

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

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

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

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

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

六、Сравнение Claude Code и Codex¶

Если вы уже используете Claude Code, следующее сравнение поможет понять различия в позиционировании двух инструментов: