Codex Gateway — документация · Сергей Комаров

О проекте

Нужно было дать нескольким Codex-клиентам управляемый доступ через один шлюз, видеть сроки конфигураций, ошибки и расход токенов и при этом не превращать мониторинг в новую точку отказа.

Codex Gateway — Ruby proxy перед модельным API. Он управляет несколькими конфигурациями доступа, выборочно инспектирует только Codex-трафик, проксирует HTTP, SSE и WebSocket и считает usage по пользователям. Копия очищенных событий уходит в ограниченный outbox и NATS, не блокируя основной запрос Codex.

Что отличает реализацию

Gateway объединяет управление доступом, потоковый transport и наблюдаемость в одном Ruby-процессе, но выводит мониторинг из критического пути. Выборочная TLS-инспекция ограничена Codex-доменами; event copy очищается до NATS. Поэтому Synadia получает живые данные, а сбой NATS не прерывает работу Codex.

Состав прикладного кода

Доли по размеру прикладных файлов Git в закреплённой версии. Каждый файл отнесён к одной подсистеме по правилам scripts/generate-stack-share.mjs; тесты, ассеты, зависимости и generated-файлы исключены. Округление — до 0,1%. Это состав кода, а не уровень владения технологиями. Для Gateway измеряются два отслеживаемых Ruby-модуля proxy и observer; библиотеки базового образа в расчёт не входят.

Административный интерфейс закрыт Basic Auth; публичная страница содержит только обезличенные снимки.
Снимки показывают реальные агрегаты, но аккаунты и конфигурационные значения заменены в DOM перед кадром.
Tracing в самом Gateway не является источником публичного эфира: живые события передаются в отдельный Synadia-контур.

Скриншоты, схемы и исходные материалы сохранены на языке оригинала; подписи и описание переведены.

Архитектура и схемы

TLS-инспекция включается только для разрешённых Codex-hostnames; остальной CONNECT остаётся обычным туннелем.
Основной ответ клиенту не ждёт NATS: при недоступности мониторинга событие попадает в ограниченный outbox, а Codex продолжает работу.
SSE и WebSocket разбираются по мере поступления с учётом разделённых сообщений, UTF-8 и reconnect.
Секретные заголовки и токены исключаются до формирования события мониторинга.

Поток Codex-трафика и очищенных событий · Mermaid ↓

Размещение owner-интерфейса и хранилищ · Mermaid ↓

Code-map: файлы и связи

Карта привязана к версии 5a8e7e332b81. В таблице — экран или API, связанный модуль и данные.

Функция	Экран / API	Модуль	Данные / проверка
CONNECT / TLS	Proxy CONNECT endpoint	proxy.rb: handle_connect; codex_interception_required?	OpenSSL; permitted hostnames and relay checks
HTTP / SSE / WebSocket	Forwarded model requests	proxy.rb: forward_request; forward_websocket_request	Response streams, usage and observer tests
Configurations / usage	Owner dashboard / control API	proxy.rb: handle_control_request; AssetStore	JSON files; active configuration and usage aggregates
Monitoring events	Bounded outbox → NATS	docker/monitor/observer.rb	Sanitized events; fragmented secrets and overflow tests

Как работать с картой

Перед изменением найти функцию и пройти связи до API, состояния и хранилища.
Проверить входы, ошибки, повторные события и зависимые сценарии.
После изменения обновить карту и затронутые схемы вместе с кодом.
Выполнить связанные проверки и привязать новые материалы к версии исходников.

Сценарии и API

Открыть закрытую панель и проверить активную конфигурацию, сроки и состояние обновления.
Сопоставить usage proxy-пользователя с агрегатами за 24 часа и 7 дней.
Проверить прохождение HTTP, SSE и WebSocket и состояние Ruby proxy.
Открыть документацию proxy и границы TLS-инспекции.

Проверка опубликованной версии

Проверка health, HTTP и потоковых transport с сохранением ответа клиенту.
Проверка очистки секретных заголовков и переполнения ограниченного outbox.
Browser QA dashboard, sessions, stats and mobile layout after DOM-only masking.

Эти проверки относятся к указанной версии. Коммерческие показатели и качество моделей на независимой выборке здесь не измерялись.

Измерения

Рабочий Gateway обслуживает Codex-клиентов и показывает агрегированный usage по отдельным proxy-пользователям.
Восемь снимков получены с действующего экземпляра; серверные данные не изменялись, ошибок страницы не обнаружено.

Запуск и эксплуатация

Gateway запускается как отдельный контейнер на loopback, а Nginx публикует только закрытый административный интерфейс.

Недоступность NATS не останавливает основной proxy-поток. Отключение сбора через MONITOR_ENABLED=false требует пересоздания proxy и краткого переподключения активных соединений.

Стек

Ruby	MITM proxy, маршрутизация CONNECT и сервер административного интерфейса.
OpenSSL	Локальные сертификаты и выборочная инспекция разрешённого трафика.
HTTP / SSE / WebSocket	Обычные и потоковые запросы Codex, reconnect и usage.
NATS / outbox	Неблокирующая доставка очищенных событий в мониторинг.

Материалы и исходники

Документация Markdown ↓Архив материалов ↓Галерея проекта →

Разработка и эксплуатация: 2026. Снимки подготовлены 8 сентября 2026.

Архив материалов на языке оригинала.