lidge-jun · lidge-jun · Sep 18, 2026 · Sep 18, 2026 · Sep 18, 2026 · coderabbitai
@@ -313,8 +313,9 @@ ocx v2 <...>                   # multi-agent v1/v2 surface controls
 ocx update [--tag preview]     # update opencodex
 ```
 
-Unpinned starts may pick another free port if the preferred one is busy; an explicit `--port`
-never hops. Full reference: [CLI docs](https://opencodex.me/reference/cli/).
+A start whose preferred port is busy stops and names the holder instead of moving to another port,
+so it can never leave a second proxy running beside the first. Free the port, or name a different
+one with `--port`. Full reference: [CLI docs](https://opencodex.me/reference/cli/).
 
 ### Health and readiness
 

@@ -82,7 +82,7 @@ Codex actifs se trouvent sous `$CODEX_HOME` (par défaut `~/.codex`).
 | --- | --- |
 | `$OPENCODEX_HOME/config.json` | Vos fournisseurs, fournisseur par défaut, port et options. |
 | `$OPENCODEX_HOME/ocx.pid` | PID du proxy en cours d'exécution (garde à instance unique). |
-| `$OPENCODEX_HOME/runtime-port.json` | Le PID en direct, le nom d'hôte et le port, y compris un port de secours sélectionné automatiquement. |
+| `$OPENCODEX_HOME/runtime-port.json` | Le PID actif, le nom d’hôte et le port, y compris un port attribué par le système d’exploitation lorsque `config.port` vaut `0`. |
 | `$OPENCODEX_HOME/auth.json` | Informations d’identification OAuth enregistrées après `ocx login`. |
 | `$OPENCODEX_HOME/catalog-backup*.json` | Sauvegardes du catalogue de modèles Codex créées avant toute modification par opencodex. |
 | `$CODEX_HOME/config.toml` | Avec une liaison de bouclage, opencodex ajoute une valeur racine `openai_base_url` délimitée par ses marqueurs. Les liaisons hors bouclage utilisent `model_provider = "opencodex"` avec `[model_providers.opencodex]` afin que Codex puisse envoyer l’en-tête d’authentification API. |

@@ -46,8 +46,10 @@ Au démarrage, opencodex :
   le catalogue de modèles de Codex**,
 - écoute sur `http://localhost:<port>/v1`.
 
-Si le port demandé est occupé, `ocx start` sélectionne un port libre, l'enregistre dans `runtime-port.json`,
-et met à jour Codex pour utiliser l'écouteur en direct.
+Si le port demandé est occupé, `ocx start` s’arrête et indique ce qui l’occupe : exécutez d’abord
+`ocx stop` si un processus opencodex y répond, ou démarrez sur un port libre avec
+`ocx start --port <port>`. La commande ne change jamais de port d’elle-même : auparavant, ce
+comportement laissait deux proxys en cours d’exécution et redirigeait Codex vers le plus récent.
 
 Vérifiez-le :
 

@@ -15,7 +15,7 @@ Assistant de configuration interactif (`setup` est un alias de `init`). Il deman
 
 ### `ocx start [--port <port>] [--socks5 [host:port] | --socks5-off]`
 
