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.

Чек-лист первого дня ✅

  1. [ ] npm install -g @openai/codex (или brew)
  2. [ ] codex auth login (OpenAI)
  3. [ ] codex auth login --github (GitHub)
  4. [ ] Создать ~/.codex/config.toml с моделью
  5. [ ] codex в папке проекта — первый TUI запуск
  6. [ ] Попробовать codex -p "Hello" --output-format json
  7. [ ] Настроить GitHub токен для PR
  8. [ ] Протестировать песочницу: codex -p "ls -la /root" (должен запретить)
  9. [ ] Добавить алиасы в .bashrc/.zshrc
  10. [ ] Почитать доки