Настройка Codex в VS Code: подробное руководство для разработчика

Codex в VS Code — это не просто чат сбоку от редактора. В 2026 году это полноценный AI-агент для разработки: он может читать файлы проекта, объяснять код, предлагать правки, запускать команды, помогать с тестами, делать ревью и передавать длинные задачи в облако. OpenAI описывает Codex как coding agent, который умеет читать, редактировать и запускать код, а расширение для VS Code позволяет работать с ним прямо внутри IDE или делегировать задачи в Codex Cloud.

Что такое Codex в VS Code

Codex в VS Code — это AI-помощник, который работает прямо внутри редактора и понимает контекст проекта. Он видит открытые файлы, может анализировать код, выполнять команды и помогать с реальными задачами разработки.

Представьте, что рядом появился напарник, которому не нужно долго объяснять устройство проекта. Вместо поиска по десяткам файлов можно просто написать задачу обычным языком.

Например:

— «Найди, почему здесь падает запрос после авторизации»
— «Добавь обработку пустого ответа API»
— «Создай тест для этой функции»
— «Покажи, где используется этот компонент»
— «Объясни, зачем здесь нужен useMemo»

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

Главное отличие от обычного AI-чата — работа в контексте кода. Если стандартный чат отвечает только на основе текста сообщения, то Codex понимает структуру проекта и взаимодействует с рабочей директорией. Благодаря этому он способен выполнять более практические задачи: искать ошибки, рефакторить код, создавать тесты и помогать с навигацией по большому проекту.

В официальном quickstart OpenAI указано, что после входа Codex запускается в режиме Agent по умолчанию. В этом режиме он может читать файлы проекта, запускать команды и изменять код напрямую в рабочей директории.

Что понадобится перед установкой

Для начала нужен установленный VS Code или совместимый редактор. Расширение Codex работает не только в Visual Studio Code, но и в VS Code-совместимых редакторах вроде Cursor и Windsurf. OpenAI также указывает поддержку macOS, Windows и Linux для IDE-интеграций; на Windows можно запускать Codex нативно с Windows sandbox или через WSL2, если нужен Linux-native workflow.

Также нужен аккаунт ChatGPT или OpenAI API key. В документации OpenAI указано, что планы ChatGPT Plus, Pro, Business, Edu и Enterprise включают Codex, а после установки расширение предлагает войти через ChatGPT-аккаунт или API key.

Установка расширения Codex

Установка выглядит привычно для любого расширения VS Code.

Откройте VS Code, перейдите в Extensions, найдите Codex от OpenAI и установите его. В документации OpenAI также указано, что расширение можно получить через Visual Studio Code Marketplace или скачать для VS Code, Cursor, Windsurf и VS Code Insiders.

После установки Codex появляется в боковой панели редактора. В VS Code он по умолчанию открывается в правой боковой панели. Если значок не появился сразу, стоит перезапустить редактор; OpenAI прямо рекомендует перезапуск VS Code, если Codex не виден после установки.

Дальше нужно открыть панель Codex и войти в аккаунт. Quickstart OpenAI описывает этот процесс просто: установить расширение, открыть панель, войти через ChatGPT-аккаунт или API key и начать первую задачу.

Первый запуск: что попросить у Codex

Лучше не начинать с большой задачи вроде «перепиши весь проект». Первый запрос должен быть безопасным и диагностическим. Например:

Расскажи, как устроен этот проект. Найди основные директории, точку входа, тесты и конфигурационные файлы. Пока ничего не меняй.

Такой запрос полезен по двум причинам. Во-первых, вы проверите, видит ли Codex проект. Во-вторых, вы получите карту кодовой базы: где frontend, где backend, где тесты, где конфиги, какие команды сборки и проверки есть в проекте.

Еще один хороший первый запрос:

Проверь проект на баги, логические ошибки и потенциальные проблемы в коде, объясни найденные ошибки и предложи исправления.

Так вы привыкаете к роли Codex как напарника, а не как «автоматической кнопки исправить все».

Режимы работы: Chat, Agent и Agent Full Access

Одна из самых важных настроек Codex в VS Code — режим автономности. От него зависит, будет ли Codex просто обсуждать код или сможет действовать в проекте.

В режиме Chat Codex ведет себя как помощник для обсуждения. Он может объяснять, планировать, отвечать на вопросы, но не должен сам менять проект. Это хороший режим для знакомства с кодом, планирования архитектуры, разбора ошибки или ревью идеи.

Режим Agent — основной рабочий режим. По данным OpenAI, в нем Codex может читать файлы, вносить изменения и запускать команды в рабочей директории автоматически, но ему все равно нужно подтверждение для действий за пределами рабочей директории или для доступа к сети.

Режим Agent Full Access дает агенту больше свободы, включая сетевой доступ без подтверждения. OpenAI прямо советует использовать его осторожно.

