Справочник CLI

CLI opencodex — это ocx. Запустите ocx help (или --help / -h) для общей справки по использованию. Для команд, зарегистрированных в таблице справки, используйте ocx help <command>. Команды справки и версии доступны только для чтения и не запускают, не останавливают, не устанавливают, не удаляют и не переписывают состояние Codex/opencodex.

Настройка и жизненный цикл

`ocx init`

Интерактивный мастер настройки. Запрашивает провайдера (пресет или пользовательский), API-ключ (литерал или ${ENV}), модель по умолчанию и порт прокси; сохраняет ~/.opencodex/config.json; по желанию внедряет прокси в $CODEX_HOME/config.toml (по умолчанию ~/.codex/config.toml); и по желанию устанавливает shim автозапуска Codex.

`ocx start [--port <port>]`

Запускает прокси-сервер (предпочтительный порт 10100). Если этот порт занят, opencodex выбирает и записывает другой свободный порт. Команда сохраняет состояние PID/runtime-порта и отказывается запускать второй живой экземпляр. При старте она синхронизирует модели каждого провайдера в каталог Codex. При завершении она восстанавливает нативный Codex — если только прокси не был запущен как управляемый сервис (OCX_SERVICE=1).

ocx start
ocx start --port 8080

`ocx stop`

Останавливает работающий прокси (по PID), удаляет PID-файл и восстанавливает нативный Codex. Если установлен управляемый фоновый сервис, ocx stop сначала останавливает и его (чтобы он не перезапустил прокси). То же действие доступно по кнопке Stop веб-дашборда (POST /api/stop).

`ocx restore` · `ocx eject`

Восстанавливает нативный Codex без остановки прокси — удаляет внедрённые строки конфигурации и маршрутизируемые записи каталога, чтобы обычный codex снова работал нативно. eject — алиас restore.

Добавьте back к любому из вариантов написания, чтобы снова направить обычный codex на уже работающий прокси, не меняя жизненный цикл прокси:

ocx restore back
ocx eject back

`ocx recover-history --legacy-openai`

Явное восстановление для старых сборок времён разработки, которые переназначали историю Codex App до появления поддержки обратимых резервных копий. Если база данных истории заблокирована, сначала закройте Codex.

`ocx restart`

Выполняет stop, затем ensure: останавливает прокси/сервис, восстанавливает нативный Codex, запускает прокси в фоне и синхронизирует фактический порт обратно в Codex.

`ocx ensure`

Идемпотентно гарантирует, что фоновый прокси запущен, затем синхронизирует его живой каталог моделей. Если codexAutoStart равен false, команда сообщает, что автозапуск отключён, и ничего не делает.

`ocx status [--json]`

Печатает диагностическую сводку только для чтения: PID прокси, доступность /healthz, URL дашборда, путь к конфигурации, провайдера по умолчанию, настройку автозапуска Codex, состояние сервиса и состояние shim.

Используйте --json для машиночитаемого диагностического контракта только для чтения:

ocx status --json

Сокращённый пример структуры:

{
  "schemaVersion": 1,
  "proxy": {
    "running": false,
    "pid": null,
    "health": {
      "ok": false,
      "url": "http://127.0.0.1:10100/healthz",
      "message": "unreachable"
    }
  },
  "dashboard": {
    "url": "http://localhost:10100/"
  },
  "paths": {
    "config": "/Users/example/.opencodex/config.json",
    "pid": "/Users/example/.opencodex/ocx.pid",
    "runtime": "/path/to/bun"
  },
  "runtime": {
    "source": "bundled"
  },
  "codexAutostart": true,
  "defaultProvider": "openai",
  "service": {
    "summary": "not installed (logs: /Users/example/.opencodex/service.log)"
  },
  "codexShim": {
    "summary": "Codex autostart shim: not installed"
  }
}

Реальный объект также включает listen (порт, имя хоста, источник runtime/конфигурации), диагностику загрузки конфигурации и диагностику встроенного плагина Codex. JSON-схема допускает только добавления: будущие версии могут вводить новые поля, но существующие поля должны оставаться стабильными. Она намеренно исключает API-ключи, OAuth-токены, заголовки authorization, содержимое запросов, адреса электронной почты и идентификаторы аккаунтов.

