{
  "title": "View recent connection events",
  "content": "openclaw logs --limit 200 | grep \"connection\\\\|disconnect\\\\|logout\"\nbash theme={null}\nopenclaw gateway --verbose\nbash theme={null}\nopenclaw channels logout\ntrash \"${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/credentials\" # if logout can't cleanly remove everything\nopenclaw channels login --verbose       # re-scan QR\nbash theme={null}\nls -la /path/to/your/image.jpg\nbash theme={null}\ngrep \"media\\\\|fetch\\\\|download\" \"$(ls -t /tmp/openclaw/openclaw-*.log | head -1)\" | tail -20\njson theme={null}\n{\n  \"session\": {\n    \"historyLimit\": 100 // Max messages to keep\n  }\n}\nbash theme={null}\nopenclaw doctor\nopenclaw doctor --fix\njson5 theme={null}\n{\n  channels: {\n    whatsapp: {\n      selfChatMode: true,\n      dmPolicy: \"allowlist\",\n      allowFrom: [\"+15555550123\"],\n    },\n  },\n}\nbash theme={null}\nopenclaw channels login\nbash theme={null}\ngit status   # ensure you’re in the repo root\npnpm install\npnpm build\nopenclaw doctor\nopenclaw gateway restart\nbash theme={null}\ncurl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --no-onboard\nbash theme={null}\ncurl -fsSL https://openclaw.ai/install.sh | bash\nbash theme={null}\n  openclaw doctor\n  openclaw gateway restart\n  bash theme={null}\ntccutil reset All bot.molt.mac.debug\nbash theme={null}\nopenclaw gateway status\nopenclaw gateway stop",
  "code_samples": [
    {
      "code": "**Fix:** Usually reconnects automatically once the Gateway is running. If you’re stuck, restart the Gateway process (however you supervise it), or run it manually with verbose output:",
      "language": "unknown"
    },
    {
      "code": "If you’re logged out / unlinked:",
      "language": "unknown"
    },
    {
      "code": "### Media Send Failing\n\n**Check 1:** Is the file path valid?",
      "language": "unknown"
    },
    {
      "code": "**Check 2:** Is it too large?\n\n* Images: max 6MB\n* Audio/Video: max 16MB\n* Documents: max 100MB\n\n**Check 3:** Check media logs",
      "language": "unknown"
    },
    {
      "code": "### High Memory Usage\n\nOpenClaw keeps conversation history in memory.\n\n**Fix:** Restart periodically or set session limits:",
      "language": "unknown"
    },
    {
      "code": "## Common troubleshooting\n\n### “Gateway won’t start — configuration invalid”\n\nOpenClaw now refuses to start when the config contains unknown keys, malformed values, or invalid types.\nThis is intentional for safety.\n\nFix it with Doctor:",
      "language": "unknown"
    },
    {
      "code": "Notes:\n\n* `openclaw doctor` reports every invalid entry.\n* `openclaw doctor --fix` applies migrations/repairs and rewrites the config.\n* Diagnostic commands like `openclaw logs`, `openclaw health`, `openclaw status`, `openclaw gateway status`, and `openclaw gateway probe` still run even if the config is invalid.\n\n### “All models failed” — what should I check first?\n\n* **Credentials** present for the provider(s) being tried (auth profiles + env vars).\n* **Model routing**: confirm `agents.defaults.model.primary` and fallbacks are models you can access.\n* **Gateway logs** in `/tmp/openclaw/…` for the exact provider error.\n* **Model status**: use `/model status` (chat) or `openclaw models status` (CLI).\n\n### I’m running on my personal WhatsApp number — why is self-chat weird?\n\nEnable self-chat mode and allowlist your own number:",
      "language": "unknown"
    },
    {
      "code": "See [WhatsApp setup](/channels/whatsapp).\n\n### WhatsApp logged me out. How do I re‑auth?\n\nRun the login command again and scan the QR code:",
      "language": "unknown"
    },
    {
      "code": "### Build errors on `main` — what’s the standard fix path?\n\n1. `git pull origin main && pnpm install`\n2. `openclaw doctor`\n3. Check GitHub issues or Discord\n4. Temporary workaround: check out an older commit\n\n### npm install fails (allow-build-scripts / missing tar or yargs). What now?\n\nIf you’re running from source, use the repo’s package manager: **pnpm** (preferred).\nThe repo declares `packageManager: \"pnpm@…\"`.\n\nTypical recovery:",
      "language": "unknown"
    },
    {
      "code": "Why: pnpm is the configured package manager for this repo.\n\n### How do I switch between git installs and npm installs?\n\nUse the **website installer** and select the install method with a flag. It\nupgrades in place and rewrites the gateway service to point at the new install.\n\nSwitch **to git install**:",
      "language": "unknown"
    },
    {
      "code": "Switch **to npm global**:",
      "language": "unknown"
    },
    {
      "code": "Notes:\n\n* The git flow only rebases if the repo is clean. Commit or stash changes first.\n* After switching, run:",
      "language": "unknown"
    },
    {
      "code": "### Telegram block streaming isn’t splitting text between tool calls. Why?\n\nBlock streaming only sends **completed text blocks**. Common reasons you see a single message:\n\n* `agents.defaults.blockStreamingDefault` is still `\"off\"`.\n* `channels.telegram.blockStreaming` is set to `false`.\n* `channels.telegram.streamMode` is `partial` or `block` **and draft streaming is active**\n  (private chat + topics). Draft streaming disables block streaming in that case.\n* Your `minChars` / coalesce settings are too high, so chunks get merged.\n* The model emits one large text block (no mid‑reply flush points).\n\nFix checklist:\n\n1. Put block streaming settings under `agents.defaults`, not the root.\n2. Set `channels.telegram.streamMode: \"off\"` if you want real multi‑message block replies.\n3. Use smaller chunk/coalesce thresholds while debugging.\n\nSee [Streaming](/concepts/streaming).\n\n### Discord doesn’t reply in my server even with `requireMention: false`. Why?\n\n`requireMention` only controls mention‑gating **after** the channel passes allowlists.\nBy default `channels.discord.groupPolicy` is **allowlist**, so guilds must be explicitly enabled.\nIf you set `channels.discord.guilds.<guildId>.channels`, only the listed channels are allowed; omit it to allow all channels in the guild.\n\nFix checklist:\n\n1. Set `channels.discord.groupPolicy: \"open\"` **or** add a guild allowlist entry (and optionally a channel allowlist).\n2. Use **numeric channel IDs** in `channels.discord.guilds.<guildId>.channels`.\n3. Put `requireMention: false` **under** `channels.discord.guilds` (global or per‑channel).\n   Top‑level `channels.discord.requireMention` is not a supported key.\n4. Ensure the bot has **Message Content Intent** and channel permissions.\n5. Run `openclaw channels status --probe` for audit hints.\n\nDocs: [Discord](/channels/discord), [Channels troubleshooting](/channels/troubleshooting).\n\n### Cloud Code Assist API error: invalid tool schema (400). What now?\n\nThis is almost always a **tool schema compatibility** issue. The Cloud Code Assist\nendpoint accepts a strict subset of JSON Schema. OpenClaw scrubs/normalizes tool\nschemas in current `main`, but the fix is not in the last release yet (as of\nJanuary 13, 2026).\n\nFix checklist:\n\n1. **Update OpenClaw**:\n   * If you can run from source, pull `main` and restart the gateway.\n   * Otherwise, wait for the next release that includes the schema scrubber.\n2. Avoid unsupported keywords like `anyOf/oneOf/allOf`, `patternProperties`,\n   `additionalProperties`, `minLength`, `maxLength`, `format`, etc.\n3. If you define custom tools, keep the top‑level schema as `type: \"object\"` with\n   `properties` and simple enums.\n\nSee [Tools](/tools) and [TypeBox schemas](/concepts/typebox).\n\n## macOS Specific Issues\n\n### App Crashes when Granting Permissions (Speech/Mic)\n\nIf the app disappears or shows \"Abort trap 6\" when you click \"Allow\" on a privacy prompt:\n\n**Fix 1: Reset TCC Cache**",
      "language": "unknown"
    },
    {
      "code": "**Fix 2: Force New Bundle ID**\nIf resetting doesn't work, change the `BUNDLE_ID` in [`scripts/package-mac-app.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-app.sh) (e.g., add a `.test` suffix) and rebuild. This forces macOS to treat it as a new app.\n\n### Gateway stuck on \"Starting...\"\n\nThe app connects to a local gateway on port `18789`. If it stays stuck:\n\n**Fix 1: Stop the supervisor (preferred)**\nIf the gateway is supervised by launchd, killing the PID will just respawn it. Stop the supervisor first:",
      "language": "unknown"
    }
  ],
  "headings": [
    {
      "level": "h3",
      "text": "Media Send Failing",
      "id": "media-send-failing"
    },
    {
      "level": "h3",
      "text": "High Memory Usage",
      "id": "high-memory-usage"
    },
    {
      "level": "h2",
      "text": "Common troubleshooting",
      "id": "common-troubleshooting"
    },
    {
      "level": "h3",
      "text": "“Gateway won’t start — configuration invalid”",
      "id": "“gateway-won’t-start-—-configuration-invalid”"
    },
    {
      "level": "h3",
      "text": "“All models failed” — what should I check first?",
      "id": "“all-models-failed”-—-what-should-i-check-first?"
    },
    {
      "level": "h3",
      "text": "I’m running on my personal WhatsApp number — why is self-chat weird?",
      "id": "i’m-running-on-my-personal-whatsapp-number-—-why-is-self-chat-weird?"
    },
    {
      "level": "h3",
      "text": "WhatsApp logged me out. How do I re‑auth?",
      "id": "whatsapp-logged-me-out.-how-do-i-re‑auth?"
    },
    {
      "level": "h3",
      "text": "Build errors on `main` — what’s the standard fix path?",
      "id": "build-errors-on-`main`-—-what’s-the-standard-fix-path?"
    },
    {
      "level": "h3",
      "text": "npm install fails (allow-build-scripts / missing tar or yargs). What now?",
      "id": "npm-install-fails-(allow-build-scripts-/-missing-tar-or-yargs).-what-now?"
    },
    {
      "level": "h3",
      "text": "How do I switch between git installs and npm installs?",
      "id": "how-do-i-switch-between-git-installs-and-npm-installs?"
    },
    {
      "level": "h3",
      "text": "Telegram block streaming isn’t splitting text between tool calls. Why?",
      "id": "telegram-block-streaming-isn’t-splitting-text-between-tool-calls.-why?"
    },
    {
      "level": "h3",
      "text": "Discord doesn’t reply in my server even with `requireMention: false`. Why?",
      "id": "discord-doesn’t-reply-in-my-server-even-with-`requiremention:-false`.-why?"
    },
    {
      "level": "h3",
      "text": "Cloud Code Assist API error: invalid tool schema (400). What now?",
      "id": "cloud-code-assist-api-error:-invalid-tool-schema-(400).-what-now?"
    },
    {
      "level": "h2",
      "text": "macOS Specific Issues",
      "id": "macos-specific-issues"
    },
    {
      "level": "h3",
      "text": "App Crashes when Granting Permissions (Speech/Mic)",
      "id": "app-crashes-when-granting-permissions-(speech/mic)"
    },
    {
      "level": "h3",
      "text": "Gateway stuck on \"Starting...\"",
      "id": "gateway-stuck-on-\"starting...\""
    }
  ],
  "url": "llms-txt#view-recent-connection-events",
  "links": []
}