网关、服务与安全检查

Run openclaw doctor interactively to review legacy gateway services (launchd/systemd/schtasks) and confirm supported cleanup. Explicit repair maintenance skips this separate cleanup flow. Removal is reported separately from installation; use openclaw gateway install when the intended native service is missing. Doctor can also scan for extra gateway-like services and print cleanup hints. Profile-named OpenClaw gateway services are considered first-class and are not flagged as "extra."

Cleanup previews include only legacy launchd services and recognized legacy systemd unit names in the user scope. Legacy Windows services, unrecognized Linux unit names, and services in the system scope remain findings for manual review.

Windows extra-service hints use read-only schtasks /Query inspection. Node hosts remain visible in diagnostics; discovery alone does not make a service a removal target.

Linux user-service cleanup preserves the unit file if stopping or disabling the service fails. An interrupted status probe does not permit file-only removal; that fallback is reported only when systemctl is unavailable.

On Linux, if the user-level gateway service is missing but a system-level OpenClaw gateway service exists, doctor does not install a second user-level service automatically. Inspect with openclaw gateway status --deep or openclaw doctor --deep, then remove the duplicate or set OPENCLAW_SERVICE_REPAIR_POLICY=external when a system supervisor owns the gateway lifecycle.

When a Matrix channel account has a pending or actionable legacy state migration, doctor (in --fix / --repair mode) creates a pre-migration snapshot and then runs the best-effort migration steps: legacy Matrix state migration and legacy encrypted-state preparation. Both steps are non-fatal; errors are logged and startup continues. Without explicit repair (--fix, --repair, or --yes), this check is skipped.

Doctor inspects device-pairing state as part of the normal health pass, reporting:

