lidge-jun · lidge-jun · Sep 13, 2026 · Sep 13, 2026 · Sep 13, 2026 · chatgpt-codex-connector
@@ -155,6 +155,22 @@ Si des processus Codex `app-server` de longue durée sont encore actifs, `ocx sy
 
 Invalide le cache local du sélecteur de modèles de Codex afin qu’il soit reconstruit à partir du catalogue opencodex actif. Le même avertissement concernant un `app-server` obsolète et le même comportement facultatif `--restart-codex` que pour `ocx sync` s’appliquent.
 
+### `ocx catalog pull <https-url> [--auth-env <NAME>] [--json] [--restart-codex]`
+
+Installe un catalogue complet servi par le point de terminaison `/v1/catalog` d'une autre instance
+OpenCodex, puis synchronise `models_cache.json`. L'URL doit être en HTTPS ; le HTTP est accepté
+uniquement en loopback. Les identifiants intégrés à l'URL, les requêtes, les fragments, les
+redirections, les réponses trop volumineuses et les catalogues invalides sont refusés avant toute
+écriture locale. L'authentification est facultative et lue uniquement par référence à une variable
+d'environnement (`--auth-env`), jamais depuis argv.
+
+Le catalogue et le cache sont écrits sous le verrou de catalogue Codex partagé ; un échec préserve
+les derniers fichiers valides connus. Des octets identiques constituent une non-opération qui
+préserve les mtimes. `--restart-codex` ne s'applique qu'après une écriture réelle. Les requêtes
+conditionnelles `ETag` et le redémarrage de l'application Desktop ne font pas partie de cette
+commande. Voir la [référence anglaise](/reference/cli/lifecycle/) pour l'enveloppe `--json`
+complète et les codes de sortie.
+
 ## Service d’arrière-plan
 
 ### `ocx service [install|repair|restart|start|stop|status|uninstall|remove]`

@@ -92,6 +92,10 @@ local login state, and `ocx config show` on a client prints a `_remoteHub` note
 credentials and model availability live on the hub. The hub read uses the per-client data key
 only; no admin token and no provider secret ever reaches a client.
 
+`ocx status` makes a live hub-state request only when the saved connection still matches the
+status snapshot and the data-token file matches that connection. If either check fails, it skips
+the request and shows matching cached hub state, or `unavailable` if no matching cache exists.
+
 ## Linux systemd or macOS launchd
 
 Bind the data listener to the hub's Tailscale address, enable the loopback companion so the hub's

@@ -158,6 +158,20 @@ ocx status --json
 
 Codex のローカル モデル ピッカー キャッシュを無効にし、アクティブな opencodex カタログから再構築されるようにします。 `ocx sync` と同じ、古い `app-server` 警告とオプションの `--restart-codex` 動作が適用されます。
 
+### `ocx catalog pull <https-url> [--auth-env <NAME>] [--json] [--restart-codex]`
+
+別の OpenCodex インスタンスの `/v1/catalog` エンドポイントが提供する完全なカタログをインストール
+し、続いて `models_cache.json` を同期します。URL は HTTPS が必須で、HTTP はループバックのみ許可
+されます。URL 埋め込み資格情報、クエリ、フラグメント、リダイレクト、サイズ超過の応答、不正な
+カタログは、ローカル書き込みの前に拒否されます。認証は任意で、環境変数参照 (`--auth-env`) から
+のみ読み取られ、argv からは読み取られません。
+
+カタログとキャッシュは共有の Codex カタログロックの下で書き込まれ、失敗時は last-known-good の
+ファイルが保持されます。バイトが同一の場合は mtime を保持する no-op です。`--restart-codex` は
+実際の書き込みの後にのみ適用されます。`ETag` 条件付きリクエストと Desktop アプリの再起動は、この
+コマンドには含まれません。`--json` エンベロープと終了コードの詳細は
+[英語版リファレンス](/reference/cli/lifecycle/)を参照してください。
+
 ## バックグラウンドサービス
 
 ### `ocx service [install|repair|restart|start|stop|status|uninstall|remove]`

@@ -36,6 +36,13 @@ ocx sync
 
 허브가 발급한 클라이언트별 키는 권한이 제한된 `service-api-token` 파일에 저장됩니다. `config.json`에는 저장되지 않습니다. 연결 중 사용량은 허브 기록에서 해당 `apiKeyId`만 조회하고, 연결을 끊은 뒤에는 로컬 기록을 봅니다. 두 기록은 서로 복제되지 않습니다.
 
+### 연결된 클라이언트의 상태 표시
+
+연결된 클라이언트의 `ocx status`는 허브 상태를 표시합니다. 상태 수집 중 연결 정보가
+바뀌거나 데이터 토큰 파일이 현재 연결과 일치하지 않으면 실시간 허브 조회를 건너뜁니다.
+이때 상태 조회 대상 연결의 캐시를 표시하고, 일치하는 캐시가 없으면 `unavailable`로 보고합니다.
+`ocx status --json`의 `remoteHub.stateSource`는 `hub`, `cache`, `unavailable` 중 하나입니다.
+
 ## systemd 또는 launchd
 
 데이터 리스너는 허브의 Tailscale 주소에 바인드하고, 허브 자신의 프로세스가 같은 포트를 자격 증명 없이 쓸 수 있도록 루프백 companion을 켜고, 관리 평면은 따로 공개합니다. 아래 값은 예시입니다.

@@ -236,6 +236,18 @@ single-flight/lock 파일을 만들 수 있는지, 건강하지 않은 OAuth 또
 Codex의 로컬 모델 선택기 캐시를 무효화하여, 활성 opencodex 카탈로그에서 다시 빌드되게 합니다.
 `ocx sync`와 같은 오래된 `app-server` 경고와 선택적 `--restart-codex` 동작이 적용됩니다.
 
+### `ocx catalog pull <https-url> [--auth-env <NAME>] [--json] [--restart-codex]`
+
+다른 OpenCodex 인스턴스의 `/v1/catalog` 엔드포인트가 제공하는 완성된 카탈로그를 설치한 뒤
+`models_cache.json`을 맞춥니다. URL은 HTTPS여야 하고 HTTP는 루프백만 허용합니다. URL에 박힌
+자격증명, 쿼리, 프래그먼트, 리다이렉트, 크기를 넘는 응답, 잘못된 카탈로그는 로컬에 쓰기 전에
+거절합니다. 인증은 선택이며 환경변수 이름(`--auth-env`)으로만 읽고 argv로는 받지 않습니다.
+
+카탈로그와 캐시는 공유 Codex 카탈로그 잠금 아래에서 쓰고, 실패하면 직전까지 정상이던 파일을
+그대로 둡니다. 바이트가 같으면 mtime까지 건드리지 않는 no-op입니다. `--restart-codex`는 실제로
+쓴 뒤에만 적용됩니다. `ETag` 조건부 요청과 Desktop 앱 재시작은 이 명령에 없습니다. `--json`
+envelope 필드와 종료 코드는 [영문 레퍼런스](/reference/cli/lifecycle/)를 보세요.
+
 ## 백그라운드 서비스
 
 ### `ocx service [install|repair|restart|start|stop|status|uninstall|remove]`

@@ -282,6 +282,60 @@ were updated. Pass `--restart-codex` to send `SIGTERM` only to matching `codex
 Invalidate Codex's local model picker cache so it is rebuilt from the active opencodex catalog. The
 same stale-`app-server` warning and optional `--restart-codex` behavior as `ocx sync` apply.
 