`ocx health [--json]`

Проверяет идентичность работающего прокси. Человекочитаемый вывод сообщает PID/порт; --json выдаёт {ok, pid, port}. Команда завершается с кодом 0 только когда прокси здоров, и с кодом 1 в остальных случаях, что делает её пригодной для сервисных проб.

`ocx uninstall` · `ocx remove`

Останавливает сервис и прокси, удаляет сервис и shim Codex, восстанавливает нативный Codex, затем удаляет локальную конфигурацию opencodex только если все шаги восстановления завершились успешно. remove — алиас uninstall.

Модели и Codex

`ocx sync`

Получает живой список моделей от каждого настроенного провайдера и заново внедряет объединённый каталог в Codex. Запускайте после добавления провайдера или для обновления списка доступных моделей.

`ocx sync-cache`

Инвалидирует локальный кэш селектора моделей Codex, чтобы он был перестроен из активного каталога opencodex.

`ocx v2 [subcommand]`

Управляет флагом функции Codex multi_agent_v2 и трёхпозиционным режимом multi-agent surface.

Subcommand	Action
`status` (по умолчанию)	Сообщает текущий флаг v2, режим multi-agent и параллелизм потоков.
`on`	Включает функцию `multi_agent_v2` в `$CODEX_HOME/config.toml` и повторно синхронизирует каталог.
`off`	Отключает функцию `multi_agent_v2` и повторно синхронизирует каталог.
`mode v1`	Принудительно переводит ВСЕ модели на v1, отключает нативный v2 и сохраняет лимит потоков в `[agents] max_threads`.
`mode default`	Учитывает вышестоящие привязки моделей (sol/terra=v2, luna=v1, остальные=флаг codex). Значение по умолчанию при установке.
`mode v2`	Принудительно переводит ВСЕ модели на v2, включает нативный v2 и переносит тот же лимит потоков в ключ v2.
`threads <n>`	Устанавливает активный лимит потоков v1/v2 (целое число >= 1).

ocx v2 status
ocx v2 mode v1
ocx v2 mode default
ocx v2 on
ocx v2 threads 16

Подкоманда mode записывает multiAgentMode в конфигурацию opencodex и повторно синхронизирует каталог Codex. mode v1/mode v2 и on/off переносят текущий числовой лимит потоков между действительными ключами Codex v1/v2, переключая нативную функцию через codex features enable|disable. Неудачный переход восстанавливает исходный config.toml. Изменения применяются к новым сессиям Codex; работающие сессии сохраняют закреплённую за ними поверхность.

`ocx models [--provider <name>] [--json]`

Перечисляет модели, статически заданные в настроенных провайдерах. --provider фильтрует одного настроенного провайдера, а --json возвращает метаданные моделей плюс напоминание о том, что liveModels может добавлять записи, существующие только во время выполнения. Эта команда не запрашивает живые каталоги; для этого используйте ocx sync или дашборд.

`ocx provider <subcommand>`

Неинтерактивное управление провайдерами. Записи реестра задаются по имени; для пользовательского имени требуются и --adapter, и --base-url.

Subcommand	Supported flags	Action
`list`	`--json`	Перечисляет настроенных провайдеров и оставшиеся записи реестра.
`add <name>`	`--adapter <adapter>`, `--base-url <url>`, `--api-key <key>`, `--default-model <model>`, `--set-default`, `--force`, `--json`, `--sync`	Добавляет провайдера из реестра или пользовательского. `--force` перезаписывает; `--sync` обновляет работающий прокси в режиме человекочитаемого вывода.
`show <name>`	`--json`	Показывает конфигурацию с замаскированными API-ключами.
`remove <name>`	`--json`	Удаляет провайдера, не являющегося провайдером по умолчанию; последнего провайдера удалить нельзя.
`set-default <name>`	`--json`	Выбирает существующего провайдера в качестве провайдера по умолчанию.

ocx provider list --json
ocx provider add anthropic --api-key sk-ant-... --set-default --sync
ocx provider add local-dev --adapter openai-chat --base-url http://localhost:11434/v1
ocx provider show anthropic --json
ocx models --provider anthropic --json