• pending first-time pairing requests
• pending role or scope upgrades for already-paired devices
• public-key mismatch repairs where the device id still matches but the device identity no longer matches the approved record
• paired records missing an active token for an approved role
• paired tokens whose scopes drift outside the approved pairing baseline
• local cached device-token entries for the current machine that predate a gateway-side token rotation or carry stale scope metadata
• a retired identity/device-auth.json file that is still present and blocks inspection of locally cached tokens, including in remote Gateway mode; stop the Gateway and run openclaw doctor --fix to finish migration or cleanup
• retired devices/*.json and nodes/*.json stores on a local Gateway; stop the Gateway and run openclaw doctor --fix to import device approvals before node capabilities and archive the originals. Existing SQLite records take precedence; unreadable sources remain in place for repair.

Doctor does not auto-approve pair requests or auto-rotate device tokens. It prints the exact next steps:

• inspect pending requests with openclaw devices list
• approve the exact request with openclaw devices approve <requestId>
• rotate a fresh token with openclaw devices rotate --device <deviceId> --role <role>
• remove and re-approve a stale record with openclaw devices remove <deviceId>

This distinguishes first-time pairing from pending role/scope upgrades and from stale token/device-identity drift, closing the common "already paired but still getting pairing required" hole.

Doctor emits a Security note only when it finds a warning, such as a provider open to DMs without an allowlist or a dangerously configured policy. Use openclaw security audit for the full security inventory.

Missing multi-agent DM routing ownership is reported as a finding. It does not stop the remaining channel security checks or pending state migrations. Configure the reported account binding before expecting that route to work. Telegram account discovery preserves the legacy default-agent account choice during upgrade previews without requiring an ambient agent.

If running as a systemd user service, doctor ensures lingering is enabled so the gateway stays alive after logout.

Doctor checks workspace bootstrap candidates (AGENTS.md, SOUL.md, IDENTITY.md, USER.md, BOOTSTRAP.md, and MEMORY.md) against the configured character budget after runtime filtering. Root BOOTSTRAP.md is excluded after workspace setup completes. It reports per-file raw vs. injected character counts, truncation percentage, truncation cause (max/file or max/total), and total injected characters as a fraction of the total budget. When files are truncated or near the limit, doctor prints tips for tuning agents.defaults.bootstrapMaxChars and agents.defaults.bootstrapTotalMaxChars. USER.md is the exception: it has a fixed 4,000-character cap that these settings cannot raise, so doctor names the cap and recommends compacting the file instead. See User model.

This includes files declared by the bundled bootstrap-extra-files hook when a fresh Gateway startup would select it, provided each matched basename is one of those six (for example, packages/core/AGENTS.md). Other basenames are ignored. Doctor uses each agent's workspace and limits without importing or running custom hook handlers. It predicts fresh-start selection, not the previous handler generation that a running Gateway can retain after a failed hook reload.

Doctor checks whether tab completion is installed for the current shell (zsh, bash, fish, or PowerShell):

• If the shell profile uses a slow dynamic completion pattern (source <(openclaw completion ...)), doctor upgrades it to the faster cached file variant.
• If completion is configured in the profile but the cache file is missing, doctor regenerates the cache automatically.
• If no completion is configured at all, doctor prompts to install it (interactive mode only; skipped with --non-interactive).

Run openclaw completion --write-state to regenerate the cache manually.

When openclaw doctor --fix removes a missing channel plugin, it also removes the dangling channel-scoped config that referenced that plugin: channels.<id> entries, heartbeat targets that named the channel, and agents.*.models["<channel>/*"] overrides. This prevents Gateway boot loops where the channel runtime is gone but config still asks the gateway to bind to it.

Doctor checks stored project clones registered with source: "cloned". It reports the project name and path, shallow state, every remote.*.partialclonefilter and remote.*.promisor key (including URL-keyed twins), and extensions.partialclone when present. Address-like names replace userinfo with *** and omit query strings and fragments, including remote-helper and scp-like addresses that are not standard URLs. Full clones produce no finding. Missing or unreadable clones are reported as skipped; other projects are still checked. Agent workspaces and manually registered checkouts are outside this check.

Each clone uses three local Git reads, each limited to five seconds and 64 KiB of captured output. Doctor does not fetch, repack, or change clone configuration, even with --fix. Partial clones support managed-worktree object prefetch, but full clones avoid missing-object and shallow-history failures during checkout and snapshot restore.

For a focused read-only report, run:

openclaw doctor --lint --only core/doctor/project-clone-shape --json

The check also runs in ordinary Doctor and --lint --all; it is excluded from the default lint profile. Lint inspects the registry through Doctor's private state snapshot.

Follow Doctor's printed commands in a POSIX shell with access to origin. Stop on any failed step. For a shallow partial clone with the usual origin keys, the sequence is:

cd /path/to/project-clone
git config --unset-all remote.origin.partialclonefilter
git fetch --refetch --unshallow origin
git rev-list --objects --missing=print --all | grep '^?' | cut -c2- | git fetch origin --no-tags --no-write-fetch-head --recurse-submodules=no --stdin
git config --unset-all remote.origin.promisor
git repack -a -d

Unset every reported partialclonefilter key before refetching, including keys such as remote.https://github.com/openclaw/openclaw.git.partialclonefilter. Omit --unshallow if the repository is not shallow; Git rejects that option for complete history. Keep promisor settings until missing objects have been fetched by ID, then unset every reported promisor key and, if present, extensions.partialclone before repacking. Doctor prints exact unset commands for plain remote names without ://, ::, or @. For address-like entries, follow the local lookup and unset instructions before continuing; the original key may contain credentials and must not be copied into shared reports. The redacted name identifies the entry but is not its literal Git config key.

Git can retain objects/pack/*.promisor sidecars after the remote keys are unset and the repository is repacked. The sidecars are harmless: OpenClaw determines partial-clone repair availability from Git configuration, not from those files. To remove the stale on-disk label, first confirm that the missing object command below prints nothing and that git fsck succeeds:

git rev-list --objects --missing=print --all | sed -n 's/^?//p'
git fsck --full

Then move only the sidecars out of the pack directory, keeping them as a recoverable backup until the next successful Doctor and managed-worktree run:

promisor_marker_backup="$(git rev-parse --git-dir)/retired-promisor-markers"
mkdir -p "$promisor_marker_backup"
find "$(git rev-parse --git-dir)/objects/pack" -maxdepth 1 -type f -name '*.promisor' -exec mv -n {} "$promisor_marker_backup"/ \;
git fsck --full

Rerun Doctor afterward. If history or objects remain missing, recover them from the original repository. Origin may not contain local-only snapshots; see snapshot restore.

Doctor checks local gateway token auth readiness.

• If token mode needs a token and no token source exists, doctor offers to generate one.
• If gateway.auth.token is SecretRef-managed but unavailable, doctor warns and does not overwrite it with plaintext.
• openclaw doctor --generate-gateway-token reports when a healthy SecretRef makes generation unnecessary.
• If a store-backed token resolves to a known redaction placeholder, --fix or --generate-gateway-token verifies a database backup and regenerates that entry while preserving its SecretRef. Doctor prints the backup path and restart/re-pair guidance. Other external secrets require replacement at their source.

Some repair flows need to inspect configured credentials without weakening runtime fail-fast behavior.

• openclaw doctor --fix uses the same read-only SecretRef summary model as status-family commands for targeted config repairs.
• Example: Telegram allowFrom / groupAllowFrom @username repair tries to use configured bot credentials when available.
• If the Telegram bot token is configured via SecretRef but unavailable in the current command path, doctor reports that the credential is configured-but-unavailable and skips auto-resolution instead of crashing or misreporting the token as missing.

Guided Doctor runs a health check and can offer recovery for a local Gateway, subject to service ownership and confirmation. A failed remote health check does not trigger local service recovery, even when the remote URL is a loopback SSH tunnel. Check the remote connection and recover the Gateway on its host. Explicit repair maintenance resumes the matching service it stopped. After successful standalone openclaw doctor --fix, it also starts and verifies an already-stopped managed Gateway whose service targets the current installation. Update-time Doctor leaves activation with the updater. A loaded, enabled macOS job between respawns is not treated as an intentionally stopped service.

Doctor checks whether the configured memory search embedding provider is ready for the default agent. The behavior depends on the configured provider:

• Explicit local provider: checks for a local model file or a recognized remote/downloadable model URL. If missing, suggests switching to a remote provider.
• Explicit remote provider (openai, voyage, etc.): verifies an API key is present in the environment or auth store. Prints actionable fix hints if missing.
• Legacy auto provider: treats memorySearch.provider: "auto" as OpenAI, checks OpenAI readiness, and doctor --fix rewrites it to provider: "openai".

When a cached gateway probe result is available (gateway was healthy at the time of the check), doctor cross-references its result with the CLI-visible config and notes any discrepancy. Doctor does not start a fresh embedding ping on the default path; use the deep memory status command when you want a live provider check.

Use openclaw memory status --deep to verify embedding readiness at runtime.

Embedding-provider readiness is a health check, not a state migration. Gateway startup does not initialize memory embedding providers during readiness checks, so auth-profile SecretRefs can activate afterward. If embeddings remain unavailable, memory sync preserves an existing semantic index rather than replacing it with FTS-only data. Readiness warnings allow degraded startup; errors that leave required state unsafe to read still block Gateway readiness.

If the gateway is healthy, doctor runs a channel status probe and reports warnings with suggested fixes.

Plain Doctor inspection checks the installed supervisor config (launchd/systemd/schtasks) for missing or outdated defaults (for example systemd network-online dependencies and restart delay) and can offer an interactive repair. Explicit repair maintenance skips this separate service-rewrite phase, but reconciles eligible installation drift in a previously running service through the native installer. Stopped services keep their launcher and stop state. Run openclaw gateway install --force from the intended installation to replace the launcher and managed environment.

Before a Linux maintenance stop, policy refresh backs up outdated OpenClaw unit settings, confirms daemon-reload, and verifies that the effective TimeoutStopSec covers drain and cleanup (currently 330 seconds). This refresh preserves the launcher, environment, and operator drop-ins; an offline service can receive it without being started. A short or unknown resident shutdown budget uses bounded lifecycle drain before stopping. At the update deadline, reported write custody refuses the stop with its owner phase; remaining admitted turns or unknown custody produce a warning and the stop proceeds.

Notes:

• An older installation marker does not make custom native settings safe to replace. Automatic reconciliation repairs only missing or recognized released defaults; unrecognized base-unit, LaunchAgent, or Scheduled Task settings remain unchanged with a diagnostic. Linux operator drop-ins are never rewritten.
• On macOS, reconciliation recognizes the complete default PATH generated by the 2026.4.29 installer and refreshes it to the current service PATH after backing up the definition. Added custom entries and other unrecognized values remain protected, including edits inside the generated environment file. If optional user-bin directories have changed since installation, the old PATH remains unrecognized rather than being discarded.
• If backup or migration subprocess cleanup cannot confirm that owned work stopped, its write-custody blocker remains for the Gateway process lifetime, even after the command reports an error. Automatic maintenance does not clear it on a timeout. The deployment owner must independently verify that the work stopped before replacing the Gateway process.
• openclaw doctor prompts before rewriting supervisor config. openclaw doctor --force alone remains guided: it allows aggressive repair choices but still requires interactive consent for an eligible service rewrite. It does not enter repair maintenance or bypass ownership and write-access checks.
• openclaw doctor --yes accepts default non-service repair prompts and enters maintenance under the policy-refresh and installation-drift rules above.
• openclaw doctor --fix applies recommended repairs without prompts (--repair is an alias; --yes also enters repair maintenance). It stops the matching managed Gateway before plugin or mutable-state inspection, verifies repairs, and restarts the same service once, even when no changes are needed. It reconciles eligible installation drift, preserves launchers and stop state for services confirmed offline before maintenance, and refuses to stop an ancestor Gateway. Plain inspection does not enter maintenance, and custom state directories do not adopt native services.
• Explicit repair refuses unavailable service inspection and unmatched services that may still run. After their owner stops them and the native manager confirms they are offline, Doctor repairs its selected state without changing or starting those services. A disabled systemd unit can still be restarting; Doctor checks runtime state as well as installation state.
• An updater's explicit Gateway activation policy leaves stop/restart ownership with the updater. Doctor still requires native proof that the service is offline; a live update --no-restart repair fails without stopping or restarting it. Stop the service through its owner before retrying the update. Older update parents without that policy retain ordinary Doctor maintenance.
• openclaw doctor --fix --force uses the same policy-refresh and installation-drift rules. Use openclaw gateway install --force to request a rewrite; operator-owned systemd drop-ins remain unchanged.
• OPENCLAW_SERVICE_REPAIR_POLICY=external keeps doctor read-only for gateway service lifecycle. Have the deployment owner stop the Gateway, run Doctor as the state-owning account, then restart through that owner. The policy skips native maintenance inspection and service mutations, including install/start/restart/bootstrap, supervisor config rewrites, and legacy service cleanup. It keeps Gateway/state coordinators and agent-database lease checks, reports service health, and runs non-service repairs. See Existing system LaunchDaemons.
• Doctor and gateway status --deep name unavailable launchd domains, missing systemd user-session buses, and native probe access denial separately. Linux guidance covers XDG_RUNTIME_DIR, DBUS_SESSION_BUS_ADDRESS, and dbus-user-session; externally supervised deployments receive the existing policy above. See Gateway and service recovery.

• Within a live Linux service inspection, OpenClaw can retain the authenticated user manager's private connection if its session bus stops. Typed command and runtime reads continue only for that original manager and unit. A missing initial manager identity or a replaced manager remains unavailable; OpenClaw does not start the bus or select another manager. This read-only recovery does not change service start/stop authority.

• On macOS, a same-label system LaunchDaemon blocks user LaunchAgent install, start, restart, and bootstrap repair. Doctor reports the system owner and stops service recovery; --force does not bypass this ownership boundary. See Existing system LaunchDaemons.

• On Linux, doctor does not rewrite command/entrypoint metadata while the matching systemd gateway unit is active. If a stopped unit's command or working directory is overridden by an operator-owned systemd drop-in, inspect it with systemctl --user cat <unit>.service, then update or remove the drop-in; rewriting the managed base cannot change the effective launcher. Environment= drop-ins remain supported. Doctor also ignores inactive non-legacy extra gateway-like units during the duplicate-service scan so companion service files do not create cleanup noise.
• On Linux, doctor checks authority over the installed and planned service files before persisting a recovered gateway token. If that check blocks service repair, the repair leaves config and token unchanged and reports how to restore inspection access or involve the deployment owner; --force cannot bypass it. Unrelated Doctor config repairs are unaffected.
• If token auth requires a token and gateway.auth.token is SecretRef-managed, doctor service install/repair validates the SecretRef but does not persist resolved plaintext token values into supervisor service environment metadata.
• Doctor detects managed .env/SecretRef-backed service environment values that older LaunchAgent, systemd, or Windows Scheduled Task installs embedded inline and rewrites the service metadata so those values load from the runtime source instead of the supervisor definition.
• Doctor detects when the service command still pins an old --port after gateway.port changes and rewrites the service metadata to the current port.
• If token auth requires a token and the configured token SecretRef is unresolved, doctor blocks the install/repair path with actionable guidance.
• If both gateway.auth.token and gateway.auth.password are configured and gateway.auth.mode is unset, doctor blocks install/repair until mode is set explicitly.
• For Linux user-systemd units, doctor token drift checks include both Environment= and EnvironmentFile= sources when comparing service auth metadata.
• Doctor service repairs refuse to rewrite, stop, or restart a gateway service from an older OpenClaw binary when the config was last written by a newer version. See Gateway troubleshooting.
• openclaw gateway install --force rewrites the managed base unit, but never removes operator-owned systemd drop-ins; it warns if a command or working-directory override remains effective.

Doctor inspects the service runtime (PID, last exit status) and warns when the service is installed but not actually running. It also checks for port collisions on the gateway port (default 18789) and reports likely causes (gateway already running, SSH tunnel).

Doctor accepts Bun 1.4+ runtimes that provide WAL-reset-safe node:sqlite and warns when the gateway service runs on an older or unsafe Bun or a version-managed Node path (nvm, fnm, volta, asdf, etc.). Supported Bun services, whether recorded or pinned, are retained. A pinned runtime is never migrated. Only an unpinned, unsupported Bun is offered migration to a supported system Node, with interactive approval. Update-driven Doctor runs never migrate the runtime. If no supported Node is available, the service stays on Bun and Doctor warns. Version-manager paths can break after upgrades because the service does not load your shell init. Doctor can offer to migrate an unpinned version-managed Node to a supported system Node install (Homebrew/apt/choco).

When reinstalling an existing but unloaded service without a wrapper or runtime pin, Doctor defaults its runtime picker to the supported recorded Node or Bun. Keeping that runtime retains its executable without creating a pin; choosing the other runtime selects a new executable. An unavailable or unsupported recorded runtime falls back to the fresh-install default of Node, or the running supported Bun without creating a pin when no supported Node is found and no explicit runtime, pin, or wrapper is set.

Doctor uses that same suggestion for its non-interactive runtime fallback. Choosing Node explicitly still fails before installation if no supported Node is available; it does not silently substitute Bun. This does not change when Doctor requires confirmation to install a service.

Explicit runtime-path pins are retained during service repair. Doctor still checks their runtime capabilities, but does not migrate a valid pin away from a version manager. Replace or remove an invalid pin with openclaw gateway install --runtime-path <path> --force or openclaw gateway install --runtime node --force.

Service installation and repair recognize current Node executables named node, nodejs, or versioned names such as node24 and node-24, including Windows .exe variants. Each candidate still has to pass the Node and SQLite capability checks before selection.

Newly installed or repaired macOS LaunchAgents use a canonical system PATH (/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin) instead of copying the interactive shell PATH, so Homebrew-managed system binaries stay available while Volta, asdf, fnm, pnpm, and other version-manager directories do not change which Node child processes resolve. Linux services still keep explicit environment roots (NVM_DIR, FNM_DIR, VOLTA_HOME, ASDF_DATA_DIR, BUN_INSTALL, PNPM_HOME) and stable user-bin directories, but guessed version-manager fallback directories are only written to the service PATH when those directories exist on disk.