Troubleshooting

This page is the deep runbook. Start at /help/troubleshooting if you want the fast triage flow first.

Command ladder

Run these first, in this order:

OmeniaClaw statusOmeniaClaw gateway statusOmeniaClaw logs --followOmeniaClaw doctorOmeniaClaw channels status --probe

Expected healthy signals:

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

After an update

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

OmeniaClaw status --allOmeniaClaw update status --jsonOmeniaClaw gateway status --deepOmeniaClaw doctor --fixOmeniaClaw gateway restart

Look for:

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

Split brain installs and newer config guard

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

OmeniaClaw stamps config writes with meta.lastTouchedVersion. Read-only commands can still inspect a config written by a newer OmeniaClaw, but process and service mutations refuse to continue from an older binary. Blocked actions include gateway service start, stop, restart, uninstall, forced service reinstall, service-mode gateway startup, and gateway --force port cleanup.

which OmeniaClawOmeniaClaw --versionOmeniaClaw gateway status --deepOmeniaClaw config get meta.lastTouchedVersion

OmeniaClaw gateway install --forceOmeniaClaw gateway restart

Protocol mismatch after rollback

Use this when logs keep printing protocol mismatch after you downgrade or roll back OmeniaClaw. This means an older Gateway is running, but a newer local client process is still trying to reconnect with a protocol range that the older Gateway cannot speak.

OmeniaClaw --versionwhich -a OmeniaClawOmeniaClaw gateway status --deepOmeniaClaw doctor --deepOmeniaClaw logs --follow

Look for:

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

Fix:

1. Stop or restart the stale OmeniaClaw client process shown by gateway status --deep.
2. Restart apps or wrappers that embed OmeniaClaw, such as local dashboards, editors, app-server helpers, or long-running OmeniaClaw logs --follow shells.
3. Re-run OmeniaClaw gateway status --deep or OmeniaClaw doctor --deep and confirm the stale client PID is gone.

Do not make an older Gateway accept a newer incompatible protocol. Protocol bumps protect the wire contract; rollback recovery is a process/version cleanup problem.

Skill symlink skipped as path escape

Use this when logs include:

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

OmeniaClaw treats every skill root as a containment boundary. A symlink under ~/.agents/skills, <workspace>/.agents/skills, <workspace>/skills, or ~/.OmeniaClaw/skills is skipped when its real target resolves outside that root unless the target is explicitly trusted.

Inspect the link:

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

If the target is intentional, configure both the direct skill root and the allowed symlink target:

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

Then start a new session or wait for the skills watcher to refresh. Restart the gateway if the running process predates the config change.

Do not use broad targets such as ~, /, or a whole synced project folder. Keep allowSymlinkTargets scoped to the real skill root that contains trusted SKILL.md directories.

If Skill Workshop apply should also write through those trusted symlinked workspace skill paths, enable skills.workshop.allowSymlinkTargetWrites. Keep it disabled for read-only shared skill roots.

Related:

• Skills config
• Configuration examples

Anthropic 429 extra usage required for long context

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

OmeniaClaw logs --followOmeniaClaw models statusOmeniaClaw config get agents.defaults.models

Look for:

• Selected Anthropic model is a GA-capable 1M Claude 4.x model, or the model has 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.

Fix options:

Related:

• Anthropic
• Token use and costs
• Why am I seeing HTTP 429 from Anthropic?

Upstream 403 blocked responses

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

Do not assume this is always an OmeniaClaw configuration issue. The response can come from an upstream security layer such as a CDN, WAF, bot-management rule, or reverse proxy in front of an OpenAI-compatible endpoint.

OmeniaClaw statusOmeniaClaw gateway statusOmeniaClaw logs --follow

Look for:

• multiple models under the same provider failing in 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

Fix the provider-side filtering first when the evidence points to a WAF/CDN block. Prefer a narrowly scoped allow or skip rule for the API path OmeniaClaw uses, and avoid disabling protection for the whole site.

Related:

• OpenAI-compatible endpoints
• Provider configuration
• Logs

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

Use this when:

• curl ... /v1/models works
• tiny direct /v1/chat/completions calls work
• OmeniaClaw model runs fail only on normal agent turns

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

Look for:

• direct tiny calls succeed, but OmeniaClaw 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

