Codex: полное руководство по официальному AI-агенту от OpenAI

Codex — это официальный легковесный coding agent от OpenAI, который запускается в вашем терминале. Написан на Rust (core: codex-rs) и TypeScript (CLI: codex-cli). 135k+ звёзд на GitHub, Apache-2.0 лицензия, активная разработка (13,600+ коммитов, 727 контрибьюторов).

1. Установка и быстрый старт

Установка через npm (рекомендуется)

npm install -g @openai/codex
# или
npx @openai/codex

Установка бинарника (Rust)

# macOS (Homebrew)
brew install openai/codex/codex

# Linux
curl -fsSL https://codex.openai.com/install.sh | bash

# Или скачайте релиз с GitHub
# https://github.com/openai/codex/releases

Запуск

codex                    # Интерактивный режим в терминале
codex -p "Задача"       # Headless режим с промптом
codex --help            # Все флаги

2. Архитектура и ключевые особенности

Два компонента

  • codex-rs (Rust) — ядро: выполнение кода, песочница, файловые операции, LLM интеграция
  • codex-cli (TypeScript) — терминальный интерфейс, TUI, управление сессиями

Песочница (Sandbox)

Codex выполняет код в изолированной песочнице. На Windows — через codex-windows-sandbox-service, на Linux/macOS — через namespace-based изоляцию. Это безопасно: агент не может сломать вашу систему.

Легковесность

  • Бинарник ~50-100 MB
  • Быстрый холодный старт
  • Минимум зависимостей
  • Работает на любом железе

3. Конфигурация

Конфиг: ~/.codex/config.toml (или .codex/config.toml в проекте).

[model]
provider = "openai"
model = "gpt-4o"
# или
provider = "anthropic"
model = "claude-3.5-sonnet"

[sandbox]
enabled = true
# windows: "windows-sandbox"
# linux: "namespace"

[permissions]
allow = ["read", "write", "bash", "grep"]
# ask = ["bash(rm*)"]

github
token = "$GITHUB_TOKEN"
# или авторизация через браузер

4. Использование

Интерактивный режим (TUI)

codex
# Открывается TUI с панелями: чат, файлы, терминал
# Ctrl+C — прервать генерацию
# /help — команды
# /compact — сжать контекст

Headless режим (для CI/CD, скриптов)

# Одноразовый промпт с JSON выводом
codex -p "Создай REST API для пользователей на FastAPI" --output-format json

# В GitHub Actions
- name: Run Codex
  run: |
    codex -p "$TASK" --output-format json |
    jq -r '.result' > output.md

# Потоковый вывод
codex -p "Рефакторни этот код" --stream

Работа с GitHub

  • Автоматическое создание PR
  • Чтение issues, комментариев
  • Запуск CI проверок
  • Интеграция с GitHub Actions
codex -p "Создай PR с исправлением бага #123" --github-token $GITHUB_TOKEN

5. Продвинутые фишки

Model Providers

Поддерживает OpenAI (GPT-4o, o1, o3-mini), Anthropic (Claude 3.5 Sonnet), а также кастомные эндпоинты через OpenAI-совместимый API.

[model]
provider = "openai"
model = "gpt-4o"
base_url = "https://api.openai.com/v1"
api_key = "$OPENAI_API_KEY"

Background Compaction

Автоматическое сжатие контекста в фоне при приближении к лимиту токенов. Хуки pre_model_request / post_model_request с request_id и attempt_number для отслеживания ретраев.

Hooks

Хуки на события модели для логирования, метрик, кастомной логики.

Windows Sandbox Service

На Windows песочница работает как отдельная служба (codex-windows-sandbox-service), включённая в релизные билды.

6. Сборка из исходников

Требуется Rust toolchain + Bazel.

git clone https://github.com/openai/codex
cd codex
# Установка Bazel (bazelisk)
npm install -g @bazel/bazelisk
# Сборка
bazel build //codex-cli:codex
bazel build //codex-rs:codex
# Запуск
./bazel-bin/codex-cli/codex

7. Сравнение с конкурентами

ФичаCodexClaude CodeOpenCode
Open Source✅ Apache-2.0❌ Proprietary✅ MIT
Язык ядраRustTypeScript/NodeGo
Песочница✅ Встроенная❌ (через permissions)❌
ModelsOpenAI + Anthropic + customAnthropic only200+ через Models.dev
GitHub Integration✅ Нативная✅ MCP✅ MCP
Desktop App❌❌✅
Mobile App❌❌✅
Multi-Session❌❌✅
Custom Agents❌✅ Subagents✅
Free TierAPI key requiredSubscription✅ Built-in
LicenseApache-2.0ProprietaryMIT

8. Полезные ссылки

Чек-лист первого запуска

  1. npm install -g @openai/codex (или brew install openai/codex/codex)
  2. codex auth login — авторизация через браузер (OpenAI аккаунт)
  3. Настройте ~/.codex/config.toml (модель, песочница, GitHub токен)
  4. Запустите codex в папке проекта
  5. Попробуйте headless: codex -p "Hello world" --output-format json
  6. Настройте GitHub токен для PR интеграции