Cursor и Codex: полный гайд — от установки до работы через шлюз NeuroZal

01 Codex и Cursor: что выбрать

Это два разных инструмента с разными сценариями, и они хорошо работают вместе. Codex — консольный агент OpenAI: запускается в терминале внутри папки проекта, сам открывает нужные файлы, вносит правки, выполняет команды, тесты и git-операции. Cursor — редактор на базе VS Code, где агенты встроены прямо в интерфейс: подсказки по ходу набора, правки по выделенному фрагменту, отдельный агентский воркспейс и собственный CLI agent для терминала и скриптов.

02 Быстрый старт: 4 шага

Вся последовательность целиком — примерно на пять минут. Подробности по каждому шагу идут дальше.

# 1. Установить Codex CLI (Windows, PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

# 2. Сохранить ключ шлюза в переменную окружения и открыть новый терминал
setx NEUROZAL_API_KEY "sk-ваш-ключ-из-кабинета"

# 3. Указать провайдера и модель в файле ~/.codex/config.toml (см. шаг 3)

# 4. Перейти в проект, запустить агента и проверить связь
cd C:\путь\к\проекту
codex
/status

Дальше коротко: шаг 3 — подключение к шлюзу, Cursor: установка, таблица проверенных моделей, разбор ошибок.

03 Шаг 1. Установка Codex CLI

Codex CLI — консольный агент OpenAI: он запускается в каталоге проекта, сам читает файлы, вносит правки, выполняет команды и проверяет результат. Работает на Windows, macOS и Linux, интерфейс — обычный терминал плюс расширение для редактора, если нужно.

# установка
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

# обновление до свежей версии — та же команда
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

# установка одной строкой
curl -fsSL https://chatgpt.com/codex/install.sh | sh

npm install -g @openai/codex

brew install --cask codex

# обновление
brew upgrade --cask codex

codex --version     # версия, например: codex-cli 0.153.4
codex doctor        # проверка установки, конфига и авторизации
codex --help        # список подкоманд и флагов

04 Шаг 2. Ключ NeuroZal

Ключ шлюза — это единственный секрет, который нужен Codex. Он подходит и для остальных инструментов: Cursor в терминале, SDK, Cline, OpenWebUI. Отдельная подписка OpenAI при этом не требуется.

curl https://api.neurozal.ru/v1/models \
  -H "Authorization: Bearer sk-ВАШ_КЛЮЧ"

curl.exe https://api.neurozal.ru/v1/models `
  -H "Authorization: Bearer sk-ВАШ_КЛЮЧ"

05 Шаг 3. Подключение Codex к шлюзу

Codex умеет работать с любым OpenAI-совместимым провайдером: достаточно описать его в конфиге и указать, откуда брать ключ. Шлюз NeuroZal поддерживает оба протокола OpenAI — /v1/responses и /v1/chat/completions, поэтому Codex работает с ним «из коробки», без прослоек и прокси.

Где лежит конфиг

Проектный слой намеренно не может переопределять провайдера и модель — это защита от «сюрпризов» в чужом репозитории. Провайдера задают один раз в пользовательском конфиге.

Конфиг шлюза

Откройте ~/.codex/config.toml (файл создаётся вручную, если его ещё нет) и добавьте:

# модель по умолчанию и провайдер
model = "gpt-5.5"
model_provider = "neurozal"
model_reasoning_effort = "medium"

# описание провайдера NeuroZal
[model_providers.neurozal]
name = "NeuroZal"
base_url = "https://api.neurozal.ru/v1"
env_key = "NEUROZAL_API_KEY"
wire_api = "responses"

Что здесь важно:

• base_url — адрес шлюза с обязательным /v1 на конце.
• env_key — имя переменной окружения, из которой берётся ключ. Сам ключ в конфиге не хранится.
• wire_api — протокол запросов. Поддерживается значение responses (по умолчанию, если не указывать).
• model — имя модели, которое понимает шлюз. Список — в разделе Модели шлюза.

Переменная окружения с ключом

# только для текущего окна терминала
$env:NEUROZAL_API_KEY = "sk-ВАШ_КЛЮЧ"