Related:

• Configuration
• Local models
• OpenAI-compatible endpoints

No replies

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

OmeniaClaw statusOmeniaClaw channels status --probeOmeniaClaw pairing list --channel <channel> [--account <id>]OmeniaClaw config get channelsOmeniaClaw logs --follow

Look for:

• Pairing pending for DM senders.
• Group mention gating (requireMention, mentionPatterns).
• Channel/group allowlist mismatches.

Common signatures:

• drop guild message (mention required → group message ignored until mention.
• pairing request → sender needs approval.
• blocked / allowlist → sender/channel was filtered by policy.

Related:

• Channel troubleshooting
• Groups
• Pairing

Dashboard control UI connectivity

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

OmeniaClaw gateway statusOmeniaClaw statusOmeniaClaw logs --followOmeniaClaw doctorOmeniaClaw gateway status --json

Look for:

• Correct probe URL and dashboard URL.
• Auth mode/token mismatch between client and gateway.
• HTTP usage where device identity is required.

If a local browser cannot connect to 127.0.0.1:18789 after an update, first recover the local Gateway service and confirm it is serving the dashboard:

OmeniaClaw gateway restartlsof -i :18789curl http://127.0.0.1:18789

If curl returns OmeniaClaw HTML, the Gateway is working and the remaining issue is likely browser cache, an old deep link, or stale tab state. Open http://127.0.0.1:18789 directly and navigate from the dashboard. If restart does not leave the service running, run OmeniaClaw gateway start and recheck OmeniaClaw gateway status.

Auth detail codes quick map

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

Device auth v2 migration check:

OmeniaClaw --versionOmeniaClaw doctorOmeniaClaw gateway status

If logs show nonce/signature errors, update the connecting client and verify it:

If OmeniaClaw devices rotate / revoke / remove is denied unexpectedly:

• paired-device token sessions can manage only their own device unless the caller also has operator.admin
• OmeniaClaw devices rotate --scope ... can only request operator scopes that the caller session already holds

Related:

• Configuration (gateway auth modes)
• Control UI
• Devices
• Remote access
• Trusted proxy auth

Gateway service not running

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

OmeniaClaw gateway statusOmeniaClaw statusOmeniaClaw logs --followOmeniaClaw doctorOmeniaClaw gateway status --deep   # also scan system-level services

Look for:

• 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.

Related:

• Background exec and process tool
• Configuration
• Doctor

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

Use this 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 OmeniaClaw status because by the time you look the gateway is alive again.

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

Look for:

• One or more *-uncaught_exception.json bundles in ~/.OmeniaClaw/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.

Common signatures:

• A stability bundle whose error.code is ENETDOWN or a sibling code, with the call stack pointing into Node net lookupAndConnect / Socket.connect. OmeniaClaw 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/OmeniaClaw/gateway.log: clean shutdowns log a signal; transient crashes do not.

What to do:

1. Upgrade the gateway if you are running a release before 2026.5.26. After upgrading, future ENETDOWN errors are logged as warnings instead of terminating the process.

2. Reduce maintenance sleep activity on Mac mini / desktop hosts that are meant to run as always-on servers:

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

   This significantly reduces, but does not entirely eliminate, the underlying driver flap. The system can still perform some maintenance sleeps for TCP keepalive and mDNS upkeep regardless of these flags.

3. Add a liveness watchdog so a future crash burst that gets parked by launchd is caught quickly:

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

   The point is to externally re-arm the respawn gate; KeepAlive=true alone is not sufficient on macOS after a crash burst.

Related:

• macOS platform notes
• Logging
• Doctor

Gateway exits during high memory use

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

OmeniaClaw gateway status --deepOmeniaClaw logs --followOmeniaClaw gateway stability --bundle latestOmeniaClaw gateway diagnostics export

Look for:

• 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.

Common signatures:

• critical memory pressure bundle written appears shortly before restart → OmeniaClaw captured a pre-OOM stability bundle. Inspect it with OmeniaClaw gateway stability --bundle latest.
• memory pressure: level=critical ... memoryPressureSnapshot=disabled appears in gateway logs → OmeniaClaw detected critical memory pressure, but the pre-OOM stability snapshot is off.
• 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, reduce concurrent work, or raise the Node heap limit only after confirming the workload is expected.
• 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 → this is the default. Set diagnostics.memoryPressureSnapshot: true to capture the pre-OOM stability bundle on future critical memory pressure events.

The stability bundle is payload-free. It includes operational memory evidence and redacted relative file paths, not message text, webhook bodies, credentials, tokens, cookies, or raw session ids. Attach the diagnostics export to bug reports instead of copying raw logs.

Related:

• Gateway health
• Diagnostics export
• Sessions

Gateway rejected invalid config

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

OmeniaClaw logs --followOmeniaClaw config fileOmeniaClaw config validateOmeniaClaw doctor

Look for:

• Invalid config at ...
• config reload skipped (invalid config): ...
• Config write rejected: ...
• A timestamped OmeniaClaw.json.rejected.* file beside the active config
• A timestamped OmeniaClaw.json.clobbered.* file if doctor --fix repaired a broken direct edit
• OmeniaClaw keeps the latest 32 .clobbered.* files for each config path and rotates older ones

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

Related:

• Config
• Configuration: hot reload
• Configuration: strict validation
• Doctor

Gateway probe warnings

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

OmeniaClaw gateway probeOmeniaClaw gateway probe --jsonOmeniaClaw gateway probe --ssh user@gateway-host

Look for:

• warnings[].code and primaryTargetId in JSON output.
• Whether the warning is about SSH fallback, multiple gateways, missing scopes, or unresolved auth refs.

Common signatures:

• 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 OmeniaClaw 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.

Related:

• Gateway
• Multiple gateways on the same host
• Remote access

Channel connected, messages not flowing

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

OmeniaClaw channels status --probeOmeniaClaw pairing list --channel <channel> [--account <id>]OmeniaClaw status --deepOmeniaClaw logs --followOmeniaClaw config get channels

Look for:

• DM policy (pairing, allowlist, open, disabled).
• Group allowlist and mention requirements.
• Missing channel API permissions/scopes.

Common signatures:

• 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.

Related:

• Channel troubleshooting
• Discord
• Telegram
• WhatsApp

Cron and heartbeat delivery

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

OmeniaClaw cron statusOmeniaClaw cron listOmeniaClaw cron runs --id <jobId> --limit 20OmeniaClaw system heartbeat lastOmeniaClaw logs --follow

Look for:

• 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, no-tasks-due).

