Skip to content

fix(service): complete the repair migration — docs, startup health, doctor, and update advice #991

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lidge-jun merged 6 commits into from
Aug 4, 2026
Merged

fix(service): complete the repair migration — docs, startup health, doctor, and update advice #991

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ba68e90
docs(service): document the repair subcommand and fix the stale launc…
lidge-jun Aug 4, 2026
bee1cc7
fix(startup): recommend repair for an installed service, not re-regis…
lidge-jun Aug 4, 2026
0662e34
fix(service): finish the repair migration across update, doctor, and …
lidge-jun Aug 4, 2026
b3dfdc2
fix(startup): keep the repair choice across the health cache and the …
lidge-jun Aug 4, 2026
a632c87
fix(service): the auth preflight must not recommend a command that re…
lidge-jun Aug 4, 2026
362771a
test(service): make the preflight guard call the production selector
lidge-jun Aug 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs-site/src/content/docs/ja/reference/cli/lifecycle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,14 +135,15 @@ Codex のローカル モデル ピッカー キャッシュを無効にし、

## バックグラウンドサービス

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

opencodex を、ログイン時に自動起動し、クラッシュ時に自動再起動するログイン管理バックグラウンド サービス (macOS **launchd**、Linux **systemd ユーザー ユニット**、Windows **タスク スケジューラ**) として実行します。サービスは `OCX_SERVICE=1` を設定して実行されるため、再起動によって Codex 設定が変更されることはありません。

|サブコマンド |アクション |
| --- | --- |
|なし |サービスを作成/更新して開始します。 |
| `install` |サービスを作成して開始します。 |
| `repair` | 既存のサービスを再登録せずに更新して再起動します。 |
| `start` |インストールされているサービスを開始します。 |
| `stop` |サービスを停止し、ネイティブ Codex を復元します。 |
| `status` |サービスとプロキシの診断とログ パスをレポートします。 |
Expand All @@ -152,6 +153,7 @@ opencodex を、ログイン時に自動起動し、クラッシュ時に自動
```bash
ocx service
ocx service install
ocx service repair
ocx service status
ocx service uninstall
```
Expand Down
4 changes: 3 additions & 1 deletion docs-site/src/content/docs/ko/reference/cli/lifecycle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -176,7 +176,7 @@ Codex의 로컬 모델 선택기 캐시를 무효화하여, 활성 opencodex 카

## 백그라운드 서비스

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

로그인 관리형 백그라운드 서비스로 opencodex를 실행합니다(macOS **launchd**, Linux **systemd** 사용자
유닛, Windows **Task Scheduler**). 로그인 시 자동 시작하고 충돌 시 자동 재시작합니다. 서비스 실행은
Expand All @@ -186,6 +186,7 @@ Codex의 로컬 모델 선택기 캐시를 무효화하여, 활성 opencodex 카
| --- | --- |
| 없음 | 서비스를 생성/업데이트하고 시작합니다. |
| `install` | 서비스를 생성하고 시작합니다. |
| `repair` | 설치된 서비스를 다시 등록하지 않고 제자리에서 새로 고친 뒤 재시작합니다. |
| `start` | 설치된 서비스를 시작합니다. |
| `stop` | 서비스를 중지하고 기본 Codex를 복원합니다. |
| `status` | 서비스와 프록시 진단, 로그 경로를 보고합니다. |
Expand All @@ -195,6 +196,7 @@ Codex의 로컬 모델 선택기 캐시를 무효화하여, 활성 opencodex 카
```bash
ocx service
ocx service install
ocx service repair
ocx service status
ocx service uninstall
```
Expand Down
10 changes: 6 additions & 4 deletions docs-site/src/content/docs/reference/cli/lifecycle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,7 @@ same stale-`app-server` warning and optional `--restart-codex` behavior as `ocx

## Background service

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

@chatgpt-codex-connector chatgpt-codex-connector Bot Aug 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Add repair to the built-in service help

The reference now advertises repair, but src/cli/help.ts still renders ocx help service and ocx service --help as ocx service [install|start|stop|status|uninstall|remove]. This leaves the shipped CLI help contradicting the newly synchronized public reference and continues to hide the recovery command from users who consult local help; update the service help entry and its CLI-help coverage alongside this heading.

AGENTS.md reference: docs-site/AGENTS.md:L7-L10

Useful? React with 👍 / 👎.


Run opencodex as a login-managed background service (macOS **launchd**, Linux **systemd user unit**,
Windows **Task Scheduler**) that auto-starts on login and auto-restarts on crash. Service runs set
Expand All @@ -184,7 +184,8 @@ Windows **Task Scheduler**) that auto-starts on login and auto-restarts on crash
| Subcommand | Action |
| --- | --- |
| none | Create/update and start the service. |
| `install` | Create and start the service. |
| `install` | Create and start the service. Registers it, which on Windows needs elevation. |
| `repair` | Refresh an installed service in place and restart it, without re-registering it. |

@chatgpt-codex-connector chatgpt-codex-connector Bot Aug 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Scope the no-registration claim to Windows

The claim that repair does not re-register the service is only true for the Windows Task Scheduler path: repairService() delegates macOS repairs to installLaunchd(), which explicitly unloads and reloads the plist, and delegates Linux repairs to the normal install/reload path. As written, this newly added cross-platform table row misdescribes macOS behavior; qualify the no-registration guarantee as Windows-specific or describe the portable guarantee that the installed backend is preserved.

AGENTS.md reference: docs-site/AGENTS.md:L5-L10

Useful? React with 👍 / 👎.

| `start` | Start an installed service. |
| `stop` | Stop the service and restore native Codex. |
| `status` | Report service and proxy diagnostics plus log paths. |
Expand All @@ -194,6 +195,7 @@ Windows **Task Scheduler**) that auto-starts on login and auto-restarts on crash
```bash
ocx service
ocx service install
ocx service repair
ocx service status
ocx service uninstall
```
Expand Down Expand Up @@ -230,9 +232,9 @@ log named in the message, and use `ocx start` to serve in the foreground meanwhi
⚠️ installed and loaded (launchd; logs: …)
Registered, but no proxy is answering on port 10100.
launchd is running an OLDER plist than the one on disk.
Fix: launchctl bootout gui/$(id -u)/com.opencodex.proxy && ocx service install
Fix: launchctl bootout gui/$(id -u)/com.opencodex.proxy && ocx service repair
Log: ~/.opencodex/service.log
Repair: ocx service install
Repair: ocx service repair
Meanwhile: ocx start (serves in the foreground)
```