+### `ocx catalog pull <https-url> [--auth-env <NAME>] [--json] [--restart-codex]`
+
+Install a complete catalog served by another OpenCodex instance's `/v1/catalog` endpoint, then
+synchronize `models_cache.json`. Unlike `ocx sync`, this command does not discover configured
+providers or inject Codex configuration. Unlike `ocx sync-cache`, it replaces the active catalog
+before rebuilding the cache. It works even when the local Codex integration desired state is off.
+
+The URL must be HTTPS; loopback HTTP is accepted for local testing. Embedded URL credentials,
+queries, fragments, redirects, oversized responses, malformed JSON, duplicate or unsafe slugs, and
+unknown `input_modalities` are refused before any local write. Authentication is optional and is
+read only by environment-variable reference:
+
+```bash
+export OPENCODEX_CATALOG_AUTH_TOKEN='...'
+ocx catalog pull https://proxy.example.com/v1/catalog \
+  --auth-env OPENCODEX_CATALOG_AUTH_TOKEN
+```
+
+The value is sent as a Bearer token but is never accepted as an argv value. Redirects are refused,
+so authorization cannot cross origins. Catalog and cache writes use the shared Codex catalog lock
+and atomic writer. A failed fetch, validation, lock acquisition, catalog write, or cache rebuild
+preserves the last-known-good files. Identical catalog bytes are a no-op that preserves mtimes and
+never touches processes. `--restart-codex` applies only after a real write and remains explicit;
+Desktop restart is not part of this command.
+
+The URL must name `/v1/catalog` at the host root. A reverse proxy that serves the endpoint under a
+path prefix is not supported by this command.
+
+Two behaviors are deliberately out of scope in this first cut. The command downloads the full
+catalog and compares bytes locally instead of issuing an `ETag` / `If-None-Match` conditional
+request, and it has no Windows `--restart-desktop-app`. Identical bytes are treated as a complete
+no-op, so a home whose catalog is correct but whose `models_cache.json` is missing or stale is not
+repaired by this command; use `ocx sync-cache` for that.
+
+`--json` emits one stable envelope on stdout. `schemaVersion`, `ok`, `status`, `catalogWritten`,
+`cacheSynced`, and `codexRestarted` are always present. `status` is `updated`, `unchanged`, or
+`failed`. A successful pull adds `modelCount`; a failure adds `code`, which is the field a script
+branches on:
+
+| `code` | Meaning | Exit |
+| --- | --- | --- |
+| `usage` | The arguments were not a valid `catalog pull` invocation | 2 |
+| `auth_env_missing` | `--auth-env` named a variable that is not set | 1 |
+| `url_invalid`, `insecure_http_refused` | The URL was refused before any request | 1 |
+| `request_failed`, `redirect_refused`, `http_error` | The request did not produce a usable response | 1 |
+| `body_too_large`, `body_invalid`, `catalog_invalid` | The response was refused before any local write | 1 |
+| `write_failed`, `lock_database`, `unsafe_path` | The coordinated write did not complete; files are unchanged | 1 |
+| `lock_busy` | Another writer holds the Codex catalog lock | 3 |
+| `restart_incomplete` | The catalog and cache landed, but a Codex app-server survived `--restart-codex` | 1 |
+
+`restart_incomplete` is the one failure that reports real writes: `catalogWritten` and
+`cacheSynced` stay true and `ok` is false, because a surviving app-server still serves the
+previous catalog from memory.
+
 ## Background service
 
 ### `ocx service [install|repair|restart|start|stop|status|uninstall|remove]`

