fix(openclaw): fix gateway status detection and improve error reporting by DeJeune · Pull Request #13433 · CherryHQ/cherry-studio

DeJeune · 2026-03-13T06:08:13Z

What this PR does

Before this PR:

getStatus only probed health when status was stopped or error. If the gateway crashed while status was running, the UI would never detect the crash and keep showing "运行中" (running).
checkHealth probed the gateway but never updated gatewayStatus, so a failed health check had no lasting effect.
startAndWaitForGateway spawned the process with stdio: 'ignore', discarding stderr. On startup failure, the user only saw "gateway exited with code 1" with no actionable detail.
parseUpdateStatus matched any update channel (npm, pkg, binary), causing false positives for binary-installed users when only an npm/pkg update was available.

After this PR:

getStatus probes health in all non-starting states, transitioning running → stopped when the gateway is unreachable.
checkHealth syncs gatewayStatus to stopped when the probe returns unhealthy.
startAndWaitForGateway pipes stderr and extracts the first 3 lines of error output for meaningful error messages.
parseUpdateStatus only matches binary-channel updates, ignoring npm/pkg channels.
29 new state-machine tests cover all gateway status transitions and lifecycle scenarios.

Fixes #

Why we need it and why it was done in this way

The gateway status was a one-way latch: once set to running, it could only be changed by an explicit stopGateway call. External crashes (process killed, config errors, port conflicts) left the UI in an incorrect state.

The following tradeoffs were made:

getStatus now always calls probeGatewayHealth (except during starting). This adds a small overhead per status poll, but is necessary for correctness since the gateway process lifecycle is independent (detached).
stderr capture uses ['ignore', 'ignore', 'pipe'] instead of full 'pipe' to minimize resource usage — we only need stderr for error diagnostics.

The following alternatives were considered:

Keeping a persistent health-check interval timer — rejected as over-engineered for the current polling-based UI.
Parsing the full openclaw update status table structure — rejected in favor of simple regex matching on the binary channel keyword.

Breaking changes

None.

Special notes for your reviewer

The parseUpdateStatus change means users who installed OpenClaw via npm will no longer see update notifications in Cherry Studio. This is intentional — Cherry Studio only manages binary installations.
The test file grew significantly (from 90 lines to 595 lines) because this is the first time the OpenClawService class has state-machine test coverage.

Checklist

PR: The PR description is expressive enough and will help future contributors
Code: Write code that humans can understand and Keep it simple
Refactor: You have left the code cleaner than you found it (Boy Scout Rule)
Upgrade: Impact of this change on upgrade flows was considered and addressed if required
Documentation: A user-guide update was considered and is present (link) or not required. Check this only when the PR introduces or changes a user-facing feature or behavior.
Self-review: I have reviewed my own code (e.g., via /gh-pr-review, gh pr diff, or GitHub UI) before requesting review from others

Release note

fix(openclaw): gateway status now correctly detects crashed/externally-stopped gateways; startup errors show detailed messages instead of generic exit codes; update checker only reports binary-channel updates

- getStatus now probes health in all states (not just stopped/error), detecting crashed gateways that still show as 'running' - checkHealth syncs gatewayStatus to 'stopped' when probe returns unhealthy - startAndWaitForGateway captures stderr (via pipe) to surface meaningful error messages instead of generic "gateway exited with code 1" - parseUpdateStatus only matches binary-channel updates, ignoring npm/pkg channels that require a different upgrade path - Add 29 state-machine tests covering getStatus, checkHealth, startGateway, stopGateway, restartGateway, and full lifecycle transitions Co-Authored-By: Claude Opus 4.6 <[email protected]> Signed-off-by: suyao <[email protected]>

kangfenmao · 2026-03-13T10:14:39Z

…erflow Add max-h-25, overflow-y-auto, and break-all to the error message span so long error texts (stack traces, config errors) don't blow out the layout vertically or horizontally. Co-Authored-By: Claude Opus 4.6 <[email protected]> Signed-off-by: suyao <[email protected]>

DeJeune · 2026-03-13T10:30:13Z

fixed

kangfenmao · 2026-03-13T10:41:44Z

Note

