PR #72820: Fix: Issue 72693 gateway service lifecycle

• Repository: openclaw/openclaw
• Author: sahilsatralkar
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/72820

Description (problem / solution / changelog)

Summary

Describe the problem and fix in 2–5 bullets:

If this PR fixes a plugin beta-release blocker, title it fix(<plugin-id>): beta blocker - <summary> and link the matching Beta blocker: <plugin-name> - <summary> issue labeled beta-blocker. Contributors cannot label PRs, so the title is the PR-side signal for maintainers and automation.

• Problem: openclaw doctor --fix could install a user-level gateway service even when a system-level OpenClaw gateway service already existed, and installed services could keep using an old pinned --port after gateway.port changed.
• Why it matters: Both cases can leave users with confusing gateway lifecycle drift, including duplicate supervisors or a service restarting on the wrong port.
• What changed: Doctor now blocks automatic Linux user-service install when a system-level OpenClaw gateway-like service is detected, and service audit/repair now detects and rewrites stale pinned gateway ports.
• What did NOT change (scope boundary): This does not change WSL2 ghost listener handling, health monitor behavior, Gmail watcher behavior, broad gateway startup lifecycle, or intentional multi-gateway setups with isolated ports/config/state.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #72693
• Related #
• This PR fixes a bug or regression

Root Cause (if applicable)

For bug fixes or regressions, explain why this happened, not just what changed. Otherwise write N/A. If the cause is unclear, write Unknown.

• Root cause: Gateway service repair audited several persisted supervisor fields, but it did not compare the installed command’s pinned --port against the current resolved gateway port. The missing-service install path also treated “user service not loaded” as enough to offer installation, without first checking for system-level OpenClaw gateway services.
• Missing detection / guardrail: No test covered stale service --port drift, and no doctor daemon-flow test covered system-level service presence while the user-level service was missing.
• Contributing context (if known): Existing deep service discovery already had the information needed for duplicate supervisor detection, but the install flow did not use it as a blocker.

Regression Test Plan (if applicable)

For bug fixes or regressions, name the smallest reliable test coverage that should catch this. Otherwise write N/A.

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
  • Target test or file:
    • src/daemon/service-audit.test.ts
    • src/commands/doctor-gateway-services.test.ts
    • src/commands/doctor-gateway-daemon-flow.test.ts
  • Scenario the test should lock in:
    • Service audit reports gateway-port-mismatch when installed --port differs from resolved config port.
    • Doctor repair passes the expected port into service audit and reinstalls the service with the current port.
    • Doctor does not auto-install a Linux user-level service when a system-level OpenClaw gateway-like service exists.
  • Why this is the smallest reliable guardrail: These tests cover the exact audit and repair decision points without needing a real systemd install.
  • Existing test that already covers this (if any): None.
  • If no new test is added, why not: N/A.

User-visible / Behavior Changes

• openclaw doctor / service audit can now report and repair a gateway service whose command still pins an old port.
• On Linux, doctor refuses to automatically install a user-level gateway service when it detects a system-level OpenClaw gateway-like service, and tells the user to inspect duplicates or mark service repair as externally managed.

Diagram (if applicable)

For UI changes or non-trivial logic flows, include a small ASCII diagram reviewers can scan quickly. Otherwise write N/A.

  Before:
  [gateway.port changes] -> [service keeps old --port] -> [restart uses old port]
  [user service missing + system service exists] -> [doctor installs user service] -> [duplicate supervisors]

  After:
  [gateway.port changes] -> [doctor detects port mismatch] -> [service metadata rewritten]
  [user service missing + system service exists] -> [doctor blocks auto-install] -> [user inspects/removes duplicate or sets external policy]

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS local dev environment; Linux behavior covered with mocked platform/service discovery tests.
• Runtime/container: Node 22 / pnpm workspace.
• Model/provider: N/A
• Integration/channel (if any): Gateway service lifecycle.
• Relevant config (redacted): gateway.port changed from installed service port.

Steps

1. Install or mock a gateway service command pinned to --port 18789.
2. Resolve current config port as 18888.
3. Run doctor service audit/repair.
4. For split-brain behavior, mock Linux with user service missing and a system-scope OpenClaw gateway-like service present.

Expected

• Doctor reports port drift and rewrites the service with the current port.
• Doctor does not install a second user-level service when a system-level OpenClaw gateway service exists.

Actual

• Before this PR, port drift was not audited, and the missing user-service path could proceed to install even with a system-level service present.
• After this PR, both cases are detected and guarded.

Evidence

Attach at least one:

• Failing test/log before + passing after

• Trace/log snippets

• Screenshot/recording

• Perf numbers (if relevant)

  Passing local verification:

  pnpm test src/daemon/service-audit.test.ts src/commands/doctor-gateway-services.test.ts src/commands/doctor-gateway-daemon-flow.test.ts pnpm check:changed pnpm build codex review --base origin/main

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • Focused tests for port parsing, port mismatch audit, doctor service repair using the current port, and split-brain install blocking.
  • Changed-lane validation with pnpm check:changed.
  • Build validation with pnpm build.
  • Local Codex review with codex review --base origin/main.
• Edge cases checked:
  • --port 18888 and --port=18888 argument forms.
  • Matching service/config ports do not produce a mismatch.
  • Split-brain guard only blocks system-scope OpenClaw gateway-like services in the Linux install path.
• What you did not verify:
  • A live systemd system-service install on a Linux host.
  • WSL2 ghost listener behavior, because it is intentionally out of scope.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: N/A. Users with stale service metadata can run openclaw doctor --fix or openclaw gateway install --force.

Risks and Mitigations

List only real risks for this PR. Add/remove entries as needed. If none, write None.

• Risk: A user intentionally running a system-level OpenClaw gateway may expect doctor to also install a user-level service.
  • Mitigation: The new behavior only blocks automatic install in that duplicate-supervisor case and points users to openclaw gateway status --deep, openclaw doctor --deep, and OPENCLAW_SERVICE_REPAIR_POLICY=external.

Changed files

• docs/gateway/doctor.md (modified, +4/-0)
• docs/gateway/index.md (modified, +10/-0)
• docs/gateway/troubleshooting.md (modified, +2/-0)
• src/commands/doctor-gateway-daemon-flow.test.ts (modified, +34/-0)
• src/commands/doctor-gateway-daemon-flow.ts (modified, +27/-0)
• src/commands/doctor-gateway-services.test.ts (modified, +39/-0)
• src/commands/doctor-gateway-services.ts (modified, +1/-0)
• src/commands/doctor-service-audit.test-helpers.ts (modified, +1/-0)
• src/daemon/service-audit.test.ts (modified, +46/-0)
• src/daemon/service-audit.ts (modified, +46/-0)
• src/plugins/cli-registry-loader.ts (modified, +27/-1)
• src/plugins/cli.test.ts (modified, +87/-0)