@@ -232,6 +232,20 @@ credential'ы и не выполняет repair.
 opencodex. Предупреждение о stale-`app-server` и optional `--restart-codex` работают так же, как
 и у `ocx sync`.
 
+### `ocx catalog pull <https-url> [--auth-env <NAME>] [--json] [--restart-codex]`
+
+Устанавливает полный каталог, который отдаёт эндпоинт `/v1/catalog` другого экземпляра OpenCodex,
+и затем синхронизирует `models_cache.json`. URL должен быть HTTPS; HTTP допускается только на
+loopback. Учётные данные в URL, query, фрагменты, редиректы, слишком большие ответы и невалидные
+каталоги отклоняются до любой локальной записи. Аутентификация необязательна и читается только по
+имени переменной окружения (`--auth-env`), но не из argv.
+
+Каталог и кэш пишутся под общей блокировкой каталога Codex; при сбое сохраняются last-known-good
+файлы. Идентичные байты — это no-op, сохраняющий mtime. `--restart-codex` применяется только после
+реальной записи. Условные запросы `ETag` и перезапуск Desktop-приложения в эту команду не входят.
+Полная `--json`-обёртка и коды выхода описаны в
+[английской справке](/reference/cli/lifecycle/).
+
 ## Фоновая служба
 
 ### `ocx service [install|repair|restart|start|stop|status|uninstall|remove]`

@@ -242,6 +242,21 @@ Codex'in yerel model seçici önbelleğini geçersiz kılın, böylece aktif ope
 kataloğundan yeniden oluşturulur. `ocx sync` ile aynı eski `app-server` uyarısı
 ve isteğe bağlı `--restart-codex` davranışı geçerlidir.
 
