opencodex/docs-site/src/content/docs/ru/reference/cli/lifecycle.md at c297dba307506eca9d3ee85750f12570b2e65749 · lidge-jun/opencodex

title	Жизненный цикл CLI
description	Настройка, запуск, остановка, служба, диагностика, sync и update-команды.

Эти команды устанавливают, запускают, проверяют, ремонтируют и обновляют локальный прокси opencodex и его интеграцию с Codex.

Настройка

`ocx init` · `ocx setup`

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

Жизненный цикл прокси

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

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

ocx start
ocx start --port 8080

`ocx stop`

Остановить работающий прокси (по PID), удалить PID-file и восстановить native Codex. Если установлена managed background service, ocx stop сначала останавливает и её, чтобы она не перезапустила прокси обратно. То же действие доступно из кнопки Stop в веб-дашборде (POST /api/stop).

`ocx restart`

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

`ocx ensure`

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

`ocx restore [back]` · `ocx eject [back]`

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

Передайте back, чтобы любая из этих форм снова направила обычный codex на уже запущенный прокси, не меняя жизненный цикл самого прокси:

ocx restore back
ocx eject back

`ocx recover-history --legacy-openai`

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

`ocx uninstall` · `ocx remove`

Остановить службу и прокси, удалить службу и Codex shim, восстановить native Codex, а затем удалить локальную конфигурацию opencodex только если все шаги восстановления завершились успешно. remove — alias команды uninstall. Очистка конфигурации требует ownership metadata, созданных при свежей установке; legacy- или shared-directory остаются на месте.

Status и health

`ocx status [--json]`

Печатает read-only диагностическую сводку: PID прокси, достижимость /healthz, URL дашборда, путь к конфигу, провайдера по умолчанию, настройку автозапуска Codex, состояние службы, состояние shim'а и redacted effective Codex home. Только явная и высокоуверенная сигнатура mismatch runtime-home Windows Orca даёт actionable-warning о несоответствии App-home; CODEX_HOME автоматически при этом не меняется.

В текстовом выводе после сводки OAuth-logins также присутствует блок OAuth health: OAuth health: ok, если все известные аккаунты здоровы, либо OAuth health: warning с одной redacted-строкой на каждый нездоровый аккаунт (провайдер, замаскированный id аккаунта, статус вроде reauthentication required, rate/quota limited или refresh conflict) плюс необязательная подсказка Action:. Идентификаторы маскируются; токены и email никогда не печатаются. В контракт --json этот health-блок пока не входит.

ocx status
ocx status --json

Сокращённая форма 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"
  },
  "codexHome": {
    "effectiveCodexHome": "C:\\Users\\[USER]\\.codex",
    "appCodexHome": "C:\\Users\\[USER]\\.codex",
    "mismatch": false,
    "warning": null,
    "action": null
  },
  "codexAutostart": true,
  "defaultProvider": "openai",
  "service": {
    "summary": "not installed (logs: /Users/example/.opencodex/service.log)"
  },
  "codexShim": {
    "summary": "Codex autostart shim: not installed"
  }
}

Реальный объект также включает listen (порт, hostname, источник runtime/config), диагностику загрузки конфига и диагностику bundled-plugin'а Codex. JSON-schema только расширяемая: новые версии могут добавлять поля, но существующие должны оставаться стабильными. Она намеренно не включает API-key'и, OAuth-token'ы, заголовки авторизации, содержимое запросов, email и идентификаторы аккаунтов.

`ocx health [--json]`

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

`ocx doctor`

Запускает read-only диагностику среды и связности: пути состояний и тип файловой системы, двойные установки WSL, proxy environment/config, достижимость ChatGPT, предупреждения о plugin'е и project-config Codex, а также ожидающую миграцию истории. Раздел, касающийся app-home Codex, тоже обнаруживает узкий mismatch runtime-home Windows Orca и при необходимости объясняет миграцию службы. Пути в этом выводе маскируют имя пользователя ОС. Doctor печатает подсказки по ремонту, но ничего не меняет.

Раздел OAuth reliability показывает, можно ли записывать credential storage, удаётся ли создавать refresh single-flight/lock file'ы в OPENCODEX_HOME, есть ли нездоровые OAuth- или Codex-pool-аккаунты (с masked-id) с подсказкой Action:, а также статическое OK-подтверждение, что путь Codex forward не подделывает metadata официального клиента. Doctor никогда не мутирует credential'ы и не выполняет repair.

Синхронизация каталога

`ocx sync [--restart-codex]`

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

