opencodex/readme/README.ru.md at main · lidge-jun/opencodex

make codex open!

Универсальный прокси провайдеров для OpenAI Codex, Claude Code, Claude Desktop и Grok Build
Две команды — и каждый из них работает на любой LLM, которую вы укажете.

npm install -g @bitkyc08/opencodex
ocx start

Claude Code на любой модели Селектор — штатный Claude Code. Мозг за ним — нет.
Codex на любой модели Выберите провайдера — и вперёд: тот же рабочий процесс, другой «мозг».
Claude Desktop на любой модели Opus отвечает, затем передаёт задачу подагенту GPT-5.6 Sol.
Grok Build на любой модели Sol ведёт сессию и вызывает подагента Kimi K3.

English · Français · 한국어 · 简体中文 · 繁體中文 · Русский · 日本語 · Türkçe · 📖 Полная документация →

opencodex — лёгкий локальный прокси, который транслирует Responses API Codex в протокол, понятный вашему провайдеру: потоковая передача, вызовы инструментов, токены рассуждений и изображения — в обе стороны. Используйте Claude, Gemini, Grok, GLM, DeepSeek, Kimi, Qwen, Ollama или любую другую LLM с Codex, Claude Code, Claude Desktop и Grok Build. Кроме того, он умеет управлять пулом аккаунтов ChatGPT для аутентификации Codex: добавляйте аккаунты, обновляйте их квоты в панели управления, и новые сессии будут автоматически направляться на работоспособный аккаунт с наименьшим использованием, а существующие треды останутся закреплёнными за аккаунтом, с которого они начались.

Быстрый старт

Личная установка (CLI)

npm install -g @bitkyc08/opencodex   # Node 18+; рантайм Bun подключается автоматически
ocx start                         # прокси + панель управления на localhost:10100

Чтобы запустить его в фоне, используйте ocx service.

Откройте http://localhost:10100 и настройте всё в веб-панели: добавьте провайдеров (40+ встроенных или любой OpenAI-совместимый endpoint), выберите модели, управляйте аккаунтами. ocx gui в любой момент снова откроет панель.

Настольное приложение (бета)

