configuration.md

title	Справочник конфигурации
description	Все поля ~/.opencodex/config.json — параметры верхнего уровня, провайдеры и сайдкары.

opencodex настраивается файлом ~/.opencodex/config.json. Его записывают ocx init и дашборд, но вы можете редактировать его и напрямую; прокси перечитывает его при запуске. Пока сервис запущен, лучше остановить прокси или править через панель/API: процесс держит конфиг в памяти, и любое сохранение на лету может перезаписать файл. С v2.7.41 ручные правки поддерева claudeCode сохраняются при таких записях; другие ключи (например, providers) всё ещё могут быть потеряны. Если файл не удаётся распарсить (например, он усечён или содержит некорректный JSON), opencodex создаёт резервную копию config.json.invalid-<timestamp>, печатает предупреждение в консоль и стартует с настройками по умолчанию. При отсутствии файла также используется конфигурация по умолчанию (один forward-провайдер openai).

Зарезервированные провайдеры OpenAI

openai и openai-apikey — фиксированные зарезервированные id. openai.codexAccountMode по умолчанию равен "pool" и выбирает среди основного и добавленных аккаунтов; "direct" использует только текущий вход вызывающей стороны/основной вход. API использует только свой настроенный API-ключ/пул ключей. Используйте «голую» модель или openai-apikey/<model>; отката учётных данных между маршрутами нет. Строки API GPT-5.6 несут метаданные: контекст 1,050,000 / максимальный ввод 922,000, а виртуальные id Pro переписываются в базовую wire-модель с reasoning.mode: "pro".

openaiProviderTierVersion: 2 помечает текущую однопровайдерную проекцию. Перед миграцией ранее поставлявшейся v1-конфигурации opencodex создаёт config.json.pre-openai-tiers-v2.bak, не заменяя отличающуюся резервную копию, и переписывает известные устаревшие выбранные id с пространствами имён в «голые» id.

Верхний уровень (OcxConfig)