-Démarre le serveur proxy, de préférence sur le port `10100`. Si ce port est occupé, opencodex en choisit un autre qui est disponible et l’enregistre. La commande écrit l’état du PID et du port d’exécution, et refuse de démarrer une deuxième instance active. Au démarrage, elle synchronise dans le catalogue Codex les modèles de chaque fournisseur. À l’arrêt, elle rétablit le fonctionnement natif de Codex, sauf si le proxy a été lancé comme service géré (`OCX_SERVICE=1`).
+Démarre le serveur proxy, de préférence sur le port `10100`. La commande écrit l’état du PID et du port d’exécution, et refuse de démarrer une deuxième instance active. Lorsque le port préféré est occupé, `start` interroge le processus qui l’occupe puis s’arrête dans tous les cas : elle refuse de démarrer si un processus opencodex y répond et signale sinon que le processus est inconnu. Elle ne déplace jamais l’écouteur vers un autre port d’elle-même, car cela laisserait le premier proxy en cours d’exécution et redirigerait Codex vers le second. Indiquez un autre port avec `--port`, ou définissez `port: 0` dans la configuration pour demander au système d’exploitation d’en attribuer un. Au démarrage, elle synchronise dans le catalogue Codex les modèles de chaque fournisseur. À l’arrêt, elle rétablit le fonctionnement natif de Codex, sauf si le proxy a été lancé comme service géré (`OCX_SERVICE=1`).
 
 `--socks5` (par défaut `127.0.0.1:10808`) enregistre l’URL SOCKS5 dans `config.proxy` et achemine
 les requêtes HTTP(S) sortantes dans un véritable tunnel SOCKS5. `--socks5-off` supprime uniquement

@@ -87,7 +87,7 @@ under `$CODEX_HOME` (default `~/.codex`).
 | --- | --- |
 | `$OPENCODEX_HOME/config.json` | Your providers, default provider, port, and options. |
 | `$OPENCODEX_HOME/ocx.pid` | PID of the running proxy (single-instance guard). |
-| `$OPENCODEX_HOME/runtime-port.json` | The live PID, hostname, and port, including an automatically selected fallback port. |
+| `$OPENCODEX_HOME/runtime-port.json` | The live PID, hostname, and port — including an OS-assigned port when `config.port` is `0`. |
 | `$OPENCODEX_HOME/auth.json` | Stored OAuth credentials (when you `ocx login`). |
 | `$OPENCODEX_HOME/catalog-backup*.json` | Codex model catalog backups made before opencodex edits it. |
 | `$CODEX_HOME/config.toml` | On loopback, opencodex adds a marker-owned root `openai_base_url`; non-loopback binds use `model_provider = "opencodex"` plus `[model_providers.opencodex]` so Codex can send the API-auth header. |

@@ -86,8 +86,10 @@ On start, opencodex:
   Codex's model catalog**,
 - listens on `http://localhost:<port>/v1`.
 
-If the requested port is busy, `ocx start` selects a free port, records it in `runtime-port.json`,
-and updates Codex to use the live listener.
+If the requested port is busy, `ocx start` stops and tells you what holds it: run `ocx stop` first
+when the holder is an opencodex, or start on a free port with `ocx start --port <port>`. It does not
+move to another port by itself — that is what used to leave two proxies running with Codex pointed
+at the newer one.
 
 Check it:
 