`ocx account <subcommand>`

Перечисляет и переключает аккаунты провайдеров и пулы API-ключей через работающий прокси. Поставляемая справка выглядит так:

Usage: ocx account <list|current|use|refresh|auto-switch|remove|add-key> ...

List and switch provider accounts and API-key pools (GUI parity).

list [provider]     Codex account pool, OAuth accounts and API keys (identifiers shown masked as the API returns them).
current <provider>  Show the active account or key.
use <provider> <id> Switch the active credential; 'main' selects the Codex App login.
refresh <provider>  Force-refresh Codex or provider quota reports.
auto-switch <provider> <on|off|status|threshold N>  Control the Codex pool threshold.
remove <provider> <id> --yes  Remove a stored account or key after an existence check.
add-key <provider> [--label <label>]  Add a key read only from piped stdin.
Codex pool switches apply to new sessions; running threads keep their account.

Все подкоманды требуют работающего прокси; CLI автоматически определяет записанный runtime-порт. Успешные операции завершаются с кодом 0. Неверное использование, неизвестный провайдер или id аккаунта/ключа, недоступный прокси и ошибка API завершаются с кодом 1. Поля учётных данных отображаются ровно так, как их возвращает management API (включая его маскирование); API-ключи и OAuth-токены в открытом виде никогда не возвращаются. Отображаемые для удобства значения синтезируются на стороне клиента, так же как в дашборде: main — это CLI-алиас входа Codex App в пуле аккаунтов openai, OAuth-аккаунты без email отображаются как Account N, а столбец plan/label по цепочке фолбэков использует план, замаскированный email, метку и замаскированный ключ.

Строки аккаунтов в --json используют общую структуру (необязательные поля опускаются, когда данные недоступны):

{
  "provider": "openai",
  "type": "codex | oauth | api-key",
  "id": "__main__",
  "label": "plus",
  "email": "m***@example.com",
  "plan": "plus",
  "masked": "sk-ab****wxyz",
  "active": true,
  "needsReauth": false,
  "quota": null
}

`ocx account list [provider] [--json] [--all]`

Без указания провайдера перечисляет пул Codex, OAuth-аккаунты и настроенные пулы API-ключей. Пустые провайдеры пропускаются, если не передан --all. С указанным провайдером перечисляет только это семейство учётных данных. Человекочитаемый вывод использует столбцы PROVIDER TYPE ID PLAN/LABEL STATUS; закреплённая строка Codex помечается как next session. Если существует сохранённый аккаунт Kiro, вывод отмечает, что у Kiro один слот входа и что повторный вход заменяет текущий аккаунт. Пустой результат — по-прежнему успех. --json возвращает:

{ accounts: AccountRow[], notes: string[] }

`ocx account current <provider> [--json]`

Показывает активный аккаунт или ключ. Пул Codex без ручного закрепления сообщает об автоматическом выборе аккаунта с наименьшим использованием; другое семейство без активных учётных данных сообщает об этом состоянии и всё равно завершается с кодом 0. --json возвращает:

{ provider, type, activeId: string | null, autoSwitchThreshold?: number, account: AccountRow | null }

`ocx account use <provider> <account-or-key-id|main> [--json]`

Выбирает существующий аккаунт Codex, OAuth-аккаунт или API-ключ. Для openai значение main выбирает вход Codex App. Выбор для Codex применяется только к новым сессиям; существующие потоки сохраняют свой аккаунт, а включённый порог автопереключения может позже переопределить ручное закрепление. Неизвестные провайдеры или id завершаются с кодом 1. --json возвращает:

{ ok: true, provider, type, activeId }

`ocx account refresh <provider> [--json]`

Для пула Codex используйте ocx account refresh openai [--json]. Команда принудительно обновляет квоты аккаунтов и печатает доступные недельные/месячные проценты и время сброса; отсутствующие данные о квоте сообщаются как неизвестные, а не как 0%. JSON-обёртка команды — { accounts: AccountRow[] } с полем quota в каждой строке Codex.

