{
  "title": "Troubleshooting",
  "content": "If the gateway is reachable, deep probes:\n\n## Common “it broke” cases\n\n### `openclaw: command not found`\n\nAlmost always a Node/npm PATH issue. Start here:\n\n* [Install (Node/npm PATH sanity)](/install#nodejs--npm-path-sanity)\n\n### Installer fails (or you need full logs)\n\nRe-run the installer in verbose mode to see the full trace and npm output:\n\nYou can also set `OPENCLAW_VERBOSE=1` instead of the flag.\n\n### Gateway “unauthorized”, can’t connect, or keeps reconnecting\n\n* [Gateway troubleshooting](/gateway/troubleshooting)\n* [Gateway authentication](/gateway/authentication)\n\n### Control UI fails on HTTP (device identity required)\n\n* [Gateway troubleshooting](/gateway/troubleshooting)\n* [Control UI](/web/control-ui#insecure-http)\n\n### `docs.openclaw.ai` shows an SSL error (Comcast/Xfinity)\n\nSome Comcast/Xfinity connections block `docs.openclaw.ai` via Xfinity Advanced Security.\nDisable Advanced Security or add `docs.openclaw.ai` to the allowlist, then retry.\n\n* Xfinity Advanced Security help: [https://www.xfinity.com/support/articles/using-xfinity-xfi-advanced-security](https://www.xfinity.com/support/articles/using-xfinity-xfi-advanced-security)\n* Quick sanity checks: try a mobile hotspot or VPN to confirm it’s ISP-level filtering\n\n### Service says running, but RPC probe fails\n\n* [Gateway troubleshooting](/gateway/troubleshooting)\n* [Background process / service](/gateway/background-process)\n\n### Model/auth failures (rate limit, billing, “all models failed”)\n\n* [Models](/cli/models)\n* [OAuth / auth concepts](/concepts/oauth)\n\n### `/model` says `model not allowed`\n\nThis usually means `agents.defaults.models` is configured as an allowlist. When it’s non-empty,\nonly those provider/model keys can be selected.\n\n* Check the allowlist: `openclaw config get agents.defaults.models`\n* Add the model you want (or clear the allowlist) and retry `/model`\n* Use `/models` to browse the allowed providers/models\n\n### When filing an issue\n\nIf you can, include the relevant log tail from `openclaw logs --follow`.",
  "code_samples": [
    {
      "code": "If the gateway is reachable, deep probes:",
      "language": "unknown"
    },
    {
      "code": "## Common “it broke” cases\n\n### `openclaw: command not found`\n\nAlmost always a Node/npm PATH issue. Start here:\n\n* [Install (Node/npm PATH sanity)](/install#nodejs--npm-path-sanity)\n\n### Installer fails (or you need full logs)\n\nRe-run the installer in verbose mode to see the full trace and npm output:",
      "language": "unknown"
    },
    {
      "code": "For beta installs:",
      "language": "unknown"
    },
    {
      "code": "You can also set `OPENCLAW_VERBOSE=1` instead of the flag.\n\n### Gateway “unauthorized”, can’t connect, or keeps reconnecting\n\n* [Gateway troubleshooting](/gateway/troubleshooting)\n* [Gateway authentication](/gateway/authentication)\n\n### Control UI fails on HTTP (device identity required)\n\n* [Gateway troubleshooting](/gateway/troubleshooting)\n* [Control UI](/web/control-ui#insecure-http)\n\n### `docs.openclaw.ai` shows an SSL error (Comcast/Xfinity)\n\nSome Comcast/Xfinity connections block `docs.openclaw.ai` via Xfinity Advanced Security.\nDisable Advanced Security or add `docs.openclaw.ai` to the allowlist, then retry.\n\n* Xfinity Advanced Security help: [https://www.xfinity.com/support/articles/using-xfinity-xfi-advanced-security](https://www.xfinity.com/support/articles/using-xfinity-xfi-advanced-security)\n* Quick sanity checks: try a mobile hotspot or VPN to confirm it’s ISP-level filtering\n\n### Service says running, but RPC probe fails\n\n* [Gateway troubleshooting](/gateway/troubleshooting)\n* [Background process / service](/gateway/background-process)\n\n### Model/auth failures (rate limit, billing, “all models failed”)\n\n* [Models](/cli/models)\n* [OAuth / auth concepts](/concepts/oauth)\n\n### `/model` says `model not allowed`\n\nThis usually means `agents.defaults.models` is configured as an allowlist. When it’s non-empty,\nonly those provider/model keys can be selected.\n\n* Check the allowlist: `openclaw config get agents.defaults.models`\n* Add the model you want (or clear the allowlist) and retry `/model`\n* Use `/models` to browse the allowed providers/models\n\n### When filing an issue\n\nPaste a safe report:",
      "language": "unknown"
    }
  ],
  "headings": [
    {
      "level": "h2",
      "text": "First 60 seconds",
      "id": "first-60-seconds"
    },
    {
      "level": "h2",
      "text": "Common “it broke” cases",
      "id": "common-“it-broke”-cases"
    },
    {
      "level": "h3",
      "text": "`openclaw: command not found`",
      "id": "`openclaw:-command-not-found`"
    },
    {
      "level": "h3",
      "text": "Installer fails (or you need full logs)",
      "id": "installer-fails-(or-you-need-full-logs)"
    },
    {
      "level": "h3",
      "text": "Gateway “unauthorized”, can’t connect, or keeps reconnecting",
      "id": "gateway-“unauthorized”,-can’t-connect,-or-keeps-reconnecting"
    },
    {
      "level": "h3",
      "text": "Control UI fails on HTTP (device identity required)",
      "id": "control-ui-fails-on-http-(device-identity-required)"
    },
    {
      "level": "h3",
      "text": "`docs.openclaw.ai` shows an SSL error (Comcast/Xfinity)",
      "id": "`docs.openclaw.ai`-shows-an-ssl-error-(comcast/xfinity)"
    },
    {
      "level": "h3",
      "text": "Service says running, but RPC probe fails",
      "id": "service-says-running,-but-rpc-probe-fails"
    },
    {
      "level": "h3",
      "text": "Model/auth failures (rate limit, billing, “all models failed”)",
      "id": "model/auth-failures-(rate-limit,-billing,-“all-models-failed”)"
    },
    {
      "level": "h3",
      "text": "`/model` says `model not allowed`",
      "id": "`/model`-says-`model-not-allowed`"
    },
    {
      "level": "h3",
      "text": "When filing an issue",
      "id": "when-filing-an-issue"
    }
  ],
  "url": "llms-txt#troubleshooting",
  "links": []
}