Практическое правило простое: для повседневной разработки используйте Agent, для обсуждений — Chat, а Full Access включайте только тогда, когда точно понимаете, зачем это нужно. Например, если Codex должен установить зависимости, обратиться к внешней документации или выполнить сложную интеграционную настройку.

Настройка модели и уровня рассуждения

В расширении Codex можно переключать модели через переключатель под полем ввода. Там же можно менять reasoning effort — насколько глубоко Codex должен «думать» над задачей. OpenAI указывает варианты low, medium и high: высокий уровень помогает на сложных задачах, но занимает больше времени и расходует больше токенов; рекомендация для старта — medium, а high включать только там, где нужна глубина.

На практике это выглядит так:

• Для простых задач вроде «переименуй переменную», «добавь тип», «объясни функцию» достаточно low или medium.
• Для багов, которые затрагивают несколько файлов, лучше medium.
• Для архитектурных изменений, миграций, сложных race conditions, безопасности и больших рефакторингов лучше high.

Хорошая привычка — сначала попросить Codex составить план, а потом уже разрешать изменения:

Сначала составь план исправления. Не меняй файлы, пока я не подтвержу подход.

Это особенно полезно, когда задача затрагивает базу данных, авторизацию, платежи, многопоточность или публичный API.

Конфигурационный файл Codex

Многие важные настройки Codex задаются не только через интерфейс VS Code, но и через общий конфигурационный файл. OpenAI указывает, что пользовательская конфигурация хранится в ~/.codex/config.toml, а настройки для конкретного проекта можно положить в .codex/config.toml внутри репозитория. CLI и IDE extension используют общие конфигурационные слои.

Открыть конфигурацию можно прямо из расширения: нажать на значок шестеренки в Codex и выбрать Codex Settings → Open config.toml.

Пример базовой конфигурации:

model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

Что здесь происходит:

model задает модель по умолчанию.

approval_policy = "on-request" означает, что Codex будет спрашивать подтверждение в ситуациях, где это нужно.

sandbox_mode = "workspace-write" ограничивает работу областью проекта, но позволяет вносить изменения в рабочую директорию.

По данным OpenAI, через конфигурацию можно задавать модель и провайдера, approval policies, sandbox settings и MCP-серверы.

Пользовательская и проектная настройка

Есть два уровня настройки: личная и проектная.

Личная настройка живет в:

~/.codex/config.toml

Она подходит для ваших обычных предпочтений: модель по умолчанию, уровень осторожности, политика подтверждений, базовый sandbox.

Проектная настройка живет в:

.codex/config.toml

Она полезна, когда у конкретного репозитория есть свои правила. Например, в одном проекте можно разрешить агенту запускать unit-тесты и линтеры, а в другом — запретить любые сетевые операции и требовать подтверждения перед каждым изменением.

OpenAI уточняет важную деталь: проектные .codex/-слои загружаются только тогда, когда вы доверяете проекту. Если проект помечен как недоверенный, Codex пропускает project-scoped настройки, hooks и rules, но пользовательская и системная конфигурация продолжают применяться.

Это хорошая защита от случайного запуска чужих правил в непроверенном репозитории.

Как настроить approvals и sandbox

Sandbox — это граница, внутри которой Codex может действовать. OpenAI объясняет, что sandbox не дает агенту неограниченный доступ к машине: когда Codex запускает локальные команды в приложении, IDE extension или CLI, эти команды выполняются в ограниченной среде.

Важно понимать разницу:

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

Approval policy отвечает за то, когда Codex должен остановиться и спросить разрешение.

Эти два механизма работают вместе. OpenAI прямо пишет, что sandbox и approvals — разные, но связанные инструменты: sandbox задает границы, а approval policy решает, когда агент должен спросить разрешение перед выходом за них.

Для большинства проектов хорошая стартовая настройка такая:

approval_policy = "on-request"
sandbox_mode = "workspace-write"

Она дает Codex достаточно свободы для обычных задач, но не превращает его в процесс с полным доступом ко всему компьютеру.

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

approval_policy = "on-request"
sandbox_mode = "read-only"

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

Настройки VS Code для расширения Codex

Часть настроек находится в самом VS Code. Чтобы изменить их, откройте настройки редактора и найдите Codex или название нужной настройки. В документации OpenAI перечислены, например, настройки размера шрифта чата, размера шрифта для code snippets и diffs, автозапуска панели Codex, языка интерфейса и режима WSL на Windows.

Практически полезные настройки:

chat.fontSize — размер текста в Codex sidebar.

chat.editor.fontSize — размер кода и diff-фрагментов в разговорах Codex.

chatgpt.openOnStartup — открывать ли Codex при запуске редактора.

chatgpt.localeOverride — язык интерфейса Codex.