Field	Type	Default	Meaning
port	number	10100	Порт, который слушает прокси.
hostname?	string	"127.0.0.1"	Адрес привязки. Установите "0.0.0.0", чтобы открыть доступ по LAN (требуется OPENCODEX_API_AUTH_TOKEN; см. Удалённый доступ ниже).
proxy?	string	—	URL исходящего HTTP(S)-прокси или ссылка ${ENV_VAR}. Применяется к HTTP_PROXY / HTTPS_PROXY, когда эти переменные окружения не заданы; loopback остаётся в NO_PROXY.
providers	Record<string, OcxProviderConfig>	—	Отображение имя провайдера → конфигурация.
openaiProviderTierVersion?	2	задаётся миграцией	Отмечает, что единая проекция OpenAI с учётом опций завершена.
defaultProvider	string	"openai"	Провайдер, используемый, когда маршрутизация не находит лучшего совпадения.
subagentModels?	string[]	gpt-5.5, тройка GPT-5.6, gpt-5.4-mini	До 5 нативных slug или id вида provider/model, отображаемых первыми в селекторе подагентов Codex. Список в руководстве v2 — пересечение настроенных моделей с первыми пятью видимыми в селекторе, совместимыми с v2 и отсортированными по priority записями Codex; используются канонические slug каталога и доступные уровни effort, а исключённые элементы остаются в конфигурации. Явно заданный пустой список сохраняется.
injectionModel?	string	—	Предпочитаемая нативная или маршрутизируемая модель подагента. Она используется в v2-руководстве по делегированию от OpenCodex, отдельно управляемом multiAgentGuidanceEnabled, а опциональное syncCodexSubagentDefaults также может сделать её нативным значением Codex по умолчанию для новых задач.
injectionEffort?	string	—	Предпочитаемый уровень рассуждений подагента (от low до ultra). Имеет смысл только вместе с injectionModel; используется руководством по делегированию и, при явном согласии, нативным значением Codex по умолчанию.
syncCodexSubagentDefaults?	boolean	false	Явное согласие применить выбранные injectionModel / injectionEffort как нативные значения подагентов Codex по умолчанию в [agents] при следующей синхронизации или перезапуске, когда активной маршрутизацией Codex управляет OpenCodex. Внешняя пользовательская конфигурация провайдера остаётся неизменной. Они влияют только на вновь создаваемые задачи Codex и сами по себе не запускают делегирование. Существующие пользовательские целевые записи сохраняются как конфликты, а не перезаписываются. Требует injectionModel; очистка модели отключает это поле. Доступно как поле частичного обновления GET/PUT /api/injection-model.
effortCap?	string	—	Жёсткий потолок уровня рассуждений на каждый запрос. Функция multi-agent V2: применяется к основным ходам, чей собственный список инструментов несёт поверхность совместной работы V2, а также к ходам порождённых потомков, помеченным ровно x-openai-subagent: collab_spawn или "subagent_kind": "thread_spawn" в x-codex-turn-metadata (помеченные потомки подпадают под потолок независимо от их собственной поверхности инструментов). Обычные основные ходы и основные ходы с поверхностью V1 не затрагиваются, ходы compaction всегда обходят потолки, а multiAgentMode: "v1" полностью отключает потолки (дашборд скрывает панель). Принимает значения от low до ultra; потолки только понижают уровень, никогда не повышают. Уровень опускается до самой высокой поддерживаемой ступени, не превышающей потолок. Если модель не предоставляет управление уровнем рассуждений или под потолком нет ни одной поддерживаемой ступени, поле уровня удаляется и действует значение провайдера по умолчанию. max и ultra принимаются, но не задают потолок более низкого ранга (после клиентского преобразования ultra → max запросы приходят со значениями от low до max), хотя известные лестницы моделей всё же могут вызвать понижение ступени или удаление поля. Селектор в дашборде предлагает значения от low до xhigh. Управляется через GET /api/effort-caps и PUT /api/effort-caps.
subagentEffortCap?	string	—	Тот же жёсткий потолок, применяемый только к ходам порождённых потомков, идентифицированным маркерами codex-rs с точным совпадением: x-openai-subagent: collab_spawn или "subagent_kind": "thread_spawn" в x-codex-turn-metadata. Другие внутренние категории подагентов (ревью, compaction, консолидация памяти) никогда не подпадают под этот потолок, а multiAgentMode: "v1" полностью его отключает. Принимает значения от low до ultra; когда заданы оба потолка, действует более низкий, и потолки только понижают уровень, никогда не повышают. Уровень опускается до самой высокой поддерживаемой ступени, не превышающей потолок. Если модель не предоставляет управление уровнем рассуждений или под потолком нет ни одной поддерживаемой ступени, поле уровня удаляется и действует значение провайдера по умолчанию. max и ultra принимаются, но не задают потолок более низкого ранга (после клиентского преобразования ultra → max запросы приходят со значениями от low до max), хотя известные лестницы моделей всё же могут вызвать понижение ступени или удаление поля. Селектор в дашборде предлагает значения от low до xhigh. Управляется через GET /api/effort-caps и PUT /api/effort-caps.
injectionPrompt?	string	—	Пользовательская замена текста внедряемого v2-руководства. Заменяет встроенный текст; плейсхолдеры {{model}}, {{effort}} и {{roster}} подставляются. Условия срабатывания не меняются. Настраивается через PUT /api/injection-model (ключ prompt).
multiAgentGuidanceEnabled?	boolean	true	Управляет только developer-руководством multi-agent, добавляемым OpenCodex. Отсутствующее значение/true сохраняет руководство v1/v2; false подавляет оба варианта, не меняя нативные значения [agents] по умолчанию, поверхность совместной работы, subagentModels, маршрутизацию и пределы effort. GET/PUT /api/injection-model возвращает эффективное значение; PUT является частичным обновлением.
disabledModels?	string[]	—	Модели, скрываемые от Codex. Маршрутизируемые id provider/model исключаются из каталога и /v1/models; «голые» нативные GPT-slug (например, gpt-5.4) переводят свою запись каталога в visibility: "hide" и исчезают из «голого» списка /v1/models. Переключается для каждой модели на странице Models дашборда.
multiAgentMode?	"v1" | "default" | "v2"	"default"	Трёхпозиционное переопределение multi-agent-поверхности. "v1" принудительно переводит все модели на поверхность v1 (перекрывает вышестоящие привязки); "default" учитывает вышестоящие привязки моделей (sol/terra=v2, luna=v1); "v2" принудительно переводит все модели на v2. Настраивается на странице Models дашборда или через ocx v2 mode.
providerContextCaps?	Record<string,number>	{}	Видимые Codex лимиты контекста по провайдерам. Лимит только понижает известные контекстные окна.
contextCapValue?	number	350000	Значение, используемое элементами управления лимитом контекста в дашборде; его изменение обновляет каждую включённую запись в providerContextCaps.
stallTimeoutSec?	number	300	Секунды без данных от вышестоящей стороны, после которых мост прерывает запрос и генерирует response.incomplete. Минимум 1.
connectTimeoutMs?	number	200000	Дедлайн каждой попытки только для DNS/TCP/TLS и финальных заголовков ответа; он заканчивается до генерации тела ответа.
shutdownTimeoutMs?	number	5000	Дедлайн корректного завершения (drain) перед прерыванием активных ходов.
websockets?	boolean	false	Объявляет supports_websockets, чтобы Codex использовал путь Responses WebSocket. Опустите или установите false, чтобы остаться на HTTP/SSE.
apiKeys?	OcxApiKey[]	[]	Дополнительные сгенерированные учётные данные ocx_…, принимаемые аутентификацией management API и плоскости данных на не-loopback-привязках. Управляются дашбордом; поля записей перечислены ниже.
codexAutoStart?	boolean	true	Разрешает shim Codex выполнять ocx ensure перед запуском Codex. false делает ocx ensure пустой операцией.
codexShimAutoRestore?	boolean	true	Восстанавливает ранее установленный shim после того, как завершённое внешнее обновление Codex заменило его. Для отключения задайте false или установите процессу OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0.
syncResumeHistory?	boolean	true	Обратимый режим совместимости истории Codex App. opencodex резервирует исходные метаданные потоков Codex, переназначает старые интерактивные строки OpenAI на opencodex и временно повышает созданные opencodex строки exec до видимого в приложении источника. ocx stop / ocx restore восстанавливают зарезервированные строки OpenAI и возвращают оставшиеся пользовательские потоки opencodex обратно к OpenAI, чтобы нативный Codex мог возобновлять их после удаления прокси из config.toml. Установите false, чтобы отказаться.
codexAccounts?	CodexAccount[]	[]	Метаданные аккаунтов пула ChatGPT/Codex, управляемые дашбордом Codex Auth. Секреты хранятся отдельно в codex-accounts.json.
pausedCodexAccountIds?	string[]	[]	ID аккаунтов, исключённых из всех будущих выборов Pool до возобновления в Codex Auth. При паузе основного аккаунта включает __main__.
codexAccountNamespaces?	Record<string,string>	—	Необязательное сопоставление публичного namespace селектора модели с сохранённым аккаунтом Codex. <selector>/<native OpenAI model> направляется только в сопоставленный аккаунт; сама настройка не добавляет строки в model picker.
activeCodexAccountId?	string	—	Вручную выбранный аккаунт пула. Выбор очищает существующие привязки потоков и действует со следующего запроса; выполняющиеся запросы сохраняют захваченный аккаунт.
autoSwitchThreshold?	number	80	Порог процента использования для автопереключения новых сессий. Оценка использует самое «горячее» из известных окон квоты — 5-часовое, недельное или 30-дневное. Установите 0, чтобы отключить автопереключение по квоте. Используется стратегией quota и как порог исчерпания для fill-first.
accountPoolStrategy?	"quota" | "round-robin" | "fill-first"	"quota"	Стратегия ротации новых сессий для пула Codex. Применяется только к новым сессиям; существующие id потоков сохраняют affinity. quota (по умолчанию) — выбор наименьшего известного usage, когда активный аккаунт превышает autoSwitchThreshold. round-robin — равномерное распределение между подходящими аккаунтами через smooth weighted selection. fill-first — использовать активный аккаунт до cooldown, недоступности или (если задано) autoSwitchThreshold (неизвестный usage не принуждает к переключению), затем переход к следующему подходящему аккаунту в стабильном отсортированном порядке.
accountPoolStickyLimit?	number	1	Число успешных привязок новых сессий, удерживаемых на одном выборе round-robin перед переходом дальше. Диапазон 1–100; только при accountPoolStrategy = round-robin.
upstreamFailoverThreshold?	number	3	Число подряд идущих временных сбоев вышестоящей стороны, после которого будущие новые сессии переключаются (failover) на другой подходящий аккаунт пула. Установите 0, чтобы отключить переключение по сбоям.
modelCacheTtlMs?	number	300000	Окно свежести кэша /models каждого провайдера (5 минут).
appOwnedMemoryBudgetMb?	number	256	Общий для процесса лимит в МиБ для вытесняемого удерживаемого состояния приложения (журналы, кэши, BLOB-данные и данные продолжения), допустимый диапазон — 64–4096. Это не лимит RSS или нативной памяти среды выполнения.
cacheRetention?	"none" | "short" | "long"	"short"	Политика кэша промптов Anthropic: отключён, эфемерный на 5 минут или расширенный на 1 час.
webSearchSidecar?	OcxWebSearchSidecarConfig	вкл.	Параметры сайдкара веб-поиска (см. ниже).
visionSidecar?	OcxVisionSidecarConfig	вкл.	Параметры vision-сайдкара (см. ниже).
tokenGuardian?	OcxTokenGuardianConfig	выкл.	Необязательная политика проактивного обновления OAuth и прогрева аккаунтов Codex; поля перечислены ниже.
corsAllowOrigins?	string[]	[]	Дополнительные точные origin, разрешённые CORS. Loopback-origin разрешены всегда.