# постоянно — для всех новых окон
setx NEUROZAL_API_KEY "sk-ВАШ_КЛЮЧ"

# только для текущего окна
set NEUROZAL_API_KEY=sk-ВАШ_КЛЮЧ

# постоянно
setx NEUROZAL_API_KEY "sk-ВАШ_КЛЮЧ"

# только для текущей сессии
export NEUROZAL_API_KEY="sk-ВАШ_КЛЮЧ"

# постоянно, для новых терминалов
echo 'export NEUROZAL_API_KEY="sk-ВАШ_КЛЮЧ"' >> ~/.zshrc

После setx обязательно откройте новое окно терминала: переменная подхватывается при старте процесса, а уже запущенный Codex её не увидит.

Проверить связь

Самый быстрый способ убедиться, что ключ, адрес и модель настроены верно, — один неинтерактивный запрос:

codex exec "Ответь одним словом: работает" --skip-git-repo-check

Ответ модели в терминале означает, что Codex ходит через шлюз NeuroZal. Если вместо ответа приходит ошибка авторизации, проверьте три вещи: переменная окружения задана в том же окне, ключ скопирован целиком, в конфиге указано именно env_key = "NEUROZAL_API_KEY". Диагностика целиком — codex doctor.

Профили: несколько наборов настроек

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

model = "gpt-5.4-mini"
model_reasoning_effort = "low"

codex -p fast                     # запуск с профилем fast
codex -m gpt-5.6                  # разово другая модель
codex -c model_reasoning_effort=high   # разовое переопределение настройки

Флаг -c принимает пару «ключ=значение» из конфига и действует только на этот запуск — удобно, чтобы проверить настройку, не правя файл.

Второй способ авторизации

Если окружение менять не хочется, ключ можно сохранить во внутреннем хранилище Codex — команда читает его из stdin:

printenv NEUROZAL_API_KEY | codex login --with-api-key
codex login status

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

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

Эти ключи описываются в том же блоке [model_providers.neurozal] и нужны в основном на медленных каналах:

06 Шаг 4. Первый запуск

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

# зафиксировать текущее состояние — точка возврата перед экспериментами
cd C:\путь\к\проекту
git status
git add -A && git commit -m "чекпойнт перед работой с агентом"

# запустить агента
codex

При первом запуске в новом проекте Codex спросит, доверяете ли вы этому каталогу: только после подтверждения он подхватывает проектный слой настроек .codex/config.toml и правила проекта. Это защита — в чужом репозитории конфигурация не применяется автоматически.

Что набрать в первые минуты

07 Codex: права, флаги и команды

В Codex две независимые настройки: спрашивать ли разрешение перед действием и насколько широк доступ к файлам и сети. Вместе они дают предсказуемое поведение — от «только чтение» до полной автоматизации.

Режимы подтверждений

Уровни доступа (песочница)

Задаются в конфиге или флагом на запуск:

approval_policy = "on-request"     # когда спрашивать разрешение
sandbox_mode = "workspace-write"   # насколько широк доступ
web_search = "cached"              # cached | indexed | live | disabled

# Windows: нативная песочница (нужны права администратора)
[windows]
sandbox = "elevated"

Флаги запуска

08 Codex: сессия, команды и клавиши

Внутри сессии почти всё управляется слэш-командами — их 47, ниже самые нужные в работе.

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

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

09 Codex вне сессии: подкоманды

Кроме интерактивного запуска codex есть отдельные команды — они и делают агента частью рабочего процесса.

Разовая задача без интерфейса

# одна задача без интерактивного интерфейса
codex exec "прогони тесты и почини то, что упало"

# машиночитаемый прогресс + человеческая сводка в файл (для CI)
codex exec --json -o summary.md "проверь сборку и опиши риски"

# запуск вне git-репозитория и без сохранения сессии
codex exec --skip-git-repo-check --ephemeral "почисти временные файлы"

10 Cursor: установка и первый проект

Cursor — редактор кода на базе VS Code со встроенными агентами: вы работаете в привычном интерфейсе, а изменения агент показывает прямо в файлах. Отдельно от редактора существует Cursor CLI — тот же агент из терминала (о нём — следующий раздел).