Для OAuth-провайдеров и провайдеров с API-ключами команда принудительно обновляет конечную точку отчёта о квотах провайдера; это не повторный вход по токену и не простое перечитывание списка аккаунтов. --json возвращает { provider, report: ProviderQuotaReport | null }. Провайдер без поддерживаемого отчёта о квотах печатает no quota report available for <provider> и завершается с кодом 0. Неизвестные провайдеры и ошибки management API завершаются с кодом 1; неудачная или истёкшая по времени вышестоящая проверка квоты вместо этого деградирует до null-отчёта или устаревшего отчёта (код 0), как и полосы квот в дашборде.

`ocx account auto-switch <provider> <on|off|status|threshold <0-100>> [--json]`

Управляет только пулом аккаунтов Codex openai. on устанавливает 80%, off устанавливает 0%, status читает текущее значение, а threshold <n> принимает целое число от 0 до 100. Другие провайдеры и недопустимые значения завершаются с кодом 1. --json возвращает:

{ provider, autoSwitchThreshold: number, enabled: boolean }

`ocx account remove <provider> <id|main> --yes [--json]`

Это защищённое неинтерактивное удаление требует --yes. Перед удалением команда проверяет, что id существует; отсутствующий id завершается с кодом 1 без отправки DELETE. Основной вход Codex App удалить нельзя, поэтому remove openai main --yes отклоняется. После удаления семейство читается заново: удаление закреплённого аккаунта Codex снимает закрепление и возвращает автоматический выбор; OAuth делает активным первый оставшийся аккаунт или сообщает, что аккаунтов не осталось; пулы API-ключей делают активным первый оставшийся ключ или сообщают, что ключей не осталось. Структуры --json для успеха и ошибки:

{ ok: true, provider, id, removedActive: boolean, promotedActiveId: string | null }
{ error: string } // stderr, exit 1

`ocx account add-key <provider> [--label <label>] [--json]`

Добавляет и активирует ключ для провайдера с API-ключами. Ключ читается только из неинтерактивного (не-TTY) stdin — через конвейер или перенаправление; интерактивный ввод в TTY, пустой ввод, провайдеры OAuth/Codex и ошибки API завершаются с кодом 1. Ключ никогда не выводится на экран, в том числе когда он встречается внутри метки. Предпочитайте менеджер секретов или here-string:

ocx account add-key openrouter --label personal <<< "$OPENROUTER_API_KEY"
security find-generic-password -w openrouter | ocx account add-key openrouter --json

--json возвращает { ok: true, id: string | null, label?: string } и никогда не включает ключ.

Аутентификация

`ocx login <provider>`

Запускает зарегистрированный процесс входа провайдера. OAuth-провайдеры открывают браузер и сохраняют автоматически обновляемые учётные данные в ~/.opencodex/; провайдеры со входом по API-ключу открывают свой дашборд ключей, запрашивают ключ, по возможности валидируют его и сохраняют полученную конфигурацию провайдера. Если имя отсутствует или неизвестно, команда печатает принимаемые в данный момент id OAuth-провайдеров и провайдеров с API-ключами.

ocx login xai

`ocx logout <provider>`

Удаляет сохранённые OAuth-учётные данные провайдера.

Дашборд

`ocx gui`

Открывает веб-дашборд по адресу http://localhost:<port>, автоматически запуская прокси, если он не работает.

Фоновый сервис

`ocx service [subcommand]`

Запускает opencodex как фоновый сервис, управляемый при входе в систему (macOS launchd, Linux systemd user unit, Windows Task Scheduler), который автоматически стартует при входе и автоматически перезапускается при сбое. Запуски сервиса устанавливают OCX_SERVICE=1, поэтому перезапуск не перетряхивает конфигурацию Codex.

Subcommand	Action
нет	Создаёт/обновляет и запускает сервис.
`install`	Создаёт и запускает сервис.
`start`	Запускает установленный сервис.
`stop`	Останавливает сервис и восстанавливает нативный Codex.
`status`	Сообщает, работает ли сервис.
`uninstall`	Удаляет сервис и восстанавливает нативный Codex.
`remove`	Алиас `uninstall`.

ocx service
ocx service install
ocx service status
ocx service uninstall

`ocx codex-shim <subcommand>`

Оборачивает скриптовый лаунчер codex в PATH лёгким скриптом автозапуска. Настоящие цели codex.exe не затрагиваются, чтобы не ломать вызовы точного исполняемого файла.