Ключи codexAccountNamespaces — публичные селекторы длиной 1–64 символа. Они должны начинаться и заканчиваться ASCII-буквой или цифрой; внутри разрешены буквы, цифры, ., _ и -. Зарезервированные имена объектов JavaScript запрещены. Значение — допустимый id аккаунта пула (кроме внутреннего __main__) либо "@main" для аккаунта Codex Desktop. Коллизии с provider и зарезервированными openai / combo проверяются без учёта регистра; namespace-префикс namespaced combo alias не может повторять селектор. Настроенные id пула и цели других селекторов также нельзя повторно использовать как селектор. Сохраняйте raw id аккаунтов и email приватными, а селектор используйте как публичное имя. Запрос вроде side/gpt-5.6-sol использует только аккаунт, сопоставленный с side, даже когда openai работает в режиме Direct, и отправляет вышестоящей стороне gpt-5.6-sol. Если целевой аккаунт недоступен, запрос завершается ошибкой без переключения на другой аккаунт и без изменения active Pool account. Голые нативные модели сохраняют обычную маршрутизацию Pool / Direct. Само сопоставление не создаёт записи model picker.

maxConcurrentThreadsPerSession — это camelCase-поле, используемое PUT /api/v2, а не ключ config.json. ocx v2 threads <n> сохраняет соответствующее значение max_concurrent_threads_per_session в [features.multi_agent_v2] в $CODEX_HOME/config.toml Codex; сначала включите v2, чтобы эта таблица существовала.

Если более старая сборка времён разработки уже выполнила syncResumeHistory до появления поддержки резервных копий, то же восстановление нативного провайдера можно принудительно выполнить командой ocx recover-history --legacy-openai.

