codex-lb — балансировщик нескольких ChatGPT/Codex-подписок

codex-lb — сторонний прокси с открытым исходным кодом, который объединяет несколько ChatGPT-аккаунтов с доступом к Codex в один пул. Codex CLI, OpenCode и другие клиенты с совместимым OpenAI API обращаются к одному сервису, а он выбирает доступный аккаунт и ведёт учёт использования.

Практический результат: вы запустите codex-lb, добавите аккаунты, подключите Codex CLI и проверите запрос в dashboard.

Содержание

1. Возможности и архитектура
2. Маршрутизация и состояние диалога
3. Установка и подключение Codex CLI
4. Проверка HTTP и WebSocket
5. API-ключи и удалённый доступ
6. Подключение OpenCode
7. Полезные сценарии и диагностика

Возможности и архитектура

codex-lb работает как промежуточный слой между клиентами и пулом аккаунтов:

Codex CLI / OpenCode ──→ codex-lb ──→ пул аккаунтов ──→ Codex backend

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

Основные адреса:

Dashboard:                  http://127.0.0.1:2455
Codex CLI / IDE:            http://127.0.0.1:2455/backend-api/codex
OpenAI-совместимые клиенты: http://127.0.0.1:2455/v1

Каталог моделей поступает из upstream Codex и может зависеть от тарифа, workspace, этапа rollout и снятия модели с поддержки. Перед настройкой используйте живой ответ /v1/models или /backend-api/codex/models, а не старый статический список.

Маршрутизация и состояние диалога

В спецификации проекта описаны стратегии relative_availability, sequential_drain, reset_drain и single_account. Они выбирают только кандидатов, прошедших проверки доступности, совместимости модели, квоты, cooldown и других ограничений. single_account использует только заданный аккаунт: при его недоступности резервного перехода нет.

Мягкая привязка потока сохраняет локальность запроса и повторное использование upstream-кэша. Если закреплённый аккаунт недоступен, новый выбор возможен по правилам маршрутизации.

Некоторые состояния продолжения Responses, операции compaction и файлы могут быть закреплены за конкретным аккаунтом. codex-lb не должен переносить такое состояние между аккаунтами произвольно:

Новый независимый запрос       → обычный выбор аккаунта
Продолжение со связанным состоянием → требуется его владелец

Локальный снимок стандартного использования, включая значение 100%, сам по себе не доказывает upstream-лимит. Для активного аккаунта он не должен блокировать попытку маршрутизации, если не исчерпана явная локальная политика или ограничение ёмкости.

Установка и подключение Codex CLI

Для локального сценария нужны:

• Docker runtime или установленный uv;
• собственные аккаунты с разрешённым доступом к Codex;
• браузер для первоначальной авторизации.

Официальный Quick Start рекомендует Docker:

docker volume create codex-lb-data
docker network inspect codex-lb-net >/dev/null 2>&1 || docker network create codex-lb-net
docker run -d --name codex-lb --network codex-lb-net -p 2455:2455 -p 1455:1455 -v codex-lb-data:/var/lib/codex-lb ghcr.io/soju06/codex-lb:latest

Откройте http://localhost:2455, выберите Add account и повторите авторизацию для остальных аккаунтов.

Запуск без Docker

uvx codex-lb

Данные находятся здесь:

uvx:    ~/.codex-lb/
Docker: /var/lib/codex-lb/

Каталог или Docker volume включите в резервное копирование.

Конфигурация Codex CLI

Добавьте в ~/.codex/config.toml:

model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"
model_provider = "codex-lb"

[model_providers.codex-lb]
name = "openai" # нижний регистр нужен для современного Codex
base_url = "http://127.0.0.1:2455/backend-api/codex"
wire_api = "responses"
env_key = "CODEX_LB_API_KEY" # добавьте при включённой proxy-аутентификации
supports_websockets = true
requires_openai_auth = true # требуется для Codex app

gpt-5.6-sol — пример. Сначала проверьте доступные модели:

curl http://127.0.0.1:2455/v1/models

Если proxy-аутентификация отключена, строку env_key можно убрать. При включённой аутентификации задайте ключ локально:

export CODEX_LB_API_KEY="sk-clb-..."
codex

Проверка HTTP и WebSocket

Для минимальной проверки выполните:

codex exec "Reply with OK only."

Затем откройте dashboard. В нём должны появиться запрос и выбранный аккаунт.

Для проверки WebSocket:

RUST_LOG=debug codex exec "Reply with OK only."

Признаки успешного WebSocket-соединения:

• в логах Codex есть сообщения о подключении и успешном соединении;
• в логах codex-lb есть WebSocket /backend-api/codex/responses;
• для того же запуска нет резервного POST /backend-api/codex/responses.

Параметр supports_websockets = true разрешает попытку WebSocket, но не запрещает откат на HTTP. Upstream-транспорт выбирается в Settings → Routing → Upstream stream transport: auto, http или websocket; auto используется по умолчанию.

