<!-- source: https://deepwiki.com/openclaw/openclaw/2.6-service-lifecycle-and-diagnostics -->

# Service Lifecycle & Diagnostics

- extensions/codex/src/app-server/attempt-startup.ts
- extensions/phone-control/index.test.ts
- extensions/phone-control/index.ts
- src/agents/acp-runtime-overlay.ts
- src/agents/agent-runtime-metadata.ts
- src/agents/auth-profiles/external-cli-scope.ts
- src/agents/model-transport-debug.ts
- src/agents/openai-reasoning-compat.ts
- src/agents/openai-routing.test.ts
- src/agents/openai-routing.ts
- src/agents/openclaw-tools.subagents.sessions-spawn.test-harness.ts
- src/agents/prompt-surface.ts
- src/agents/queued-file-writer.ts
- src/agents/subagent-control.test.ts
- src/agents/subagent-control.ts
- src/cli/command-execution-startup.test.ts
- src/commands/agent-command.test-mocks.ts
- src/commands/doctor-config-analysis.test.ts
- src/commands/doctor-config-analysis.ts
- src/commands/doctor-config-flow.test.ts
- src/commands/doctor-config-flow.ts
- src/commands/doctor-config-preflight.state-migration.test.ts
- src/commands/doctor-config-preflight.test.ts
- src/commands/doctor-config-preflight.ts
- src/commands/doctor-disk-space.test.ts
- src/commands/doctor-disk-space.ts
- src/commands/doctor-lint.test.ts
- src/commands/doctor/emit-notes.test.ts
- src/commands/doctor/emit-notes.ts
- src/commands/doctor/repair-sequencing.test.ts
- src/commands/doctor/repair-sequencing.ts
- src/commands/doctor/shared/codex-route-warnings.test.ts
- src/commands/doctor/shared/codex-route-warnings.ts
- src/commands/doctor/shared/preview-warnings.test.ts
- src/commands/doctor/shared/preview-warnings.ts
- src/commands/doctor/shared/stale-oauth-profile-shadows.test.ts
- src/commands/doctor/shared/stale-oauth-profile-shadows.ts
- src/commands/doctor/shared/stale-plugin-config.test.ts
- src/commands/doctor/shared/stale-plugin-config.ts
- src/commands/sessions.acp-runtime-metadata.test.ts
- src/config/codex-plugin-diagnostics.ts
- src/config/config.plugin-validation.test.ts
- src/config/validation.ts
- src/flows/doctor-core-checks.test.ts
- src/flows/doctor-core-checks.ts
- src/flows/doctor-health-contributions.test.ts
- src/flows/doctor-health-contributions.ts
- src/flows/doctor-health-conversion-plan.ts
- src/flows/doctor-lint-flow.ts
- src/gateway/server-chat.agent-events.test.ts
- src/gateway/server-chat.ts
- src/infra/diagnostic-events.ts
- src/infra/state-migrations.test.ts
- src/logging/diagnostic-run-activity.ts
- src/logging/diagnostic-session-recovery-coordinator.ts
- src/logging/diagnostic-session-recovery.ts
- src/logging/diagnostic-session-state.ts
- src/logging/diagnostic-stuck-session-recovery.runtime.test.ts
- src/logging/diagnostic-stuck-session-recovery.runtime.ts
- src/logging/diagnostic.test.ts
- src/logging/diagnostic.ts
- src/routing/channel-route-targets.test.ts
- src/routing/channel-route-targets.ts

This page details OpenClaw Gateway's process lifecycle management, daemon supervision integration, health checks, diagnostic tooling, and automated repair capabilities. It covers Gateway daemon management on macOS (`launchd`), Linux (`systemd`), and Windows (`schtasks`), the real-time status command, and the extensive `doctor` command used for diagnostics and auto-repair. It also details how diagnostic contracts contributed by plugins and channels are surfaced and managed.

For broader context, see [Gateway Architecture (2)](https://github.com/openclaw/openclaw/blob/fbdf5937/Gateway Architecture (2)) [Configuration System (2.3)](https://github.com/openclaw/openclaw/blob/fbdf5937/Configuration System (2.3)) and [Authentication (2.2)](https://github.com/openclaw/openclaw/blob/fbdf5937/Authentication (2.2))

## Gateway Startup Sequence

The Gateway process can start in:

- Foreground/CLI mode : For direct invocation ( openclaw gateway run ).
- Daemon mode : Supervised by OS service managers like launchd , systemd , or Windows Task Scheduler.
- Embedded mode : Bundled inside native apps or device nodes.

The startup involves:

1. Ensuring the CLI executable is on the system PATH via ensureOpenClawCliOnPath src/gateway/server.impl.ts 119
2. Loading a startup config snapshot.
3. Initializing tracing and telemetry, including resuming restart traces if handoff occurred src/gateway/server.impl.ts 76-83
4. Loading models, plugins, and preparing runtime.
5. Launching sidecar services like memory backend, cron scheduler, and channel health monitors.

```

```

**Sources:** `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server.impl.ts#L119-L162" min=119 max=162 file-path="src/gateway/server.impl.ts">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-startup-post-attach.ts#L194-L205" min=194 max=205 file-path="src/gateway/server-startup-post-attach.ts">Hii</FileRef>`

## Daemon Management & Restart Loop

OpenClaw integrates deeply with service supervisors for longevity and auto-restart. The Gateway utilizes a `runGatewayLoop` to handle signals and manage process respawning during updates or failures.

### macOS Launchd Service Management

- Installed Gateway services run as launchd agents.
- Managed via Apple launchctl tool.
- Key operations: Install and configure launch agent plists via installLaunchAgent . Detect and repair stale launch agent states with repairLaunchAgentBootstrap . Execute controlled restarts with fallback detached restart handoff scripts.
- The restartLaunchAgent function attempts a launchctl kickstart . If this fails (e.g., I/O error), it falls back to scheduleDetachedLaunchdRestartHandoff .

```

```

**Sources:** `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/daemon/launchd.ts#L26-L26" min=26  file-path="src/daemon/launchd.ts">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/daemon/launchd.test.ts#L152-L211" min=152 max=211 file-path="src/daemon/launchd.test.ts">Hii</FileRef>`

### The Gateway Run Loop

The `runGatewayLoop` is responsible for the Gateway's lifecycle state machine. It handles:

- Signal Handling : Listens for SIGTERM , SIGINT , and SIGUSR1 src/gateway/server.impl.ts 35
- Drain Management : Before restarting, it calls waitForActiveTasks and waitForActiveEmbeddedRuns to ensure clean state src/cli/gateway-cli/run-loop.test.ts 148-171
- Update Respawn : When an update is triggered, it spawns a new version via respawnGatewayProcessForUpdate and verifies its health src/cli/gateway-cli/run-loop.test.ts 65-72

**Sources:** `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/gateway-cli/run-loop.test.ts#L145-L175" min=145 max=175 file-path="src/cli/gateway-cli/run-loop.test.ts">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server.impl.ts#L34-L36" min=34 max=36 file-path="src/gateway/server.impl.ts">Hii</FileRef>`

## Health Checks & Diagnostics Runtime

### Real-time Diagnostic Heartbeat

The Gateway maintains an internal diagnostic heartbeat via `startDiagnosticHeartbeat` [src/logging/diagnostic.ts49-50](https://github.com/openclaw/openclaw/blob/fbdf5937/src/logging/diagnostic.ts#L49-L50) This system monitors:

- Event Loop Health : Tracks P99 delay and utilization using monitorEventLoopDelay src/logging/diagnostic.ts 1-111
- Stuck Session Detection : Identifies sessions that have not made progress within resolveStuckSessionWarnMs src/logging/diagnostic.ts 48
- Liveness Sampling : Emits DiagnosticLivenessSample events when CPU core ratio or event loop delay exceeds thresholds src/logging/diagnostic.ts 106-116

### Stuck Session Recovery

If a session is deemed "stuck" (e.g., a tool call never returned), the heartbeat triggers `requestStuckSessionRecovery` [src/logging/diagnostic.test.ts23-25](https://github.com/openclaw/openclaw/blob/fbdf5937/src/logging/diagnostic.test.ts#L23-L25) This runtime attempts to abort the stalled embedded run and clean up associated resources via `recoverStuckDiagnosticSession` [src/logging/diagnostic-stuck-session-recovery.runtime.ts1-20](https://github.com/openclaw/openclaw/blob/fbdf5937/src/logging/diagnostic-stuck-session-recovery.runtime.ts#L1-L20)

**Sources:** `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/logging/diagnostic.ts#L41-L50" min=41 max=50 file-path="src/logging/diagnostic.ts">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/logging/diagnostic.test.ts#L151-L175" min=151 max=175 file-path="src/logging/diagnostic.test.ts">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/logging/diagnostic-stuck-session-recovery.runtime.ts#L1-L20" min=1 max=20 file-path="src/logging/diagnostic-stuck-session-recovery.runtime.ts">Hii</FileRef>`

## Doctor Command for Diagnostics and Auto-Repair

The `openclaw doctor` command is the all-in-one health inspection and repair tool. It supports multiple modes including `--fix` for automated repair and surfaces contributions from various subsystems.

### Core Health Contributions

The doctor executes a series of "Health Contributions" defined in `doctor-health-contributions.ts` [src/flows/doctor-health-contributions.ts48-53](https://github.com/openclaw/openclaw/blob/fbdf5937/src/flows/doctor-health-contributions.ts#L48-L53):

- Gateway Config : Validates gateway.mode and ensures auth settings aren't ambiguous via runGatewayConfigHealth src/flows/doctor-health-contributions.ts 135-161
- Auth Profiles : Repairs legacy flat auth profile stores via maybeRepairLegacyFlatAuthProfileStores and canonicalizes API key field aliases src/flows/doctor-health-contributions.ts 163-181
- Plugin Validation : Scans for missing plugins and attempts reinstallation via ClawHub or NPM src/config/validation.ts 185-200

### Repair Logic Flow

```

```

**Sources:** `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/flows/doctor-health-contributions.ts#L31-L53" min=31 max=53 file-path="src/flows/doctor-health-contributions.ts">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/flows/doctor-health-contributions.ts#L135-L181" min=135 max=181 file-path="src/flows/doctor-health-contributions.ts">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/commands/doctor-disk-space.ts#L1-L10" min=1 max=10 file-path="src/commands/doctor-disk-space.ts">Hii</FileRef>`

### Channel & Plugin Doctor Contracts

Plugins and channels surface their own diagnostic requirements through the doctor:

- Codex Route Warnings : Detects legacy openai-codex/* model refs and prompts for policy-based migration via collectCodexRouteWarnings src/commands/doctor/shared/codex-route-warnings.ts 34-37
- OAuth Sidecars : maybeRepairLegacyOAuthSidecarProfiles handles the migration of shadowed OAuth credentials src/flows/doctor-health-contributions.ts 168-169
- Diagnostic Events : The Gateway surfaces a DiagnosticEventPayload for visualizing startup and runtime events src/infra/diagnostic-events.ts 1-10
- Phone Control Arming : The phone-control plugin contributes diagnostics for node command policies, allowing owners to "arm" specific device capabilities like sms.send or camera.snap extensions/phone-control/index.ts 51-56

**Sources:** `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/flows/doctor-health-contributions.ts#L163-L181" min=163 max=181 file-path="src/flows/doctor-health-contributions.ts">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/commands/doctor/shared/codex-route-warnings.ts#L34-L37" min=34 max=37 file-path="src/commands/doctor/shared/codex-route-warnings.ts">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/phone-control/index.ts#L51-L56" min=51 max=56 file-path="extensions/phone-control/index.ts">Hii</FileRef>`