This issue/comment/review was translated by Claude.

Environment variable configuration
Use openclaw.json as configuration file
Process state management

Original Content

环境变量配置
使用 openclaw.json 作为配置文件
进程状态管理

The gateway is not registered as a system service, so restart is not applicable. Remove the restart method, IPC channel, UI button, and related tests. Co-Authored-By: Claude Opus 4.6 <[email protected]> Signed-off-by: suyao <[email protected]>

…herry config Migrate from openclaw.cherry.json back to openclaw.json so that the CLI can also read the config without needing the OPENCLAW_CONFIG_PATH env var override. Co-Authored-By: Claude Opus 4.6 <[email protected]> Signed-off-by: suyao <[email protected]>

Add migration logic to handle existing users who have the old openclaw.cherry.json config file. Renames it to openclaw.json if no default config exists, otherwise removes the legacy file. Co-Authored-By: Claude Opus 4.6 <[email protected]> Signed-off-by: suyao <[email protected]>

…nstall On macOS/Linux, symlink the openclaw binary to /usr/local/bin so it is accessible from the command line. On Windows, add the bin directory to the user PATH via the registry. Both are cleaned up on uninstall. Co-Authored-By: Claude Opus 4.6 <[email protected]> Signed-off-by: suyao <[email protected]>

…SS class order When both openclaw.json and openclaw.cherry.json exist, back up the default config and use the cherry config since it contains the user's Cherry Studio settings. Also fix Biome CSS class sort order. Co-Authored-By: Claude Opus 4.6 <[email protected]> Signed-off-by: suyao <[email protected]>

…requests for improved performance

kangfenmao

Note

This review was translated by Claude.

Review Summary

✅ Approved

Core Improvements:

Gateway Status Detection - Changed from Socket detection to HTTP request, more reliable
Health Check Sync - Correctly updates gatewayStatus on failure
Error Messages - Captures stderr to display detailed errors, no longer just code 1
Update Detection - Only matches binary channels to avoid false positives
Configuration Migration - Automatically handles openclaw.cherry.json → openclaw.json
CLI Installation - Supports macOS/Linux symlinks and Windows PATH

Test Coverage:

✅ Added 29 state machine tests
✅ Covers complete lifecycle

Code Quality:

Clear commit messages
Comprehensive backward compatibility handling
Biome CSS class sorting fixes

**LGTM! 👍

Original Content

审查总结

✅ 批准合并

核心改进:

网关状态检测 - 从 Socket 探测改为 HTTP 请求，更可靠
健康检查同步 - 失败时正确更新 gatewayStatus
错误信息 - 捕获 stderr 显示详细错误，不再是 code 1
更新检测 - 只匹配 binary 通道，避免误报
配置迁移 - 自动处理 openclaw.cherry.json → openclaw.json
CLI 安装 - 支持 macOS/Linux 软链和 Windows PATH

测试覆盖:

✅ 新增 29 个状态机测试
✅ 覆盖完整生命周期

代码质量:

清晰的提交信息
完善的向后兼容处理
Biome CSS 类排序修复

**LGTM! 👍

… consistency

…ompatibility on Windows fix(process): ensure console window is hidden on Windows during cross-platform spawn fix(openclaw): enhance process spawning on Windows to hide console window fix(openclaw): update Windows process spawning to use PowerShell for hidden console window fix(openclaw): update gateway process spawning to avoid console window on Windows

…ference and updating stop logic

GeorgeDong32

Note

This review was translated by Claude.

Code review passed.

Review Conclusion: Approve

Key Fixes:

✅ Gateway state machine fixes - Now correctly detects external crashes/stops
✅ Startup error reporting improvements - Captures stderr for detailed error information
✅ Update detection refinement - Only detects binary channel updates

Code Quality:

Added 29 state machine tests with comprehensive coverage
Follows project coding standards
No security risks

Optional Optimizations (non-blocking):

Consider adding stderr size limit (~10KB) to prevent memory accumulation
Consider downgrading checkHealth failures to info log level

Review by kimi-k2.5

Original Content

代码审查通过。

审查结论: Approve

关键修复:

