Справочник конфигурации

opencodex хранит постоянную конфигурацию в $OPENCODEX_HOME/config.json, обычно в ~/.opencodex/config.json. На Windows путь по умолчанию — %USERPROFILE%\.opencodex\config.json.

Способы редактировать конфигурацию

Выберите канал редактирования под задачу:

Dashboard: используйте web UI для пошаговой настройки провайдеров, моделей, агентов, доступа и хранилища.
CLI: ocx init создаёт исходный файл, а команды вроде ocx provider, ocx models, ocx combo, ocx agent и ocx config обновляют или показывают принадлежащие им настройки.
File: редактируйте config.json напрямую для полей, у которых нет отдельной UI- или CLI-команды. Файл должен оставаться корректным JSON.

Dashboard, management API и mutating-команды CLI записывают в один и тот же файл. Предпочитайте эти каналы либо останавливайте прокси перед ручным редактированием. Запущенный процесс держит конфигурацию в памяти, поэтому более позднее сохранение «наживую» может перезаписать несвязанные ручные изменения своим снимком. Живые сохранения умеют merge’ить внешние правки полей claudeCode и listener binding там, где для этих путей есть явная защита конфликтов, но эта защита покрывает не все поддеревья.

Если файл не удаётся распарсить, opencodex сохраняет его резервную копию как config.json.invalid-<timestamp>, пишет предупреждение в консоль и стартует с настройками по умолчанию. Если файла нет, используется тот же свежий дефолт: один forward-провайдер openai.

Приоритет и значения по умолчанию

Корректные значения из config.json перекрывают встроенные дефолты. Для отсутствующих необязательных полей применяются значения по умолчанию, описанные на страницах соответствующих доменов. OPENCODEX_HOME имеет приоритет над каталогом конфигурации по умолчанию. Поля, которые принимают ссылку на окружение, например apiKey: "${PROVIDER_API_KEY}", разрешают эту переменную в момент запроса. Для outbound-proxying уже заданные HTTP_PROXY или HTTPS_PROXY имеют приоритет над верхнеуровневым полем proxy.

Для routing действует собственный упорядоченный набор правил разрешения; см. Routing.

Домены конфигурации

Providers — записи провайдеров, аутентификация, endpoint’ы, каталоги, allowlist’ы, лимиты контекста, квоты и provider-specific параметры.
Routing — defaultProvider, порядок разрешения моделей, combo, alias и значения combo effort по умолчанию.
Agents — multi-agent mode, guidance при делегировании, fallback-модели, синхронизация нативных default’ов и effort cap’ы.
Server and runtime — listener и удалённый доступ, admission key, таймауты, storage, sidecar’ы, startup behavior и shadow call’ы.

Не храните секреты в файле

Для API-ключей предпочитайте ссылки ${ENV_VAR}. Буквальные значения apiKey, apiKeyPool[].key и apiKeys[].key — это секреты; не коммитьте их, не вставляйте в логи и не делитесь ими. OAuth-токены и forward-provider токены хранятся в отдельных credential store, а не в config.json. Идентификаторы аккаунтов и email тоже должны оставаться приватными; где возможно, используйте публичные alias для селекторов.