# ключ репозитория
curl -fsSL https://downloads.cursor.com/keys/anysphere.asc | gpg --dearmor | sudo tee /etc/apt/keyrings/cursor.gpg > /dev/null

# подключить репозиторий
echo "deb [arch=amd64,arm64 signed-by=/etc/apt/keyrings/cursor.gpg] https://downloads.cursor.com/aptrepo stable main" | sudo tee /etc/apt/sources.list.d/cursor.list > /dev/null

# установка
sudo apt update
sudo apt install cursor

Первый проект

1. Откройте папку с кодом и дождитесь индексации — по ней агент ищет файлы и понимает структуру.
2. Войдите в аккаунт Cursor: без него редактор работать не будет.
3. Задайте правила проекта (файл AGENTS.md в корне) — это же описание читает и Codex.
4. Начните с небольшой задачи: «объясни, как этот сервис обрабатывает заказы». Спросите до правок — так виднее, правильно ли агент понял проект.

11 Cursor: режимы работы

Режимы задают, что агенту разрешено делать прямо сейчас. Переключение — Shift+Tab или слэш-команда.

Как формулировать задачи агенту

• Один результат на запрос. «Починить checkout в тестах» отдельно от «отрефакторить модуль оплаты» — так проще проверять.
• Просите сначала объяснить. «Сначала опиши причину, потом правь» отсекает правки наугад.
• Задавайте границы. «Меняй только файлы в src/api», «не трогай миграции» — агент остаётся в рамках.
• Требуйте проверку. «Запусти тесты и покажи результат» — иначе агент считает задачу сделанной после правки.

12 Cursor CLI: агент в терминале

Отдельная программа agent — тот же агент Cursor, но из командной строки. Удобна, когда проект открыт по SSH, или когда задача должна идти из скрипта.

Установка

# macOS, Linux, WSL
curl https://cursor.com/install -fsS | bash

# Windows (PowerShell)
irm 'https://cursor.com/install?win32=true' | iex

# запуск
agent

Вход

# вход через браузер (рекомендуется)
agent login
agent status

# для скриптов и CI — ключ аккаунта Cursor
export CURSOR_API_KEY="ваш_ключ"       # ключ берётся в панели Cursor → API Keys
agent "реализуй авторизацию пользователей"

# или ключ разово флагом
agent --api-key "ваш_ключ" "исправь падающий тест"

Если браузер не открывается, добавьте NO_OPEN_BROWSER=1 перед agent login — команда напечатает ссылку, которую можно открыть вручную.

Режимы и запуск без интерфейса

Настройки песочницы и доступа к сети сохраняются между сессиями, поэтому переключать их каждый раз не нужно.

Сессии и продолжение работы

agent ls                    # список прошлых чатов
agent resume                # продолжить последний
agent --continue            # продолжить предыдущую сессию
agent --resume="chat-id"    # продолжить конкретный чат

Кнопка переноса работы в облако есть и в CLI: если начать сообщение с символа &, задача уйдёт в Cloud Agent и продолжит выполняться, пока вас нет за компьютером. Вернуться к ней можно с сайта или из мобильного приложения.

Настройки CLI

Каталог настроек можно перенести переменной CURSOR_CONFIG_DIR, если нужно держать разные профили. В JSON-выводе режима -p видно, откуда взят ключ (apiKeySource: env, flag или login) — удобно для диагностики в CI.

13 Правила проекта: AGENTS.md и .cursor/rules

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

AGENTS.md — общий файл для Cursor и Codex

Простой markdown в корне проекта. Cursor читает его из корня и из подкаталогов, Codex — как инструкции проекта (команда /init создаёт заготовку). Если правил немного, начните именно с него.

# Проект: сервис заказов

## Стек
Python 3.11, FastAPI, PostgreSQL, тесты на pytest.

## Как проверять изменения
- Запуск тестов: `pytest -q`
- Линтер: `ruff check .`
- Перед коммитом обязательно зелёный прогон тестов.

## Правила кода
- Комментарии и докстринги — на русском.
- Публичные функции возвращают типизированные модели, не словари.
- Не менять миграции: только добавлять новые.

## Запрещено
- Править файлы в `deploy/` и `.env*`.
- Выполнять команды git push и что-либо с боевыми адресами.

Правила Cursor: файлы .mdc с настройками охвата

Проектные правила лежат в .cursor/rules и версионируются вместе с кодом. Файл должен иметь расширение .mdc — обычный .md в этом каталоге правила-система игнорирует.

---
description: Правила для эндпоинтов API
globs: src/api/**
alwaysApply: false
---

- Каждый эндпоинт описан схемой ответа.
- Ошибки возвращаются в едином формате: код, сообщение, детали.
- Валидация входных данных — до обращения к базе.

Правила Codex: политика команд

У Codex отдельный механизм — файлы .rules (формат Starlark) в каталоге rules/ рядом с активным конфигом, например ~/.codex/rules/default.rules. Они описывают, какие команды разрешены, а какие требуют подтверждения. Когда вы в сессии отвечаете «разрешить всегда», Codex сам дописывает правило в пользовательский файл — дальше такие команды уже не спрашивают.

14 Навыки: свои сценарии одной командой

Навык — папка с файлом SKILL.md: описание и пошаговая инструкция. Агент подключает её, когда задача совпадает с описанием. Так повторяющиеся процедуры перестают быть «простыней в чате» и становятся частью проекта.

Где лежат навыки

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

---
name: release
description: Подготовить релиз: тесты, changelog, тег, черновик PR
---

1. Запусти `pytest -q` и `ruff check .` — при ошибках остановись.
2. Собери changelog из git-лога с последнего тега, сгруппируй по типам.
3. Обнови версию в `pyproject.toml` и `CHANGELOG.md`.
4. Создай тег и черновик PR с описанием изменений.
5. Ничего не публикуй без подтверждения.

Как вызвать

• Cursor: навык подключается автоматически по описанию; команда /create-skill помогает создать структуру, /migrate-to-skills переносит подходящие правила в навыки.
• Codex: /skills показывает доступные навыки, вызов — по имени в запросе (символ $ перед именем).

15 Хуки: автоматика вокруг агента

Хук — внешняя программа, которую агент запускает на определённых событиях. Она получает данные по stdio в формате JSON и может ответить: пропустить, спросить подтверждение или запретить. Так в цикл работы агента встраиваются ваши правила — без надежды на память модели.

Где задаются (Cursor)

Обратите внимание на пути: в личных хуках пишут ./hooks/format.sh, в проектных — .cursor/hooks/format.sh.

{
  "version": 1,
  "hooks": {
    "afterFileEdit": [{ "command": "./hooks/format.sh" }]
  }
}

Основные события

Что ими решают на практике

• Форматирование после правок. Агент закончил файл — хук запустил форматтер, и код всегда в едином стиле.
• Защита секретов. Хук перед записью файла проверяет, не попал ли в него ключ или пароль, и блокирует правку.
• Гейт опасных операций. Запись в базу, удаление каталогов, отправка писем — всё, что требует вашего решения.
• Аналитика. Запись событий в журнал: какие инструменты агент вызывает и где тратит время.

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

16 MCP: подключение внешних сервисов

MCP (Model Context Protocol) — общий способ отдать агенту доступ к внешним данным и действиям: базе знаний, тикетам, документации, внутренним API. Оба инструмента поддерживают его, отличаются только файлы настроек.

Cursor

Поддерживаются локальные серверы (запускаются как процесс) и удалённые — по SSE или Streamable HTTP, с авторизацией через OAuth.

{
  "mcpServers": {
    "files": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "docs": {
      "url": "https://mcp.example.com"
    }
  }
}

Codex

Серверы описываются таблицами в ~/.codex/config.toml или в проектном .codex/config.toml:

[mcp_servers.files]
command = "npx"                             # команда запуска сервера
args = ["-y", "@modelcontextprotocol/server-filesystem", "."]
env = { LOG_LEVEL = "info" }                # переменные для процесса

[mcp_servers.docs]
url = "https://mcp.example.com"             # удалённый сервер

Управлять можно и командами: codex mcp add, codex mcp list, codex mcp remove, а для серверов с авторизацией — codex mcp login.

17 Разрешения и безопасность

Агент с доступом к терминалу может сделать всё, что можете вы. Поэтому доступ выдаётся по задаче, а не «на всякий случай»: сначала только чтение, потом запись в проекте, и лишь для изолированных сред — полный доступ.

Рабочие сочетания в Codex

Нужен доступ к соседним каталогам — добавляйте их точечно флагом --add-dir, вместо того чтобы открывать всю файловую систему. На Windows песочница включается в конфиге: [windows] sandbox = "elevated" (режим unelevated — запасной, если нет прав администратора).

Права в Cursor CLI

В cli-config.json есть списки permissions.allow и permissions.deny: что разрешено без запроса, а что запрещено всегда. Из проекта настраивается только этот раздел — файл проект/.cursor/cli.json держится в репозитории и задаёт правила для команды. Плюс режим песочницы: --sandbox enabled ограничивает команды агента, а доступ к сети включается отдельно.

Гигиена ключей

• Отдельный ключ на инструмент. Ключ шлюза для Codex не стоит использовать ещё и в скриптах выгрузки: если он утечёт, отзывать придётся в одном месте, а не везде.
• Ключи — только в переменных окружения. Файлы конфигов часто попадают в бэкапы и синхронизацию; ключ в config.toml — плохая идея.
• Проверяйте расход. Команды /status, /usage в Codex и дашборд шлюза показывают, сколько уходит на задачи — аномалия видна сразу.
• Не давайте агенту боевые доступы. Токены продакшена, ключи платёжных систем и SSH-доступы держите вне рабочего окружения агента.

18 Автоматизация и CI

Оба инструмента умеют работать без человека. Это самый практичный сценарий: агент выполняет повторяющуюся проверку или рутину, а вы читаете короткий отчёт вместо логов.

Codex: разовые задачи и конвейеры

# зависимости и агент
npm install -g @openai/codex

# ключ шлюза приходит из секретов CI
export NEUROZAL_API_KEY="$NEUROZAL_API_KEY"

# задача без интерфейса: машинный лог + сводка в файл
codex exec --json -o summary.md \
  --sandbox workspace-write \
  "прогони тесты и линтер; если что-то падает — почини только причину падения,
   ничего не рефактори; в конце опиши, что менял"

cat summary.md

Флаг --output-schema принимает файл со схемой JSON — тогда финальный ответ агента приходит в нужной структуре, и его можно сразу разбирать скриптом. Флаг --ephemeral не сохраняет сессию на диск, а --skip-git-repo-check позволяет запускать задачу вне репозитория.

Ревью изменений

# Codex: ревью без интерфейса — по незакоммиченным правкам, коммиту или ветке
codex review

# Cursor CLI: то же самое, но с понятным выводом в терминал
agent -p "проверь изменения на уязвимости и регрессии" --output-format text

Ревью не меняет рабочее дерево: агент сообщает находки по приоритету, а решение остаётся за вами.

Что автоматизировать в первую очередь

19 Модели шлюза: что проверено

Шлюз NeuroZal отдаёт два интерфейса, и Codex умеет работать с обоими: /v1/chat/completions (классический формат чата) и /v1/responses (формат Responses, который Codex использует по умолчанию). На живом шлюзе проверено: ответ приходит, потоковая передача работает, вызов инструментов (tool use) возвращается корректно в обоих интерфейсах.

Кого выбирать под задачи

Как выбрать модель на практике

• Начните с gpt-5.5 — на нём проверена и работа с инструментами, и потоковая передача.
• Тяжёлую задачу («почему падает прод», «спроектируй схему миграции») отправляйте на reasoning-модель: думает дольше, ошибается меньше.
• Мелочь и повтор — на быстрых моделях: не нужно платить за рассуждения там, где их не читают.
• Переключайтесь на ходу командой /model внутри сессии или флагом -m при запуске.

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

20 12 рабочих рецептов

Формулировки, которые дают предсказуемый результат и в Cursor, и в Codex. Копируйте и меняйте под свой проект.

21 Как экономить токены

Расход определяет не длина вашего сообщения, а объём контекста, который агент читает на каждом шаге. Поэтому экономия — это дисциплина разговора, а не «короткие промпты».

22 Типичные ошибки и что делать

23 Чек-лист настройки

Скопировать чек-лист

24 Вопросы и ответы