Expand Down
4 changes: 3 additions & 1 deletion docs-site/src/content/docs/ru/reference/cli/lifecycle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -191,7 +191,7 @@ opencodex. Предупреждение о stale-`app-server` и optional `--res

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

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

Запустить opencodex как login-managed background service (macOS **launchd**, Linux **systemd user
unit**, Windows **Task Scheduler**), которая автоматически стартует при логине и сама
Expand All @@ -202,6 +202,7 @@ unit**, Windows **Task Scheduler**), которая автоматически
| --- | --- |
| none | Создать/обновить и запустить службу. |
| `install` | Создать и запустить службу. |
| `repair` | Обновить установленную службу на месте и перезапустить её без повторной регистрации. |
| `start` | Запустить уже установленную службу. |
| `stop` | Остановить службу и восстановить native Codex. |
| `status` | Показать диагностику службы и прокси, а также пути к логам. |
Expand All @@ -211,6 +212,7 @@ unit**, Windows **Task Scheduler**), которая автоматически
```bash
ocx service
ocx service install
ocx service repair
ocx service status
ocx service uninstall
```
Expand Down
4 changes: 3 additions & 1 deletion docs-site/src/content/docs/zh-cn/reference/cli/lifecycle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,14 +135,15 @@ ocx status --json

## 后台服务

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

将 opencodex 作为登录管理的后台服务运行（macOS **launchd**、Linux **systemd user unit**、Windows **Task Scheduler**），在登录时自动启动，在崩溃时自动重启。服务运行会设置 `OCX_SERVICE=1`，因此重启时不会反复改动 Codex 配置。

| 子命令 | 操作 |
| --- | --- |
| none | 创建/更新并启动服务。 |
| `install` | 创建并启动服务。 |
| `repair` | 就地刷新已安装的服务并重启，不重新注册。 |
| `start` | 启动已安装的服务。 |
| `stop` | 停止服务并恢复原生 Codex。 |
| `status` | 报告服务和代理诊断信息及日志路径。 |
Expand All @@ -152,6 +153,7 @@ ocx status --json
```bash
ocx service
ocx service install
ocx service repair
ocx service status
ocx service uninstall
```
Expand Down
2 changes: 1 addition & 1 deletion src/service.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2475,7 +2475,7 @@ export async function serviceStatusReport(
: null);
const staleLine = stalePlist && stalePlist.loaded && !stalePlist.matchesPlist
? " launchd is running an OLDER plist than the one on disk.\n"
+ ` Fix: launchctl bootout gui/$(id -u)/${LABEL} && ocx service install\n`
+ ` Fix: launchctl bootout gui/$(id -u)/${LABEL} && ocx service repair\n`

@chatgpt-codex-connector chatgpt-codex-connector Bot Aug 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Pin the stale-plist repair command in the service test

This changes user-facing recovery behavior, but the existing adds the bootout hint when launchd runs an older plist test in tests/service.test.ts checks only for OLDER plist and bootout, so it would still pass if this command regressed to ocx service install. Add a focused assertion for ocx service repair—ideally the complete bootout … && ocx service repair sequence—to preserve the corrected recovery path.

AGENTS.md reference: src/AGENTS.md:L22-L25

Useful? React with 👍 / 👎.

: "";

return `⚠️ ${diag.summary}\n`
Expand Down
Loading