@@ -80,7 +80,7 @@ opencodex の状態ファイルは `$OPENCODEX_HOME`(デフォルト `~/.opencod
  --- | --- |
 | `$OPENCODEX_HOME/config.json` | プロバイダー、デフォルトプロバイダー、ポート、オプション。 |
 | `$OPENCODEX_HOME/ocx.pid` | 実行中のプロキシの PID(単一インスタンスガード)。 |
-| `$OPENCODEX_HOME/runtime-port.json` | 自動で選んだ代替ポートを含む現在の PID、ホスト名、ポート。 |
+| `$OPENCODEX_HOME/runtime-port.json` | 現在の PID、ホスト名、ポート。`config.port` が `0` の場合に OS が割り当てたポートも含みます。 |
 | `$OPENCODEX_HOME/auth.json` | 保存された OAuth 認証情報(`ocx login` 時)。 |
 | `$OPENCODEX_HOME/catalog-backup*.json` | opencodex が変更する前に作成した Codex モデルカタログのバックアップ。 |
 | `$CODEX_HOME/config.toml` | ローカル専用構成では opencodex が管理するルート `openai_base_url` を追加します。ローカル以外のアドレスにバインドする場合は Codex が API 認証ヘッダーを送れるよう `model_provider = "opencodex"` と `[model_providers.opencodex]` を使います。 |

@@ -41,7 +41,7 @@ ocx start --port 8080
 Codex のモデル カタログ**、
 - `http://localhost:<port>/v1`で聴いています。
 
-要求されたポートがビジーの場合、`ocx start` は空きポートを選択し、それを `runtime-port.json` に記録し、ライブ リスナーを使用するように Codex を更新します。
+要求されたポートが使用中の場合、`ocx start` は停止し、そのポートを使用しているプロセスを通知します。opencodex が応答している場合は先に `ocx stop` を実行し、空いているポートで起動する場合は `ocx start --port <port>` を使用してください。`ocx start` が自動で別のポートへ移ることはありません。以前はこの動作によって 2 つのプロキシが同時に動作し、Codex が後から起動した方を指すことがありました。
 
 確認してください:
 

@@ -15,7 +15,7 @@ description: セットアップ、開始、停止、サービス、診断、同
 
 ### `ocx start [--port <port>] [--socks5 [host:port] | --socks5-off]`
 
-プロキシ サーバー (優先ポート `10100`) を起動します。そのポートが占有されている場合、opencodex は別の使用可能なポートを選択して記録します。 PID/ランタイムポートの状態を書き込み、2 番目のライブインスタンスの起動を拒否します。開始時に、各プロバイダーのモデルを Codex のカタログに同期します。マネージド サービス (`OCX_SERVICE=1`) として起動されていない限り、シャットダウン時にネイティブ Codex が復元されます。
+プロキシ サーバー (優先ポート `10100`) を起動します。PID/ランタイムポートの状態を書き込み、2 番目のライブインスタンスの起動を拒否します。優先ポートが使用中の場合、`start` はそのポートを使用しているプロセスを確認して、どちらの場合も停止します。opencodex が応答していれば起動を拒否し、それ以外は使用しているプロセスを特定できないと報告します。最初のプロキシを実行したまま Codex を 2 番目のプロキシへ向けることになるため、自動でリスナーを別のポートへ移すことはありません。別のポートは `--port` で指定するか、設定で `port: 0` を指定して OS に割り当てを依頼してください。開始時に、各プロバイダーのモデルを Codex のカタログに同期します。マネージド サービス (`OCX_SERVICE=1`) として起動されていない限り、シャットダウン時にネイティブ Codex が復元されます。
 
 `--socks5`（デフォルト `127.0.0.1:10808`）は SOCKS5 URL を `config.proxy` に保存し、送信 HTTP(S) リクエストを実際の SOCKS5 トンネル経由で送信します。`--socks5-off` は保存された SOCKS5 プロキシだけを削除し、HTTP プロキシは削除しません。値は設定に保存されるため、`ocx update` 後も保持されます。URL にユーザー名とパスワードを含めることはできますが、起動ログでは非表示になります。
 

@@ -80,7 +80,7 @@ opencodex 상태 파일은 `$OPENCODEX_HOME`(기본값 `~/.opencodex`) 아래에
 | --- | --- |
 | `$OPENCODEX_HOME/config.json` | 프로바이더, 기본 프로바이더, 포트, 옵션. |
 | `$OPENCODEX_HOME/ocx.pid` | 실행 중인 프록시의 PID(단일 인스턴스 가드). |
-| `$OPENCODEX_HOME/runtime-port.json` | 자동으로 고른 대체 포트를 포함한 현재 PID, 호스트명, 포트. |
+| `$OPENCODEX_HOME/runtime-port.json` | 현재 PID, 호스트명, 포트. `config.port`가 `0`이면 OS가 할당한 포트도 포함합니다. |
 | `$OPENCODEX_HOME/auth.json` | 저장된 OAuth 자격 증명(`ocx login` 시). |
 | `$OPENCODEX_HOME/catalog-backup*.json` | opencodex가 수정하기 전에 만든 Codex 모델 카탈로그 백업. |
 | `$CODEX_HOME/config.toml` | 로컬 전용 구성에서는 opencodex가 관리하는 루트 `openai_base_url`을 추가합니다. 로컬이 아닌 주소에 바인딩할 때는 Codex가 API 인증 헤더를 보낼 수 있도록 `model_provider = "opencodex"`와 `[model_providers.opencodex]`를 사용합니다. |

@@ -39,7 +39,7 @@ ocx start --port 8080
 - 프로바이더가 지원하는 경우 실시간 모델을 찾아 네이티브와 라우팅 항목을 **Codex 모델 카탈로그에 동기화**하고,
 - `http://localhost:<port>/v1`에서 수신 대기합니다.
 
-요청한 포트가 이미 사용 중이면 `ocx start`가 빈 포트를 고르고, 그 값을 `runtime-port.json`에 기록한 뒤 Codex가 실시간 리스너를 쓰도록 갱신합니다.
+요청한 포트가 이미 사용 중이면 `ocx start`는 실행을 멈추고 무엇이 포트를 점유하고 있는지 알려 줍니다. opencodex가 응답하면 먼저 `ocx stop`을 실행하고, 빈 포트에서 시작하려면 `ocx start --port <port>`를 사용하세요. 이제 다른 포트로 자동 이동하지 않습니다. 이전 동작은 프록시 두 개를 동시에 실행한 채 Codex가 나중에 시작한 프록시를 가리키게 했습니다.
 
 확인:
 

@@ -18,10 +18,13 @@ Codex 자동 시작 shim도 설치합니다.
 
 ### `ocx start [--port <port>] [--socks5 [host:port] | --socks5-off]`
 
-프록시 서버를 시작합니다(권장 포트는 `10100`). 해당 포트가 이미 사용 중이면 opencodex가 다른
-사용 가능한 포트를 골라 기록합니다. PID와 런타임 포트 상태를 기록하고, 두 번째 활성 인스턴스는 시작하지
-않습니다. 시작할 때는 각 공급자의 모델을 Codex 카탈로그로 동기화합니다. 종료할 때는 기본 Codex를
-복원합니다. 단, 관리형 서비스로 실행한 경우(`OCX_SERVICE=1`)는 예외입니다.
+프록시 서버를 시작합니다(권장 포트는 `10100`). PID와 런타임 포트 상태를 기록하고, 두 번째 활성
+인스턴스는 시작하지 않습니다. 권장 포트가 이미 사용 중이면 `start`가 점유자를 확인한 뒤 어느 경우든
+실행을 멈춥니다. opencodex가 응답하면 시작을 거부하고, 그렇지 않으면 점유자를 식별할 수 없다고
+알립니다. 첫 번째 프록시를 실행한 채 Codex가 두 번째 프록시를 가리키게 되므로, 리스너를 다른 포트로
+자동 이동하지 않습니다. 다른 포트는 `--port`로 지정하거나, OS에 포트 할당을 요청하려면 구성에서
+`port: 0`을 설정하세요. 시작할 때는 각 공급자의 모델을 Codex 카탈로그로 동기화합니다. 종료할 때는
+기본 Codex를 복원합니다. 단, 관리형 서비스로 실행한 경우(`OCX_SERVICE=1`)는 예외입니다.
 
 `--socks5`(기본값 `127.0.0.1:10808`)는 SOCKS5 URL을 `config.proxy`에 저장하고 실제 SOCKS5
 터널을 통해 송신 HTTP(S) 요청을 전달합니다. `--socks5-off`는 저장된 SOCKS5 프록시만 지우며

@@ -18,10 +18,14 @@ optionally installs the Codex autostart shim.
 
 ### `ocx start [--port <port>] [--socks5 [host:port] | --socks5-off]`
 
-Start the proxy server (preferred port `10100`). If that port is occupied, opencodex selects and
-records another available port. It writes PID/runtime-port state and refuses to start a second live
-instance. On start it syncs each provider's models into Codex's catalog. On shutdown it restores
-native Codex — unless it was launched as a managed service (`OCX_SERVICE=1`).
+Start the proxy server (preferred port `10100`). It writes PID/runtime-port state and refuses to
+start a second live instance. When the preferred port is occupied, `start` asks the holder who it
+is and stops either way: it refuses outright when an opencodex answers there, and reports an
+unidentified holder otherwise. It never moves the listener to another port on its own, because that
+would leave the first proxy running and re-point Codex at the second. Name a different port with
+`--port`, or set `port: 0` in the config to ask the OS for one. On start it syncs each provider's
+models into Codex's catalog. On shutdown it restores native Codex — unless it was launched as a
+managed service (`OCX_SERVICE=1`).
 
 `--socks5` (default `127.0.0.1:10808`) saves `config.proxy` as a SOCKS5 URL and routes outbound
 HTTP(S) through a real SOCKS5 tunnel. `--socks5-off` clears only that saved SOCKS5 proxy; it

@@ -83,7 +83,7 @@ bun run dev:gui     # запускает dev-сервер панели упра
 | --- | --- |
 | `$OPENCODEX_HOME/config.json` | Ваши провайдеры, провайдер по умолчанию, порт и параметры. |
 | `$OPENCODEX_HOME/ocx.pid` | PID запущенного прокси (защита от повторного запуска). |
-| `$OPENCODEX_HOME/runtime-port.json` | Текущие PID, имя хоста и порт, включая автоматически выбранный запасной порт. |
+| `$OPENCODEX_HOME/runtime-port.json` | Текущие PID, имя хоста и порт, включая порт, назначенный ОС, когда `config.port` равен `0`. |
 | `$OPENCODEX_HOME/auth.json` | Сохранённые учётные данные OAuth (после `ocx login`). |
 | `$OPENCODEX_HOME/catalog-backup*.json` | Резервные копии каталога моделей Codex, создаваемые перед тем, как opencodex его изменит. |
 | `$CODEX_HOME/config.toml` | На loopback-адресе opencodex добавляет корневой `openai_base_url`, отмеченный собственным маркером; при привязке не к loopback используются `model_provider = "opencodex"` и `[model_providers.opencodex]`, чтобы Codex мог отправлять заголовок API-аутентификации. |

@@ -50,8 +50,10 @@ ocx start --port 8080
   маршрутизируемые записи в каталог моделей Codex**,
 - слушает `http://localhost:<port>/v1`.
 
-Если запрошенный порт занят, `ocx start` выбирает свободный порт, записывает его в
-`runtime-port.json` и обновляет настройки Codex, чтобы тот использовал актуальный адрес.
+Если запрошенный порт занят, `ocx start` останавливается и сообщает, какой процесс его удерживает:
+если там отвечает opencodex, сначала выполните `ocx stop`; либо запустите прокси на свободном порту
+через `ocx start --port <port>`. Команда не переходит на другой порт сама — раньше из-за этого два
+прокси продолжали работать одновременно, а Codex перенаправлялся на более новый.
 
 Проверьте:
 

@@ -20,9 +20,13 @@ opencodex и его интеграцию с Codex.
 
 ### `ocx start [--port <port>] [--socks5 [host:port] | --socks5-off]`
 
-Запустить proxy server (предпочтительный порт `10100`). Если этот порт занят, opencodex выбирает и
-записывает другой свободный порт. При запуске пишется состояние PID/runtime-port, а попытка
-поднять второй живой экземпляр отвергается. На старте прокси синхронизирует модели каждого
+Запустить proxy server (предпочтительный порт `10100`). При запуске пишется состояние
+PID/runtime-port, а попытка поднять второй живой экземпляр отвергается. Если предпочтительный порт
+занят, `start` проверяет, кто его удерживает, и в любом случае останавливается: он отказывается от
+запуска, если там отвечает opencodex, а иначе сообщает о неопознанном владельце порта. Прокси
+никогда сам не переносит listener на другой порт, поскольку тогда первый прокси продолжил бы
+работать, а Codex был бы перенаправлен на второй. Укажите другой порт через `--port` или задайте
+`port: 0` в конфигурации, чтобы порт назначила ОС. На старте прокси синхронизирует модели каждого
 провайдера в каталог Codex. При shutdown он восстанавливает native Codex — если только прокси не
 был запущен как managed service (`OCX_SERVICE=1`).