:::note[Пул аккаунтов Codex] Используйте страницу Codex Auth дашборда для добавления аккаунтов пула и обновления квот. Конфигурация хранит только несекретные метаданные аккаунтов; access- и refresh-токены хранятся в защищённом хранилище учётных данных аккаунтов Codex. Существующие id потоков сохраняют привязку к аккаунту; новые сессии маршрутизируются по accountPoolStrategy, квоте, cooldown и работоспособности. Приостановленный аккаунт и его метаданные квоты остаются видимыми, но исключаются из автоматического переключения, повторов/failover, проб восстановления cooldown и ручной активации. Пауза также очищает карту affinity потоков этого аккаунта: выполняющиеся запросы сохраняют захваченные учётные данные, но последующие ходы перемаршрутизируются и не могут повторно использовать приостановленный аккаунт. Состояние сохраняется после перезапуска; если приостановлены все аккаунты, маршрутизация Pool завершается ошибкой, а не выбирает аккаунт скрытно. Приостановить исчерпанные сначала обновляет только подходящие аккаунты с доступными учётными данными и приостанавливает только те, для которых актуальное окно квоты в этом ответе подтверждено на уровне 100%. Аккаунты без учётных данных, с неизвестной квотой или неудачным обновлением не меняются.

Стратегии ротации (только новые сессии; привязанные потоки не меняются): quota (по умолчанию) — выбор наименьшего usage при превышении autoSwitchThreshold; round-robin — равномерное распределение, accountPoolStickyLimit (по умолчанию 1, 1–100) задаёт число успешных bind на один выбор; fill-first — исчерпание активного аккаунта (cooldown, reauth или threshold; неизвестный usage не принуждает к переключению), затем переход к следующему. Ротация не защищает от enforcement провайдера — использование нескольких аккаунтов может нарушать ToS. :::

claudeCode (OcxClaudeCodeConfig)

Входящие настройки Claude Code, используемые поверхностью /v1/messages, лаунчером ocx claude и страницей Claude в GUI. Ограничения тела нативного passthrough (добавлены вместе с защитой body-occupancy):

Key	Type	Default	Description
claudeCode.bodyStallSec?	number	90	Бюджет неактивности тела нативного passthrough в секундах — тишина по сырым байтам от вышестоящей стороны, пока ожидается чтение, а не общая длительность. Минимум 1. Ровно 0 отключает.
claudeCode.bodyMaxBytes?	number	67108864	Ограничение суммарного размера тела нативного passthrough в байтах (потоковый SSE и буферизованный непотоковый ответ). Ровно 0 отключает.
claudeCode.subagentEffort?	"low" | "medium" | "high" | "xhigh" | "max"	не задано (наследуется)	Уровень effort, записываемый во все сгенерированные определения ~/.claude/agents/ocx-*.md. Если значение не задано, subagent наследует effort родительской сессии Claude Code. Это поле управляет frontmatter пользовательского агента Claude Code и не связано с Codex injectionEffort или ограничениями effort на стороне proxy. После изменения запустите через ocx claude, чтобы пересоздать определения.

Управляемые формы записей

Записи apiKeys[] содержат id: string, name: string, сгенерированный key: string и ISO-строку createdAt: string. Записи codexAccounts[] содержат обязательные поля id, email и isMain, а также необязательные строки plan, chatgptAccountId и безопасный для приватности logLabel. Обычно эти записи управляются дашбордом.

tokenGuardian (OcxTokenGuardianConfig)

Field	Type	Default	Meaning
enabled?	boolean	false	Глобальный переключатель проактивного обновления.
tickSeconds?	number	21600	Интервал обхода (6 часов, минимум 60 секунд).
jitterSeconds?	number	300	Случайная задержка, добавляемая перед обходом.
concurrency?	number	3	Максимум одновременных обновлений за один обход.
leadSeconds?	number	900	Дополнительный запас времени обновления сверх одного тика.
failureBackoffBaseSeconds?	number	300	Начальный backoff при временном сбое.
failureBackoffMaxSeconds?	number	3600	Потолок backoff и задержка при постоянном сбое.
codexWarmupEnabled?	boolean	false	Согласие (opt-in) на синтетическую проверку аккаунтов пула Codex.
codexWarmupMaxAgeSeconds?	number	691200	Повторная проверка аккаунта через 8 дней.
codexWarmupModel?	string	gpt-5.4-mini	Нативная модель для необязательного прогрева.

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

