Skip to content

feat(openclaw): binary download install, auto update check, and gateway refactor#13440

Merged
kangfenmao merged 43 commits intomainfrom
DeJeune/fix-openclaw-close
Mar 13, 2026
Merged

feat(openclaw): binary download install, auto update check, and gateway refactor#13440
kangfenmao merged 43 commits intomainfrom
DeJeune/fix-openclaw-close

Conversation

@kangfenmao
Copy link
Copy Markdown
Collaborator

What this PR does

Refactors OpenClaw installation to use direct binary downloads instead of npm, adds auto update detection, and delegates gateway lifecycle to OS service manager CLI commands.

Binary download install (replaces npm install):

  • Download pre-built binaries from GitHub releases (or gitcode.com mirror for China users)
  • Install to ~/.cherrystudio/bin/ — no npm/Node.js dependency required
  • Uninstall by simply deleting the binary file
  • Detect old npm-installed versions and prompt migration

Auto update check:

  • Automatically check for updates via openclaw update status when entering the OpenClaw page
  • Show info alert with version details when an update is available
  • Perform update via openclaw update command (stops gateway first if running)
  • Version parsing extracted to services/utils/openClawParsers.ts with inline snapshot tests

Gateway lifecycle refactor:

  • Gateway lifecycle delegated to OS service manager via openclaw gateway CLI commands
  • Removes in-process ChildProcess management, node:net Socket probing, and killProcess helper
  • Health checks use openclaw gateway health CLI command
  • getStatus is now async and probes health to detect externally-started gateways
  • Return type unified to discriminated union OperationResult

Windows-specific handling:

  • Skip gateway install/uninstall (scheduled task integration has upstream bugs)
  • Gateway started via openclaw gateway start --force
  • Port conflict detection before startup with clear error messages

UI improvements:

  • Auto update alert with "Reinstall" button when new version detected
  • Copy button on install/uninstall log container and error alerts

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

  • Binary download is faster, more reliable, and removes the npm/Node.js dependency for end users
  • openclaw update leverages the tool's built-in update mechanism rather than re-downloading
  • Delegating to OS service management (launchd/systemd) is more robust — the gateway survives app restarts
  • Version parsers are pure functions with snapshot tests to prevent regressions

Breaking changes

None. Internal refactoring only — no user-facing API changes.

Special notes for your reviewer

  • New IPC channels: OpenClaw_CheckUpdate, OpenClaw_PerformUpdate
  • New file: src/main/services/utils/openClawParsers.ts (pure parsing functions)
  • New test: src/main/services/__tests__/OpenClawService.test.ts (16 snapshot tests)
  • i18n: added openclaw.update.* and openclaw.quick_actions.check_update keys (all locales synced)
  • Windows: no service registration, gateway started with --force, port checked before startup
  • macOS/Linux: full service lifecycle via CLI commands

Checklist

Release note

feat(openclaw): switch to binary download install and add auto update check
fix(openclaw): gateway start or stop exception

DeJeune and others added 30 commits March 3, 2026 13:45
…e dead fields

- Extract repeated `{ success: boolean; message: string }` into
  `OperationResult = { success: true } | { success: false; message: string }`
- Success path no longer carries unused message strings
- Unify restartGateway return type (was `message?: string`, now consistent)
- Remove never-populated `uptime` and `version` from HealthInfo
- Update preload and renderer store types to match

Co-Authored-By: Claude Opus 4.6 <[email protected]>
…, shared type

- Extract probeGatewayHealth() without status guard so getStatus() can
  detect externally-started gateways and startAndWaitForGateway() can
  poll during 'starting' state
- Check restartGateway command exit code instead of always returning success
- Move OperationResult to @shared/config/types to avoid duplicate definitions

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Use the official OpenClaw install scripts (install.sh / install.ps1) instead
of manual npm install. The scripts handle Node.js detection, build tools,
PATH setup, and diagnostics automatically.

- macOS/Linux: curl piped to bash, with sudo-prompt fallback on permission errors
- Windows: PowerShell inline execution
- Remove China mirror logic (official package includes Chinese support)
- Remove SHARP_IGNORE_GLOBAL_LIBVIPS workaround
- Refresh shell env in installGatewayService for PATH changes
- Drop @qingchencloud/openclaw-zh from uninstall args

Co-Authored-By: Claude Opus 4.6 <[email protected]>
…F-8 encoding

- Add copy button to install/uninstall log container header
- Make error alerts selectable with select-text class
- Fix Windows GBK mojibake by wrapping PowerShell via cmd.exe with chcp 65001

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Use buffer mode for execFileSync instead of encoding: 'utf8' to prevent
garbled Chinese Windows stderr. Log only exit code on failure instead of
the raw error object containing GBK-encoded text.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Include accumulated stderr in logger.error calls when install or uninstall
processes exit with non-zero code, enabling better debugging of failures.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
- Remove setShowLogs(false) from checkInstallation to prevent logs from
  disappearing immediately after install completes
- Remove dead lastHealthCheck.version display (field removed from HealthInfo)

Co-Authored-By: Claude Opus 4.6 <[email protected]>
…e quote stripping

Replace cmd.exe /c chcp wrapper with PowerShell-native [Console]::OutputEncoding
to set UTF-8 output. cmd.exe was consuming the quotes needed by PowerShell,
causing the install script to be echoed instead of executed.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
…ownload