+### `ocx catalog pull <https-url> [--auth-env <NAME>] [--json] [--restart-codex]`
+
+Başka bir OpenCodex örneğinin `/v1/catalog` uç noktasının sunduğu eksiksiz kataloğu kurar ve
+ardından `models_cache.json` dosyasını eşitler. URL HTTPS olmalıdır; HTTP yalnızca loopback için
+kabul edilir. URL içine gömülü kimlik bilgileri, sorgular, parçalar, yönlendirmeler, boyutu aşan
+yanıtlar ve geçersiz kataloglar, herhangi bir yerel yazma işleminden önce reddedilir. Kimlik
+doğrulama isteğe bağlıdır ve yalnızca ortam değişkeni adıyla (`--auth-env`) okunur, argv'den
+alınmaz.
+
+Katalog ve önbellek, paylaşılan Codex katalog kilidi altında yazılır; bir hata durumunda
+last-known-good dosyalar korunur. Aynı baytlar, mtime değerlerini koruyan bir no-op'tur.
+`--restart-codex` yalnızca gerçek bir yazmadan sonra uygulanır. `ETag` koşullu istekleri ve Desktop
+uygulamasının yeniden başlatılması bu komutun kapsamında değildir. Tam `--json` zarfı ve çıkış
+kodları için [İngilizce referansa](/reference/cli/lifecycle/) bakın.
+
 ## Arka plan servisi
 
 ### `ocx service [install|repair|restart|start|stop|status|uninstall|remove]`

@@ -154,6 +154,12 @@ ocx status --json
 
 使 Codex 的本地模型选择器缓存失效，让它根据当前激活的 opencodex 目录重新生成。与 `ocx sync` 相同的陈旧 `app-server` 警告和可选 `--restart-codex` 行为同样适用。
 
+### `ocx catalog pull <https-url> [--auth-env <NAME>] [--json] [--restart-codex]`
+
+安装由另一个 OpenCodex 实例的 `/v1/catalog` 端点提供的完整目录，然后同步 `models_cache.json`。URL 必须是 HTTPS；仅回环地址允许 HTTP。URL 内嵌凭据、查询、片段、重定向、超出大小的响应以及无效目录，都会在任何本地写入之前被拒绝。认证是可选的，并且只通过环境变量名（`--auth-env`）读取，不接受 argv 传入。
+
+目录和缓存在共享的 Codex 目录锁下写入；失败时保留 last-known-good 文件。字节完全相同时是保留 mtime 的空操作。`--restart-codex` 仅在发生真实写入之后生效。`ETag` 条件请求和 Desktop 应用重启不属于此命令。完整的 `--json` 信封与退出码请参见[英文参考](/reference/cli/lifecycle/)。
+
 ## 后台服务
 
 ### `ocx service [install|repair|restart|start|stop|status|uninstall|remove]`

@@ -148,6 +148,12 @@ ocx status --json
 
 使 Codex 的本機模型選擇器快取失效，使其從現用的 opencodex 目錄重建。與 `ocx sync` 相同的過時 `app-server` 警告與可選的 `--restart-codex` 行為適用。
 
+### `ocx catalog pull <https-url> [--auth-env <NAME>] [--json] [--restart-codex]`
+
+安裝由另一個 OpenCodex 執行個體的 `/v1/catalog` 端點提供的完整目錄，接著同步 `models_cache.json`。URL 必須是 HTTPS；僅回送位址允許 HTTP。URL 內嵌憑證、查詢、片段、重新導向、超出大小的回應以及無效目錄，都會在任何本機寫入之前遭拒。驗證為選用，且只透過環境變數名稱（`--auth-env`）讀取，不接受 argv 傳入。
+
+目錄與快取在共用的 Codex 目錄鎖之下寫入；失敗時保留 last-known-good 檔案。位元組完全相同時是保留 mtime 的無操作。`--restart-codex` 僅在實際寫入之後生效。`ETag` 條件式請求與 Desktop 應用程式重新啟動不屬於此命令。完整的 `--json` 信封與結束碼請參見[英文參考](/reference/cli/lifecycle/)。
+
 ## 背景服務
 
 ### `ocx service [install|repair|restart|start|stop|status|uninstall|remove]`

@@ -282,6 +282,7 @@
     "catalog-input-modality-enum.test.ts": "codex-integration",
     "catalog-llamacpp-capabilities.test.ts": "codex-integration",
     "catalog-oauth-observation.test.ts": "codex-integration",
+    "catalog-remote-pull.test.ts": "codex-integration",
     "catalog-retain-models.test.ts": "codex-integration",
     "catalog-verbosity-default.test.ts": "codex-integration",
     "catalog-vision-sidecar-modalities.test.ts": "codex-integration",