English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Start here

General troubleshooting

If you only have 2 minutes, use this page as a triage front door.

First 60 seconds

Run this exact ladder in order:

bash
OmeniaClaw statusOmeniaClaw status --allOmeniaClaw gateway probeOmeniaClaw gateway statusOmeniaClaw doctorOmeniaClaw channels status --probeOmeniaClaw logs --follow

Good output in one line:

  • OmeniaClaw status → shows configured channels and no obvious auth errors.
  • OmeniaClaw status --all → full report is present and shareable.
  • OmeniaClaw gateway probe → expected gateway target is reachable (Reachable: yes). Capability: ... tells you what auth level the probe could prove, and Read probe: limited - missing scope: operator.read is degraded diagnostics, not a connect failure.
  • OmeniaClaw gateway status → Runtime: running, Connectivity probe: ok, and a plausible Capability: ... line. Use --require-rpc if you need read-scope RPC proof too.
  • OmeniaClaw doctor → no blocking config/service errors.
  • OmeniaClaw channels status --probe → reachable gateway returns live per-account transport state plus probe/audit results such as works or audit ok; if the gateway is unreachable, the command falls back to config-only summaries.
  • OmeniaClaw logs --follow → steady activity, no repeating fatal errors.

Assistant feels limited or missing tools

If the assistant cannot inspect files, run commands, use browser automation, or see expected tools, check the effective tool profile first:

bash
OmeniaClaw statusOmeniaClaw status --allOmeniaClaw doctor

Common causes:

  • tools.profile: "messaging" is intentionally narrow for chat-only agents.
  • tools.profile: "coding" is the usual profile for repository, file, shell, and runtime workflows.
  • tools.profile: "full" exposes the broadest tool set and should be limited to trusted operator-controlled agents.
  • Per-agent agents.list[].tools overrides can narrow or expand the root profile for one agent.

Change the root or per-agent tool profile, then restart or reload the Gateway and run OmeniaClaw status --all again. See Tools for the profile model and allow/deny overrides.

Anthropic long context 429

If you see: HTTP 429: rate_limit_error: Extra usage is required for long context requests, go to /gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context.

Local OpenAI-compatible backend works directly but fails in OmeniaClaw

If your local or self-hosted /v1 backend answers small direct /v1/chat/completions probes but fails on OmeniaClaw infer model run or normal agent turns:

  1. If the error mentions messages[].content expecting a string, set models.providers.<provider>.models[].compat.requiresStringContent: true.
  2. If the backend still fails only on OmeniaClaw agent turns, set models.providers.<provider>.models[].compat.supportsTools: false and retry.
  3. If tiny direct calls still work but larger OmeniaClaw prompts crash the backend, treat the remaining issue as an upstream model/server limitation and continue in the deep runbook: /gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail

Plugin install fails with missing OmeniaClaw extensions

If install fails with package.json missing OmeniaClaw.extensions, the plugin package is using an old shape that OmeniaClaw no longer accepts.

Fix in the plugin package:

  1. Add OmeniaClaw.extensions to package.json.
  2. Point entries at built runtime files (usually ./dist/index.js).
  3. Republish the plugin and run OmeniaClaw plugins install <package> again.

Example:

json
{  "name": "@OmeniaClaw/my-plugin",  "version": "1.2.3",  "OmeniaClaw": {    "extensions": ["./dist/index.js"]  }}

Reference: Plugin architecture

Install policy blocks plugin installs or updates

If an update finishes but plugins are stale, disabled, or show messages such as blocked by install policy, install policy failed closed, or Disabled "<plugin>" after plugin update failure, check security.installPolicy.

