Troubleshooting

Troubleshooting 문서는 OpenClaw 공식 문서(gateway/troubleshooting)를 한국어로 정리한 가이드입니다. Deep troubleshooting runbook for gateway, channels, automation, nodes, and browser 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Deep troubleshooting runbook for gateway, channels, automation, nodes, and browser

한국어 가이드 범위: gateway/troubleshooting 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Command ladder
After an update
Split brain installs and newer config guard
Protocol mismatch after rollback
Skill symlink skipped as path escape
Anthropic 429 extra usage required for long context
Upstream 403 blocked responses
Local OpenAI-compatible backend passes direct probes but agent runs fail
No replies
Dashboard control UI connectivity
Auth detail codes quick map
Gateway service not running
macOS gateway silently stops responding, then resumes when you touch the dashboard
macOS launchd supervisor loop with duplicate gateway/node LaunchAgents
Gateway exits during high memory use
Gateway rejected invalid config
Gateway probe warnings
Channel connected, messages not flowing
Cron and heartbeat delivery
Node paired, tool fails
Browser tool fails
If you upgraded and something suddenly broke
관련 문서

상세 내용

본문

This is the deep runbook. Start at /help/troubleshooting for the fast triage flow first.

Command ladder

주요 항목:

openclaw gateway status shows Runtime: running, Connectivity probe: ok, and a Capability: ... line.
openclaw doctor reports no blocking config/service issues.
openclaw channels status --probe shows live per-account transport status and, where supported, works or audit ok.

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

After an update

Use when an update finishes but the Gateway is down, channels are empty, or model calls fail with 401s.

주요 항목:

Update restart in openclaw status / openclaw status --all. Pending or failed handoffs include the next command to run.
plugin load failed: dependency tree corrupted; run openclaw doctor --fix under Channels: the channel config still exists, but plugin registration failed before the channel could load.
Provider 401s after re-auth: openclaw doctor --fix checks for stale per-agent OAuth auth shadows and removes old copies so all agents resolve the current shared profile.

openclaw status --all
openclaw update status --json
openclaw gateway status --deep
openclaw doctor --fix
openclaw gateway restart

Split brain installs and newer config guard

Use when a gateway service unexpectedly stops after an update, or logs show one openclaw binary is older than the version that last wrote openclaw.json.

which openclaw
openclaw --version
openclaw gateway status --deep
openclaw config get meta.lastTouchedVersion

openclaw gateway install --force
    openclaw gateway restart

Protocol mismatch after rollback

Use when logs keep printing protocol mismatch after a downgrade or rollback. An older Gateway is running, but a newer local client process is still reconnecting with a protocol range the older Gateway cannot speak.

주요 항목:

protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n> in Gateway logs.
Established clients: in openclaw gateway status --deep or Gateway clients in openclaw doctor --deep: active TCP clients connected to the Gateway port, with PIDs and command lines when the OS allows it.
A client process whose command line points at the newer OpenClaw install or wrapper you rolled back from.

openclaw --version
which -a openclaw
openclaw gateway status --deep
openclaw doctor --deep
openclaw logs --follow

Skill symlink skipped as path escape

Every skill root is a containment boundary. A symlink under ~/.agents/skills, /.agents/skills, /skills, or ~/.openclaw/skills is skipped when its real target resolves outside that root, unless the target is explicitly trusted.

주요 항목:

Skills config
Configuration examples

Skipping escaped skill path outside its configured root: ... reason=symlink-escape

ls -l ~/.agents/skills/<name>
realpath ~/.agents/skills/<name>
openclaw config get skills.load

