Жизненный цикл CLI

Эти команды устанавливают, запускают, проверяют, ремонтируют и обновляют локальный прокси 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>] [--socks5 [host:port] | --socks5-off]`

Запустить proxy server (предпочтительный порт 10100). При запуске пишется состояние PID/runtime-port, а попытка поднять второй живой экземпляр отвергается. Если предпочтительный порт занят, start проверяет, кто его удерживает, и в любом случае останавливается: он отказывается от запуска, если там отвечает opencodex, а иначе сообщает о неопознанном владельце порта. Прокси никогда сам не переносит listener на другой порт, поскольку тогда первый прокси продолжил бы работать, а Codex был бы перенаправлен на второй. Явно указанный другой --port также отклоняется при общем OPENCODEX_HOME: режим наблюдения и режим с лимитами оба пишут в один журнал расходов. Для независимого соседнего экземпляра используйте отдельный OPENCODEX_HOME; port: 0 поручает ОС выбрать только порт и не разделяет состояние. На старте прокси синхронизирует модели каждого провайдера в каталог Codex. При shutdown он восстанавливает native Codex — если только прокси не был запущен как managed service (OCX_SERVICE=1). Соседний экземпляр, запущенный рядом с уже работающим прокси, не делает ни того, ни другого, в том числе при остановке через ocx stop или сигналом: он обслуживает только прямые запросы на своём порту, а Codex, Grok и Claude остаются направленными на прокси, который уже работал.

--socks5 (по умолчанию 127.0.0.1:10808) сохраняет SOCKS5 URL в config.proxy и направляет исходящие HTTP(S)-запросы через настоящий SOCKS5-туннель. --socks5-off удаляет только сохранённый SOCKS5-прокси и не удаляет HTTP-прокси. Значение переживает ocx update, поскольку хранится в конфигурации, а не в установленном пакете. Имя пользователя и пароль можно указать в URL, но в startup-логах они скрываются.

ocx start
ocx start --port 8080
ocx start --port 10100 --socks5
ocx start --socks5-off

`ocx stop`

Остановить работающий прокси (по PID) и удалить PID-file; для автономного владельца также восстановить native Codex. Если установлена managed background service, ocx stop сначала останавливает и её, чтобы она не перезапустила прокси обратно. Кнопка Stop в веб-дашборде выполняет то же действие (POST /api/stop) на всех бэкендах, кроме планировщика заданий Windows: там обёртка может перезапустить прокси после завершения задачи, поэтому дашборд отказывает с respawnable_service, ничего не меняет и просит выполнить ocx stop.

На подключённом клиенте hub команда ocx stop, включая успешную остановку через API, сохраняет принадлежащие соединению маршрутизацию Codex, каталог моделей и конфигурацию Grok. ocx start снова обслуживает их, не внедряя маршрутизацию заново. Чтобы вернуть Codex к собственному аккаунту, выполните ocx disconnect; для повторного применения уже восстановленной нативной маршрутизации используйте ocx sync --restart-codex.

Явная остановка Remote Link Child при успешном восстановлении общей конфигурации восстанавливает нативную маршрутизацию Codex, каталог и сохранённые в резервной копии метаданные истории возобновления, а также удаляет управляемую конфигурацию Grok. Сохранённое соединение с Home остаётся; удалить его можно командой ocx disconnect. Чтобы снова использовать Home из Codex, выполните ocx start (или ocx service start для установленной службы), затем ocx sync --restart-codex. Один запуск не применяет маршрутизацию заново; sync не создаёт блок Grok повторно.

Если владение соединением нельзя подтвердить до остановки службы, API остановки возвращает HTTP 409 с sharedTeardown: "refused", оставляя прокси и менеджер службы работающими. Дождитесь завершения подключения или отключения и повторите попытку.

При остановке подключённого клиента команда сверяет доказательство идентичности слушателя с защищённой локальной записью рантайма. Это требуется и для клиентского слушателя, и для обычного прокси; обычный прокси также должен подтвердить сохранение настроек через аутентифицированный запрос чтения. Старые или непроверенные рантаймы отклоняются до остановки службы или процесса. Обновите и перезапустите рантайм через управляющий супервизор, затем повторите команду.

Для уже остановленного клиента команда подтверждает неактивность службы и отсутствие рантайма на известных локальных адресах, затем возвращает обычный результат «не запущен».

`ocx restart`

Если прокси уже работает, команда запрашивает перезапуск на месте у точно аттестованных PID и порта, ждёт штатного drain и проверяет появление другого runtime PID на том же порту. Управляемая маршрутизация и supervision службы сохраняются; неопределённый результат запроса не повторяется как отдельный stop/start. Если прокси не запущен, используется обычный запуск через ensure. Если работающий слушатель нельзя подтвердить привязкой к runtime PID (включая прокси до обновления), перезапуск завершается безопасным отказом без ensure или stop/start. После проверки владения выполните ocx stop, затем один раз ocx start.

`ocx ensure`

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

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

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

Восстановленный каталог исключает снятые нативные модели, включая gpt-5.3-codex-spark, как с bare ID, так и с доверенным префиксом аккаунта. Это действует с резервной копией и без неё; исходная копия и сохранённые пользователем прежние настройки выбора моделей остаются нетронутыми.

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

ocx restore back
ocx eject back

`ocx recover-history --legacy-openai --yes`

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

Это широкое и разрушительное переименование: все треды с пользовательским сообщением, которые сейчас помечены opencodex, меняются на openai, exec нормализуется в cli, а event marker устанавливается. Корректная история выделенного провайдера тоже входит в охват. Сначала сделайте резервную копию и запускайте команду только если нужен весь этот охват.

`ocx recover-history --ocx-compaction <thread-id> --yes`

Исправьте историю одной задачи, сжатой через маршрутизируемого провайдера, перед её возобновлением в нативном Codex. Команда выбирает ровно одну задачу по UUID, сначала сохраняет приватную побайтовую резервную копию, а затем преобразует только принадлежащее OpenCodeX состояние сжатия ocx1:/ocx2: в обычную сводку, которую может воспроизвести нативный Codex. Нативное зашифрованное содержимое и другие задачи не изменяются. Перед запуском закройте выбранную задачу; если rollout изменится во время обработки, восстановление остановится без замены файла.

`ocx uninstall` · `ocx remove`

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

Status и health

`ocx status [--json]`

Status и ocx doctor сравнивают версии текущего CLI и работающего прокси. Если CLI новее, перезапустите прокси из нужной актуальной установки. Для фоновой службы используйте ocx service restart. В macOS рассинхронизация версий оставляет определение службы байт-в-байт неизменным, поэтому ocx service repair ничего не перезагрузит и старый процесс продолжит обслуживание. Если новее прокси, обновите CLI или исправьте PATH, чтобы он указывал на нужную установку. Диагностика не ремонтирует службу и не меняет разрешение запросов.

При одинаковых строках версий, значениях unknown / 0.0.0 или отсутствии версии прокси предупреждение подавляется. Doctor не считает placeholder подтверждённым совпадением. Разные строки, которые нельзя строго разобрать как SemVer, и версии, отличающиеся только build metadata, вызывают нейтральное предупреждение без указания устаревшей стороны. Пробелы не удаляются, префикс v не нормализуется. JSON содержит ту же рекомендацию в versionSkew с прежними полями cliVersion, proxyVersion, skewed и warning.

Печатает 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 и идентификаторы аккаунтов.

Чтение отчёта работающего прокси ожидает завершения ограниченной по времени диагностики службы: до 6,5 секунды на macOS/Linux и до 16,5 секунды на Windows, если кэш диагностики пуст или устарел. Чтение из кэша возвращает результат без такого ожидания. При тайм-ауте по-прежнему используются локальные диагностические данные; успешная проверка /healthz сама по себе не подтверждает защиту при перезапуске.

`ocx health [--json]`

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

`ocx ready [--json] [--wait [--timeout <seconds>]]`

Проверяет готовность после синхронизации через не требующий аутентификации GET /readyz. При готовности возвращается 200; для pending и терминального failed возвращается 503 с Retry-After: 1. Санитизированные поля HTTP-ответа: {service, version, uptime, pid, port, status, protocol, minimumClientProtocol, managementUrl, features}. protocol — текущая версия удалённого протокола hub, minimumClientProtocol — минимальная совместимая версия клиента, а managementUrl — канонический origin управления для браузера. Старые прокси без /readyz fail-closed как unreachable; /healthz — отдельная проверка liveness, а не готовности. По умолчанию команда выполняет одну пробу. --wait опрашивает до готовности или тайм-аута, но при терминальном failed завершается немедленно. Тайм-аут по умолчанию — 45 секунд; --timeout <seconds> требует --wait и принимает целые положительные значения 1–300 секунд. CLI JSON выдаёт {ready, status, pid, port}, где status — ready, pending, failed или unreachable. Коды завершения: 0 — готово; 1 — не готово, pending, failed, тайм-аут или недоступность; 64 — недопустимые аргументы.

`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] [--restart-app-server-only]`

Дочерняя машина Remote Link: ocx sync также применяет настройки Codex с Home и, если клиентский рантайм запущен раньше этого применения, перезапускает его даже без флага перезапуска. Если перезапуск не удался, прежний рантайм продолжает работать, а команда завершается с ненулевым кодом. Соответствующие поля ocx status --json и ocx link status --json описаны в разделе Remote Link apply parity (на английском).

Явно запрошенный перезапуск также выполняется после успешного сохранения изменения config.toml, даже если байты каталога и кэша не изменились. Операция только с конфигурацией без изменений, отказ, предварительная проверка или отменённая запись не вызывают перезапуск. Без флага перезапуска sync никогда не перезапускает Codex автоматически.

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

Если всё ещё работают долгоживущие процессы Codex app-server, ocx sync предупредит, что они могут продолжать отдавать старый in-memory список моделей, хотя файлы opencodex-catalog.json / models_cache.json уже обновлены. Передайте --restart-codex, чтобы перезапустить подходящие процессы codex … app-server и codex-code-mode-host и полностью закрыть и заново запустить Desktop-приложение Codex на macOS, Linux и Windows, чтобы model picker перечитал каталог. Живые conversation’ы при этом завершаются. Широкий pkill -f codex намеренно не используется.

--restart-desktop-app — устаревший alias --restart-codex. Он по-прежнему работает, печатает предупреждение об устаревании и не ограничен Windows.

--restart-app-server-only возвращает прежнее узкое поведение: SIGTERM только подходящим процессам app-server / code-mode-host текущего пользователя, Desktop-приложение остаётся запущенным (активные turn’ы всё ещё могут оборваться). Если флаг указан вместе с --restart-codex или --restart-desktop-app, побеждает узкий scope: потеря живых conversation’ов невосстановима, а устаревший picker — нет.

Если команда запущена изнутри приложения Codex, restart передаётся detached helper’у, и эта сессия завершается вместе с приложением.

Синхронизация с закреплённым источником. ocx sync --expect-link <linkId> (Remote Link Child) и ocx sync --expect-hub-key <apiKeyId> (клиент hub) выполняют синхронизацию, только если эта машина всё ещё подключена к этой связи или с этим ключом. Иначе ничего не меняется, локальные провайдеры не синхронизируются, команда завершается с кодом 5, а последняя строка stderr — {"phase":"child_link_mismatch"|"hub_client_mismatch","reason":...}. Неверный или повторённый флаг завершает команду с кодом 2. Подробнее: английская справка.

`ocx sync-cache [--restart-codex] [--restart-app-server-only]`

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

`ocx catalog pull <https-url> [--auth-env <NAME>] [--json] [--restart-codex] [--restart-app-server-only]`

Устанавливает полный каталог, который отдаёт эндпоинт /v1/catalog другого экземпляра OpenCodex, и затем синхронизирует models_cache.json. URL должен быть HTTPS; HTTP допускается только на loopback. Учётные данные в URL, query, фрагменты, редиректы, слишком большие ответы и невалидные каталоги отклоняются до любой локальной записи. Аутентификация необязательна и читается только по имени переменной окружения (--auth-env), но не из argv.

HTTP-запросы к loopback отклоняются до добавления заголовков аутентификации и отправки запроса, если применяется HTTP_PROXY или http_proxy, а в NO_PROXY или no_proxy нет подходящего исключения. ALL_PROXY/all_proxy и настройки только HTTPS_PROXY/https_proxy не вызывают это ограничение для HTTP; получение каталогов по HTTPS остаётся разрешённым. Сообщение об отказе не содержит адрес прокси или токен аутентификации. Непустые значения http_proxy и no_proxy имеют приоритет над HTTP_PROXY и NO_PROXY соответственно. Для совместимых с Bun правил обхода прокси используйте имена хостов, совпадающие записи host:port, IPv6-адреса в квадратных скобках, например [::1], или *; не используйте URL, пути или префикс *..

Каталог и кэш пишутся под общей блокировкой каталога Codex; при сбое сохраняются last-known-good файлы. Идентичные байты — это no-op, сохраняющий mtime. --restart-codex, --restart-app-server-only и устаревший alias --restart-desktop-app здесь означают то же, что у ocx sync и ocx sync-cache, и применяются только после реальной записи. Условные запросы ETag в эту команду не входят. Полная --json-обёртка и коды выхода описаны в английской справке.

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

`ocx service [install|repair|restart|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.

При установке через Windows Task Scheduler используется обычный приоритет процесса (Priority=4). Прежний фоновый приоритет (7, также значение планировщика по умолчанию при отсутствии параметра) при конкуренции за CPU может задерживать ответы проверки состояния: трей показывает Offline, хотя процесс работает. После обновления выполните ocx service repair, чтобы изменить этот зарегистрированный приоритет и перезапустить службу. Может потребоваться подтверждение UAC. Если уже задан обычный или высокий приоритет, сам приоритет не вызывает перерегистрацию.

В Linux systemd-юнит вызывает первый обычный исполняемый файл ocx, найденный в PATH на момент установки, а не пути Bun и CLI внутри установленного дерева пакета. Менеджеры версий вроде mise и asdf устанавливают в каталог с версией и удаляют старый при обновлении; их стабильный shim сохраняет разрешение юнита. Исходные checkout’ы без launcher’а ocx сохраняют прямую форму Bun + CLI. Доверенный OPENCODEX_BUN_PATH, выбранный до запуска Bun, сохраняется через shim; пути к Bun, поставляемому внутри пакета, перенаходятся после обновлений.

В macOS launchd, напротив, использует пути Bun и CLI внутри пакета, выбранные при install или repair. Это не даёт изменяемому PATH-shim получить service API token и настроенное окружение прокси при последующем restart. После обновления установки через менеджер версий выполните ocx service repair, чтобы обновить эти пути перед перезапуском службы.

Определения, установленные до этого изменения, по-прежнему содержат старые версионные пути и не могут мигрировать сами — после удаления старого исполняемого файла ни один код opencodex уже не запустится, чтобы это исправить. Выполните ocx service repair один раз после обновления. После этого запуски службы в Linux следуют за launcher’ом, а repair в macOS записывает новые пути пакета в определение launchd. Уже работающий прокси внешним обновлением не заменяется: если установленный CLI новее работающего прокси, выполните ocx service restart, чтобы обслуживалась новая сборка. В macOS здесь repair недостаточно: определение не изменилось, а repair, который ничего не меняет, ничего не перезагружает. Если новее прокси, проверьте установку CLI и PATH, как описано в ocx status.

Подкоманда	Действие
none	Установить и запустить службу, если её нет; иначе выполнить `repair` для существующей службы. Исправная конфигурация Windows Task Scheduler используется повторно; устаревшая может быть перерегистрирована и потребовать повышения прав.
`install`	Создать и запустить службу.
`repair`	Обновить установленную службу на месте. В macOS менеджер перезагружается только при наличии изменений, поэтому исправная неизменённая задача продолжает работать и обновление не является простоем. В Linux и Windows служба перезапускается; исправная конфигурация Windows Task Scheduler используется повторно, а устаревшая может быть перерегистрирована и потребовать повышения прав.
`restart`	То же обновление с гарантированным перезапуском на всех платформах. В macOS неизменённая, уже загруженная задача перезапускается на месте (kickstart). Не псевдоним команды `repair`.
`start`	Запустить уже установленную службу.
`stop`	Остановить службу и восстановить native Codex.
`status`	Показать диагностику службы и прокси, а также пути к логам.
`uninstall`	Удалить службу и восстановить native Codex.
`remove`	Alias команды `uninstall`.

ocx service
ocx service install
ocx service repair
ocx service restart
ocx service status
ocx service uninstall

На Windows bare ocx service выполняет путь установки только после того, как отсутствие подтверждено и для Task Scheduler, и для WinSW. Если любой из запросов статуса не даёт определённого ответа, он отказывается что-либо регистрировать и предлагает выполнить ocx service status; явный ocx service install используйте только после подтверждения отсутствия.

На 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.

Если при запуске выводится another process owns the runtime mutation lease или ocx service status показывает Runtime mutation lease busy, аренда блокирует запуск или изменения службы, даже если прокси не запущен. Сообщение содержит путь к блокировке, записанный PID, жив ли этот PID сейчас, имя исполняемого файла, если его удалось получить, и возраст аренды. Подлинность процесса не проверяется: PID мог быть переиспользован, поэтому состояние и имя исполняемого файла относятся к процессу, который занимает этот PID сейчас. Дождитесь завершения операции и повторите попытку; не удаляйте блокировку и не останавливайте процесс, опираясь только на этот PID. Последующая попытка изменения может забрать устаревшую аренду, когда её возраст превысит 30 секунд, а записанный PID больше не будет жив; ocx service status только просматривает её.

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

На macOS и Linux ocx codex-shim install создаёт частную обёртку <OPENCODEX_HOME>/bin/codex и подключаемый файл <OPENCODEX_HOME>/codex-shell-env.sh в разрешённом каталоге OpenCodex. Нативный launcher остаётся там, где его установили brew, npm или fnm, поэтому обновления и возврат к предыдущей версии не требуют повторного оборачивания. В Windows скриптовые launcher по-прежнему оборачиваются на месте, а настоящий codex.exe не изменяется. Если доступен только codex.exe, используйте ocx service install.

После настройки PATH для brew/fnm выполните команду активации, напечатанную при установке. Для каталога по умолчанию:

. "$HOME/.opencodex/codex-shell-env.sh"

Для другого каталога используйте напечатанный путь в кавычках. Повторное подключение удаляет дубликаты частного bin и ставит его первым в PATH. Для будущих оболочек добавьте эту строку самостоятельно после настройки PATH в файле запуска; OpenCodex никогда не редактирует такие файлы. Установка не меняет PATH родительской оболочки. Если обёртка может выполняться, установка успешна даже до активации в текущей оболочке; отказ или неработоспособная обёртка остаются ошибкой. ocx status, ocx codex-shim status, ocx doctor и ocx connect сообщают not active и команду активации, если PATH не выбирает обёртку. Предупреждения connect не меняют код завершения. Псевдонимы, функции и запуск из настольной среды или служб требуют отдельной настройки.

Перед фиксацией установки или repair OpenCodex запускает сохранённый launcher с --version, не запуская сервис. Изменение отклоняется и откатывается, если launcher снова разрешает codex в shim, завершается с ненулевым кодом, работает дольше пяти секунд, оставляет дочерние процессы или не может быть безопасно проверен и очищен. Поэтому codex-shim install не является безусловной установкой. После отказа переустановите Codex так, чтобы запись в PATH указывала на конкретный исполняемый файл или launcher, и повторите попытку. Если динамический launcher менеджера команд не проходит эти проверки, используйте вместо него ocx service install. Старый Unix shim, установленный на месте, переносится только явной командой ocx codex-shim install. Записанный нативный launcher восстанавливается без замены уже имеющегося более нового launcher, затем устанавливается частная обёртка. При последующей ошибке установки нативный launcher остаётся восстановленным, а операцию можно повторить. Если записанный launcher отсутствует или не работает, исправьте установку через менеджер пакетов: OpenCodex не выбирает другую установку и не оборачивает заново путь менеджера.

На Unix автоматическое исправление обновляет только частную обёртку: пути менеджера пакетов не перезаписываются, старые shim на месте не переносятся. На Windows после завершённого внешнего обновления, заменившего shim, следующая обычная команда ocx сохраняет новый стабильный launcher и восстанавливает shim. Меняющийся launcher остаётся нетронутым до повторной попытки. ocx status, ocx doctor, ocx codex-shim status, ocx system codex-cli-update check и некорректные вызовы его зарезервированного пространства не запускают это исправление. Ошибки приводят к предупреждению без изменения кода завершения запрошенной команды. Ручной вариант: ocx codex-shim install. Отключение: codexShimAutoRestore: false или OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0 для процесса.

Подкоманда	Действие
`install`	Установить shim (или починить, если он устарел).
`uninstall`	Удалить частные файлы Unix, сохранив нативный Codex; на Windows восстановить исходный launcher.
`remove`	Alias команды `uninstall`.
`status`	Показать состояние shim и активность частной обёртки в PATH.

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

После удаления на Unix уберите строку подключения из файла запуска оболочки и перезапустите её либо удалите частный bin из PATH. Удаляются только принадлежащие OpenCodex обёртка, файл окружения и состояние; launcher менеджера пакетов остаётся нетронутым. Старый Unix shim на месте освобождается по записанным данным восстановления.

Передача токена в Codex

При привязке к адресу, отличному от loopback, внедрённый провайдер содержит env_key = "OPENCODEX_API_AUTH_TOKEN". Эта строка указывает Codex, какую переменную читать, но не создаёт её. Если переменная отсутствует, Codex отказывается начинать запрос (Missing environment variable: OPENCODEX_API_AUTH_TOKEN), и запрос не доходит до прокси. Значение хранится в $OPENCODEX_HOME/service-api-token; запускающий процесс должен передать его в окружение Codex.

Используйте поддерживаемую обёртку, устанавливаемую командой ocx codex-shim install. Если в контексте запуска выбирается эта обёртка, она читает файл токена, созданный OpenCodex, и передаёт переменную Codex. При запуске из настольной среды, cron или службы необходимо использовать PATH либо путь к средству запуска, который выбирает обёртку; установка не настраивает эти окружения автоматически. Собственные дочерние процессы Codex также могут унаследовать токен.

Не экспортируйте этот Bearer-токен из файла запуска оболочки и не копируйте его в config.toml. Файл service-api-token содержит сам токен, а не присваивания вида NAME=value, поэтому его нельзя напрямую использовать как EnvironmentFile= в systemd.

EnvironmentFile= или OCX_API_TOKEN_FILE в opencodex-proxy.service настраивает только процесс прокси и никогда не передаётся в независимо запущенный codex exec.

На Unix обновления менеджера пакетов сохраняют частную обёртку. Если она не активна, подключите напечатанный файл активации. На Windows или со старым shim на месте обновление, заменяющее launcher, удаляет обёртку; на Windows следующая обычная команда ocx восстанавливает её (см. выше), но codex exec, запущенный до этого, завершается ошибкой. ocx doctor сообщает об этом состоянии и неактивной обёртке в разделе “Codex env_key launch readiness” (env_key настроен, переменная не задана, обёртка отсутствует или неисправна, файл токена присутствует), приводит инструкции исправления или активации и никогда не выводит токен. Чтение файла токена не входит в контракт внедрённого env_key; запускающий процесс должен передать эту переменную.

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

Установить и управлять Windows tray icon со статусом. Иконка стартует при логине в Windows и даёт one-click управление прокси. start и stop управляют только иконкой; самим прокси нужно управлять из её меню. --no-start применяется к install и устанавливает tray, не запуская её немедленно. Устарело: приложение OpenCodex для рабочего стола предоставляет трей в Windows, macOS и Linux; ocx tray остаётся для установок без приложения для рабочего стола. Когда становится известна новая версия пакета, трей добавляет синюю точку к значку онлайн, предупреждения или офлайн и показывает Update available. Локально кэшированный badge проверяется примерно раз в минуту; устаревшие или недоступные результаты убирают точку. Пункт меню открывает панель управления, где можно запустить обновление пакета. Автоматическая установка не выполняется.

Дашборд

`ocx gui`

Открыть веб-дашборд по адресу http://127.0.0.1:<port> (или http://127.0.0.1:<порт управления>, если на хабе включён management ingress), автоматически запустив прокси, если он ещё не работает.

Обновление

ocx update обновляет сам OpenCodex, а не Codex CLI. Используйте ocx system codex-cli-update check из system-команд инспекции для ограниченной read-only проверки provenance настроенного кандидата Codex CLI. Команда не обращается к package registry и не устанавливает обновление.

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

Если OpenCodex установлен через mise, команда завершается с ошибкой до остановки прокси или изменения файлов пакета и показывает mise upgrade <tool> с проверенным локальным псевдонимом mise. Проверка обновлений остаётся доступной и сообщает о внешнем управлении. Нечитаемые или противоречивые метаданные владельца mise также запрещают изменения без угадывания имени инструмента, а --tag preview никогда не меняет выбранную в mise версию.

В Linux фоновая служба, у которой записанный лаунчер — пакетный лаунчер mise (<tool>/latest/node_modules/.bin/ocx, а не shim mise), сама следует за mise upgrade: примерно через десять секунд после того, как новая версия стабилизируется, она завершает активные запросы и перезапускается на ней, и так же восстанавливается, если mise позже удалит версию, на которой она работала. В macOS, для службы, установленной через shim mise, и для прокси на переднем плане перезапустите её сами после обновления (в macOS сначала ocx service repair).

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

ocx update
ocx update --tag preview

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

Жизненный цикл клиента Remote Hub

Используйте ocx connect <url> --pairing-code-stdin, ocx connect status, ocx sync и ocx connect rotate --pairing-code-stdin. ocx disconnect офлайн восстанавливает локальное состояние, но не отзывает ключ hub. Пока подключение активно, ocx connect revoke --admin-token-stdin отзывает сохранённый apiKeyId; после отключения используйте Подключение → API-ключи на hub. Секреты передаются только через stdin, не argv.

Жизненный цикл CLI

Настройка

ocx init · ocx setup

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

ocx start [--port <port>] [--socks5 [host:port] | --socks5-off]

ocx stop

ocx restart

ocx ensure

ocx restore [back] · ocx eject [back]

ocx recover-history --legacy-openai --yes

ocx recover-history --ocx-compaction <thread-id> --yes

ocx uninstall · ocx remove