{
  "title": "Run on the gateway host (paste the setup-token)",
  "content": "openclaw models auth setup-token --provider anthropic\nopenclaw models status\nbash theme={null}\nopenclaw models auth paste-token --provider anthropic\nopenclaw models status\nbash theme={null}\nopenclaw gateway status\nopenclaw doctor\njson theme={null}\n  { \"logging\": { \"level\": \"debug\" } }\n  json theme={null}\n  { \"logging\": { \"consoleLevel\": \"debug\", \"consoleStyle\": \"pretty\" } }\n  bash theme={null}\n  openclaw configure\n  bash theme={null}\n  openclaw config set gateway.mode local\n  bash theme={null}\n  openclaw config set gateway.mode remote\n  openclaw config set gateway.remote.url \"wss://gateway.example.com\"\n  bash theme={null}\nopenclaw gateway status\nbash theme={null}\nopenclaw status\nbash theme={null}",
  "code_samples": [
    {
      "code": "If you generated the token elsewhere:",
      "language": "unknown"
    },
    {
      "code": "More detail: [Anthropic](/providers/anthropic) and [OAuth](/concepts/oauth).\n\n### Control UI fails on HTTP (\"device identity required\" / \"connect failed\")\n\nIf you open the dashboard over plain HTTP (e.g. `http://<lan-ip>:18789/` or\n`http://<tailscale-ip>:18789/`), the browser runs in a **non-secure context** and\nblocks WebCrypto, so device identity can’t be generated.\n\n**Fix:**\n\n* Prefer HTTPS via [Tailscale Serve](/gateway/tailscale).\n* Or open locally on the gateway host: `http://127.0.0.1:18789/`.\n* If you must stay on HTTP, enable `gateway.controlUi.allowInsecureAuth: true` and\n  use a gateway token (token-only; no device identity/pairing). See\n  [Control UI](/web/control-ui#insecure-http).\n\n### CI Secrets Scan Failed\n\nThis means `detect-secrets` found new candidates not yet in the baseline.\nFollow [Secret scanning](/gateway/security#secret-scanning-detect-secrets).\n\n### Service Installed but Nothing is Running\n\nIf the gateway service is installed but the process exits immediately, the service\ncan appear “loaded” while nothing is running.\n\n**Check:**",
      "language": "unknown"
    },
    {
      "code": "Doctor/service will show runtime state (PID/last exit) and log hints.\n\n**Logs:**\n\n* Preferred: `openclaw logs --follow`\n* File logs (always): `/tmp/openclaw/openclaw-YYYY-MM-DD.log` (or your configured `logging.file`)\n* macOS LaunchAgent (if installed): `$OPENCLAW_STATE_DIR/logs/gateway.log` and `gateway.err.log`\n* Linux systemd (if installed): `journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager`\n* Windows: `schtasks /Query /TN \"OpenClaw Gateway (<profile>)\" /V /FO LIST`\n\n**Enable more logging:**\n\n* Bump file log detail (persisted JSONL):",
      "language": "unknown"
    },
    {
      "code": "* Bump console verbosity (TTY output only):",
      "language": "unknown"
    },
    {
      "code": "* Quick tip: `--verbose` affects **console** output only. File logs remain controlled by `logging.level`.\n\nSee [/logging](/logging) for a full overview of formats, config, and access.\n\n### \"Gateway start blocked: set gateway.mode=local\"\n\nThis means the config exists but `gateway.mode` is unset (or not `local`), so the\nGateway refuses to start.\n\n**Fix (recommended):**\n\n* Run the wizard and set the Gateway run mode to **Local**:",
      "language": "unknown"
    },
    {
      "code": "* Or set it directly:",
      "language": "unknown"
    },
    {
      "code": "**If you meant to run a remote Gateway instead:**\n\n* Set a remote URL and keep `gateway.mode=remote`:",
      "language": "unknown"
    },
    {
      "code": "**Ad-hoc/dev only:** pass `--allow-unconfigured` to start the gateway without\n`gateway.mode=local`.\n\n**No config file yet?** Run `openclaw setup` to create a starter config, then rerun\nthe gateway.\n\n### Service Environment (PATH + runtime)\n\nThe gateway service runs with a **minimal PATH** to avoid shell/manager cruft:\n\n* macOS: `/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin`, `/bin`\n* Linux: `/usr/local/bin`, `/usr/bin`, `/bin`\n\nThis intentionally excludes version managers (nvm/fnm/volta/asdf) and package\nmanagers (pnpm/npm) because the service does not load your shell init. Runtime\nvariables like `DISPLAY` should live in `~/.openclaw/.env` (loaded early by the\ngateway).\nExec runs on `host=gateway` merge your login-shell `PATH` into the exec environment,\nso missing tools usually mean your shell init isn’t exporting them (or set\n`tools.exec.pathPrepend`). See [/tools/exec](/tools/exec).\n\nWhatsApp + Telegram channels require **Node**; Bun is unsupported. If your\nservice was installed with Bun or a version-managed Node path, run `openclaw doctor`\nto migrate to a system Node install.\n\n### Skill missing API key in sandbox\n\n**Symptom:** Skill works on host but fails in sandbox with missing API key.\n\n**Why:** sandboxed exec runs inside Docker and does **not** inherit host `process.env`.\n\n**Fix:**\n\n* set `agents.defaults.sandbox.docker.env` (or per-agent `agents.list[].sandbox.docker.env`)\n* or bake the key into your custom sandbox image\n* then run `openclaw sandbox recreate --agent <id>` (or `--all`)\n\n### Service Running but Port Not Listening\n\nIf the service reports **running** but nothing is listening on the gateway port,\nthe Gateway likely refused to bind.\n\n**What \"running\" means here**\n\n* `Runtime: running` means your supervisor (launchd/systemd/schtasks) thinks the process is alive.\n* `RPC probe` means the CLI could actually connect to the gateway WebSocket and call `status`.\n* Always trust `Probe target:` + `Config (service):` as the “what did we actually try?” lines.\n\n**Check:**\n\n* `gateway.mode` must be `local` for `openclaw gateway` and the service.\n* If you set `gateway.mode=remote`, the **CLI defaults** to a remote URL. The service can still be running locally, but your CLI may be probing the wrong place. Use `openclaw gateway status` to see the service’s resolved port + probe target (or pass `--url`).\n* `openclaw gateway status` and `openclaw doctor` surface the **last gateway error** from logs when the service looks running but the port is closed.\n* Non-loopback binds (`lan`/`tailnet`/`custom`, or `auto` when loopback is unavailable) require auth:\n  `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`).\n* `gateway.remote.token` is for remote CLI calls only; it does **not** enable local auth.\n* `gateway.token` is ignored; use `gateway.auth.token`.\n\n**If `openclaw gateway status` shows a config mismatch**\n\n* `Config (cli): ...` and `Config (service): ...` should normally match.\n* If they don’t, you’re almost certainly editing one config while the service is running another.\n* Fix: rerun `openclaw gateway install --force` from the same `--profile` / `OPENCLAW_STATE_DIR` you want the service to use.\n\n**If `openclaw gateway status` reports service config issues**\n\n* The supervisor config (launchd/systemd/schtasks) is missing current defaults.\n* Fix: run `openclaw doctor` to update it (or `openclaw gateway install --force` for a full rewrite).\n\n**If `Last gateway error:` mentions “refusing to bind … without auth”**\n\n* You set `gateway.bind` to a non-loopback mode (`lan`/`tailnet`/`custom`, or `auto` when loopback is unavailable) but didn’t configure auth.\n* Fix: set `gateway.auth.mode` + `gateway.auth.token` (or export `OPENCLAW_GATEWAY_TOKEN`) and restart the service.\n\n**If `openclaw gateway status` says `bind=tailnet` but no tailnet interface was found**\n\n* The gateway tried to bind to a Tailscale IP (100.64.0.0/10) but none were detected on the host.\n* Fix: bring up Tailscale on that machine (or change `gateway.bind` to `loopback`/`lan`).\n\n**If `Probe note:` says the probe uses loopback**\n\n* That’s expected for `bind=lan`: the gateway listens on `0.0.0.0` (all interfaces), and loopback should still connect locally.\n* For remote clients, use a real LAN IP (not `0.0.0.0`) plus the port, and ensure auth is configured.\n\n### Address Already in Use (Port 18789)\n\nThis means something is already listening on the gateway port.\n\n**Check:**",
      "language": "unknown"
    },
    {
      "code": "It will show the listener(s) and likely causes (gateway already running, SSH tunnel).\nIf needed, stop the service or pick a different port.\n\n### Extra Workspace Folders Detected\n\nIf you upgraded from older installs, you might still have `~/openclaw` on disk.\nMultiple workspace directories can cause confusing auth or state drift because\nonly one workspace is active.\n\n**Fix:** keep a single active workspace and archive/remove the rest. See\n[Agent workspace](/concepts/agent-workspace#extra-workspace-folders).\n\n### Main chat running in a sandbox workspace\n\nSymptoms: `pwd` or file tools show `~/.openclaw/sandboxes/...` even though you\nexpected the host workspace.\n\n**Why:** `agents.defaults.sandbox.mode: \"non-main\"` keys off `session.mainKey` (default `\"main\"`).\nGroup/channel sessions use their own keys, so they are treated as non-main and\nget sandbox workspaces.\n\n**Fix options:**\n\n* If you want host workspaces for an agent: set `agents.list[].sandbox.mode: \"off\"`.\n* If you want host workspace access inside sandbox: set `workspaceAccess: \"rw\"` for that agent.\n\n### \"Agent was aborted\"\n\nThe agent was interrupted mid-response.\n\n**Causes:**\n\n* User sent `stop`, `abort`, `esc`, `wait`, or `exit`\n* Timeout exceeded\n* Process crashed\n\n**Fix:** Just send another message. The session continues.\n\n### \"Agent failed before reply: Unknown model: anthropic/claude-haiku-3-5\"\n\nOpenClaw intentionally rejects **older/insecure models** (especially those more\nvulnerable to prompt injection). If you see this error, the model name is no\nlonger supported.\n\n**Fix:**\n\n* Pick a **latest** model for the provider and update your config or model alias.\n* If you’re unsure which models are available, run `openclaw models list` or\n  `openclaw models scan` and choose a supported one.\n* Check gateway logs for the detailed failure reason.\n\nSee also: [Models CLI](/cli/models) and [Model providers](/concepts/model-providers).\n\n### Messages Not Triggering\n\n**Check 1:** Is the sender allowlisted?",
      "language": "unknown"
    },
    {
      "code": "Look for `AllowFrom: ...` in the output.\n\n**Check 2:** For group chats, is mention required?",
      "language": "unknown"
    }
  ],
  "headings": [
    {
      "level": "h3",
      "text": "Control UI fails on HTTP (\"device identity required\" / \"connect failed\")",
      "id": "control-ui-fails-on-http-(\"device-identity-required\"-/-\"connect-failed\")"
    },
    {
      "level": "h3",
      "text": "CI Secrets Scan Failed",
      "id": "ci-secrets-scan-failed"
    },
    {
      "level": "h3",
      "text": "Service Installed but Nothing is Running",
      "id": "service-installed-but-nothing-is-running"
    },
    {
      "level": "h3",
      "text": "\"Gateway start blocked: set gateway.mode=local\"",
      "id": "\"gateway-start-blocked:-set-gateway.mode=local\""
    },
    {
      "level": "h3",
      "text": "Service Environment (PATH + runtime)",
      "id": "service-environment-(path-+-runtime)"
    },
    {
      "level": "h3",
      "text": "Skill missing API key in sandbox",
      "id": "skill-missing-api-key-in-sandbox"
    },
    {
      "level": "h3",
      "text": "Service Running but Port Not Listening",
      "id": "service-running-but-port-not-listening"
    },
    {
      "level": "h3",
      "text": "Address Already in Use (Port 18789)",
      "id": "address-already-in-use-(port-18789)"
    },
    {
      "level": "h3",
      "text": "Extra Workspace Folders Detected",
      "id": "extra-workspace-folders-detected"
    },
    {
      "level": "h3",
      "text": "Main chat running in a sandbox workspace",
      "id": "main-chat-running-in-a-sandbox-workspace"
    },
    {
      "level": "h3",
      "text": "\"Agent was aborted\"",
      "id": "\"agent-was-aborted\""
    },
    {
      "level": "h3",
      "text": "\"Agent failed before reply: Unknown model: anthropic/claude-haiku-3-5\"",
      "id": "\"agent-failed-before-reply:-unknown-model:-anthropic/claude-haiku-3-5\""
    },
    {
      "level": "h3",
      "text": "Messages Not Triggering",
      "id": "messages-not-triggering"
    }
  ],
  "url": "llms-txt#run-on-the-gateway-host-(paste-the-setup-token)",
  "links": []
}