Если завершённое внешнее обновление Codex перезаписало установленный shim, следующая обычная команда ocx до запуска сохранит стабильный новый лончер в резервную копию и восстановит shim. Лончер, который ещё меняется, остаётся нетронутым до следующей попытки. Ошибка восстановления выдаёт предупреждение, но не приводит к сбою запрошенной команды; ручной вариант — ocx codex-shim install. Для отключения установите codexShimAutoRestore в false или задайте процессу OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0.

Subcommand	Action
`install`	Устанавливает shim (или восстанавливает, если он устарел).
`uninstall`	Удаляет shim и восстанавливает исходный бинарный файл Codex.
`remove`	Алиас `uninstall`.
`status`	Сообщает состояние shim (установлен / устарел / отсутствует).

ocx codex-shim install
ocx codex-shim status
ocx codex-shim uninstall

Диагностика

`ocx doctor`

Выполняет диагностику окружения и связности только для чтения: пути состояния и тип файловой системы, двойные установки в WSL, окружение/конфигурация прокси, доступность ChatGPT, предупреждения о плагине Codex и конфигурации проекта, а также ожидающая миграция истории. Команда печатает подсказки по исправлению, но не применяет их.

`ocx debug [provider|usage …]`

Читает или изменяет отладочные переопределения времени выполнения через management API работающего прокси.

ocx debug provider on|off|status|reset
ocx debug provider logs [-f|--follow]
ocx debug usage on|off|status|reset
ocx debug usage logs [-f|--follow]

Без указания области ocx debug печатает справку по использованию, а когда прокси остановлен — ещё и значения окружения по умолчанию для следующего запуска. Отладка провайдеров по умолчанию включается через OCX_DEBUG=1 (устаревший OCX_DEBUG_FRAMES=1 тоже работает); отладка использования — через OPENCODEX_USAGE_DEBUG=1.

Обновление

`ocx update`

Самообновление opencodex из npm. Стабильные установки используют @latest; preview-установки остаются на @preview, если не передать --tag latest|preview. Команда обнаруживает checkout исходного кода и предлагает вместо этого выполнить git pull && bun install, и ничего не делает, если у вас уже новейшая версия для этого тега. Работающий прокси останавливается перед заменой файлов; установленный сервис пересобирается и запускается автоматически, а при установке, работающей на переднем плане, команда печатает ocx start как следующий шаг.

ocx update
ocx update --tag preview

Новые версии становятся доступны в момент, когда workflow Release публикует их в npm.

Справка

ocx help, ocx --help, ocx -h — печатают общую справку по использованию и примеры.

ocx help <command>, ocx <command> --help, ocx <command> -h — печатают справку по конкретной команде для команд, зарегистрированных в src/cli/help.ts. Полные контракты подкоманд provider, debug и v2 документированы выше.

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

Версия

ocx --version, ocx -v, ocx version — печатают одну удобную для скриптов строку версии и завершаются.

Внутренние команды

Две цели диспетчеризации намеренно исключены из обычной справки: __refresh-version [preview] обновляет кэш уведомлений об обновлениях в отсоединённом процессе, а __gui-update-worker <job-id> [latest|preview] [restart] выполняет задание обновления из дашборда. Это детали реализации, а не стабильные пользовательские команды.

Справочник CLI

Настройка и жизненный цикл

ocx init

ocx start [--port <port>]

ocx stop

ocx restore · ocx eject

ocx recover-history --legacy-openai

ocx restart

ocx ensure

ocx status [--json]

ocx health [--json]

ocx uninstall · ocx remove

Модели и Codex

ocx sync

ocx sync-cache

ocx v2 [subcommand]

ocx models [--provider <name>] [--json]

ocx provider <subcommand>

ocx account <subcommand>

ocx account list [provider] [--json] [--all]

ocx account current <provider> [--json]

ocx account use <provider> <account-or-key-id|main> [--json]

ocx account refresh <provider> [--json]

ocx account auto-switch <provider> <on|off|status|threshold <0-100>> [--json]

ocx account remove <provider> <id|main> --yes [--json]

ocx account add-key <provider> [--label <label>] [--json]