Настольное приложение — это тот же прокси и та же панель управления в нативном окне, с иконкой в трее и встроенным ocx. Оно подключается к уже запущенному прокси либо запускает встроенный, а панель остаётся на порту прокси (http://localhost:10100, если вы не настроили другой). Выберите файл для своей платформы в последнем релизе:

Платформа	Файл	Примечания
macOS 13+ (Apple Silicon и Intel)	`OpenCodex-<version>-macos.dmg`	Универсальная сборка, подписана Developer ID и нотариализована
Windows (x64)	`OpenCodex-<version>-windows-x64.msi`	Пока без цифровой подписи: SmartScreen спросит один раз — выберите Подробнее → Выполнить в любом случае
Linux (x86_64)	`OpenCodex-<version>-linux-x86_64.AppImage` или `-linux-amd64.deb`	Для трея нужен рабочий стол с поддержкой AppIndicator

Рядом с каждым файлом на странице релиза есть .sha256. На macOS 14+ приложение также поставляется с расширением WidgetKit, которое показывает состояние прокси, расход за сегодня и квоты провайдеров; модель снимков, которую оно отображает, находится в app/ (MenuBarCore). Чтобы собрать приложение самостоятельно, выполните bun install && bun run build:gui в корне репозитория, затем в desktop/ выполните bun install && bun run prepare-sidecar && bun run prepare-widget && bun run build:local на macOS или bun install && bun run prepare-sidecar && bun run build:local на Windows и Linux (шаг с виджетом работает только на macOS). В руководстве по настольному приложению и руководстве по приложению macOS в строке меню описан первый запуск, а AGENTS_INSTALL.md перечисляет всё, что записывается на диск.

Пул аккаунтов ChatGPT

opencodex также умеет управлять пулом аккаунтов ChatGPT для аутентификации Codex. Добавьте несколько аккаунтов ChatGPT / Codex и обновляйте их квоты за 5 ч / неделю / 30 дней в панели. При маршрутизации по квоте новые сессии могут использовать работоспособный аккаунт с наименьшим использованием; round-robin и fill-first применяют свои политики. Существующие треды Codex обычно сохраняют привязку к аккаунту, с которого начались, поэтому длинные сессии по SSH, в tmux или с мобильного устройства не перескакивают между аккаунтами посреди разговора — но повторная оценка квот, failover, исключение аккаунта, истечение привязки или восстановление после 401/403 и 429 могут перепривязать их. Задайте аккаунтам порядок выбора, если один из них — обычно вход Codex Desktop — должен использоваться только после того, как остальные исчерпаны.

Спонсоры

Спонсоры позволяют поддерживать opencodex при каждом изменении вышестоящих протоколов. Интересно? См. SPONSORS.md.

	Благодарим OrcaRouter за спонсорскую поддержку проекта! OrcaRouter — единый OpenAI-совместимый AI-шлюз для продакшена: адаптивная маршрутизация оценивает каждый промпт и отправляет его модели, которая проходит ваш порог, плюс автоматический failover, правила маршрутизации как код, цены провайдеров без наценки с кэшированием промптов, а также guardrails, файрвол агентов и журналы запросов на каждый вызов среди 200+ моделей. Выберите `OrcaRouter` в селекторе Add provider или выполните `ocx provider add orcarouter`; `orcarouter/auto` — адаптивный маршрутизатор.
	Благодарим PackyCode за спонсорскую поддержку проекта! PackyCode — стабильный высокопроизводительный API-релей, предоставляющий релей-сервисы для Claude Code, Codex, Gemini и других. Автоматический failover, умная маршрутизация и неограниченная конкурентность превращают AI в настоящий инструмент продуктивности. Зарегистрируйтесь по этой ссылке и начните работу! Выберите `PackyCode` в селекторе Add provider или выполните `ocx provider add packycode`. _{PackyCode 是一家稳定、高效的 API 中转服务商，提供 Claude Code、Codex、Gemini 等多种中转服务。具备自动故障转移、智能路由和无限并发等多种功能，让 AI 编程成为真正的生产力工具。点此链接注册，立即开始使用！}
	Благодарим TokenLab за спонсорскую поддержку проекта! TokenLab даёт агентам для программирования один API-ключ для ведущих моделей с поддержкой форматов OpenAI Responses и Chat Completions, Anthropic Messages и нативного API Gemini, включая стриминг и вызов инструментов. Также доступны MCP-сервер и Skills для агентов, чтобы упростить интеграцию. Выберите режим доставки и платите по мере использования. Выберите `TokenLab` в селекторе Add provider или выполните `ocx provider add tokenlab`. _{TokenLab 为编程智能体提供统一的多模型 API，一枚 API Key 即可接入主流模型，支持 OpenAI Responses、Chat Completions、Anthropic Messages 和 Gemini 原生 API 格式，以及流式输出和工具调用。同时提供 MCP 服务器和 Agent Skills，方便接入现有工作流；交付模式可选，按量付费。}

Docker Compose

Репозиторий поставляет сборку Compose с закреплённым дайджестом и без root. Сборка сама создаёт и проверяет канонический манифест совместимости из выбранного снимка Git. Для локального клона нужны Git и Docker Compose, для удалённого Git-контекста — Docker Compose. Ни одному варианту не нужны Bun на хосте или подготовительный шаг. Один раз инициализируйте токен плоскости данных через stdin и запустите хаб:

git clone https://github.com/lidge-jun/opencodex.git
cd opencodex
docker compose build
openssl rand -hex 32 | docker compose run --rm -T hub bun run docker/bootstrap-token.ts
docker compose up -d
curl --fail --silent http://127.0.0.1:10100/healthz
curl --fail --silent http://127.0.0.1:10100/readyz

Привязка по умолчанию — 127.0.0.1:10100. Удалённый доступ требует явного OPENCODEX_BIND_ADDRESS=<LAN-or-Tailscale-IP> docker compose up -d; 0.0.0.0 открывает все интерфейсы хоста. Ограничьте доступ файрволом и аутентифицированным TLS/tailnet-фронтендом. Сгенерированный JSON остаётся неотслеживаемым. В контекст сборки допускаются только .git/index и .git/HEAD — инвентарь, который читает git ls-files, объёмом около 1 МБ вместо полного хранилища объектов. Они видны только этапу манифеста, используемому при сборке, через монтирование только для чтения, поэтому ни один COPY не включает .git. Манифест, ранее созданный на хосте, принимается только после проверки; иначе сборка создаёт его сама. Сборка отклоняет устаревшие манифесты, отсутствующие или несовпадающие файлы, лишние исходники и символические ссылки. Она сверяет каждый записанный SHA-256 с контекстом сборки и скопированными рантайм-файлами, включая package.json, bun.lock и явно включённый scripts/model-metadata.source.json.

Для удалённого Git-контекста BuildKit должен сохранять метаданные Git. Этот фрагмент сборки Compose выбирает удалённый снимок и передаёт требуемый встроенный аргумент:

services:
  hub:
    pull_policy: build
    build:
      context: https://github.com/lidge-jun/opencodex.git#main
      dockerfile: Dockerfile
      target: runtime
      args:
        BUILDKIT_CONTEXT_KEEP_GIT_DIR: "1"

Токен и изменяемое состояние живут в именованном томе ocx-state; ни одно учётное данное не попадает в образ, Compose-файл, окружение или аргументы оболочки. См. руководство по развёртыванию Remote Hub для настройки провайдеров, аутентифицированных проверок приёмки, удалённого управления и отката.

Установка из исходников (последний dev)

macOS / Linux:

curl -fsSL https://bun.sh/install | bash
git clone -b dev https://github.com/lidge-jun/opencodex.git
cd opencodex && ~/.bun/bin/bun install
~/.bun/bin/bun run build:gui
~/.bun/bin/bun run src/cli/index.ts start

Windows (PowerShell):

irm bun.sh/install.ps1 | iex
git clone -b dev https://github.com/lidge-jun/opencodex.git
cd opencodex; bun install
bun run build:gui
bun run src/cli/index.ts start

Установка из исходников запускает последнюю ветку dev. Патчи владения памятью, улучшения GC рантайма и ещё не опубликованные исправления доступны здесь раньше, чем в npm-пакете.

Для агентов

npm install -g @bitkyc08/opencodex
ocx start     # или `ocx service`
ocx init      # интерактивная настройка: пишет ~/.opencodex/config.json и подключает Codex

ocx init никогда не запускает прокси; запустите его сначала (или после — оба порядка работают, но headless-команды вроде ocx provider add и ocx combo set обращаются к живому прокси и завершаются с ненулевым кодом, если он недоступен). ocx status / ocx doctor / ocx health показывают состояние запущенного процесса.

Агентам, которые устанавливают или запускают opencodex: прочитайте AGENTS_INSTALL.md. Интерактивный ocx start может один раз спросить, ставить ли star этому репозиторию — это решение пользователя, никогда не агента. CLI подавляет подсказку в агентных запусках, а API отказывает с 403 agent_consent_required.

Поддерживаемые платформы

ОС	Статус	Менеджер служб	Настольное приложение (бета)
macOS (arm64 / x64)	Полная поддержка	launchd	Универсальный `.dmg`
Linux (x64 / arm64)	Полная поддержка	systemd (пользовательский unit)	`.AppImage` / `.deb` для x86_64
Windows (x64)	Полная поддержка	Task Scheduler (скрыто) / опциональная нативная служба (`--native`, WinSW)	`.msi` для x64

Для установки CLI требуется Node 18+; настольному приложению не нужны ни Node, ни Bun. Рантайм Bun добавляется автоматически при npm install — отдельно устанавливать Bun не нужно, WSL на Windows тоже не нужен. Если npm заблокировал скрипты установки встроенного рантайма, см. документацию по установке.

Основные возможности

Любая LLM в Codex, Claude Code, Claude Desktop и Grok Build — 40+ провайдеров из коробки, каждый со своим нативным UI.
Пул аккаунтов ChatGPT — привязка тредов, автопереключение с учётом квот, кулдаун и fail-closed обработка аутентификации.

Замечание о политике провайдеров: пул аккаунтов нужен только для маршрутизации и операционной устойчивости; он не гарантирует защиты от лимитов провайдера, принудительных мер, блокировок и других действий в отношении аккаунтов. OpenCodex не одобряет использование дополнительных аккаунтов для обхода лимитов провайдера и совместное использование учётных данных между людьми. Вы отвечаете за соблюдение актуальных условий каждого провайдера. См. руководство по пулу аккаунтов Codex Auth и актуальные Terms of Use OpenAI.
Combos — один виртуальный id модели с failover или взвешенным round-robin между провайдерами. См. руководство по combos.
Подагенты на любой модели — выводите маршрутизируемые модели в селектор подагентов Codex, с управлением поверхностями v1/v2 и цепочками fallback. См. руководство по подагентам.

Один вход — без API-ключа — OAuth для xAI, Anthropic и Kimi; либо пробросьте codex login, вставьте ключ или используйте ссылки ${ENV_VAR}.
Сайдкары веб-поиска и зрения — модели не от OpenAI получают настоящий веб-поиск и понимание изображений через сайдкар поверх вашего входа ChatGPT.
Видно, что происходит — панель показывает провайдеров, статус OAuth, выбор моделей и живой журнал запросов с количеством токенов кэша.
Чистый выход без следов — ocx stop возвращает Codex к исходной конфигурации.
Ограниченное владение памятью — у каждого долгоживущего кэша, кольцевого буфера и хранилища трансляции протокола есть конечный потолок, байтовый бюджет или активная сверка. Ни один неограниченный Map или Set не переживает перезагрузку конфигурации.

Подробности владения памятью

OpenCodex отслеживает состояние, удерживаемое процессом, в категориях ниже. У каждой есть документированная граница:

14 удерживаемых хранилищ (журнал запросов, отладочные кольца, кэш изображений, кэш моделей, vision-описания, cursor-блобы, продолжение responses и т. д.) учитываются в байтах и вытесняются бюджетом памяти приложения (по умолчанию 256 MiB), кроме хранилища native control replay: оно закреплено и не вытесняется.
4 наблюдаемых буфера (аккумуляторы транслятора, хвосты image/OAuth/Grok) мониторятся по байтовому давлению in-flight без вытеснения.
28 регистраций state-store выполняют sweeps истечения (интервал 60 с) и сверку поколений конфигурации, чтобы удалять устаревшие ключи провайдеров и аккаунтов.
Мемо пути и отпечатков (метаданные рабочей области, усиленные идентификаторы, соли установки, возможности mode-hint) используют LRU-потолки в порядке вставки (8–128 записей).
Tombstone поколений кэша моделей удаляются после сверки; глобальный инкремент поколения не даёт устаревшим in-flight discovery снова заполнить удалённых провайдеров.
Дедупликация event-id в Lab работает под блокировкой журнала с диска, без процессного RAM-индекса.

Выполните GET /api/system/memory (с admin-токеном), чтобы посмотреть живые удержанные байты, счётчики вытеснения и выборки watchdog.

Маршрутизация моделей

Обращайтесь к любому настроенному провайдеру и модели синтаксисом provider/model:

codex -m "anthropic/claude-opus-5" "Разберите этот stack trace"
codex -m "google/gemini-3-pro" "Напишите unit-тесты для auth.ts"
codex -m "ollama/llama3" "Отрефакторьте эту функцию"

Опустите префикс provider/, чтобы использовать провайдера по умолчанию или автоматически подобрать его по шаблону имени модели. Id моделей провайдера, содержащие /, отдаются с внутренними слэшами, заменёнными на -; исходная форма со всеми слэшами тоже продолжает работать. Подробности: документация по маршрутизации моделей.

Маршрутизация JEV Auto (опционально)

TypeSafe JEV может выбирать первую модель и уровень рассуждения для явно включённого Combo, не меняя обычный выбор модели и прямые маршруты. Добавьте ключ через ocx login jev, в Providers → TypeSafe JEV → Add API key или через TYPESAFE_API_KEY/JEV_API_KEY. Затем откройте Models → Combos → Create JEV Auto, выберите разрешённые целевые модели и отметьте, какие уровни рассуждения JEV может выбрать для каждой цели. Если настройку не трогать, цель разрешает все уровни, которые модель сейчас объявляет.

JEV вызывается только для jev-auto и только один раз на логический вызов модели. При отсутствии ключа, сетевой ошибке или некорректном решении запрос уходит на первую доступную цель (fail-open); отмена со стороны клиента по-прежнему отменяет запрос. Автотесты используют имитацию TypeSafe и не проверяют настоящий аккаунт JEV.

Провайдеры и адаптеры

OpenAI (вход ChatGPT или API-ключ), Anthropic, Google Gemini, xAI, Kimi, Azure OpenAI, Ollama (локально + Cloud), Cursor (экспериментально) и любой OpenAI-совместимый endpoint — плюс DeepSeek, Groq, OpenRouter, Together, Fireworks, Cerebras, Mistral, Hugging Face, NVIDIA NIM, MiniMax, Qwen Cloud, Qoder Global и CN (официальный PAT + CLI), SiliconFlow и другие. Полный список: ocx init или документация по провайдерам.

CLI

ocx init                       # интерактивная настройка (пишет конфиг, подключает Codex, предлагает shim)
ocx start [--port 10100] [--socks5 [host:port] | --socks5-off]  # SOCKS5 по умолчанию: socks5://127.0.0.1:10808
ocx stop                       # остановить + восстановить нативный Codex
ocx service [install|repair|restart|start|stop|status|uninstall|remove]  # фоновая служба
ocx codex-shim install         # запускать прокси по требованию при старте `codex`
ocx health [--json]            # проверить немедленную живость прокси
ocx ready [--json] [--wait [--timeout <seconds>]]  # проверить готовность после синхронизации
ocx status                     # работает ли прокси?
ocx gui                        # открыть веб-панель
ocx provider <...>             # управлять провайдерами (list/add/edit/test/remove)
ocx account <...>              # управлять аккаунтами ChatGPT и пулами API-ключей
ocx combo <...>                # управлять combos с failover / round-robin
ocx v2 <...>                   # управление мультиагентными поверхностями v1/v2
ocx update [--tag preview]     # обновить opencodex

Если предпочтительный порт занят, запуск останавливается и сообщает, какой процесс его занимает, вместо перехода на другой порт, поэтому второй прокси никогда не останется работать рядом с первым. Освободите порт или укажите другой с помощью --port. Полный справочник: документация CLI.

Здоровье и готовность

GET /healthz сообщает о немедленной живости прокси. Неаутентифицированный endpoint GET /readyz сообщает о готовности после синхронизации с очищенной JSON-идентичностью {service, version, uptime, pid, port, status}. Он возвращает 200, когда status равен ready; pending и терминальный failed возвращают 503 с Retry-After: 1.

ocx ready [--json] [--wait [--timeout <seconds>]] по умолчанию выполняет один зонд. --wait опрашивает до 45 секунд по умолчанию, но сразу завершается при терминальном failed; --timeout <seconds> задаёт лимит 1–300 секунд, требует --wait и принимает только положительные целые. CLI --json выводит {ready, status, pid, port}, где status — ready, pending, failed или unreachable.

Код	Результат
`0`	Готов
`1`	Не готов: pending, failed, timeout или unreachable
`64`	Некорректные аргументы

Старый прокси без /readyz закрывается как unreachable с кодом 1, тогда как ocx health остаётся совместимым.

Автозапуск: служба или shim

Используйте службу (ocx service) для постоянно работающего прокси, который перезапускается при сбое. Используйте shim (ocx codex-shim install) для лёгкого запуска по требованию без фонового демона. Удаляйте их командами ocx service uninstall / ocx codex-shim uninstall.

Удаление

ocx uninstall                  # остановить, удалить службу/shim, восстановить нативный Codex, очистить состояние
npm uninstall -g @bitkyc08/opencodex

Удалённый доступ

По умолчанию opencodex привязывается к 127.0.0.1 и не требует дополнительной аутентификации. Привязка за пределами loopback ("hostname": "0.0.0.0") требует bearer-токен — прокси откажется запускаться без OPENCODEX_API_AUTH_TOKEN, и каждый клиентский запрос должен нести его как x-opencodex-api-key. Подробности: справочник по конфигурации.

Документация

Публичная документация — установка, провайдеры, маршрутизация, combos, подагенты, сайдкары, интеграции и справочники CLI/конфигурации/management-API — собирается из docs-site/ и публикуется на opencodex.me.

Заметки мейнтейнеров, служащие источником истины, находятся в structure/, настройка для контрибьюторов — в CONTRIBUTING.md, сообщения о проблемах безопасности — в SECURITY.md. Нераскрытые уязвимости сообщайте приватно через GitHub private vulnerability reporting, а не публичный issue. Эта форма — единственный технический канал, отдельного адреса для безопасности нет. Дальнейшее обсуждение остаётся внутри приватного отчёта; в публичном issue допустима только координация, но не детали уязвимости. Подтверждение получения отчёта — это ещё не разбор, и срок первого ответа не обещан.

Разработка

Разработка из исходников требует CLI bun в вашем PATH. Это отдельно от встроенного рантайма Bun опубликованного npm-пакета, который используют только установленные команды ocx.

git clone https://github.com/lidge-jun/opencodex.git
cd opencodex
bun install
bun run typecheck
bun run test

См. Contributing.

Работа контрибьюторов, которая попала через перенос или реимплементацию мейнтейнером, если коммит не называет исходного автора, записана в CREDITS.md.

Отказ от ответственности

opencodex — независимый проект, поддерживаемый сообществом; он не аффилирован с OpenAI, Anthropic или каким-либо другим провайдером и не одобрен ими.

Некоторые провайдеры — в частности Anthropic (Claude) — могут приостанавливать или ограничивать аккаунты, которые направляют API-трафик через сторонние прокси. Используйте на свой страх и риск (UAYOR). Прежде чем подключать провайдера, изучите его Terms of Service и убедитесь, что доступ через прокси разрешён. Мейнтейнеры opencodex не несут ответственности за какие-либо действия вышестоящих провайдеров в отношении аккаунтов.

Лицензия

MIT

FilesExpand file tree

README.ru.md

Latest commit

History