✅ Gateway 状态机修复 - 现在正确检测外部崩溃/停止
✅ 启动错误报告改进 - 捕获 stderr 显示详细错误信息
✅ 更新检测精准化 - 只检测 binary 渠道更新

代码质量:

新增 29 个状态机测试，覆盖全面
遵循项目编码规范
无安全风险

可选优化 (非阻塞):

考虑添加 stderr 大小限制 (~10KB) 防止内存累积
checkHealth 失败可考虑降为 info 日志级别

Review by kimi-k2.5

When openclaw respawns itself internally, the original process reference becomes stale. Now stopGateway falls back to killing whatever process occupies the gateway port via lsof/netstat. startGateway also stops stale gateways before starting a new one instead of reporting port-in-use errors. Co-Authored-By: Claude Opus 4.6 <[email protected]> Signed-off-by: suyao <[email protected]>

checkPortOpen used 'localhost' which may resolve to IPv6 [::1], causing false positives when the gateway only listens on IPv4. This made startGateway report "port already in use" even when the port was actually free. Align with health check by using 127.0.0.1 explicitly. Also add debug logging to port checks. Co-Authored-By: Claude Opus 4.6 <[email protected]> Signed-off-by: suyao <[email protected]>

…n handling

…tability

DeJeune force-pushed the DeJeune/fix-checkportopen branch from a12224e to af22702 Compare March 13, 2026 06:58

DeJeune marked this pull request as draft March 13, 2026 09:12

DeJeune marked this pull request as ready for review March 13, 2026 10:13

DeJeune requested a review from 0xfullex as a code owner March 13, 2026 10:53

DeJeune and others added 5 commits March 13, 2026 19:04

fix(openclaw): refactor gateway status and health checks to use HTTP …

f4bff51

…requests for improved performance

kangfenmao approved these changes Mar 13, 2026

View reviewed changes

kangfenmao added 2 commits March 13, 2026 19:53

fix(openclaw): refactor health check methods for improved clarity and…

9aafb87

… consistency

kangfenmao force-pushed the DeJeune/fix-checkportopen branch from a895545 to f116d71 Compare March 13, 2026 13:13

fix(openclaw): manage gateway process lifecycle by storing process re…

379285f

…ference and updating stop logic

GeorgeDong32 approved these changes Mar 13, 2026

View reviewed changes

DeJeune and others added 4 commits March 14, 2026 00:13

fix(openclaw): update gateway process management for improved shutdow…

adedf67

…n handling

fix(openclaw): remove direct gateway process kill test for improved s…

1717052

…tability

kangfenmao merged commit 774cb7a into main Mar 14, 2026
7 checks passed

kangfenmao deleted the DeJeune/fix-checkportopen branch March 14, 2026 13:25

kangfenmao mentioned this pull request Mar 15, 2026

[Bug]: OpenClaw gateway fails to start on Windows and times out after 30000ms #13477

Closed

5 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(openclaw): fix gateway status detection and improve error reporting#13433

fix(openclaw): fix gateway status detection and improve error reporting#13433
kangfenmao merged 15 commits intomainfrom
DeJeune/fix-checkportopen

DeJeune commented Mar 13, 2026

Uh oh!

kangfenmao commented Mar 13, 2026

Uh oh!

DeJeune commented Mar 13, 2026

Uh oh!

kangfenmao commented Mar 13, 2026 •

edited

Loading

Uh oh!

kangfenmao left a comment •

edited

Loading

Uh oh!

GeorgeDong32 left a comment •

edited by kangfenmao

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

DeJeune commented Mar 13, 2026

What this PR does

Why we need it and why it was done in this way

Breaking changes

Special notes for your reviewer

Checklist

Release note

Uh oh!

kangfenmao commented Mar 13, 2026

Uh oh!

DeJeune commented Mar 13, 2026

Uh oh!

kangfenmao commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kangfenmao left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Review Summary

✅ Approved

审查总结

✅ 批准合并

Uh oh!

GeorgeDong32 left a comment • edited by kangfenmao Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kangfenmao commented Mar 13, 2026 •

edited

Loading

kangfenmao left a comment •

edited

Loading

GeorgeDong32 left a comment •

edited by kangfenmao

Loading