Related:

• Heartbeat
• Scheduled tasks
• Scheduled tasks: troubleshooting

Node paired, tool fails

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

OmeniaClaw nodes statusOmeniaClaw nodes describe --node <idOrNameOrIp>OmeniaClaw approvals get --node <idOrNameOrIp>OmeniaClaw logs --followOmeniaClaw status

Look for:

• Node online with expected capabilities.
• OS permission grants for camera/mic/location/screen.
• Exec approvals and allowlist state.

Common signatures:

• 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.

Related:

• Exec approvals
• Node troubleshooting
• Nodes

Browser tool fails

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

OmeniaClaw browser statusOmeniaClaw browser start --browser-profile OmeniaClawOmeniaClaw browser profilesOmeniaClaw logs --followOmeniaClaw doctor

Look for:

• Whether plugins.allow is set and includes browser.
• Valid browser executable path.
• CDP profile reachability.
• Local Chrome availability for existing-session / user profiles.

Related:

• Browser (OmeniaClaw-managed)
• Browser troubleshooting

If you upgraded and something suddenly broke

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

OmeniaClaw gateway statusOmeniaClaw config get gateway.modeOmeniaClaw config get gateway.remote.urlOmeniaClaw config get gateway.auth.mode

OmeniaClaw config get gateway.bindOmeniaClaw config get gateway.auth.modeOmeniaClaw config get gateway.auth.tokenOmeniaClaw gateway statusOmeniaClaw logs --follow

OmeniaClaw devices listOmeniaClaw pairing list --channel <channel> [--account <id>]OmeniaClaw logs --followOmeniaClaw doctor

If the service config and runtime still disagree after checks, reinstall service metadata from the same profile/state directory:

OmeniaClaw gateway install --forceOmeniaClaw gateway restart

Related:

• Authentication
• Background exec and process tool
• Gateway-owned pairing

Related

• Doctor
• FAQ
• Gateway runbook