chatgpt.runCodexInWindowsSubsystemForLinux — запускать Codex через WSL на Windows, если ваш проект и инструменты находятся в WSL2. OpenAI отмечает, что в остальных случаях Codex может работать нативно на Windows с Windows sandbox.

Как дать Codex правильный контекст

Codex работает лучше, когда получает контекст из редактора. Открытые файлы, выделенный код и ссылки на файлы помогают ему отвечать точнее. В документации OpenAI указано, что в редакторе можно ссылаться на файлы прямо в запросе через @file, например попросить использовать один файл как пример для изменения другого.

Пример:

Используй @UserCard.tsx как пример стиля и добавь похожий компонент в @ProfilePage.tsx. Сохрани существующую структуру props.

Такой запрос лучше, чем «сделай похожий компонент», потому что Codex сразу понимает, на какой файл смотреть.

Еще лучше давать ограничения:

Добавь обработку пустого состояния в @OrdersTable.tsx.
Не меняй API компонента.
Сохрани текущие CSS-классы.
Добавь тест, если рядом уже есть тесты для этого компонента.

Для Codex ограничения не мешают, а помогают. Он меньше угадывает и чаще делает то, что нужно.

AGENTS.md: инструкция для агента

Если вы часто работаете с одним проектом, полезно добавить файл AGENTS.md. OpenAI в best practices советует относиться к Codex не как к одноразовому помощнику, а как к teammate, которого вы настраиваете со временем; в числе ключевых практик упоминаются правильный контекст, AGENTS.md, конфигурация под workflow, MCP, skills и автоматизация стабильных процессов.

В AGENTS.md можно описать правила проекта:

# Инструкции для Codex

## Стиль
- Используй TypeScript strict mode.
- Не добавляй зависимости без подтверждения.
- Не меняй публичные API без отдельного предупреждения.

## Проверки
- После изменений во frontend запускай: npm test
- Для форматирования используй: npm run lint
- Если тесты не запускаются, объясни причину.

## Архитектура
- UI-компоненты лежат в src/components.
- Работа с API находится в src/api.
- Не смешивай бизнес-логику и React-компоненты.

Это экономит время. Вместо того чтобы повторять правила в каждом запросе, вы один раз кладете их в проект.

Как безопасно запускать первую реальную задачу

Предположим, у вас есть баг: кнопка сохранения неактивна, хотя форма заполнена. Плохой запрос:

Почини кнопку.

Хороший запрос:

Найди, почему кнопка сохранения остается disabled после заполнения формы.
Сначала изучи связанные файлы и опиши причину.
Потом предложи минимальное исправление.
Не меняй публичный API компонентов.
После правки запусти связанные тесты или объясни, почему их нельзя запустить.

Так вы задаете Codex понятный коридор: исследование, причина, минимальное исправление, проверка.

Перед запуском полезно сделать git checkpoint. OpenAI прямо рекомендует использовать Git checkpoints до и после задач, потому что Codex может изменять кодовую базу, а checkpoint помогает легко откатиться.

Минимальный вариант:

git status
git add .
git commit -m "checkpoint before codex task"

Или хотя бы убедитесь, что рабочая директория чистая:

git status

Если Codex внесет лишние изменения, вы быстро увидите diff и сможете откатиться.

Делегирование в облако из VS Code

Codex в VS Code умеет не только работать локально, но и отправлять длинные задачи в облако. OpenAI описывает cloud delegation так: вы можете offload larger jobs to Codex in the cloud, отслеживать прогресс и просматривать результат, не выходя из IDE.

Это удобно для задач, которые могут занять много времени:

• большой рефакторинг;
• переезд на новую версию фреймворка;
• поиск причины нестабильных тестов;
• генерация недостающих тестов;
• первичный аудит большого модуля.

Практический сценарий:

Сначала локально обсудите проблему.

Попросите Codex составить план.

Если задача длинная, отправьте ее в cloud.

Потом примените diff локально, запустите тесты и проверьте результат.

Так вы не превращаете облако в черный ящик, а используете его как отдельного исполнителя.

Web search внутри Codex

В 2026 году Codex IDE Extension включает web search. Для локальных задач он по умолчанию использует кэш OpenAI с предварительно проиндексированными результатами, а не обязательно ходит на живые страницы. OpenAI объясняет, что это снижает риск prompt injection из произвольного live-контента, но веб-результаты все равно нужно считать недоверенными.

Для разработчика это значит: Codex может помочь найти информацию о библиотеке, ошибке или API, но не стоит автоматически принимать код из веб-источников. Особенно если речь о безопасности, установке пакетов, shell-командах или миграциях.

Хороший запрос:

Проверь актуальный способ настройки этой библиотеки.
Используй web search только для справки.
Перед изменениями кратко укажи источник идеи и риски.
Не запускай команды установки без моего подтверждения.

Горячие клавиши и команды