API-ключи и удалённый доступ

Локальный клиент может работать без proxy-ключа, если аутентификация отключена. Нелокальные запросы отклоняются, пока proxy-аутентификация не настроена.

1. В dashboard откройте API Keys.
2. Создайте отдельный ключ для клиента.
3. Передавайте его как Bearer token:

Authorization: Bearer sk-clb-...

Ключи поддерживают ограничения по моделям, токенам, стоимости, временным окнам и допустимому уровню reasoning effort.

Для первоначальной удалённой настройки dashboard нужен одноразовый bootstrap token из логов сервера:

docker logs codex-lb

Если proxy стоит за reverse proxy и должен видеть реальный IP клиента, разрешите forwarded headers только от доверенной подсети:

CODEX_LB_FIREWALL_TRUST_PROXY_HEADERS=true
CODEX_LB_FIREWALL_TRUSTED_PROXY_CIDRS=172.18.0.0/16

Замените пример на реальную подсеть proxy.

Подключение OpenCode

Используйте встроенный провайдер openai с переопределённым baseURL. Generic-провайдер на основе @ai-sdk/openai-compatible переводит клиент на Chat Completions и теряет reasoning state; встроенный провайдер сохраняет путь Responses API.

Пример ~/.config/opencode/opencode.json:

{
  "provider": {
    "openai": {
      "options": {
        "baseURL": "http://127.0.0.1:2455/v1",
        "apiKey": "{env:CODEX_LB_API_KEY}"
      },
      "models": {
        "gpt-5.6-sol": {
          "name": "GPT-5.6-Sol",
          "reasoning": true,
          "options": {
            "reasoningEffort": "xhigh",
            "reasoningSummary": "detailed"
          },
          "limit": {
            "context": 272000,
            "output": 65536
          }
        }
      }
    }
  },
  "model": "openai/gpt-5.6-sol"
}

Перед запуском проверьте, что OpenCode не использует конфликтующие прямые учётные данные OpenAI. Если ключ требуется, задайте его и запустите:

export CODEX_LB_API_KEY="sk-clb-..."
opencode

Полезные сценарии и диагностика

Новый поток после ограничения аккаунта

• Задача: выполнить новый запрос, когда один аккаунт временно недоступен.
• Условие: в пуле есть другой активный аккаунт с подходящей моделью.
• Действие: создайте новый независимый поток.
• Результат: запрос проходит через доступного кандидата и появляется в dashboard.
• Ограничение: состояние старого диалога может оставаться привязанным к прежнему аккаунту.

Общий пул для Codex и OpenCode

• Задача: направить два клиента через одну инфраструктуру.
• Условие: Codex подключён к /backend-api/codex, OpenCode — к /v1 через встроенный openai.
• Действие: выполните тестовый запрос из каждого клиента.
• Результат: оба запроса отображаются в общем dashboard.
• Ограничение: доступные модели зависят от живого upstream-каталога и состава пула.

Доступ со второго компьютера

• Задача: дать сетевой доступ без передачи учётных данных ChatGPT.
• Условие: настроены API-ключ, закрытая сеть или reverse proxy с WebSocket upgrades.
• Действие: создайте отдельный ключ и настройте удалённый клиент на адрес сервера.
• Результат: расход клиента виден по его ключу и ограничивается заданной политикой.
• Ограничение: нелокальный запрос без proxy-аутентификации будет отклонён.

Если старые сессии Codex не видны

codex resume фильтрует сессии по model_provider. Для сессий, созданных с прямым провайдером OpenAI, используйте встроенное переназначение. Сначала закройте Codex и выполните проверочный запуск:

codex-lb codex-sessions retag --from openai --to codex-lb --dry-run

Проверьте результат и сделайте резервную копию перед применением:

codex-lb codex-sessions retag --from openai --to codex-lb --yes

Не редактируйте файлы сессий вручную.

Базовая диагностика

docker ps
docker logs codex-lb
curl http://127.0.0.1:2455/v1/models

Затем сверьте base_url, name = "openai", wire_api = "responses" и наличие CODEX_LB_API_KEY, если аутентификация включена.

Проект развивается независимо от OpenAI. Изменения авторизации, Codex backend и модельного каталога могут потребовать обновления сервиса или конфигурации. Пул остаётся набором отдельных аккаунтов с их собственными условиями и ограничениями.

Официальные ссылки

• GitHub — Soju06/codex-lb
• Документация codex-lb
• Настройка клиентов
• Удалённый доступ
• Спецификация маршрутизации
• Changelog

Следующий шаг

Codex App — единый справочник по среде от OpenAI

Связанные материалы

• Qwen3.8 на Mac mini M4 Pro
• Codex за пределами кода — что умеет агент OpenAI по версии самих OpenAI
• Как поднять свою LLM и подключить к Codex

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

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov