Codex: чек-лист идеального старта с официальным агентом OpenAI
Codex — официальный coding agent от OpenAI. Он отличается песочницей, нативной GitHub интеграцией, Rust-ядром и headless-режимом. Но имеет свои нюансы — вот чек-лист для идеального старта.
1. Установка — выберите свой способ
| Способ | Команда | Плюсы |
|---|---|---|
| npm (универсально) | npm install -g @openai/codex | Всегда последняя версия, работает везде где есть Node.js |
| Homebrew (macOS) | brew install openai/codex/codex | Автообновления через brew, нативный бинарник |
| Linux (curl) | curl -fsSL https://codex.openai.com/install.sh | bash | Бинарник без Node.js, для серверов/контейнеров |
| GitHub Releases | Скачать с GitHub | Конкретная версия, офлайн установка |
Рекомендация: npm install -g @openai/codex — проще обновлять.
2. Авторизация — два обязательных шага
OpenAI аккаунт (для моделей)
codex auth login
# Откроется браузер → войдите в OpenAI аккаунт
# Нужен доступ к GPT-4o / o1 / o3-mini
Без этого — только локальные/бесплатные модели (если настроены кастомные эндпоинты).
GitHub токен (для PR/issue интеграции)
# Вариант 1: через gh CLI
codex auth login --github
# или
export GITHUB_TOKEN=$(gh auth token)
# Вариант 2: Personal Access Token
# GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
# Scopes: repo, workflow, read:org
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
Без GitHub токена — нет PR создания, чтения issues, CI интеграции.
3. Конфиг: ~/.codex/config.toml
Создайте файл (глобально или в проекте):
[model]
provider = "openai" # или "anthropic"
model = "gpt-4o" # gpt-4o, o1-preview, o3-mini
# model = "claude-3.5-sonnet" # для Anthropic
base_url = "https://api.openai.com/v1"
api_key = "$OPENAI_API_KEY" # или через auth login
[sandbox]
enabled = true
# Windows: "windows-sandbox" (Hyper-V)
# Linux/macOS: "namespace" (auto)
[permissions]
allow = ["read", "write", "bash", "grep", "glob"]
# ask = ["bash(rm*)"]
[github]
token = "$GITHUB_TOKEN"
# auto-detects from gh CLI if not set
[hooks]
# pre_model_request = "echo 'Request: $REQUEST_ID'"
# post_model_request = "echo 'Response: $REQUEST_ID'"
Совет: Храните секреты в переменных окружения, не в конфиге.
4. Первый запуск — TUI режим
cd ваш-проект
codex
# Откроется TUI с панелями:
# ┌─ Chat ─────────────────────┐
# │ Your message... │
# ├─ Files ────────────────────┤
# │ src/ │
# │ main.py │
# ├─ Terminal ─────────────────┤
# │ $ _ │
# └────────────────────────────┘
#
# Горячие клавиши:
# Ctrl+C — прервать генерацию
# /help — список команд
# /compact — сжать контекст
# /help sandbox — инфо о песочнице
5. Headless режим — для CI/CD и скриптов
Самая мощная фича для автоматизации:
# JSON вывод для парсинга
codex -p "Создай REST API на FastAPI" --output-format json
# {"result": "...", "files_changed": [...], "commands_run": [...]}
# В GitHub Actions
- name: Run Codex
run: |
codex -p "$TASK" --output-format json |
jq -r '.result' > output.md
# Потоковый вывод (реальное время)
codex -p "Рефакторни этот код" --stream
# С GitHub токеном
codex -p "Создай PR с тестами" --github-token $GITHUB_TOKEN --output-format json
6. Выбор модели: GPT-4o vs Claude vs o1
| Модель | Лучше для | Скорость | Стоимость |
|---|---|---|---|
| GPT-4o | Общий код, рефакторинг, тесты, документация | Быстрая | Средняя |
| Claude 3.5 Sonnet | Сложный рефакторинг, архитектура, безопасность | Средняя | Высокая (нужен Anthropic ключ) |
| o1-preview | Сложные алгоритмы, математика, планирование | Медленная | Очень высокая |
| o3-mini | Быстрые рассуждения, код-ревью, простые задачи | Очень быстрая | Низкая |
Совет: GPT-4o — дефолт для 90% задач. o3-mini — для быстрых правок. Claude — для архитектуры.
7. Песочница: Windows vs Linux/macOS
- Windows: Hyper-V sandbox service (
codex-windows-sandbox-service). Требует Pro/Enterprise редакцию Windows. Изоляция на уровне гипервизора — максимальная безопасность. - Linux/macOS: Namespace-based isolation. Работает везде где есть unprivileged user namespaces (большинство современных дистрибутивов).
- Отключение:
[sandbox] enabled = falseв конфиге (не рекомендуется).
8. GitHub интеграция — настройте один раз
# Автоматически подхватит из gh CLI
codex auth login --github
# Или переменная окружения
export GITHUB_TOKEN=$(gh auth token)
# В .bashrc / .zshrc для постоянства
После этого: codex -p "Создай PR с фиксом" --github-token $GITHUB_TOKEN — работает автоматически.
9. Алиасы для скорости
# ~/.bashrc / ~/.zshrc
alias cx='codex'
alias cxp='codex -p'
alias cxj='codex -p --output-format json'
alias cxs='codex -p --stream'
alias cxg='codex -p --github-token $GITHUB_TOKEN'
# Быстрые модели
alias cx-4o='codex -m gpt-4o'
alias cx-claude='codex -m claude-3.5-sonnet'
alias cx-o3='codex -m o3-mini'
10. Типичные ошибки новичков
- Не делают auth login → только локальные модели. Сделайте
codex auth loginсразу. - Забывают GitHub токен → теряют 50% фич (PR, issues, CI). Настройте сразу.
- Отключают песочницу → теряют главную фичу безопасности. Не отключайте.
- Не используют headless → теряют CI/CD интеграцию. Попробуйте
--output-format json. - Строят из исходников без нужды — Bazel сложен. Используйте бинарник/brew/npm.
Чек-лист первого дня ✅
- [ ]
npm install -g @openai/codex(или brew) - [ ]
codex auth login(OpenAI) - [ ]
codex auth login --github(GitHub) - [ ] Создать
~/.codex/config.tomlс моделью - [ ]
codexв папке проекта — первый TUI запуск - [ ] Попробовать
codex -p "Hello" --output-format json - [ ] Настроить GitHub токен для PR
- [ ] Протестировать песочницу:
codex -p "ls -la /root"(должен запретить) - [ ] Добавить алиасы в .bashrc/.zshrc
- [ ] Почитать доки