{
  skills: {
    load: {
      extraDirs: ["~/Projects/manager/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
  },
}

Anthropic 429 extra usage required for long context

Use when logs/errors include: HTTP 429: rate_limit_error: Extra usage is required for long context requests.

주요 항목:

Selected Anthropic model is a GA-capable 1M Claude 4.x model (Opus 4.6/4.7/4.8, Sonnet 4.6), or the model config still carries legacy params.context1m: true.
Current Anthropic credential is not eligible for long-context usage.
Requests fail only on long sessions/model runs that need the 1M context path.
Anthropic
Token use and costs
Why am I seeing HTTP 429 from Anthropic?

openclaw logs --follow
openclaw models status
openclaw config get agents.defaults.models

Upstream 403 blocked responses

Use when an upstream LLM provider returns a generic 403 such as Your request was blocked.

주요 항목:

Multiple models under the same provider failing the same way.
HTML or generic security text instead of a normal provider API error.
Provider-side security events for the same request time.
A tiny direct curl probe succeeding while normal SDK-shaped requests fail.
OpenAI-compatible endpoints
Provider configuration
Logs

openclaw status
openclaw gateway status
openclaw logs --follow

Local OpenAI-compatible backend passes direct probes but agent runs fail

Set compat.requiresStringContent: true for string-only Chat Completions backends. 2. Set compat.strictMessageKeys: true for strict Chat Completions backends that only accept role and content on each message. 3. Set compat.supportsTools: false for models/backends that cannot handle OpenClaw's tool schema surface reliably. 4. Lower prompt pressure where possible: smaller workspace bootstrap, shorter session history, lighter local model, or a backend with stronger long-context support. 5. If tiny direct requests keep passing while OpenClaw agent turns still crash inside the backend, treat it as an upstream server/model limitation and file a repro there with the accepted payload shape.

주요 항목:

curl ... /v1/models works.
Tiny direct /v1/chat/completions calls work.
OpenClaw model runs fail only on normal agent turns.
Direct tiny calls succeed, but OpenClaw runs fail only on larger prompts.
model_not_found or 404 errors even though direct /v1/chat/completions works with the same bare model id.
Backend errors about messages[].content expecting a string.
Intermittent incomplete turn detected ... stopReason=stop payloads=0 warnings with an OpenAI-compatible local backend.
Backend crashes that appear only with larger prompt-token counts or full agent runtime prompts.
model_not_found with a local MLX/vLLM-style server: verify baseUrl includes /v1, api is "openai-completions" for /v1/chat/completions backends, and models.providers.<provider>.models[].id is the bare provider-local id. Select it with the provider prefix once, for example mlx/mlx-community/Qwen3-30B-A3B-6bit; keep the catalog entry as mlx-community/Qwen3-30B-A3B-6bit.
messages[...].content: invalid type: sequence, expected a string: backend rejects structured Chat Completions content parts. Fix: set models.providers.<provider>.models[].compat.requiresStringContent: true.
validation.keys or allowed message keys like ["role","content"]: backend rejects OpenAI-style replay metadata on Chat Completions messages. Fix: set models.providers.<provider>.models[].compat.strictMessageKeys: true.
incomplete turn detected ... stopReason=stop payloads=0: the backend completed the Chat Completions request but returned no user-visible assistant text for that turn. OpenClaw retries replay-safe empty OpenAI-compatible turns once; persistent failures usually mean the backend is emitting empty/non-text content or suppressing final-answer text.
Direct tiny requests succeed, but OpenClaw agent runs fail with backend/model crashes (for example Gemma on some inferrs builds): OpenClaw transport is likely already correct; the backend is failing on the larger agent-runtime prompt shape.
Failures shrink after disabling tools but do not disappear: tool schemas were part of the pressure, but the remaining issue is still upstream model/server capacity or a backend bug.
Configuration
Local models
OpenAI-compatible endpoints

curl http://127.0.0.1:1234/v1/models
curl http://127.0.0.1:1234/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"<id>","messages":[{"role":"user","content":"hi"}],"stream":false}'
openclaw infer model run --model <provider/model> --prompt "hi" --json
openclaw logs --follow

No replies

If channels are up but nothing answers, check routing and policy before reconnecting anything.

주요 항목:

Pairing pending for DM senders.
Group mention gating (requireMention, mentionPatterns).
Channel/group allowlist mismatches.
drop guild message (mention required → group message ignored until mention.
pairing request → sender needs approval.
blocked / allowlist → sender/channel was filtered by policy.
Channel troubleshooting
Groups
Pairing

openclaw status
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw config get channels
openclaw logs --follow

Dashboard control UI connectivity

When the dashboard/control UI will not connect, validate URL, auth mode, and secure context assumptions.

주요 항목:

Correct probe URL and dashboard URL.
Auth mode/token mismatch between client and gateway.
HTTP usage where device identity is required.
device identity required → non-secure context or missing device auth.
origin not allowed → browser Origin is not in gateway.controlUi.allowedOrigins (or you are connecting from a non-loopback browser origin without an explicit allowlist).
device nonce required / device nonce mismatch → client is not completing the challenge-based device auth flow (connect.challenge + device.nonce).
device signature invalid / device signature expired → client signed the wrong payload (or stale timestamp) for the current handshake.
AUTH_TOKEN_MISMATCH with canRetryWithDeviceToken=true → client can do one trusted retry with cached device token.
That cached-token retry reuses the cached scope set stored with the paired device token. Explicit deviceToken / explicit scopes callers keep their requested scope set instead.
AUTH_SCOPE_MISMATCH → the device token was recognized, but its approved scopes do not cover this connect request; re-pair or approve the requested scope contract instead of rotating a shared gateway token.
Outside that retry path, connect auth precedence is explicit shared token/password first, then explicit deviceToken, then stored device token, then bootstrap token.
On the async Tailscale Serve Control UI path, failed attempts for the same {scope, ip} are serialized before the limiter records the failure. Two bad concurrent retries from the same client can therefore surface retry later on the second attempt instead of two plain mismatches.
too many failed authentication attempts (retry later) from a browser-origin loopback client → repeated failures from that same normalized Origin are locked out temporarily; another localhost origin uses a separate bucket.
Repeated unauthorized after that retry → shared token/device token drift; refresh token config and re-approve/rotate device token if needed.
gateway connect failed: → wrong host/port/url target.

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json

openclaw gateway restart
lsof -i :18789
curl http://127.0.0.1:18789

Auth detail codes quick map

Use error.details.code from the failed connect response to pick the next action:

주요 항목:

Paired-device token sessions can manage only their own device unless the caller also has operator.admin.
openclaw devices rotate --scope ... can only request operator scopes that the caller session already holds.
Configuration (gateway auth modes)
Control UI
Devices
Remote access
Trusted proxy auth

Detail code	Meaning	Recommended action
`AUTH_TOKEN_MISSING`	Client did not send a required shared token.	Paste/set token in the client and retry. For dashboard paths: `openclaw config get gateway.auth.token` then paste into Control UI settings.
`AUTH_TOKEN_MISMATCH`	Shared token did not match gateway auth token.	If `canRetryWithDeviceToken=true`, allow one trusted retry. Cached-token retries reuse stored approved scopes; explicit `deviceToken` / `scopes` callers keep requested scopes. If still failing, run the token drift recovery checklist.
`AUTH_DEVICE_TOKEN_MISMATCH`	Cached per-device token is stale or revoked.	Rotate/re-approve device token using devices CLI, then reconnect.
`AUTH_SCOPE_MISMATCH`	Device token is valid, but its approved role/scopes do not cover this connect request.	Re-pair the device or approve the requested scope contract; do not treat this as shared-token drift.
`PAIRING_REQUIRED`	Device identity needs approval. Check `error.details.reason` for `not-paired`, `scope-upgrade`, `role-upgrade`, or `metadata-upgrade`, and use `requestId` / `remediationHint` when present.	Approve pending request: `openclaw devices list` then `openclaw devices approve <requestId>`. Scope/role upgrades use the same flow after you review the requested access.

openclaw --version
openclaw doctor
openclaw gateway status

Gateway service not running

Use when the service is installed but the process does not stay up.

주요 항목:

Runtime: stopped with exit hints.
Service config mismatch (Config (cli) vs Config (service)).
Port/listener conflicts.
Extra launchd/systemd/schtasks installs when --deep is used.
Other gateway-like services detected (best effort) cleanup hints.
Gateway start blocked: set gateway.mode=local or existing config is missing gateway.mode → local gateway mode is not enabled, or the config file was clobbered and lost gateway.mode. Fix: set gateway.mode="local" in your config, or re-run openclaw onboard --mode local / openclaw setup to restamp the expected local-mode config. If you are running OpenClaw via Podman, the default config path is ~/.openclaw/openclaw.json.
refusing to bind gateway ... without auth → non-loopback bind without a valid gateway auth path (token/password, or trusted-proxy where configured).
another gateway instance is already listening / EADDRINUSE → port conflict.
Other gateway-like services detected (best effort) → stale or parallel launchd/systemd/schtasks units exist. Most setups should keep one gateway per machine; if you do need more than one, isolate ports + config/state/workspace. See /gateway#multiple-gateways-same-host.
System-level OpenClaw gateway service detected from doctor → a systemd system unit exists while the user-level service is missing. Remove or disable the duplicate before allowing doctor to install a user service, or set OPENCLAW_SERVICE_REPAIR_POLICY=external if the system unit is the intended supervisor.
Gateway service port does not match current gateway config → the installed supervisor still pins the old --port. Run openclaw doctor --fix or openclaw gateway install --force, then restart the gateway service.
Background exec and process tool
Configuration
Doctor

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep   # also scan system-level services

macOS gateway silently stops responding, then resumes when you touch the dashboard

Use when channels (Telegram, WhatsApp, etc.) on a macOS host go quiet for minutes to hours at a time, and the gateway appears to come back the moment you open the Control UI, SSH in, or otherwise interact with the host. There is usually no obvious symptom in openclaw status because by the time you look the gateway is alive again.

주요 항목:

One or more *-uncaught_exception.json bundles in ~/.openclaw/logs/stability/ with error.code set to a transient network code such as ENETDOWN, ENETUNREACH, EHOSTUNREACH, or ECONNREFUSED.
pmset -g log lines like Entering Sleep state due to 'Maintenance Sleep' or en0 driver is slow (msg: WillChangeState to 0) aligned with the crash timestamps. Power Nap / Maintenance Sleep briefly puts the Wi-Fi driver into state 0; any outbound connect() that lands in that window can fail with ENETDOWN even on a host that otherwise has full network connectivity.
launchctl print output showing state = not running with multiple recent runs and an exit code, especially when the gap between crash and the next launch is on the order of an hour rather than seconds. macOS launchd applies an undocumented respawn-protection gate after a crash burst that can stop honoring KeepAlive=true until an external trigger such as interactive login, dashboard connection, or launchctl kickstart re-arms it.
A stability bundle whose error.code is ENETDOWN or a sibling code, with the call stack pointing into Node net lookupAndConnect / Socket.connect. OpenClaw 2026.5.26 and newer classify these as benign transient network errors so they no longer propagate to the top-level uncaught handler; if you are on an older release, upgrade first.
Long quiet periods that end the instant you connect to the Control UI or SSH into the host: the user-visible activity is what re-arms launchd's respawn gate, not anything the dashboard does to the gateway.
runs count incrementing across the day with no corresponding received SIG*; shutting down line in ~/Library/Logs/openclaw/gateway.log: clean shutdowns log a signal; transient crashes do not.
macOS platform notes
Logging
Doctor

ls ~/.openclaw/logs/stability/ | tail -5
openclaw gateway stability --bundle latest
pmset -g log | grep -iE "sleep|wake|maintenance" | tail -50
launchctl print gui/$UID/ai.openclaw.gateway | grep -E "state|last exit|runs"

sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0

# Example launchd-aware liveness check, suitable for a 5-minute cron or LaunchAgent
   state=$(launchctl print gui/$UID/ai.openclaw.gateway 2>/dev/null | awk -F'= ' '/state =/ {print $2; exit}')
   if [ "$state" != "running" ]; then
     launchctl kickstart -k gui/$UID/ai.openclaw.gateway
   fi

macOS launchd supervisor loop with duplicate gateway/node LaunchAgents

Use this when a macOS install keeps restarting every few seconds, openclaw health checks flap between healthy and unavailable, and channel dispatch stalls even though the service appears to be running.

주요 항목:

More than one gateway PID across the 30-second sample instead of one stable
EADDRINUSE, another gateway instance is already listening, or repeated
Both ~/Library/LaunchAgents/ai.openclaw.gateway.plist and
macOS platform notes
Doctor
Gateway CLI

for i in 1 2 3 4; do
  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'
  sleep 10
done

openclaw gateway status --deep
openclaw node status
launchctl print gui/$UID/ai.openclaw.gateway | grep -E 'state|last exit|runs'
tail -n 80 ~/Library/Logs/openclaw/gateway.log

openclaw node uninstall

mkdir -p ~/.local/bin
   cat >~/.local/bin/openclaw-launchd-workaround <<'EOF'
   #!/bin/sh
   set -eu
   unset OPENCLAW_LAUNCHD_LABEL LAUNCH_JOB_LABEL LAUNCH_JOB_NAME XPC_SERVICE_NAME || true
   exec openclaw "$@"
   EOF
   chmod 700 ~/.local/bin/openclaw-launchd-workaround

   openclaw gateway install \
     --wrapper ~/.local/bin/openclaw-launchd-workaround \
     --force

openclaw gateway status --deep --require-rpc

   for i in 1 2 3 4; do
     ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'
     sleep 10
   done

Gateway exits during high memory use

Use when the Gateway disappears under load, the supervisor reports an OOM-style restart, or logs mention critical memory pressure bundle written.

주요 항목:

Reason: diagnostic.memory.pressure.critical in the latest stability bundle.
Memory pressure: with critical/rss_threshold, critical/heap_threshold, or critical/rss_growth.
V8 heap: values near the heap limit.
Largest session files: entries such as agents/<agent>/sessions/<session>.jsonl or sessions/<session>.jsonl.
Linux cgroup memory counters when the gateway runs inside a container or memory-limited service.
critical memory pressure bundle written appears shortly before restart → OpenClaw captured a pre-OOM stability bundle. Inspect it with openclaw gateway stability --bundle latest.
memory pressure: level=critical appears in gateway logs → OpenClaw detected critical memory pressure and recorded the available in-process memory facts.
Largest session files: points at a very large redacted transcript path → reduce retained session history, inspect session growth, or move old transcripts out of the active store before restarting.
V8 heap: used bytes are close to the heap limit → lower prompt/session pressure or reduce concurrent work first. For a managed service, inspect Gateway heap: in openclaw gateway status; if it says not set, regenerate old service metadata with openclaw gateway install --force. Ambient shell NODE_OPTIONS is intentionally ignored. Use an explicit supervisor-level heap override only after confirming the sustained workload and leaving enough native-memory headroom.
Memory pressure: critical/rss_growth → memory grew quickly inside one sampling window. Check the latest logs for a large import, runaway tool output, repeated retries, or a batch of queued agent work.
Critical memory pressure appears in logs but no bundle exists → capture openclaw gateway diagnostics export after the event for the available operational evidence.
Gateway health
Diagnostics export
Sessions

openclaw gateway status --deep
openclaw logs --follow
openclaw gateway stability --bundle latest
openclaw gateway diagnostics export

Gateway rejected invalid config

Use when Gateway startup fails with Invalid config or hot reload logs say it skipped an invalid edit.

주요 항목:

Invalid config at ...
config reload skipped (invalid config): ...
Config write rejected: ...
A timestamped openclaw.json.rejected.* file beside the active config.
A timestamped openclaw.json.clobbered.* file if doctor --fix repaired a broken direct edit.
OpenClaw keeps the latest 32 .clobbered.* files for each config path and rotates older ones.
The config did not validate during startup, hot reload, or an OpenClaw-owned write.
Gateway startup fails closed instead of rewriting openclaw.json.
Hot reload skips invalid external edits and keeps the current runtime config active.
OpenClaw-owned writes reject invalid/destructive payloads before commit and save .rejected.*.
openclaw doctor --fix owns repair. It can remove non-JSON prefixes or restore the last-known-good copy while preserving the rejected payload as .clobbered.*.
When many repairs happen for one config path, OpenClaw rotates older .clobbered.* files so the newest repaired payload is still available.
.clobbered.* exists → doctor preserved a broken external edit while repairing the active config.
.rejected.* exists → an OpenClaw-owned config write failed schema or clobber checks before commit.
Config write rejected: → the write tried to drop required shape, shrink the file sharply, or persist invalid config.
config reload skipped (invalid config): → a direct edit failed validation and was ignored by the running Gateway.
Invalid config at ... → startup failed before Gateway services booted.
missing-meta-vs-last-good, gateway-mode-missing-vs-last-good, or size-drop-vs-last-good:* → an OpenClaw-owned write was rejected because it lost fields or size compared with the last-known-good backup.
Config last-known-good promotion skipped → the candidate contained redacted secret placeholders such as ***.
Config
Configuration: hot reload
Configuration: strict validation
Doctor

openclaw logs --follow
openclaw config file
openclaw config validate
openclaw doctor

CONFIG="$(openclaw config file)"
    ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head
    diff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"
    openclaw config validate
    openclaw doctor

Gateway probe warnings

Use when openclaw gateway probe reaches something, but still prints a warning block.

주요 항목:

warnings[].code and primaryTargetId in JSON output.
Whether the warning is about SSH fallback, multiple gateways, missing scopes, or unresolved auth refs.
SSH tunnel failed to start; falling back to direct probes. → SSH setup failed, but the command still tried direct configured/loopback targets.
multiple reachable gateway identities detected → distinct gateways answered, or OpenClaw could not prove reachable targets are the same gateway. An SSH tunnel, proxy URL, or configured remote URL to the same gateway is treated as one gateway with multiple transports, even when transport ports differ.
Read-probe diagnostics are limited by gateway scopes (missing operator.read) → connect worked, but detail RPC is scope-limited; pair device identity or use credentials with operator.read.
Gateway accepted the WebSocket connection, but follow-up read diagnostics failed → connect worked, but the full diagnostic RPC set timed out or failed. Treat this as a reachable Gateway with degraded diagnostics; compare connect.ok and connect.rpcOk in --json output.
Capability: pairing-pending or gateway closed (1008): pairing required → the gateway answered, but this client still needs pairing/approval before normal operator access.
Unresolved gateway.auth.* / gateway.remote.* SecretRef warning text → auth material was unavailable in this command path for the failed target.
Gateway
Multiple gateways on the same host
Remote access

openclaw gateway probe
openclaw gateway probe --json
openclaw gateway probe --ssh user@gateway-host

Channel connected, messages not flowing

If channel state is connected but message flow is dead, focus on policy, permissions, and channel specific delivery rules.

주요 항목:

DM policy (pairing, allowlist, open, disabled).
Group allowlist and mention requirements.
Missing channel API permissions/scopes.
mention required → message ignored by group mention policy.
pairing / pending approval traces → sender is not approved.
missing_scope, not_in_channel, Forbidden, 401/403 → channel auth/permissions issue.
Channel troubleshooting
Discord
Telegram
WhatsApp

openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw status --deep
openclaw logs --follow
openclaw config get channels

Cron and heartbeat delivery

If cron or heartbeat did not run or did not deliver, verify scheduler state first, then delivery target.

주요 항목:

Cron enabled and next wake present.
Job run history status (ok, skipped, error).
Heartbeat skip reasons (quiet-hours, requests-in-flight, cron-in-progress, lanes-busy, alerts-disabled, empty-heartbeat-file).
cron: scheduler disabled; jobs will not run automatically → cron disabled.
cron: timer tick failed → scheduler tick failed; check file/log/runtime errors.
heartbeat skipped with reason=quiet-hours → outside active hours window.
heartbeat skipped with reason=empty-heartbeat-file → heartbeat monitor scratch only contains blank, comment, header, fence, or empty-checklist scaffolding, so OpenClaw skips the model call.
heartbeat: unknown accountId → invalid account id for heartbeat delivery target.
heartbeat skipped with reason=dm-blocked → heartbeat target resolved to a DM-style destination while agents.defaults.heartbeat.directPolicy (or per-agent override) is set to block.
Heartbeat
Scheduled tasks
Scheduled tasks: troubleshooting

openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow

Node paired, tool fails

If a node is paired but tools fail, isolate foreground, permission, and approval state.

주요 항목:

Node online with expected capabilities.
OS permission grants for camera/mic/location/screen.
Exec approvals and allowlist state.
NODE_BACKGROUND_UNAVAILABLE → node app must be in foreground.
*_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → missing OS permission.
SYSTEM_RUN_DENIED: approval required → exec approval pending.
SYSTEM_RUN_DENIED: allowlist miss → command blocked by allowlist.
Exec approvals
Node troubleshooting
Nodes

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
openclaw status

Browser tool fails

Use when browser tool actions fail even though the gateway itself is healthy.

주요 항목:

Whether plugins.allow is set and includes browser.
Valid browser executable path.
CDP profile reachability.
Local Chrome availability for existing-session / user profiles.
unknown command "browser" or unknown command 'browser' → the bundled browser plugin is excluded by plugins.allow.
Browser tool missing / unavailable while browser.enabled=true → plugins.allow excludes browser, so the plugin never loaded.
Failed to start Chrome CDP on port → browser process failed to launch.
browser.executablePath not found → configured path is invalid.
browser.cdpUrl must be http(s) or ws(s) → the configured CDP URL uses an unsupported scheme such as file: or ftp:.
browser.cdpUrl has invalid port → the configured CDP URL has a bad or out-of-range port.
Playwright is not available in this gateway build; '<feature>' is unsupported. → the current gateway install lacks the core browser runtime dependency; reinstall or update OpenClaw, then restart the gateway. ARIA snapshots and basic page screenshots can still work, but navigation, AI snapshots, CSS-selector element screenshots, and PDF export stay unavailable.
Could not find DevToolsActivePort for chrome → Chrome MCP existing-session could not attach to the selected browser data dir yet. Open the browser inspect page, enable remote debugging, keep the browser open, approve the first attach prompt, then retry. If signed-in state is not required, prefer the managed openclaw profile.
No browser tabs found for profile="user" → the Chrome MCP attach profile has no open local Chrome tabs.
Remote CDP for profile "<name>" is not reachable → the configured remote CDP endpoint is not reachable from the gateway host.
Browser attachOnly is enabled ... not reachable or Browser attachOnly is enabled and CDP websocket ... is not reachable → attach-only profile has no reachable target, or the HTTP endpoint answered but the CDP WebSocket still could not be opened.
fullPage is not supported for element screenshots → screenshot request mixed --full-page with --ref or --element.
element screenshots are not supported for existing-session profiles; use ref from snapshot. → Chrome MCP / existing-session screenshot calls must use page capture or a snapshot --ref, not CSS --element.
existing-session file uploads do not support element selectors; use ref/inputRef. → Chrome MCP upload hooks need snapshot refs, not CSS selectors.
existing-session file uploads currently support one file at a time. → send one upload per call on Chrome MCP profiles.
existing-session dialog handling does not support timeoutMs. → dialog hooks on Chrome MCP profiles do not support timeout overrides.
existing-session type does not support timeoutMs overrides. → omit timeoutMs for act:type on profile="user" / Chrome MCP existing-session profiles, or use a managed/CDP browser profile when a custom timeout is required.
response body is not supported for existing-session profiles yet. → responsebody still requires a managed browser or raw CDP profile.
Stale viewport / dark-mode / locale / offline overrides on attach-only or remote CDP profiles → run openclaw browser stop --browser-profile <name> to close the active control session and release Playwright/CDP emulation state without restarting the whole gateway.
Browser (OpenClaw-managed)
Browser troubleshooting

openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw logs --follow
openclaw doctor

If you upgraded and something suddenly broke

Most post-upgrade breakage is config drift or stricter defaults now being enforced.

주요 항목:

If gateway.mode=remote, CLI calls may be targeting remote while your local service is fine.
Explicit --url calls do not fall back to stored credentials.
gateway connect failed: → wrong URL target.
unauthorized → endpoint reachable but wrong auth.
Non-loopback binds (lan, tailnet, custom) need a valid gateway auth path: shared token/password auth, or a correctly configured non-loopback trusted-proxy deployment.
Old keys like gateway.token do not replace gateway.auth.token.
refusing to bind gateway ... without auth → non-loopback bind without a valid gateway auth path.
Connectivity probe: failed while runtime is running → gateway alive but inaccessible with current auth/url.
Pending device approvals for dashboard/nodes.
Pending DM pairing approvals after policy or identity changes.
device identity required → device auth not satisfied.
pairing required → sender/device must be approved.
Authentication
Background exec and process tool
Node pairing

openclaw gateway status
    openclaw config get gateway.mode
    openclaw config get gateway.remote.url
    openclaw config get gateway.auth.mode

openclaw config get gateway.bind
    openclaw config get gateway.auth.mode
    openclaw config get gateway.auth.token
    openclaw gateway status
    openclaw logs --follow

openclaw devices list
    openclaw pairing list --channel <channel> [--account <id>]
    openclaw logs --follow
    openclaw doctor

openclaw gateway install --force
openclaw gateway restart

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/troubleshooting
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

openclaw status --all
openclaw update status --json
openclaw gateway status --deep
openclaw doctor --fix
openclaw gateway restart

which openclaw
openclaw --version
openclaw gateway status --deep
openclaw config get meta.lastTouchedVersion

openclaw gateway install --force
    openclaw gateway restart

openclaw --version
which -a openclaw
openclaw gateway status --deep
openclaw doctor --deep
openclaw logs --follow

Skipping escaped skill path outside its configured root: ... reason=symlink-escape

Troubleshooting

핵심 요약

Deep troubleshooting runbook for gateway, channels, automation, nodes, and browser

한국어 가이드 범위: gateway/troubleshooting 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Command ladder
After an update
Split brain installs and newer config guard
Protocol mismatch after rollback
Skill symlink skipped as path escape
Anthropic 429 extra usage required for long context
Upstream 403 blocked responses
Local OpenAI-compatible backend passes direct probes but agent runs fail
No replies
Dashboard control UI connectivity
Auth detail codes quick map
Gateway service not running
macOS gateway silently stops responding, then resumes when you touch the dashboard
macOS launchd supervisor loop with duplicate gateway/node LaunchAgents
Gateway exits during high memory use
Gateway rejected invalid config
Gateway probe warnings
Channel connected, messages not flowing
Cron and heartbeat delivery
Node paired, tool fails
Browser tool fails
If you upgraded and something suddenly broke
관련 문서

상세 내용

본문

This is the deep runbook. Start at /help/troubleshooting for the fast triage flow first.

Command ladder

주요 항목:

openclaw gateway status shows Runtime: running, Connectivity probe: ok, and a Capability: ... line.
openclaw doctor reports no blocking config/service issues.
openclaw channels status --probe shows live per-account transport status and, where supported, works or audit ok.

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

After an update

Use when an update finishes but the Gateway is down, channels are empty, or model calls fail with 401s.

주요 항목:

Update restart in openclaw status / openclaw status --all. Pending or failed handoffs include the next command to run.
plugin load failed: dependency tree corrupted; run openclaw doctor --fix under Channels: the channel config still exists, but plugin registration failed before the channel could load.
Provider 401s after re-auth: openclaw doctor --fix checks for stale per-agent OAuth auth shadows and removes old copies so all agents resolve the current shared profile.

openclaw status --all
openclaw update status --json
openclaw gateway status --deep
openclaw doctor --fix
openclaw gateway restart

Split brain installs and newer config guard

Use when a gateway service unexpectedly stops after an update, or logs show one openclaw binary is older than the version that last wrote openclaw.json.

which openclaw
openclaw --version
openclaw gateway status --deep
openclaw config get meta.lastTouchedVersion

openclaw gateway install --force
    openclaw gateway restart

Protocol mismatch after rollback

주요 항목:

protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n> in Gateway logs.
Established clients: in openclaw gateway status --deep or Gateway clients in openclaw doctor --deep: active TCP clients connected to the Gateway port, with PIDs and command lines when the OS allows it.
A client process whose command line points at the newer OpenClaw install or wrapper you rolled back from.

openclaw --version
which -a openclaw
openclaw gateway status --deep
openclaw doctor --deep
openclaw logs --follow

Skill symlink skipped as path escape

주요 항목:

Skills config
Configuration examples

Skipping escaped skill path outside its configured root: ... reason=symlink-escape

ls -l ~/.agents/skills/<name>
realpath ~/.agents/skills/<name>
openclaw config get skills.load

{
  skills: {
    load: {
      extraDirs: ["~/Projects/manager/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
  },
}

Anthropic 429 extra usage required for long context

Use when logs/errors include: HTTP 429: rate_limit_error: Extra usage is required for long context requests.

주요 항목:

Selected Anthropic model is a GA-capable 1M Claude 4.x model (Opus 4.6/4.7/4.8, Sonnet 4.6), or the model config still carries legacy params.context1m: true.
Current Anthropic credential is not eligible for long-context usage.
Requests fail only on long sessions/model runs that need the 1M context path.
Anthropic
Token use and costs
Why am I seeing HTTP 429 from Anthropic?

openclaw logs --follow
openclaw models status
openclaw config get agents.defaults.models

Upstream 403 blocked responses

Use when an upstream LLM provider returns a generic 403 such as Your request was blocked.

주요 항목:

Multiple models under the same provider failing the same way.
HTML or generic security text instead of a normal provider API error.
Provider-side security events for the same request time.
A tiny direct curl probe succeeding while normal SDK-shaped requests fail.
OpenAI-compatible endpoints
Provider configuration
Logs

openclaw status
openclaw gateway status
openclaw logs --follow

Local OpenAI-compatible backend passes direct probes but agent runs fail

Set compat.requiresStringContent: true for string-only Chat Completions backends. 2. Set compat.strictMessageKeys: true for strict Chat Completions backends that only accept role and content on each message. 3. Set compat.supportsTools: false for models/backends that cannot handle OpenClaw's tool schema surface reliably. 4. Lower prompt pressure where possible: smaller workspace bootstrap, shorter session history, lighter local model, or a backend with stronger long-context support. 5. If tiny direct requests keep passing while OpenClaw agent turns still crash inside the backend, treat it as an upstream server/model limitation and file a repro there with the accepted payload shape.

주요 항목:

curl ... /v1/models works.
Tiny direct /v1/chat/completions calls work.
OpenClaw model runs fail only on normal agent turns.
Direct tiny calls succeed, but OpenClaw runs fail only on larger prompts.
model_not_found or 404 errors even though direct /v1/chat/completions works with the same bare model id.
Backend errors about messages[].content expecting a string.
Intermittent incomplete turn detected ... stopReason=stop payloads=0 warnings with an OpenAI-compatible local backend.
Backend crashes that appear only with larger prompt-token counts or full agent runtime prompts.
model_not_found with a local MLX/vLLM-style server: verify baseUrl includes /v1, api is "openai-completions" for /v1/chat/completions backends, and models.providers.<provider>.models[].id is the bare provider-local id. Select it with the provider prefix once, for example mlx/mlx-community/Qwen3-30B-A3B-6bit; keep the catalog entry as mlx-community/Qwen3-30B-A3B-6bit.
messages[...].content: invalid type: sequence, expected a string: backend rejects structured Chat Completions content parts. Fix: set models.providers.<provider>.models[].compat.requiresStringContent: true.
validation.keys or allowed message keys like ["role","content"]: backend rejects OpenAI-style replay metadata on Chat Completions messages. Fix: set models.providers.<provider>.models[].compat.strictMessageKeys: true.
incomplete turn detected ... stopReason=stop payloads=0: the backend completed the Chat Completions request but returned no user-visible assistant text for that turn. OpenClaw retries replay-safe empty OpenAI-compatible turns once; persistent failures usually mean the backend is emitting empty/non-text content or suppressing final-answer text.
Direct tiny requests succeed, but OpenClaw agent runs fail with backend/model crashes (for example Gemma on some inferrs builds): OpenClaw transport is likely already correct; the backend is failing on the larger agent-runtime prompt shape.
Failures shrink after disabling tools but do not disappear: tool schemas were part of the pressure, but the remaining issue is still upstream model/server capacity or a backend bug.
Configuration
Local models
OpenAI-compatible endpoints

curl http://127.0.0.1:1234/v1/models
curl http://127.0.0.1:1234/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"<id>","messages":[{"role":"user","content":"hi"}],"stream":false}'
openclaw infer model run --model <provider/model> --prompt "hi" --json
openclaw logs --follow

No replies

If channels are up but nothing answers, check routing and policy before reconnecting anything.

주요 항목:

Pairing pending for DM senders.
Group mention gating (requireMention, mentionPatterns).
Channel/group allowlist mismatches.
drop guild message (mention required → group message ignored until mention.
pairing request → sender needs approval.
blocked / allowlist → sender/channel was filtered by policy.
Channel troubleshooting
Groups
Pairing

openclaw status
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw config get channels
openclaw logs --follow

Dashboard control UI connectivity

When the dashboard/control UI will not connect, validate URL, auth mode, and secure context assumptions.

주요 항목:

Correct probe URL and dashboard URL.
Auth mode/token mismatch between client and gateway.
HTTP usage where device identity is required.
device identity required → non-secure context or missing device auth.
origin not allowed → browser Origin is not in gateway.controlUi.allowedOrigins (or you are connecting from a non-loopback browser origin without an explicit allowlist).
device nonce required / device nonce mismatch → client is not completing the challenge-based device auth flow (connect.challenge + device.nonce).
device signature invalid / device signature expired → client signed the wrong payload (or stale timestamp) for the current handshake.
AUTH_TOKEN_MISMATCH with canRetryWithDeviceToken=true → client can do one trusted retry with cached device token.
That cached-token retry reuses the cached scope set stored with the paired device token. Explicit deviceToken / explicit scopes callers keep their requested scope set instead.
AUTH_SCOPE_MISMATCH → the device token was recognized, but its approved scopes do not cover this connect request; re-pair or approve the requested scope contract instead of rotating a shared gateway token.
Outside that retry path, connect auth precedence is explicit shared token/password first, then explicit deviceToken, then stored device token, then bootstrap token.
On the async Tailscale Serve Control UI path, failed attempts for the same {scope, ip} are serialized before the limiter records the failure. Two bad concurrent retries from the same client can therefore surface retry later on the second attempt instead of two plain mismatches.
too many failed authentication attempts (retry later) from a browser-origin loopback client → repeated failures from that same normalized Origin are locked out temporarily; another localhost origin uses a separate bucket.
Repeated unauthorized after that retry → shared token/device token drift; refresh token config and re-approve/rotate device token if needed.
gateway connect failed: → wrong host/port/url target.

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json

openclaw gateway restart
lsof -i :18789
curl http://127.0.0.1:18789

Auth detail codes quick map

Use error.details.code from the failed connect response to pick the next action:

주요 항목:

Paired-device token sessions can manage only their own device unless the caller also has operator.admin.
openclaw devices rotate --scope ... can only request operator scopes that the caller session already holds.
Configuration (gateway auth modes)
Control UI
Devices
Remote access
Trusted proxy auth

Detail code	Meaning	Recommended action
`AUTH_TOKEN_MISSING`	Client did not send a required shared token.	Paste/set token in the client and retry. For dashboard paths: `openclaw config get gateway.auth.token` then paste into Control UI settings.
`AUTH_TOKEN_MISMATCH`	Shared token did not match gateway auth token.	If `canRetryWithDeviceToken=true`, allow one trusted retry. Cached-token retries reuse stored approved scopes; explicit `deviceToken` / `scopes` callers keep requested scopes. If still failing, run the token drift recovery checklist.
`AUTH_DEVICE_TOKEN_MISMATCH`	Cached per-device token is stale or revoked.	Rotate/re-approve device token using devices CLI, then reconnect.
`AUTH_SCOPE_MISMATCH`	Device token is valid, but its approved role/scopes do not cover this connect request.	Re-pair the device or approve the requested scope contract; do not treat this as shared-token drift.
`PAIRING_REQUIRED`	Device identity needs approval. Check `error.details.reason` for `not-paired`, `scope-upgrade`, `role-upgrade`, or `metadata-upgrade`, and use `requestId` / `remediationHint` when present.	Approve pending request: `openclaw devices list` then `openclaw devices approve <requestId>`. Scope/role upgrades use the same flow after you review the requested access.

openclaw --version
openclaw doctor
openclaw gateway status

Gateway service not running

Use when the service is installed but the process does not stay up.

주요 항목:

Runtime: stopped with exit hints.
Service config mismatch (Config (cli) vs Config (service)).
Port/listener conflicts.
Extra launchd/systemd/schtasks installs when --deep is used.
Other gateway-like services detected (best effort) cleanup hints.
Gateway start blocked: set gateway.mode=local or existing config is missing gateway.mode → local gateway mode is not enabled, or the config file was clobbered and lost gateway.mode. Fix: set gateway.mode="local" in your config, or re-run openclaw onboard --mode local / openclaw setup to restamp the expected local-mode config. If you are running OpenClaw via Podman, the default config path is ~/.openclaw/openclaw.json.
refusing to bind gateway ... without auth → non-loopback bind without a valid gateway auth path (token/password, or trusted-proxy where configured).
another gateway instance is already listening / EADDRINUSE → port conflict.
Other gateway-like services detected (best effort) → stale or parallel launchd/systemd/schtasks units exist. Most setups should keep one gateway per machine; if you do need more than one, isolate ports + config/state/workspace. See /gateway#multiple-gateways-same-host.
System-level OpenClaw gateway service detected from doctor → a systemd system unit exists while the user-level service is missing. Remove or disable the duplicate before allowing doctor to install a user service, or set OPENCLAW_SERVICE_REPAIR_POLICY=external if the system unit is the intended supervisor.
Gateway service port does not match current gateway config → the installed supervisor still pins the old --port. Run openclaw doctor --fix or openclaw gateway install --force, then restart the gateway service.
Background exec and process tool
Configuration
Doctor

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep   # also scan system-level services

macOS gateway silently stops responding, then resumes when you touch the dashboard

주요 항목:

One or more *-uncaught_exception.json bundles in ~/.openclaw/logs/stability/ with error.code set to a transient network code such as ENETDOWN, ENETUNREACH, EHOSTUNREACH, or ECONNREFUSED.
pmset -g log lines like Entering Sleep state due to 'Maintenance Sleep' or en0 driver is slow (msg: WillChangeState to 0) aligned with the crash timestamps. Power Nap / Maintenance Sleep briefly puts the Wi-Fi driver into state 0; any outbound connect() that lands in that window can fail with ENETDOWN even on a host that otherwise has full network connectivity.
launchctl print output showing state = not running with multiple recent runs and an exit code, especially when the gap between crash and the next launch is on the order of an hour rather than seconds. macOS launchd applies an undocumented respawn-protection gate after a crash burst that can stop honoring KeepAlive=true until an external trigger such as interactive login, dashboard connection, or launchctl kickstart re-arms it.
A stability bundle whose error.code is ENETDOWN or a sibling code, with the call stack pointing into Node net lookupAndConnect / Socket.connect. OpenClaw 2026.5.26 and newer classify these as benign transient network errors so they no longer propagate to the top-level uncaught handler; if you are on an older release, upgrade first.
Long quiet periods that end the instant you connect to the Control UI or SSH into the host: the user-visible activity is what re-arms launchd's respawn gate, not anything the dashboard does to the gateway.
runs count incrementing across the day with no corresponding received SIG*; shutting down line in ~/Library/Logs/openclaw/gateway.log: clean shutdowns log a signal; transient crashes do not.
macOS platform notes
Logging
Doctor

ls ~/.openclaw/logs/stability/ | tail -5
openclaw gateway stability --bundle latest
pmset -g log | grep -iE "sleep|wake|maintenance" | tail -50
launchctl print gui/$UID/ai.openclaw.gateway | grep -E "state|last exit|runs"

sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0

# Example launchd-aware liveness check, suitable for a 5-minute cron or LaunchAgent
   state=$(launchctl print gui/$UID/ai.openclaw.gateway 2>/dev/null | awk -F'= ' '/state =/ {print $2; exit}')
   if [ "$state" != "running" ]; then
     launchctl kickstart -k gui/$UID/ai.openclaw.gateway
   fi

macOS launchd supervisor loop with duplicate gateway/node LaunchAgents

주요 항목:

More than one gateway PID across the 30-second sample instead of one stable
EADDRINUSE, another gateway instance is already listening, or repeated
Both ~/Library/LaunchAgents/ai.openclaw.gateway.plist and
macOS platform notes
Doctor
Gateway CLI

for i in 1 2 3 4; do
  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'
  sleep 10
done

openclaw gateway status --deep
openclaw node status
launchctl print gui/$UID/ai.openclaw.gateway | grep -E 'state|last exit|runs'
tail -n 80 ~/Library/Logs/openclaw/gateway.log

openclaw node uninstall

mkdir -p ~/.local/bin
   cat >~/.local/bin/openclaw-launchd-workaround <<'EOF'
   #!/bin/sh
   set -eu
   unset OPENCLAW_LAUNCHD_LABEL LAUNCH_JOB_LABEL LAUNCH_JOB_NAME XPC_SERVICE_NAME || true
   exec openclaw "$@"
   EOF
   chmod 700 ~/.local/bin/openclaw-launchd-workaround

   openclaw gateway install \
     --wrapper ~/.local/bin/openclaw-launchd-workaround \
     --force

openclaw gateway status --deep --require-rpc

   for i in 1 2 3 4; do
     ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'
     sleep 10
   done

Gateway exits during high memory use

Use when the Gateway disappears under load, the supervisor reports an OOM-style restart, or logs mention critical memory pressure bundle written.

주요 항목:

Reason: diagnostic.memory.pressure.critical in the latest stability bundle.
Memory pressure: with critical/rss_threshold, critical/heap_threshold, or critical/rss_growth.
V8 heap: values near the heap limit.
Largest session files: entries such as agents/<agent>/sessions/<session>.jsonl or sessions/<session>.jsonl.
Linux cgroup memory counters when the gateway runs inside a container or memory-limited service.
critical memory pressure bundle written appears shortly before restart → OpenClaw captured a pre-OOM stability bundle. Inspect it with openclaw gateway stability --bundle latest.
memory pressure: level=critical appears in gateway logs → OpenClaw detected critical memory pressure and recorded the available in-process memory facts.
Largest session files: points at a very large redacted transcript path → reduce retained session history, inspect session growth, or move old transcripts out of the active store before restarting.
V8 heap: used bytes are close to the heap limit → lower prompt/session pressure or reduce concurrent work first. For a managed service, inspect Gateway heap: in openclaw gateway status; if it says not set, regenerate old service metadata with openclaw gateway install --force. Ambient shell NODE_OPTIONS is intentionally ignored. Use an explicit supervisor-level heap override only after confirming the sustained workload and leaving enough native-memory headroom.
Memory pressure: critical/rss_growth → memory grew quickly inside one sampling window. Check the latest logs for a large import, runaway tool output, repeated retries, or a batch of queued agent work.
Critical memory pressure appears in logs but no bundle exists → capture openclaw gateway diagnostics export after the event for the available operational evidence.
Gateway health
Diagnostics export
Sessions

openclaw gateway status --deep
openclaw logs --follow
openclaw gateway stability --bundle latest
openclaw gateway diagnostics export

Gateway rejected invalid config

Use when Gateway startup fails with Invalid config or hot reload logs say it skipped an invalid edit.

주요 항목:

Invalid config at ...
config reload skipped (invalid config): ...
Config write rejected: ...
A timestamped openclaw.json.rejected.* file beside the active config.
A timestamped openclaw.json.clobbered.* file if doctor --fix repaired a broken direct edit.
OpenClaw keeps the latest 32 .clobbered.* files for each config path and rotates older ones.
The config did not validate during startup, hot reload, or an OpenClaw-owned write.
Gateway startup fails closed instead of rewriting openclaw.json.
Hot reload skips invalid external edits and keeps the current runtime config active.
OpenClaw-owned writes reject invalid/destructive payloads before commit and save .rejected.*.
openclaw doctor --fix owns repair. It can remove non-JSON prefixes or restore the last-known-good copy while preserving the rejected payload as .clobbered.*.
When many repairs happen for one config path, OpenClaw rotates older .clobbered.* files so the newest repaired payload is still available.
.clobbered.* exists → doctor preserved a broken external edit while repairing the active config.
.rejected.* exists → an OpenClaw-owned config write failed schema or clobber checks before commit.
Config write rejected: → the write tried to drop required shape, shrink the file sharply, or persist invalid config.
config reload skipped (invalid config): → a direct edit failed validation and was ignored by the running Gateway.
Invalid config at ... → startup failed before Gateway services booted.
missing-meta-vs-last-good, gateway-mode-missing-vs-last-good, or size-drop-vs-last-good:* → an OpenClaw-owned write was rejected because it lost fields or size compared with the last-known-good backup.
Config last-known-good promotion skipped → the candidate contained redacted secret placeholders such as ***.
Config
Configuration: hot reload
Configuration: strict validation
Doctor

openclaw logs --follow
openclaw config file
openclaw config validate
openclaw doctor

CONFIG="$(openclaw config file)"
    ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head
    diff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"
    openclaw config validate
    openclaw doctor

Gateway probe warnings

Use when openclaw gateway probe reaches something, but still prints a warning block.

주요 항목:

warnings[].code and primaryTargetId in JSON output.
Whether the warning is about SSH fallback, multiple gateways, missing scopes, or unresolved auth refs.
SSH tunnel failed to start; falling back to direct probes. → SSH setup failed, but the command still tried direct configured/loopback targets.
multiple reachable gateway identities detected → distinct gateways answered, or OpenClaw could not prove reachable targets are the same gateway. An SSH tunnel, proxy URL, or configured remote URL to the same gateway is treated as one gateway with multiple transports, even when transport ports differ.
Read-probe diagnostics are limited by gateway scopes (missing operator.read) → connect worked, but detail RPC is scope-limited; pair device identity or use credentials with operator.read.
Gateway accepted the WebSocket connection, but follow-up read diagnostics failed → connect worked, but the full diagnostic RPC set timed out or failed. Treat this as a reachable Gateway with degraded diagnostics; compare connect.ok and connect.rpcOk in --json output.
Capability: pairing-pending or gateway closed (1008): pairing required → the gateway answered, but this client still needs pairing/approval before normal operator access.
Unresolved gateway.auth.* / gateway.remote.* SecretRef warning text → auth material was unavailable in this command path for the failed target.
Gateway
Multiple gateways on the same host
Remote access

openclaw gateway probe
openclaw gateway probe --json
openclaw gateway probe --ssh user@gateway-host

Channel connected, messages not flowing

If channel state is connected but message flow is dead, focus on policy, permissions, and channel specific delivery rules.

주요 항목:

DM policy (pairing, allowlist, open, disabled).
Group allowlist and mention requirements.
Missing channel API permissions/scopes.
mention required → message ignored by group mention policy.
pairing / pending approval traces → sender is not approved.
missing_scope, not_in_channel, Forbidden, 401/403 → channel auth/permissions issue.
Channel troubleshooting
Discord
Telegram
WhatsApp

openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw status --deep
openclaw logs --follow
openclaw config get channels

Cron and heartbeat delivery

If cron or heartbeat did not run or did not deliver, verify scheduler state first, then delivery target.

주요 항목:

Cron enabled and next wake present.
Job run history status (ok, skipped, error).
Heartbeat skip reasons (quiet-hours, requests-in-flight, cron-in-progress, lanes-busy, alerts-disabled, empty-heartbeat-file).
cron: scheduler disabled; jobs will not run automatically → cron disabled.
cron: timer tick failed → scheduler tick failed; check file/log/runtime errors.
heartbeat skipped with reason=quiet-hours → outside active hours window.
heartbeat skipped with reason=empty-heartbeat-file → heartbeat monitor scratch only contains blank, comment, header, fence, or empty-checklist scaffolding, so OpenClaw skips the model call.
heartbeat: unknown accountId → invalid account id for heartbeat delivery target.
heartbeat skipped with reason=dm-blocked → heartbeat target resolved to a DM-style destination while agents.defaults.heartbeat.directPolicy (or per-agent override) is set to block.
Heartbeat
Scheduled tasks
Scheduled tasks: troubleshooting

openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow

Node paired, tool fails

If a node is paired but tools fail, isolate foreground, permission, and approval state.

주요 항목:

Node online with expected capabilities.
OS permission grants for camera/mic/location/screen.
Exec approvals and allowlist state.
NODE_BACKGROUND_UNAVAILABLE → node app must be in foreground.
*_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → missing OS permission.
SYSTEM_RUN_DENIED: approval required → exec approval pending.
SYSTEM_RUN_DENIED: allowlist miss → command blocked by allowlist.
Exec approvals
Node troubleshooting
Nodes

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
openclaw status

Browser tool fails

Use when browser tool actions fail even though the gateway itself is healthy.

주요 항목:

Whether plugins.allow is set and includes browser.
Valid browser executable path.
CDP profile reachability.
Local Chrome availability for existing-session / user profiles.
unknown command "browser" or unknown command 'browser' → the bundled browser plugin is excluded by plugins.allow.
Browser tool missing / unavailable while browser.enabled=true → plugins.allow excludes browser, so the plugin never loaded.
Failed to start Chrome CDP on port → browser process failed to launch.
browser.executablePath not found → configured path is invalid.
browser.cdpUrl must be http(s) or ws(s) → the configured CDP URL uses an unsupported scheme such as file: or ftp:.
browser.cdpUrl has invalid port → the configured CDP URL has a bad or out-of-range port.
Playwright is not available in this gateway build; '<feature>' is unsupported. → the current gateway install lacks the core browser runtime dependency; reinstall or update OpenClaw, then restart the gateway. ARIA snapshots and basic page screenshots can still work, but navigation, AI snapshots, CSS-selector element screenshots, and PDF export stay unavailable.
Could not find DevToolsActivePort for chrome → Chrome MCP existing-session could not attach to the selected browser data dir yet. Open the browser inspect page, enable remote debugging, keep the browser open, approve the first attach prompt, then retry. If signed-in state is not required, prefer the managed openclaw profile.
No browser tabs found for profile="user" → the Chrome MCP attach profile has no open local Chrome tabs.
Remote CDP for profile "<name>" is not reachable → the configured remote CDP endpoint is not reachable from the gateway host.
Browser attachOnly is enabled ... not reachable or Browser attachOnly is enabled and CDP websocket ... is not reachable → attach-only profile has no reachable target, or the HTTP endpoint answered but the CDP WebSocket still could not be opened.
fullPage is not supported for element screenshots → screenshot request mixed --full-page with --ref or --element.
element screenshots are not supported for existing-session profiles; use ref from snapshot. → Chrome MCP / existing-session screenshot calls must use page capture or a snapshot --ref, not CSS --element.
existing-session file uploads do not support element selectors; use ref/inputRef. → Chrome MCP upload hooks need snapshot refs, not CSS selectors.
existing-session file uploads currently support one file at a time. → send one upload per call on Chrome MCP profiles.
existing-session dialog handling does not support timeoutMs. → dialog hooks on Chrome MCP profiles do not support timeout overrides.
existing-session type does not support timeoutMs overrides. → omit timeoutMs for act:type on profile="user" / Chrome MCP existing-session profiles, or use a managed/CDP browser profile when a custom timeout is required.
response body is not supported for existing-session profiles yet. → responsebody still requires a managed browser or raw CDP profile.
Stale viewport / dark-mode / locale / offline overrides on attach-only or remote CDP profiles → run openclaw browser stop --browser-profile <name> to close the active control session and release Playwright/CDP emulation state without restarting the whole gateway.
Browser (OpenClaw-managed)
Browser troubleshooting

openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw logs --follow
openclaw doctor

If you upgraded and something suddenly broke

Most post-upgrade breakage is config drift or stricter defaults now being enforced.

주요 항목:

If gateway.mode=remote, CLI calls may be targeting remote while your local service is fine.
Explicit --url calls do not fall back to stored credentials.
gateway connect failed: → wrong URL target.
unauthorized → endpoint reachable but wrong auth.
Non-loopback binds (lan, tailnet, custom) need a valid gateway auth path: shared token/password auth, or a correctly configured non-loopback trusted-proxy deployment.
Old keys like gateway.token do not replace gateway.auth.token.
refusing to bind gateway ... without auth → non-loopback bind without a valid gateway auth path.
Connectivity probe: failed while runtime is running → gateway alive but inaccessible with current auth/url.
Pending device approvals for dashboard/nodes.
Pending DM pairing approvals after policy or identity changes.
device identity required → device auth not satisfied.
pairing required → sender/device must be approved.
Authentication
Background exec and process tool
Node pairing

openclaw gateway status
    openclaw config get gateway.mode
    openclaw config get gateway.remote.url
    openclaw config get gateway.auth.mode

openclaw config get gateway.bind
    openclaw config get gateway.auth.mode
    openclaw config get gateway.auth.token
    openclaw gateway status
    openclaw logs --follow

openclaw devices list
    openclaw pairing list --channel <channel> [--account <id>]
    openclaw logs --follow
    openclaw doctor

openclaw gateway install --force
openclaw gateway restart

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/troubleshooting
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

openclaw status --all
openclaw update status --json
openclaw gateway status --deep
openclaw doctor --fix
openclaw gateway restart

which openclaw
openclaw --version
openclaw gateway status --deep
openclaw config get meta.lastTouchedVersion

openclaw gateway install --force
    openclaw gateway restart

openclaw --version
which -a openclaw
openclaw gateway status --deep
openclaw doctor --deep
openclaw logs --follow

Skipping escaped skill path outside its configured root: ... reason=symlink-escape

Troubleshooting

핵심 요약

문서 구성

상세 내용

본문

Command ladder

After an update

Split brain installs and newer config guard

Protocol mismatch after rollback

Skill symlink skipped as path escape

Anthropic 429 extra usage required for long context

Upstream 403 blocked responses

Local OpenAI-compatible backend passes direct probes but agent runs fail

No replies

Dashboard control UI connectivity

Auth detail codes quick map

Gateway service not running

macOS gateway silently stops responding, then resumes when you touch the dashboard

macOS launchd supervisor loop with duplicate gateway/node LaunchAgents

Gateway exits during high memory use

Gateway rejected invalid config

Gateway probe warnings

Channel connected, messages not flowing

Cron and heartbeat delivery

Node paired, tool fails

Browser tool fails

If you upgraded and something suddenly broke

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Troubleshooting

핵심 요약

문서 구성

상세 내용

본문

Command ladder

After an update

Split brain installs and newer config guard

Protocol mismatch after rollback

Skill symlink skipped as path escape

Anthropic 429 extra usage required for long context

Upstream 403 blocked responses

Local OpenAI-compatible backend passes direct probes but agent runs fail

No replies

Dashboard control UI connectivity

Auth detail codes quick map

Gateway service not running

macOS gateway silently stops responding, then resumes when you touch the dashboard

macOS launchd supervisor loop with duplicate gateway/node LaunchAgents

Gateway exits during high memory use

Gateway rejected invalid config

Gateway probe warnings

Channel connected, messages not flowing

Cron and heartbeat delivery

Node paired, tool fails

Browser tool fails

If you upgraded and something suddenly broke

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드