Genesis Docs

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

First 60 seconds

Run this exact ladder in order:

genesis status
genesis status --all
genesis gateway probe
genesis gateway status
genesis doctor
genesis channels status --probe
genesis logs --follow

Good output in one line:

  • genesis status → shows configured channels and no obvious auth errors.
  • genesis status --all → full report is present and shareable.
  • genesis 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.
  • genesis gateway status → Runtime: running, Connectivity probe: ok, and a plausible Capability: ... line. Use --require-rpc if you need read-scope RPC proof too.
  • genesis doctor → no blocking config/service errors.
  • genesis 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.
  • genesis logs --follow → steady activity, no repeating fatal errors.

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 Genesis

If your local or self-hosted /v1 backend answers small direct /v1/chat/completions probes but fails on genesis 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 Genesis agent turns, set models.providers.<provider>.models[].compat.supportsTools: false and retry.
  3. If tiny direct calls still work but larger Genesis 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 plugin extensions

If install fails with package.json missing genesis.extensions, the plugin package is using an old shape that Genesis no longer accepts. OpenClaw-compatible packages may declare the same entrypoints under openclaw.extensions.

Fix in the plugin package:

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

Example:

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

Reference: Plugin architecture

MCP OAuth popup closes immediately

If the MCP OAuth popup opens, flashes, and closes without connecting, the callback page either could not reach the Control UI or the message was rejected as untrusted. Common causes:

  1. Origin mismatch. The Control UI accepts the callback only from the gateway web origin. If you reach the Control UI through a different host or port than the one the gateway serves, the callback message is dropped. Open the Control UI from the same origin the gateway prints on startup.
  2. Callback page not served. The redirect target is /mcp-oauth-callback.html on the gateway web origin. If a reverse proxy or custom base path hides it, the provider cannot return the code. Confirm the page loads directly in a browser.
  3. Wrong redirect URI registered. The provider must allow the gateway redirect URI exactly. For remote gateways, set GENESIS_GATEWAY_WEB_URL (or gateway.remote.url) so the redirect matches the externally reachable URL.

Reference: MCP OAuth

Decision tree

flowchart TD
  A[Genesis 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
genesis status
genesis gateway status
genesis channels status --probe
genesis pairing list --channel <channel> [--account <id>]
genesis 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:

- [/gateway/troubleshooting#no-replies](/gateway/troubleshooting#no-replies)
- [/channels/troubleshooting](/channels/troubleshooting)
- [/channels/pairing](/channels/pairing)

Dashboard or Control UI will not connect

```bash
genesis status
genesis gateway status
genesis logs --follow
genesis doctor
genesis channels status --probe
```

Good output looks like:

- `Dashboard: http://...` is shown in `genesis 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/troubleshooting#dashboard-control-ui-connectivity](/gateway/troubleshooting#dashboard-control-ui-connectivity)
- [/web/control-ui](/web/control-ui)
- [/gateway/authentication](/gateway/authentication)

Gateway will not start or service installed but not running

```bash
genesis status
genesis gateway status
genesis logs --follow
genesis doctor
genesis 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:

- [/gateway/troubleshooting#gateway-service-not-running](/gateway/troubleshooting#gateway-service-not-running)
- [/gateway/background-process](/gateway/background-process)
- [/gateway/configuration](/gateway/configuration)

Channel connects but messages do not flow

```bash
genesis status
genesis gateway status
genesis logs --follow
genesis doctor
genesis 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:

- [/gateway/troubleshooting#channel-connected-messages-not-flowing](/gateway/troubleshooting#channel-connected-messages-not-flowing)
- [/channels/troubleshooting](/channels/troubleshooting)

Cron or heartbeat did not fire or did not deliver

```bash
genesis status
genesis gateway status
genesis cron status
genesis cron list
genesis cron runs --id <jobId> --limit 20
genesis 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/header-only 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:

- [/gateway/troubleshooting#cron-and-heartbeat-delivery](/gateway/troubleshooting#cron-and-heartbeat-delivery)
- [/automation/cron-jobs#troubleshooting](/automation/cron-jobs#troubleshooting)
- [/gateway/heartbeat](/gateway/heartbeat)

Node is paired but tool fails camera canvas screen exec

```bash
genesis status
genesis gateway status
genesis nodes status
genesis nodes describe --node <idOrNameOrIp>
genesis 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:

- [/gateway/troubleshooting#node-paired-tool-fails](/gateway/troubleshooting#node-paired-tool-fails)
- [/nodes/troubleshooting](/nodes/troubleshooting)
- [/tools/exec-approvals](/tools/exec-approvals)

Exec suddenly asks for approval

```bash
genesis config get tools.exec.host
genesis config get tools.exec.security
genesis config get tools.exec.ask
genesis 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
genesis config set tools.exec.host gateway
genesis config set tools.exec.security full
genesis config set tools.exec.ask off
genesis 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:

- [/tools/exec](/tools/exec)
- [/tools/exec-approvals](/tools/exec-approvals)
- [/gateway/security#what-the-audit-checks-high-level](/gateway/security#what-the-audit-checks-high-level)

Browser tool fails

```bash
genesis status
genesis gateway status
genesis browser status
genesis logs --follow
genesis doctor
```

Good output looks like:

- Browser status shows `running: true` and a chosen browser/profile.
- `genesis` 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 `genesis browser stop --browser-profile <name>` to close the active control session and release emulation state without restarting the gateway.

Deep pages:

- [/gateway/troubleshooting#browser-tool-fails](/gateway/troubleshooting#browser-tool-fails)
- [/tools/browser#missing-browser-command-or-tool](/tools/browser#missing-browser-command-or-tool)
- [/tools/browser-linux-troubleshooting](/tools/browser-linux-troubleshooting)
- [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/tools/browser-wsl2-windows-remote-cdp-troubleshooting)

Related