Если всё ещё работают долгоживущие процессы Codex app-server, ocx sync предупредит, что они могут продолжать отдавать старый in-memory список моделей, хотя файлы opencodex-catalog.json / models_cache.json уже обновлены. Передайте --restart-codex, чтобы послать SIGTERM только подходящим процессам codex … app-server и codex-code-mode-host, принадлежащим текущему пользователю (активные turn'ы при этом могут оборваться). Широкий pkill -f codex намеренно не используется.

`ocx sync-cache [--restart-codex]`

Инвалидировать локальный кэш model picker'а Codex, чтобы он пересобрался из активного каталога opencodex. Предупреждение о stale-app-server и optional --restart-codex работают так же, как и у ocx sync.

Фоновая служба

`ocx service [install|start|stop|status|uninstall|remove]`

Запустить opencodex как login-managed background service (macOS launchd, Linux systemd user unit, Windows Task Scheduler), которая автоматически стартует при логине и сама перезапускается при crash. Запуски службы выставляют OCX_SERVICE=1, чтобы restart не дёргал конфиг Codex.

Подкоманда	Действие
none	Создать/обновить и запустить службу.
`install`	Создать и запустить службу.
`start`	Запустить уже установленную службу.
`stop`	Остановить службу и восстановить native Codex.
`status`	Показать диагностику службы и прокси, а также пути к логам.
`uninstall`	Удалить службу и восстановить native Codex.
`remove`	Alias команды `uninstall`.

ocx service
ocx service install
ocx service status
ocx service uninstall

На Windows ocx service status отдельно показывает регистрацию в Task Scheduler и identity-проверенную достижимость прокси OpenCodex. Он не печатает локализованную таблицу schtasks, чтобы сводка оставалась читаемой на любых code page Windows.

На Windows создание записи в Task Scheduler требует elevation. Когда распознан локализованный текст access-denied, остаётся прежний путь guidance. Если текст неразборчив, fallback использует владение command-shape /create /tn opencodex-proxy /xml <non-empty-path> /f, status 1 и подтверждённый non-elevated token; после этого действие Startup Safety в дашборде может само запросить UAC. Если fallback не смог определить состояние token'а, он оставляет исходную scheduler-error. Чужие задачи и чужие операции никогда не получают automatic-elevation marker. Либо подтвердите UAC через дашборд, либо заново выполните ocx service install в elevated окне PowerShell.

`ocx codex-shim <install|status|uninstall|remove>`

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

Если завершённое внешнее обновление Codex перезаписало установленный shim, следующая обычная команда ocx сохранит новый стабильный launcher и восстановит shim перед выполнением запроса. Launcher, который всё ещё меняется, не трогается, а попытка откладывается до следующего раза. Сбои repair'а приводят только к warning и не ломают запрошенную команду; ручной запасной путь — ocx codex-shim install. Чтобы отключить автоматику, задайте codexShimAutoRestore: false или установите OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0.

Подкоманда	Действие
`install`	Установить shim (или починить, если он устарел).
`uninstall`	Удалить shim и восстановить исходный бинарник Codex.
`remove`	Alias команды `uninstall`.
`status`	Показать состояние shim'а (installed, stale или missing).

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

:::tip[Service vs Shim] Используйте ocx service для всегда работающего фонового прокси (рекомендуется). Используйте ocx codex-shim для лёгкого on-demand запуска без демона — в этом случае прокси стартует только когда запускается codex. :::

`ocx tray <install|start|stop|status|uninstall|remove> [--json] [--no-start]`

Установить и управлять Windows tray icon со статусом. Иконка стартует при логине в Windows и даёт one-click управление прокси. start и stop управляют только иконкой; самим прокси нужно управлять из её меню. --no-start применяется к install и устанавливает tray, не запуская её немедленно.

Дашборд

`ocx gui`

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

Обновление

`ocx update [--tag latest|preview]`

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

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

Если после остановки прокси сама команда обновления завершилась с ошибкой, автоматическое восстановление не выполняется — завершившийся сбоем установщик может ещё изменять глобальное дерево пакетов. Задание обновления остаётся failed, а его лог указывает ручной путь: восстановите пакет, затем выполните ocx service install или ocx start --port <port>.

ocx update
ocx update --tag preview

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Настройка

`ocx init` · `ocx setup`

Жизненный цикл прокси

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

`ocx stop`

`ocx restart`

`ocx ensure`

`ocx restore [back]` · `ocx eject [back]`

`ocx recover-history --legacy-openai`

`ocx uninstall` · `ocx remove`

Status и health

`ocx status [--json]`

`ocx health [--json]`

`ocx doctor`

Синхронизация каталога

`ocx sync [--restart-codex]`

`ocx sync-cache [--restart-codex]`

Фоновая служба

`ocx service [install|start|stop|status|uninstall|remove]`

`ocx codex-shim <install|status|uninstall|remove>`

`ocx tray <install|start|stop|status|uninstall|remove> [--json] [--no-start]`

Дашборд

`ocx gui`

Обновление

`ocx update [--tag latest|preview]`

FilesExpand file tree

lifecycle.md

Latest commit

History

lifecycle.md

File metadata and controls

Настройка

ocx init · ocx setup

Жизненный цикл прокси

ocx start [--port <port>]

ocx stop

ocx restart

ocx ensure

ocx restore [back] · ocx eject [back]

ocx recover-history --legacy-openai

ocx uninstall · ocx remove

Status и health

ocx status [--json]

ocx health [--json]

ocx doctor

Синхронизация каталога

ocx sync [--restart-codex]

ocx sync-cache [--restart-codex]

Фоновая служба

ocx service [install|start|stop|status|uninstall|remove]

ocx codex-shim <install|status|uninstall|remove>

ocx tray <install|start|stop|status|uninstall|remove> [--json] [--no-start]

Дашборд

ocx gui

Обновление

ocx update [--tag latest|preview]

`ocx init` · `ocx setup`

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

`ocx stop`

`ocx restart`

`ocx ensure`

`ocx restore [back]` · `ocx eject [back]`

`ocx recover-history --legacy-openai`

`ocx uninstall` · `ocx remove`

`ocx status [--json]`

`ocx health [--json]`

`ocx doctor`

`ocx sync [--restart-codex]`

`ocx sync-cache [--restart-codex]`

`ocx service [install|start|stop|status|uninstall|remove]`

`ocx codex-shim <install|status|uninstall|remove>`

`ocx tray <install|start|stop|status|uninstall|remove> [--json] [--no-start]`

`ocx gui`

`ocx update [--tag latest|preview]`