По умолчанию opencodex привязывается к 127.0.0.1 (только loopback). Когда hostname установлен в не-loopback-адрес, такой как 0.0.0.0, opencodex принудительно включает токенную аутентификацию и для management API (/api/*), и для плоскости данных (/v1/responses).

Установите переменную окружения OPENCODEX_API_AUTH_TOKEN перед запуском:

export OPENCODEX_API_AUTH_TOKEN="your-secret-token"
ocx start

Без этой переменной прокси отказывается запускаться при привязке за пределами loopback. Если вы устанавливаете фоновый сервис для доступа по LAN, экспортируйте ту же переменную перед ocx service install, чтобы её получил launchd, systemd или Task Scheduler. Клиенты должны включать токен в каждый запрос через заголовок x-opencodex-api-key:

x-opencodex-api-key: your-secret-token

Какие заголовки подходят, зависит от эндпоинта. Всегда работает только x-opencodex-api-key:

Эндпоинт	Authorization: Bearer	x-opencodex-api-key	x-api-key
/v1/responses	не принимается	обязателен	не принимается
/v1/chat/completions	не принимается	обязателен	не принимается
/v1/messages	принимается	принимается	принимается
/v1/models	принимается	принимается	принимается

Responses и Chat Completions принимают только выделенный заголовок: Authorization на этих транспортах может принадлежать passthrough Codex Direct, и две области bearer нельзя путать. Вкладка API в дашборде рисует эту же таблицу по данным сервера, поэтому она не разойдётся с кодом.

Сгенерированные в дашборде apiKeys после запуска можно использовать вместо токена из окружения; все кандидаты сравниваются за константное время (timingSafeEqual) для защиты от атак по времени.

:::caution[Доступ по LAN] Привязка к 0.0.0.0 открывает ваш прокси — и все настроенные учётные данные провайдеров — локальной сети. Делайте это только в доверенных сетях и всегда задавайте надёжный OPENCODEX_API_AUTH_TOKEN. :::

Провайдеры (OcxProviderConfig)

Field	Type	Meaning
adapter	string	Одно из openai-chat, openai-responses, anthropic, google, kiro, cursor, azure-openai (или алиас azure).
baseUrl	string	Базовый URL вышестоящего API. Большинство встроенных провайдеров с фиксированными конечными точками игнорируют несовпадающий адрес; новые API-key preset с защитой от коллизий сохраняют назначение старого одноимённого custom provider. См. Фиксированные конечные точки провайдеров.
responsesPath?	string	Необязательный относительный путь ресурса для запросов openai-responses с аутентификацией key. Должен начинаться с / и не содержать схему URL, query или fragment. Если поле опущено, сохраняется прежнее построение URL /v1/responses.
disabled?	boolean	Провайдер остаётся на диске, но исключается из маршрутизации и списков моделей/каталога.
apiKey?	string	API-ключ или ссылка ${ENV_VAR} / $ENV_VAR, разрешаемая в момент запроса.
apiKeyTransport?	"x-api-key" | "bearer"	Способ передачи API-ключа Anthropic. По умолчанию используется нативный x-api-key; для совместимых gateway, требующих Authorization: Bearer <key>, задайте "bearer". Допустимо только для anthropic provider с key-аутентификацией.
apiKeyPool?	ApiKeyPoolEntry[]	Пул из нескольких ключей. apiKey отражает активную запись; каждый элемент содержит id, key, необязательный label и необязательное числовое addedAt.
defaultModel?	string	Модель, используемая при выборе этого провайдера без явной модели.
models?	string[]	Список seed/fallback-моделей. Когда liveModels равен false, обнаруживаются только эти модели.
liveModels?	boolean	Получать живой каталог моделей при старте/синхронизации (по умолчанию true). Встроенные preset могут использовать доверенные URL, query и фильтры из registry; пользовательские provider по умолчанию запрашивают ${baseUrl}/models. Установите false, чтобы использовать только настроенные models.
selectedModels?	string[]	Allowlist каталога, применяемый после обнаружения. Непустой список открывает Codex только эти id; пустой или опущенный открывает все обнаруженные модели.
contextWindow?	number	Видимый Codex лимит контекстного окна на уровне провайдера для маршрутизируемых записей каталога. Живые метаданные ниже этого значения сохраняются.
modelContextWindows?	Record<string,number>	Лимиты контекстного окна для конкретных моделей. Они перекрывают contextWindow для совпадающих id моделей и никогда не повышают меньшие живые метаданные.
modelInputModalities?	Record<string,string[]>	Подсказки каталога о входных модальностях для конкретных моделей, например ["text"] или ["text", "image"].
headers?	Record<string,string>	Дополнительные заголовки для вышестоящей стороны. Authorization, cookie, заголовки API-ключей, встроенные переводы строк и недопустимые имена заголовков отклоняются.
openRouterRouting?	OpenRouterProviderRouting	Настройки маршрутизации провайдеров OpenRouter по умолчанию. Поддерживает order, only и allowFallbacks; действует только с каноническим URL OpenRouter и адаптером openai-chat.
modelOpenRouterRouting?	Record<string,OpenRouterProviderRouting>	Настройки для точных id моделей, заменяющие openRouterRouting.
authMode?	"key" | "forward" | "oauth"	Способ аутентификации (по умолчанию key). См. Провайдеры.
codexAccountMode?	"pool" | "direct"	Только для канонического openai; по умолчанию Pool, если опущено. Direct обходит состояние пула.
refreshPolicy?	"proactive" | "lazy-only" | "disabled"	Переопределение политики Token Guardian для этого OAuth-провайдера.
reasoningEfforts?	string[]	Метки рассуждений Codex на уровне провайдера, которые объявляются и отправляются (low, medium, high, xhigh, max, ultra).
modelReasoningEfforts?	Record<string,string[]>	Метки рассуждений для конкретных моделей. Пустой список скрывает управление уровнем рассуждений для этой модели.
modelSupportsReasoningSummaries?	Record<string,boolean>	Поддержка reasoning summary для отдельных моделей. Значение false отключает объявление summary и удаляет поля summary-delivery перед запросом openai-responses.
modelReasoningSummaryDelivery?	Record<string,"sequential" | "sequential_cutoff" | "concurrent" | "concurrent_cutoff">	Enum доставки Responses для отдельных моделей. Настроенная модель сохраняет поддержку summary, а адаптер меняет только уже существующее stream_options.reasoning_summary_delivery. Нельзя одновременно отключить summary для той же модели.
reasoningEffortMap?	Record<string,string>	Wire-алиасы меток рассуждений на уровне провайдера. Используйте только когда вышестоящая сторона ожидает другое значение.
modelReasoningEffortMap?	Record<string,Record<string,string>>	Wire-алиасы меток рассуждений для конкретных моделей.
noReasoningModels?	string[]	Модели, отклоняющие параметр reasoning/thinking — адаптер удаляет для них reasoning_effort.
noTemperatureModels?	string[]	Модели, отклоняющие заданный вызывающей стороной temperature.
noTopPModels?	string[]	Модели, отклоняющие заданный вызывающей стороной top_p.
noPenaltyModels?	string[]	Модели, отклоняющие штрафы presence/frequency.
parallelToolCalls?	boolean	Включает/отключает параллельные вызовы инструментов. В OpenAI Chat включено по умолчанию; не-chat-адаптеры объявляют поддержку только при явном true.
autoToolChoiceOnlyModels?	string[]	Модели, у которых tool_choice принимает только auto или none; принудительные/именованные выборы понижаются.
preserveReasoningContentModels?	string[]	Модели, требующие сохранять предыдущий assistant reasoning_content в истории чата.
thinkingToggleModels?	string[]	Chat-модели, использующие вендорский переключатель thinking.enabled вместо лестницы уровней рассуждений.
thinkingBudgetModels?	string[]	Chat-модели, использующие целочисленный thinking_budget; уровень отображается в долю бюджета.
noVisionModels?	string[]	Модели только для текста — vision-сайдкар описывает для них изображения. Сопоставление допускает тег Ollama :size.
escapeBuiltinToolNames?	boolean	Anthropic-совместимые шлюзы, такие как Umans, могут требовать экранирования имён инструментов на wire; opencodex убирает префикс перед возвратом вызовов инструментов в Codex.
googleMode?	"ai-studio" | "vertex" | "cloud-code-assist"	Режим транспорта/аутентификации Google. По умолчанию ai-studio.
project?	string	Id проекта Vertex или id проекта Antigravity Cloud Code Assist.
location?	string	Location Vertex; запасной вариант из окружения — GOOGLE_CLOUD_LOCATION.
mcpServers?	Record<string,CursorMcpServerConfig>	Только Cursor. MCP-серверы, запускаемые через stdio или доступные по Streamable HTTP; поля перечислены ниже.
desktopExecutor?	DesktopExecutorConfig	Только Cursor. Внешние команды computer-use/record-screen; поля перечислены ниже.
unsafeAllowNativeLocalExec?	boolean	Только адаптер Cursor. Явно включаемая лазейка для управляемого сервером Cursor локального выполнения read / write / delete / ls / grep / shell / fetch. По умолчанию false, поэтому удалённые сообщения Cursor не могут обойти одобрения и песочницу Codex. См. Провайдер Cursor ниже.

Фиксированные конечные точки провайдеров

Маршрутизация определяет конечную точку провайдера до того, как запрос увидит адаптер. Для большинства встроенных провайдеров адрес из registry имеет приоритет над baseUrl в конфигурации. Настроенный URL сохраняется на этом этапе в четырёх случаях:

• провайдер явно разрешает переопределение — ollama, vllm, lm-studio, litellm, qwen-cloud и alibaba-token-plan-intl;
• конечная точка registry является заполняемым шаблоном, как у azure-openai и cloudflare-ai-gateway;
• новый фиксированный API-key preset защищает коллизию имени: старый одноимённый custom provider, указывающий на другой адрес, сохраняет исходное назначение и не отправляет ключ новому host из registry;
• провайдер определён пользователем и отсутствует в registry.

После этого адаптер всё ещё может изменить разрешённый URL. Например, адаптер kiro использует API-регион импортированных учётных данных для канонического host runtime.{region}.kiro.dev. Правила для каждого адаптера описаны в разделе Адаптеры.

Если маршрутизация отбрасывает настроенный baseUrl, opencodex выводит предупреждение. Адрес registry показывается полностью, а настроенный адрес только как origin; путь скрывается, поскольку он может содержать данные учётных записей. Удалите неиспользуемый baseUrl либо выберите provider, чья конечная точка соответствует нужному URL. Для региональных сервисов используйте правильную запись: alibaba-token-plan закреплён за Пекином, а alibaba-token-plan-intl допускает международную конечную точку.

Провайдер Cursor (adapter: "cursor")

Мост Cursor экспериментален. После ocx login cursor добавьте или отредактируйте запись cursor в providers в ~/.opencodex/config.json (Windows: %USERPROFILE%\.opencodex\config.json).

По умолчанию управляемые сервером Cursor нативные локальные инструменты остаются отключёнными. Codex продолжает использовать собственные инструменты (apply_patch, exec_command и так далее) с политикой одобрений и песочницы. Устанавливайте unsafeAllowNativeLocalExec только для доверенных локальных экспериментов, в которых вы согласны с тем, что Cursor может читать, писать, удалять, выводить списки, выполнять grep, shell или fetch на вашей машине без пути одобрения Codex.

{
  "providers": {
    "cursor": {
      "adapter": "cursor",
      "baseUrl": "https://api2.cursor.sh",
      "authMode": "oauth",
      "defaultModel": "auto",
      "unsafeAllowNativeLocalExec": true
    }
  }
}

Флаг относится к объекту провайдера (providers.cursor), а не к верхнему уровню config.json.

Его также можно установить из веб-дашборда: Providers → Cursor → Edit JSON, добавьте "unsafeAllowNativeLocalExec": true, сохраните, затем перезапустите прокси (ocx restart или ocx stop + ocx start).

MCP, запись экрана и computer-use используют отдельную конфигурацию mcpServers / desktopExecutor и этим флагом не управляются.

Записи интеграций Cursor

Каждое значение mcpServers.<name> принимает либо command (stdio), либо url (Streamable HTTP). Stdio-записи также принимают args?: string[], env?: Record<string,string> и cwd?: string; HTTP-записи принимают headers?: Record<string,string>. Обе формы поддерживают enabled?: boolean (по умолчанию true) и toolPrefix?: string.

desktopExecutor принимает computerUseCommand?, recordScreenCommand?, cwd?, env?: Record<string,string> и timeoutMs? (по умолчанию 30000). Команды выполняются через sh -c, читают один JSON-запрос из stdin и должны записать один JSON-результат в stdout.

:::caution[Безопасность] Оставляйте unsafeAllowNativeLocalExec незаданным или равным false, если только вам явно не нужно нативное локальное выполнение Cursor, обходящее семантику одобрений и песочницы Codex. :::

Маршрутизация провайдеров OpenRouter

Для одной модели разные endpoints OpenRouter могут заметно отличаться поддержкой prompt cache, долей попаданий, сроком хранения и ценой. openRouterRouting задаёт провайдеров по умолчанию, а modelOpenRouterRouting заменяет настройки для точного id модели. Конфигурация преобразуется в поля запроса OpenRouter order, only и allow_fallbacks. При allowFallbacks: false запрос завершается ошибкой, если указанные провайдеры недоступны, вместо перехода на другой endpoint.

{
  "openRouterRouting": { "order": ["deepseek"], "allowFallbacks": false },
  "modelOpenRouterRouting": {
    "anthropic/claude-sonnet-5": { "only": ["anthropic"], "allowFallbacks": false }
  }
}

Статические allowlist моделей

Некоторые провайдеры отдают очень большие или медленные живые каталоги моделей. Установите liveModels в false, когда хотите, чтобы Codex видел только модели, закреплённые в models:

Когда liveModels равен false, а models пуст или опущен, opencodex не открывает для этого провайдера ни одной маршрутизируемой модели.

Живой discovery отклоняет ответ до кэширования, если он превышает 4 MiB или 2 000 исходных строк моделей. Встроенный preset может снизить эти лимиты и отфильтровать смешанный каталог до chat-моделей. Слишком большой или повреждённый ответ использует обычный stale/static fallback, а неподходящие строки исключаются. Корректный ответ без подходящих строк остаётся авторитетным пустым каталогом; ответ сверх лимита никогда не обрезается молча.

selectedModels служит другой цели: обнаружение по-прежнему выполняется, но в каталог Codex и /v1/models публикуются только выбранные id. Полный список моделей в дашборде остаётся доступным, поэтому allowlist можно изменить позже.

Preview-записи GPT-5.6 fallback используют тот же механизм. Пресет OpenAI по API-ключу задаёт базовые и Pro id с контекстом 1050000 и максимальным вводом 922000; пресет OpenRouter задаёт openai/gpt-5.6-sol, openai/gpt-5.6-terra и openai/gpt-5.6-luna с контекстом 1050000. Контракт каталога Codex для Pool/Direct — 372000, а синхронизированный каталог Codex объявляет reasoning max, сохраняя xhigh отдельной меткой. Оставьте liveModels включённым, чтобы объединить живые результаты провайдера с этими явными дополнениями, или установите false, чтобы открыть только models.

{
  "providers": {
    "openrouter": {
      "adapter": "openai-chat",
      "baseUrl": "https://openrouter.ai/api/v1",
      "apiKey": "${OPENROUTER_API_KEY}",
      "liveModels": false,
      "models": ["deepseek/deepseek-v4-flash", "qwen/qwen3-coder-plus"]
    }
  }
}

Сайдкары

webSearchSidecar (OcxWebSearchSidecarConfig)

Field	Type	Default	Meaning
enabled?	boolean	вкл., когда выбранный бэкенд доступен	Главный переключатель. Установите false, чтобы отключить сайдкары веб-поиска.
backend?	"openai" | "anthropic"	авто	Бэкенд-исполнитель. Явная настройка имеет приоритет; когда опущено, пригодный сохранённый OAuth-аккаунт Anthropic выбирает anthropic, иначе openai.
model?	string	зависит от бэкенда	Модель поиска: gpt-5.6-luna для openai, claude-sonnet-5 для anthropic. Явно заданные устаревшие значения gpt-5.4-mini мигрируются при запуске.
reasoning?	string	low	Уровень рассуждений сайдкара (minimal с веб-поиском отклоняется).
maxSearchesPerTurn?	number	3	Общее число реальных поисков за один ход основной модели (защита от зацикливания).
routedModelStallTimeoutMs?	number	200000	Задаваемый только в файле конфигурации дедлайн непрерывной неактивности по сырым байтам ответа для каждой итерации маршрутизируемой модели. Должен быть целым числом от 1 до 2147483647; каждый непустой фрагмент тела ответа его сбрасывает.
timeoutMs?	number	200000	Отдельный дедлайн для одного hosted-запроса веб-поиска.

Бэкенд openai выполняет hosted-поиск через включённого ChatGPT-провайдера forward, поэтому ему нужны и вход в ChatGPT, и этот провайдер. При маршрутизируемых повторных вызовах, пришедших со стороны Claude, opencodex внедряет основную аутентификацию ChatGPT во внутренний запрос сайдкара, чтобы этот путь оставался достижимым. Бэкенд anthropic использует активные сохранённые учётные данные включённого OAuth-провайдера Anthropic и запускает инструмент Claude web_search_20250305. Если backend: "anthropic" задан явно, но ни один активный аккаунт не пригоден (включая needsReauth), сайдкар завершается отказом, а не откатывается на OpenAI.

У пути веб-поиска четыре таймера: базовый бюджет простоя событий моста (stallTimeoutSec), бюджет DNS/TCP/TLS/финальных заголовков (connectTimeoutMs), неактивность по сырым байтам маршрутизируемой модели (routedModelStallTimeoutMs) и один hosted-поиск (timeoutMs). Эффективный сторожевой таймер моста равен max(базовый stall, connect timeout, stall маршрутизируемой модели, timeout сайдкара) + 30 секунд. Stall маршрутизируемой модели — это страж неактивности, а не общий таймаут генерации.

visionSidecar (OcxVisionSidecarConfig)

Field	Type	Default	Meaning
enabled?	boolean	вкл., когда выбранный бэкенд доступен	Главный переключатель. Установите false, чтобы отключить описания изображений.
backend?	"openai" | "anthropic"	авто	Бэкенд-исполнитель. Использует то же разрешение, что и веб-поиск: приоритет явной настройки с учётом учётных данных Anthropic.
model?	string	зависит от бэкенда	Модель описания изображений: gpt-5.4-mini для openai, claude-sonnet-5 для anthropic.
maxDescriptionsPerTurn?	number	8	Максимум новых промахов кэша описаний, допускаемых за один ход основной модели. 0 отключает вызовы описаний; недопустимые значения используют значение по умолчанию.
timeoutMs?	number	45000	Таймаут fetch сайдкара.

Vision активируется только для изображений, отправленных модели, совпавшей со списком noVisionModels её провайдера. Бэкенд OpenAI имеет те же требования к входу и forward-провайдеру, что и веб-поиск; бэкенд Anthropic использует сохранённый OAuth и завершается отказом, когда выбран явно без пригодных учётных данных. Успешные описания data:-изображений кэшируются в ограниченном по размеру кэше уровня процесса с ключом из бэкенда, модели, detail, байтов изображения и нормализованного контекста сообщения. Попадания в кэш и дубликаты в том же ходе не расходуют maxDescriptionsPerTurn. Удалённые https:-изображения и неудачные/пустые описания не кэшируются.

Запросы поиска и описания изображений через Anthropic OAuth переиспользуют существующий в opencodex отпечаток (fingerprint) Claude Code OAuth. Это в рамках существующего OAuth-прецедента репозитория, но стоит провести soak-тестирование с целевым аккаунтом и рабочей нагрузкой.

Полный пример

{
  "port": 10100,
  "defaultProvider": "openai",
  "providers": {
    "openai": {
      "adapter": "openai-responses",
      "baseUrl": "https://chatgpt.com/backend-api/codex",
      "authMode": "forward"
    },
    "anthropic": {
      "adapter": "anthropic",
      "baseUrl": "https://api.anthropic.com",
      "authMode": "oauth",
      "defaultModel": "claude-sonnet-4-6"
    },
    "ollama-cloud": {
      "adapter": "openai-chat",
      "baseUrl": "https://ollama.com/v1",
      "apiKey": "${OLLAMA_API_KEY}",
      "defaultModel": "glm-5.2",
      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-pro"]
    }
  },
  "subagentModels": ["anthropic/claude-opus-5", "ollama-cloud/glm-5.2"],
  "disabledModels": [],
  "websockets": false,
  "webSearchSidecar": {
    "maxSearchesPerTurn": 3,
    "routedModelStallTimeoutMs": 200000,
    "timeoutMs": 200000
  },
  "visionSidecar": { "enabled": true }
}

:::tip[Секреты] Предпочитайте ссылки ${ENV_VAR} для ключей, чтобы в config.json не оставалось секретов. OAuth- и forward-провайдеры вообще не хранят ключ. :::

:::note[Атомарная запись] Все файлы конфигурации и каталога (config.toml, opencodex-catalog.json) записываются атомарно через atomicWriteFile (временный файл + переименование). Это предотвращает наполовину записанные файлы, когда конкурирующие писатели — например, ocx stop и собственный обработчик завершения прокси — восстанавливают Codex одновременно. :::