Codex в VS Code поддерживает команды, которые можно назначать на горячие клавиши. В документации указано, что через settings icon в Codex chat можно перейти к Keyboard shortcuts и назначить команды вроде переключения Codex chat или добавления элементов в контекст.

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

открыть или скрыть панель Codex;

добавить выделенный код в контекст;

начать новый чат или задачу.

Идея простая: чем меньше мыши, тем быстрее Codex становится частью обычного workflow.

Настройка для Windows и WSL

Если вы работаете на Windows, есть два пути: нативный запуск или WSL2. OpenAI указывает, что на Windows Codex можно запускать нативно с Windows sandbox, а WSL2 использовать, когда нужна Linux-native среда.

Если ваш проект находится в Windows-файловой системе, а команды запускаются через PowerShell или npm в Windows, проще начать с нативного режима.

Если проект живет внутри WSL2, зависимости установлены в Linux, а команды вроде make, bash, grep, pytest, npm или pnpm вы запускаете из WSL, лучше включить настройку chatgpt.runCodexInWindowsSubsystemForLinux. OpenAI описывает ее как Windows-only настройку для запуска Codex в WSL, когда репозитории и инструменты живут в WSL2 или требуется Linux-native tooling.

Как писать хорошие задачи для Codex

Codex лучше работает не с туманными просьбами, а с задачами, похожими на нормальные инженерные тикеты.

Плохо:

Улучши проект.

Лучше:

Найди в проекте повторяющуюся логику форматирования даты.
Предложи общий helper.
Не меняй поведение.
Добавь или обнови тесты.
Покажи список файлов, которые собираешься изменить.

Плохо:

Сделай красиво.

Лучше:

Улучши компонент CheckoutSummary:
- выровняй отступы;
- сохрани текущую цветовую схему;
- не меняй props;
- проверь адаптивность на мобильной ширине;
- покажи diff перед финальным ответом.

Плохо:

Почини тесты.

Лучше:

Запусти тесты для модуля payments.
Если тесты падают, найди первопричину.
Не меняй тесты, пока не объяснишь, почему проблема именно в тестах, а не в коде.
Предложи минимальный фикс.

В больших проектах полезно просить Codex сначала исследовать, потом планировать, потом менять:

Сначала найди связанные файлы и объясни зависимость между ними.
Затем предложи план.
После моего подтверждения внеси изменения.

Что не стоит поручать Codex без контроля

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

Не стоит без ревью принимать изменения в:

• авторизации и правах доступа;
• платежах;
• криптографии;
• миграциях базы данных;
• логике удаления данных;
• CI/CD и deployment scripts;
• инфраструктурных скриптах;
• коде, который обрабатывает персональные данные.

Для таких задач включайте более строгий sandbox, требуйте план до изменений, смотрите diff построчно и запускайте тесты вручную.

Типичные ошибки при настройке

Первая ошибка — сразу включить Full Access. Это удобно, но опасно. Лучше начать с обычного Agent и on-request.

Вторая ошибка — запускать Codex в грязной git-директории. Если у вас уже есть незакоммиченные изменения, будет сложнее понять, что сделал агент, а что было до него.

Третья ошибка — давать слишком широкие задачи. «Оптимизируй backend» почти гарантированно приведет к расплывчатому результату. «Найди N+1-запрос в списке заказов и предложи минимальный фикс» — намного лучше.

Четвертая ошибка — не использовать проектные инструкции. Если в проекте есть правила, их нужно положить в AGENTS.md или .codex/config.toml, а не повторять вручную каждый раз.

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

Пример хорошей базовой настройки

Для личной разработки можно начать так:

# ~/.codex/config.toml

model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

Для осторожного корпоративного проекта:

# .codex/config.toml

approval_policy = "on-request"
sandbox_mode = "read-only"

А в AGENTS.md добавить:

# Инструкции для Codex

- Сначала объясняй план, потом меняй код.
- Не добавляй новые зависимости без подтверждения.
- Не меняй публичные API без отдельного предупреждения.
- Для изменений запускай релевантные тесты.
- Если тесты не запускаются, объясни причину.
- Для security-sensitive файлов предлагай изменения, но не применяй их без подтверждения.

Такой набор не идеален для всех, но он хорош как безопасная отправная точка.

Как понять, что Codex настроен правильно

Codex настроен хорошо, если он:

видит файлы проекта;

понимает открытые файлы и выделенный код;

не требует подтверждения на каждое безопасное действие;

останавливается перед рискованными действиями;

показывает понятный diff;

умеет запускать локальные тесты;

следует правилам проекта;

не выходит за пределы рабочей директории без разрешения;

помогает вам быстрее двигаться, а не создает лишний шум.

Главный критерий — не «насколько Codex автономен», а «насколько он предсказуем». Хорошая настройка дает агенту достаточно свободы для рутины, но оставляет человеку контроль над решениями.