Install policy runs on plugin installs and updates. OmeniaClaw-owned plugin versions normally move with the OmeniaClaw release, so an OmeniaClaw update can also need matching @OmeniaClaw/* plugin updates during post-update sync.

Avoid these broad policy shapes unless you also maintain the matching upgrade rule:

  • Freezing OmeniaClaw-owned plugins to one exact old version, such as allowing only @OmeniaClaw/*@2026.5.3.
  • Blocking by source kind alone, such as every npm, network, or request.mode: "update" plugin request.
  • Treating the policy command as optional. When security.installPolicy is enabled, a missing, slow, unreadable, or permission-blocked policy executable fails closed.
  • Approving plugin versions without considering the policy request's OmeniaClawVersion and the plugin candidate metadata.

Safer policy rules allow trusted OmeniaClaw-owned plugin updates when the candidate is compatible with the current OmeniaClaw host, instead of pinning a single release forever. If you block npm by default, make a narrow exception for the trusted @OmeniaClaw/* plugin packages or plugin ids you use. If you differentiate install and update requests, apply the same trust rule to request.mode: "update".

Recovery:

bash
OmeniaClaw doctor --deepOmeniaClaw plugins update --allOmeniaClaw status --all

If the policy is intentionally strict, relax it for the trusted OmeniaClaw upgrade window, rerun OmeniaClaw plugins update --all, then restore the stricter rule. If a plugin was disabled after update failure, inspect it and re-enable it only after the update succeeds:

bash
OmeniaClaw plugins inspect <plugin-id> --runtime --jsonOmeniaClaw plugins enable <plugin-id>

Reference: Operator install policy

Plugin present but blocked by suspicious ownership

If OmeniaClaw doctor, setup, or startup warnings show:

text
blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)plugin present but blocked

the plugin files are owned by a different Unix user than the process loading them. Do not remove the plugin config. Fix the file ownership or run OmeniaClaw as the same user that owns the state directory.

Docker installs normally run as node (uid 1000). For the default Docker setup, repair the host bind mounts:

bash
sudo chown -R 1000:1000 /path/to/OmeniaClaw-config /path/to/OmeniaClaw-workspaceOmeniaClaw doctor --fix

If you intentionally run OmeniaClaw as root, repair the managed plugin root to root ownership instead:

bash
sudo chown -R root:root /path/to/OmeniaClaw-config/npmOmeniaClaw doctor --fix

Deeper docs:

Decision tree

flowchart TD
  A[OmeniaClaw is not working] --> B{What breaks first}
  B --> C[No replies]
  B --> D[Dashboard or Control UI will not connect]
  B --> E[Gateway will not start or service not running]
  B --> F[Channel connects but messages do not flow]
  B --> G[Cron or heartbeat did not fire or did not deliver]
  B --> H[Node is paired but camera canvas screen exec fails]
  B --> I[Browser tool fails]

  C --> C1[/No replies section/]
  D --> D1[/Control UI section/]
  E --> E1[/Gateway section/]
  F --> F1[/Channel flow section/]
  G --> G1[/Automation section/]
  H --> H1[/Node tools section/]
  I --> I1[/Browser section/]
No replies
bash
OmeniaClaw statusOmeniaClaw gateway statusOmeniaClaw channels status --probeOmeniaClaw pairing list --channel <channel> [--account <id>]OmeniaClaw logs --follow

Good output looks like:

  • Runtime: running
  • Connectivity probe: ok
  • Capability: read-only, write-capable, or admin-capable
  • Your channel shows transport connected and, where supported, works or audit ok in channels status --probe
  • Sender appears approved (or DM policy is open/allowlist)

Common log signatures:

  • drop guild message (mention required → mention gating blocked the message in Discord.
  • pairing request → sender is unapproved and waiting for DM pairing approval.
  • blocked / allowlist in channel logs → sender, room, or group is filtered.

Deep pages:

Dashboard or Control UI will not connect
bash
OmeniaClaw statusOmeniaClaw gateway statusOmeniaClaw logs --followOmeniaClaw doctorOmeniaClaw channels status --probe

Good output looks like:

  • Dashboard: http://... is shown in OmeniaClaw gateway status
  • Connectivity probe: ok
  • Capability: read-only, write-capable, or admin-capable
  • No auth loop in logs

Common log signatures:

  • device identity required → HTTP/non-secure context cannot complete device auth.
  • origin not allowed → browser Origin is not allowed for the Control UI gateway target.
  • AUTH_TOKEN_MISMATCH with retry hints (canRetryWithDeviceToken=true) → one trusted device-token retry may occur automatically.
  • 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.
  • On the async Tailscale Serve Control UI path, failed attempts for the same {scope, ip} are serialized before the limiter records the failure, so a second concurrent bad retry can already show retry later.
  • too many failed authentication attempts (retry later) from a localhost browser origin → repeated failures from that same Origin are temporarily locked out; another localhost origin uses a separate bucket.
  • repeated unauthorized after that retry → wrong token/password, auth mode mismatch, or stale paired device token.
  • gateway connect failed: → UI is targeting the wrong URL/port or unreachable gateway.

Deep pages:

Gateway will not start or service installed but not running
bash
OmeniaClaw statusOmeniaClaw gateway statusOmeniaClaw logs --followOmeniaClaw doctorOmeniaClaw channels status --probe

Good output looks like:

  • Service: ... (loaded)
  • Runtime: running
  • Connectivity probe: ok
  • Capability: read-only, write-capable, or admin-capable

Common log signatures:

  • Gateway start blocked: set gateway.mode=local or existing config is missing gateway.mode → gateway mode is remote, or the config file is missing the local-mode stamp and should be repaired.
  • 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 or EADDRINUSE → port already taken.

Deep pages:

Channel connects but messages do not flow
bash
OmeniaClaw statusOmeniaClaw gateway statusOmeniaClaw logs --followOmeniaClaw doctorOmeniaClaw channels status --probe

Good output looks like:

  • Channel transport is connected.
  • Pairing/allowlist checks pass.
  • Mentions are detected where required.

Common log signatures:

  • mention required → group mention gating blocked processing.
  • pairing / pending → DM sender is not approved yet.
  • not_in_channel, missing_scope, Forbidden, 401/403 → channel permission token issue.

Deep pages:

Cron or heartbeat did not fire or did not deliver
bash
OmeniaClaw statusOmeniaClaw gateway statusOmeniaClaw cron statusOmeniaClaw cron listOmeniaClaw cron runs --id <jobId> --limit 20OmeniaClaw logs --follow

Good output looks like:

  • cron.status shows enabled with a next wake.
  • cron runs shows recent ok entries.
  • Heartbeat is enabled and not outside active hours.

Common log signatures:

  • cron: scheduler disabled; jobs will not run automatically → cron is disabled.
  • heartbeat skipped with reason=quiet-hours → outside configured active hours.
  • heartbeat skipped with reason=empty-heartbeat-file → HEARTBEAT.md exists but only contains blank, comment, header, fence, or empty-checklist scaffolding.
  • heartbeat skipped with reason=no-tasks-due → HEARTBEAT.md task mode is active but none of the task intervals are due yet.
  • heartbeat skipped with reason=alerts-disabled → all heartbeat visibility is disabled (showOk, showAlerts, and useIndicator are all off).
  • requests-in-flight → main lane busy; heartbeat wake was deferred.
  • unknown accountId → heartbeat delivery target account does not exist.

Deep pages:

Node is paired but tool fails camera canvas screen exec
bash
OmeniaClaw statusOmeniaClaw gateway statusOmeniaClaw nodes statusOmeniaClaw nodes describe --node <idOrNameOrIp>OmeniaClaw logs --follow

Good output looks like:

  • Node is listed as connected and paired for role node.
  • Capability exists for the command you are invoking.
  • Permission state is granted for the tool.

Common log signatures:

  • NODE_BACKGROUND_UNAVAILABLE → bring node app to foreground.
  • *_PERMISSION_REQUIRED → OS permission was denied/missing.
  • SYSTEM_RUN_DENIED: approval required → exec approval is pending.
  • SYSTEM_RUN_DENIED: allowlist miss → command not on exec allowlist.

Deep pages:

Exec suddenly asks for approval
bash
OmeniaClaw config get tools.exec.hostOmeniaClaw config get tools.exec.securityOmeniaClaw config get tools.exec.askOmeniaClaw gateway restart

What changed:

  • If tools.exec.host is unset, the default is auto.
  • host=auto resolves to sandbox when a sandbox runtime is active, gateway otherwise.
  • host=auto is routing only; the no-prompt "YOLO" behavior comes from security=full plus ask=off on gateway/node.
  • On gateway and node, unset tools.exec.security defaults to full.
  • Unset tools.exec.ask defaults to off.
  • Result: if you are seeing approvals, some host-local or per-session policy tightened exec away from the current defaults.

Restore current default no-approval behavior:

bash
OmeniaClaw config set tools.exec.host gatewayOmeniaClaw config set tools.exec.security fullOmeniaClaw config set tools.exec.ask offOmeniaClaw gateway restart

Safer alternatives:

  • Set only tools.exec.host=gateway if you just want stable host routing.
  • Use security=allowlist with ask=on-miss if you want host exec but still want review on allowlist misses.
  • Enable sandbox mode if you want host=auto to resolve back to sandbox.

Common log signatures:

  • Approval required. → command is waiting on /approve ....
  • SYSTEM_RUN_DENIED: approval required → node-host exec approval is pending.
  • exec host=sandbox requires a sandbox runtime for this session → implicit/explicit sandbox selection but sandbox mode is off.

Deep pages:

Browser tool fails
bash
OmeniaClaw statusOmeniaClaw gateway statusOmeniaClaw browser statusOmeniaClaw logs --followOmeniaClaw doctor

Good output looks like:

  • Browser status shows running: true and a chosen browser/profile.
  • OmeniaClaw starts, or user can see local Chrome tabs.

Common log signatures:

  • unknown command "browser" or unknown command 'browser' → plugins.allow is set and does not include browser.
  • Failed to start Chrome CDP on port → local browser launch failed.
  • browser.executablePath not found → configured binary path is wrong.
  • browser.cdpUrl must be http(s) or ws(s) → the configured CDP URL uses an unsupported scheme.
  • browser.cdpUrl has invalid port → the configured CDP URL has a bad or out-of-range port.
  • No Chrome 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 this host.
  • Browser attachOnly is enabled ... not reachable or Browser attachOnly is enabled and CDP websocket ... is not reachable → attach-only profile has no live CDP target.
  • stale viewport / dark-mode / locale / offline overrides on attach-only or remote CDP profiles → run OmeniaClaw browser stop --browser-profile <name> to close the active control session and release emulation state without restarting the gateway.

Deep pages:

Was this useful?
On this page

On this page