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. Сравнение с конкурентами
| Фича | Codex | Claude Code | OpenCode |
|---|---|---|---|
| Open Source | ✅ Apache-2.0 | ❌ Proprietary | ✅ MIT |
| Язык ядра | Rust | TypeScript/Node | Go |
| Песочница | ✅ Встроенная | ❌ (через permissions) | ❌ |
| Models | OpenAI + Anthropic + custom | Anthropic only | 200+ через Models.dev |
| GitHub Integration | ✅ Нативная | ✅ MCP | ✅ MCP |
| Desktop App | ❌ | ❌ | ✅ |
| Mobile App | ❌ | ❌ | ✅ |
| Multi-Session | ❌ | ❌ | ✅ |
| Custom Agents | ❌ | ✅ Subagents | ✅ |
| Free Tier | API key required | Subscription | ✅ Built-in |
| License | Apache-2.0 | Proprietary | MIT |
8. Полезные ссылки
- GitHub: openai/codex (135k★)
- Документация: developers.openai.com/codex
- Релизы: GitHub Releases
- Установка: Install Guide
- Контрибьютинг: Contributing
- Open Source Fund: Open Source Fund
Чек-лист первого запуска
npm install -g @openai/codex(илиbrew install openai/codex/codex)codex auth login— авторизация через браузер (OpenAI аккаунт)- Настройте
~/.codex/config.toml(модель, песочница, GitHub токен) - Запустите
codexв папке проекта - Попробуйте headless:
codex -p "Hello world" --output-format json - Настройте GitHub токен для PR интеграции