Windows PowerShell 5.1 may not enable TLS 1.2 by default, causing
Invoke-WebRequest to fail on HTTPS URLs. Prepend SecurityProtocol setting.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
…install

Replace the official install.sh/install.ps1 approach with direct
npm install -g openclaw, borrowing key patterns from the scripts:

- Auto-install Node.js if missing or version < 22:
  - macOS: brew install node@22 + brew link
  - Linux: pacman (Arch) or NodeSource setup_22.x + apt-get/dnf
  - Windows: winget → choco → scoop fallback chain
- Auto-install Git if missing (best-effort, non-blocking)
- npm env vars from official scripts: SHARP_IGNORE_GLOBAL_LIBVIPS=1,
  NPM_CONFIG_SCRIPT_SHELL=cmd.exe (Windows), noise suppression
- EACCES retry with sudo-prompt on macOS/Linux
- Streaming output to UI throughout all steps

This gives us full control over the install flow and avoids the
platform-specific issues with the official scripts (cmd.exe quote
stripping, TLS, PowerShell execution, mise/fnm detection).

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Backend install() now auto-installs Node.js and Git, so the frontend
no longer needs to block installation with warning UI. Install button
now proceeds directly to backend which handles everything.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
- crossPlatformSpawn: auto-quote command path containing spaces when
  shell: true on Windows, preventing cmd.exe from splitting the path
- Add decodeBufferFromShell(): detect UTF-8 replacement chars and fall
  back to GBK decoding via iconv-lite for Chinese Windows cmd.exe output
- Apply GBK decoding to install/uninstall streaming output
- Remove redundant manual quoting in uninstall() (now handled centrally)

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Add back npmmirror registry for China users (detected via isUserInChina).
Use openclaw@latest for all users now that the official package supports
Chinese — the separate @qingchencloud/openclaw-zh package is no longer needed.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
handleStartGateway had early returns for syncConfig and startGateway
failures that didn't call setIsStarting(false), leaving the button
permanently stuck in loading state.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
The polling loop in startAndWaitForGateway was discarding stderr from
checkGatewayStatus and probeGatewayHealth, so timeout errors only showed
"Gateway failed to start within 30000ms" instead of the real reason
(e.g., "gateway closed (1006 abnormal closure)"). Now captures the last
error from polling attempts and appends it to the timeout message.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
…ervice

The system service/daemon registered by `openclaw gateway install` does
not inherit the OPENCLAW_CONFIG_PATH env var, so it reads the default
~/.openclaw/openclaw.json. Without the auth token there, the gateway
starts without auth and health checks fail with 1006 abnormal closure.

Now syncProviderConfig() also writes gateway settings (mode, port, auth)
to the default openclaw.json, ensuring the system service starts with
the correct auth token.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
…aming

The transform layer was sending the full accumulated `inputBuffer` as the
`delta` field in `tool-input-delta` chunks. The renderer then concatenated
this already-accumulated string onto `streamingArgs`, causing quadratic
memory growth (~N²/2). For a 100KB file write this ballooned to ~5GB,
crashing the V8 heap.

Fix: send only the incremental `partial_json` fragment (matching how
`thinking_delta` already works) and remove the now-unused `inputBuffer`
field and `appendToolInputDelta` method from `ClaudeStreamState`.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Windows scheduled task integration has too many upstream bugs.
Skip installGatewayService, uninstallGatewayService, and
ensureGatewayServiceInstalled on Windows while keeping gateway
start/stop/health/status CLI commands working normally.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Users with git configured to use SSH ([email protected]:...) may fail
during npm install if SSH keys aren't set up. Use GIT_CONFIG env vars
to rewrite GitHub SSH URLs to HTTPS within the npm install subprocess.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
On Windows without a registered service, `openclaw gateway start` runs
in foreground mode and never exits, causing the 20s timeout to kill it.
Instead, spawn `openclaw gateway --port <port>` as a detached background
process with windowsHide, then poll for readiness as usual.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
Standardizes gateway startup across platforms by using `gateway start
--force`
instead of platform-specific detached spawning on Windows. Adds
proactive
port availability checking before startup to provide clear error
messages
when the configured port is already in use by another application.
DeJeune and others added 12 commits March 8, 2026 12:09
The gateway service install already embeds OPENCLAW_CONFIG_PATH into
the launchd/systemd service definition, so the daemon reads the
correct cherry config file directly. No need to sync back to the
default openclaw.json.

Co-Authored-By: Claude Opus 4.6 <[email protected]>
- Auto-check for updates when entering the OpenClaw page
- Show info alert with version details when update is available
- Perform update via `openclaw update` command (stops gateway first)
- Extract version parsers to `services/utils/openClawParsers.ts` with snapshot tests
- Add IPC channels: OpenClaw_CheckUpdate, OpenClaw_PerformUpdate
- Add i18n translations for update UI (en, zh-cn, zh-tw + synced locales)

Co-Authored-By: Claude Opus 4.6 <[email protected]>
# Conflicts:
#	src/main/services/OpenClawService.ts
Copy link
Copy Markdown
Collaborator

@DeJeune DeJeune left a comment

Choose a reason for hiding this comment

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

LGTM

@kangfenmao kangfenmao merged commit 97011c8 into main Mar 13, 2026
9 checks passed
@kangfenmao kangfenmao deleted the DeJeune/fix-openclaw-close branch March 13, 2026 10:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants