docs: update faq and install guidance

2026-01-13 07:58:47 +00:00
parent 89013efbca
commit 9a322d52e2
22 changed files with 431 additions and 48 deletions
--- a/docs/start/faq.md
+++ b/docs/start/faq.md
@@ -27,11 +27,13 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
  - [Can I run a "fast chat" agent and an "Opus for coding" agent?](#can-i-run-a-fast-chat-agent-and-an-opus-for-coding-agent)
  - [Does Homebrew work on Linux?](#does-homebrew-work-on-linux)
  - [Can I switch between npm and git installs later?](#can-i-switch-between-npm-and-git-installs-later)
+  - [Should I run the Gateway on my laptop or a VPS?](#should-i-run-the-gateway-on-my-laptop-or-a-vps)
 - [Skills and automation](#skills-and-automation)
  - [How do I customize skills without keeping the repo dirty?](#how-do-i-customize-skills-without-keeping-the-repo-dirty)
  - [Can I load skills from a custom folder?](#can-i-load-skills-from-a-custom-folder)
  - [How can I use different models for different tasks?](#how-can-i-use-different-models-for-different-tasks)
  - [How do I install skills on Linux?](#how-do-i-install-skills-on-linux)
+  - [Do you have a Notion or HeyGen integration?](#do-you-have-a-notion-or-heygen-integration)
 - [Sandboxing and memory](#sandboxing-and-memory)
  - [Is there a dedicated sandboxing doc?](#is-there-a-dedicated-sandboxing-doc)
  - [How do I bind a host folder into the sandbox?](#how-do-i-bind-a-host-folder-into-the-sandbox)
@@ -39,6 +41,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
  - [Does semantic memory search require an OpenAI API key?](#does-semantic-memory-search-require-an-openai-api-key)
 - [Where things live on disk](#where-things-live-on-disk)
  - [Where does Clawdbot store its data?](#where-does-clawdbot-store-its-data)
+  - [Where should AGENTS.md / SOUL.md / USER.md / MEMORY.md live?](#where-should-agentsmd--soulmd--usermd--memorymd-live)
  - [How do I completely uninstall Clawdbot?](#how-do-i-completely-uninstall-clawdbot)
  - [Can agents work outside the workspace?](#can-agents-work-outside-the-workspace)
  - [I’m in remote mode — where is the session store?](#im-in-remote-mode-where-is-the-session-store)
@@ -54,12 +57,16 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
  - [Do nodes run a gateway daemon?](#do-nodes-run-a-gateway-daemon)
  - [Is there an API / RPC way to apply config?](#is-there-an-api-rpc-way-to-apply-config)
  - [What’s a minimal “sane” config for a first install?](#whats-a-minimal-sane-config-for-a-first-install)
+  - [How do I set up Tailscale on a VPS and connect from my Mac?](#how-do-i-set-up-tailscale-on-a-vps-and-connect-from-my-mac)
+  - [How do I connect a Mac node to a remote Gateway (Tailscale Serve)?](#how-do-i-connect-a-mac-node-to-a-remote-gateway-tailscale-serve)
 - [Env vars and .env loading](#env-vars-and-env-loading)
  - [How does Clawdbot load environment variables?](#how-does-clawdbot-load-environment-variables)
  - [“I started the Gateway via a daemon and my env vars disappeared.” What now?](#i-started-the-gateway-via-a-daemon-and-my-env-vars-disappeared-what-now)
+  - [I set `COPILOT_GITHUB_TOKEN`, but models status shows “Shell env: off.” Why?](#i-set-copilot_github_token-but-models-status-shows-shell-env-off-why)
 - [Sessions & multiple chats](#sessions-multiple-chats)
  - [How do I start a fresh conversation?](#how-do-i-start-a-fresh-conversation)
  - [How do I completely reset Clawdbot (but keep it installed)?](#how-do-i-completely-reset-clawdbot-but-keep-it-installed)
+  - [I’m getting “context too large” errors — how do I reset or compact?](#im-getting-context-too-large-errors-how-do-i-reset-or-compact)
  - [Do I need to add a “bot account” to a WhatsApp group?](#do-i-need-to-add-a-bot-account-to-a-whatsapp-group)
  - [Why doesn’t Clawdbot reply in a group?](#why-doesnt-clawdbot-reply-in-a-group)
  - [Do groups/threads share context with DMs?](#do-groupsthreads-share-context-with-dms)
@@ -67,6 +74,8 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
  - [What is the “default model”?](#what-is-the-default-model)
  - [How do I switch models on the fly (without restarting)?](#how-do-i-switch-models-on-the-fly-without-restarting)
  - [Why do I see “Model … is not allowed” and then no reply?](#why-do-i-see-model-is-not-allowed-and-then-no-reply)
+  - [Why do I see “Unknown model: minimax/MiniMax-M2.1”?](#why-do-i-see-unknown-model-minimaxminimax-m21)
+  - [Can I use MiniMax as my default and OpenAI for complex tasks?](#can-i-use-minimax-as-my-default-and-openai-for-complex-tasks)
  - [Are opus / sonnet / gpt built‑in shortcuts?](#are-opus-sonnet-gpt-builtin-shortcuts)
  - [How do I define/override model shortcuts (aliases)?](#how-do-i-defineoverride-model-shortcuts-aliases)
  - [How do I add models from other providers like OpenRouter or Z.AI?](#how-do-i-add-models-from-other-providers-like-openrouter-or-zai)
@@ -89,6 +98,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
  - [The Control UI says “unauthorized” (or keeps reconnecting). What now?](#the-control-ui-says-unauthorized-or-keeps-reconnecting-what-now)
  - [I set `gateway.bind: "tailnet"` but it can’t bind / nothing listens](#i-set-gatewaybind-tailnet-but-it-cant-bind-nothing-listens)
  - [Can I run multiple Gateways on the same host?](#can-i-run-multiple-gateways-on-the-same-host)
+  - [What does “invalid handshake” / code 1008 mean?](#what-does-invalid-handshake--code-1008-mean)
 - [Logging and debugging](#logging-and-debugging)
  - [Where are logs?](#where-are-logs)
  - [How do I start/stop/restart the Gateway daemon?](#how-do-i-startstoprestart-the-gateway-daemon)
@@ -106,6 +116,11 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
  - [I’m running on my personal WhatsApp number — why is self-chat weird?](#im-running-on-my-personal-whatsapp-number-why-is-self-chat-weird)
  - [WhatsApp logged me out. How do I re‑auth?](#whatsapp-logged-me-out-how-do-i-reauth)
  - [Build errors on `main` — what’s the standard fix path?](#build-errors-on-main-whats-the-standard-fix-path)
+  - [npm install fails (allow-build-scripts / missing tar or yargs). What now?](#npm-install-fails-allow-build-scripts--missing-tar-or-yargs-what-now)
+  - [How do I switch between git installs and npm installs?](#how-do-i-switch-between-git-installs-and-npm-installs)
+  - [Telegram block streaming isn’t splitting text between tool calls. Why?](#telegram-block-streaming-isnt-splitting-text-between-tool-calls-why)
+  - [Discord doesn’t reply in my server even with `requireMention: false`. Why?](#discord-doesnt-reply-in-my-server-even-with-requiremention-false-why)
+  - [Cloud Code Assist API error: invalid tool schema (400). What now?](#cloud-code-assist-api-error-invalid-tool-schema-400-what-now)

 ## First 60 seconds if something's broken

@@ -205,7 +220,7 @@ See [Dashboard](/web/dashboard) and [Web surfaces](/web) for bind modes and auth

 ### What runtime do I need?

-Node **>= 22** is required. `pnpm` is recommended; `bun` is optional.
+Node **>= 22** is required. `pnpm` is recommended. Bun is **not recommended** for the Gateway.

 ### What does the onboarding wizard actually do?

@@ -228,6 +243,8 @@ The wizard can run `claude setup-token` on the gateway host (or you run it yours

 Yes. Clawdbot can **reuse Claude Code CLI credentials** (OAuth) and also supports **setup-token**. If you have a Claude subscription, we recommend **setup-token** on the gateway host for the most reliable long‑running setup (requires Claude Pro/Max + the `claude` CLI). OAuth reuse is supported, but avoid logging in separately via Clawdbot and Claude Code to prevent token conflicts. See [Anthropic](/providers/anthropic) and [OAuth](/concepts/oauth).

+Note: Claude subscription access is governed by Anthropic’s terms. For production or multi‑user workloads, API keys are usually the safer choice.
+
 ### Is AWS Bedrock supported?

 Yes — via pi‑ai’s **Amazon Bedrock (Converse)** provider with **manual config**. You must supply AWS credentials/region on the gateway host and add a Bedrock provider entry in your models config. See [Amazon Bedrock](/bedrock) and [Model providers](/providers/models). If you prefer a managed key flow, an OpenAI‑compatible proxy in front of Bedrock is still a valid option.
@@ -246,7 +263,11 @@ Pick region-pinned endpoints. OpenRouter exposes US-hosted options for MiniMax,

 ### Can I use Bun?

-Bun is supported for faster TypeScript execution, but **WhatsApp requires Node** in this ecosystem. The wizard lets you pick the runtime; choose **Node** if you use WhatsApp.
+Bun is **not recommended**. We see runtime bugs, especially with WhatsApp and Telegram.
+Use **Node** for stable gateways.
+
+If you still want to experiment with Bun, do it on a non‑production gateway
+without WhatsApp/Telegram.

 ### Telegram: what goes in `allowFrom`?

@@ -298,6 +319,23 @@ clawdbot daemon restart

 Doctor detects a gateway service entrypoint mismatch and offers to rewrite the service config to match the current install (use `--repair` in automation).

+### Should I run the Gateway on my laptop or a VPS?
+
+Short answer: **if you want 24/7 reliability, use a VPS**. If you want the
+lowest friction and you’re okay with sleep/restarts, run it locally.
+
+**Laptop (local Gateway)**
+- **Pros:** no server cost, direct access to local files, live browser window.
+- **Cons:** sleep/network drops = disconnects, OS updates/reboots interrupt, must stay awake.
+
+**VPS / cloud**
+- **Pros:** always‑on, stable network, no laptop sleep issues, easier to keep running.
+- **Cons:** often run headless (use screenshots), remote file access only, you must SSH for updates.
+
+**Clawdbot‑specific note:** WhatsApp/Telegram/Slack/Discord all work fine from a VPS. The only real trade‑off is **headless browser** vs a visible window. See [Browser](/tools/browser).
+
+**Recommended default:** VPS if you had gateway disconnects before. Local is great when you’re actively using the Mac and want local file access or UI automation with a visible browser.
+
 ## Skills and automation

 ### How do I customize skills without keeping the repo dirty?
@@ -320,6 +358,7 @@ See [Cron jobs](/automation/cron-jobs), [Multi-Agent Routing](/concepts/multi-ag
 ### How do I install skills on Linux?

 Use **ClawdHub** (CLI) or drop skills into your workspace. The macOS Skills UI isn’t available on Linux.
+Browse skills at https://clawdhub.com.

 Install the ClawdHub CLI (pick one package manager):

@@ -331,9 +370,20 @@ npm i -g clawdhub
 pnpm add -g clawdhub
 ```

-```bash
-bun add -g clawdhub
-```
+### Do you have a Notion or HeyGen integration?
+
+Not built‑in today.
+
+Options:
+- **Custom skill / plugin:** best for reliable API access (Notion/HeyGen both have APIs).
+- **Browser automation:** works without code but is slower and more fragile.
+
+If you want to keep context per client (agency workflows), a simple pattern is:
+- One Notion page per client (context + preferences + active work).
+- Ask the agent to fetch that page at the start of a session.
+
+If you want a native integration, open a feature request or build a skill
+targeting those APIs.

 Install skills:

@@ -396,6 +446,29 @@ Legacy single‑agent path: `~/.clawdbot/agent/*` (migrated by `clawdbot doctor`

 Your **workspace** (AGENTS.md, memory files, skills, etc.) is separate and configured via `agents.defaults.workspace` (default: `~/clawd`).

+### Where should AGENTS.md / SOUL.md / USER.md / MEMORY.md live?
+
+These files live in the **agent workspace**, not `~/.clawdbot`.
+
+- **Workspace (per agent)**: `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`,
+  `MEMORY.md` (or `memory.md`), `memory/YYYY-MM-DD.md`, optional `HEARTBEAT.md`.
+- **State dir (`~/.clawdbot`)**: config, credentials, auth profiles, sessions, logs,
+  and shared skills (`~/.clawdbot/skills`).
+
+Default workspace is `~/clawd`, configurable via:
+
+```json5
+{
+  agents: { defaults: { workspace: "~/clawd" } }
+}
+```
+
+If the bot “forgets” after a restart, confirm the Gateway is using the same
+workspace on every launch (and remember: remote mode uses the **gateway host’s**
+workspace, not your local laptop).
+
+See [Agent workspace](/concepts/agent-workspace) and [Memory](/concepts/memory).
+
 ### How do I completely uninstall Clawdbot?

 See the dedicated guide: [Uninstall](/install/uninstall).
@@ -500,6 +573,11 @@ Yes. It’s a config option:

 Default is `false` (headful). Headless is more likely to trigger anti‑bot checks on some sites. See [Browser](/tools/browser).

+Headless uses the **same Chromium engine** and works for most automation (forms, clicks, scraping, logins). The main differences:
+- No visible browser window (use screenshots if you need visuals).
+- Some sites are stricter about automation in headless mode (CAPTCHAs, anti‑bot).
+  For example, X/Twitter often blocks headless sessions.
+
 ## Remote gateways + nodes

 ### How do commands propagate between Telegram, the gateway, and nodes?
@@ -533,6 +611,52 @@ Yes. `config.apply` validates + writes the full config and restarts the Gateway

 This sets your workspace and restricts who can trigger the bot.

+### How do I set up Tailscale on a VPS and connect from my Mac?
+
+Minimal steps:
+
+1) **Install + login on the VPS**
+   ```bash
+   curl -fsSL https://tailscale.com/install.sh | sh
+   sudo tailscale up
+   ```
+2) **Install + login on your Mac**
+   - Use the Tailscale app and sign in to the same tailnet.
+3) **Enable MagicDNS (recommended)**
+   - In the Tailscale admin console, enable MagicDNS so the VPS has a stable name.
+4) **Use the tailnet hostname**
+   - SSH: `ssh user@your-vps.tailnet-xxxx.ts.net`
+   - Gateway WS: `ws://your-vps.tailnet-xxxx.ts.net:18789`
+
+If you want the Control UI without SSH, use Tailscale Serve on the VPS:
+```bash
+clawdbot gateway --tailscale serve
+```
+This keeps the gateway bound to loopback and exposes HTTPS via Tailscale. See [Tailscale](/gateway/tailscale).
+
+### How do I connect a Mac node to a remote Gateway (Tailscale Serve)?
+
+Serve only exposes the **Gateway Control UI**. Nodes use the **bridge port**.
+
+Recommended setup:
+1) **Enable the bridge on the gateway host**:
+   ```json5
+   {
+     bridge: { enabled: true, bind: "auto" }
+   }
+   ```
+   `auto` prefers a tailnet IP when Tailscale is present.
+2) **Make sure the VPS + Mac are on the same tailnet**.
+3) **Use the macOS app in Remote mode** (SSH target can be the tailnet hostname).
+   The app will tunnel the bridge port and connect as a node.
+4) **Approve the node** on the gateway:
+   ```bash
+   clawdbot nodes pending
+   clawdbot nodes approve <requestId>
+   ```
+
+Docs: [Bridge protocol](/gateway/bridge-protocol), [Discovery](/gateway/discovery), [macOS remote mode](/platforms/mac/remote).
+
 ## Env vars and .env loading

 ### How does Clawdbot load environment variables?
@@ -578,6 +702,30 @@ Two common fixes:
 This runs your login shell and imports only missing expected keys (never overrides). Env var equivalents:
 `CLAWDBOT_LOAD_SHELL_ENV=1`, `CLAWDBOT_SHELL_ENV_TIMEOUT_MS=15000`.

+### I set `COPILOT_GITHUB_TOKEN`, but models status shows “Shell env: off.” Why?
+
+`clawdbot models status` reports whether **shell env import** is enabled. “Shell env: off”
+does **not** mean your env vars are missing — it just means Clawdbot won’t load
+your login shell automatically.
+
+If the Gateway runs as a daemon (launchd/systemd), it won’t inherit your shell
+environment. Fix by doing one of these:
+
+1) Put the token in `~/.clawdbot/.env`:
+   ```
+   COPILOT_GITHUB_TOKEN=...
+   ```
+2) Or enable shell import (`env.shellEnv.enabled: true`).
+3) Or add it to your config `env` block (applies only if missing).
+
+Then restart the gateway and recheck:
+```bash
+clawdbot models status
+```
+
+Copilot tokens are read from `COPILOT_GITHUB_TOKEN` (also `GH_TOKEN` / `GITHUB_TOKEN`).
+See [/concepts/model-providers](/concepts/model-providers) and [/environment](/environment).
+
 ## Sessions & multiple chats

 ### How do I start a fresh conversation?
@@ -609,6 +757,28 @@ Notes:
 - If you used profiles (`--profile` / `CLAWDBOT_PROFILE`), reset each state dir (defaults are `~/.clawdbot-<profile>`).
 - Dev reset: `clawdbot gateway --dev --reset` (dev-only; wipes dev config + credentials + sessions + workspace).

+### I’m getting “context too large” errors — how do I reset or compact?
+
+Use one of these:
+
+- **Compact** (keeps the conversation but summarizes older turns):
+  ```
+  /compact
+  ```
+  or `/compact <instructions>` to guide the summary.
+
+- **Reset** (fresh session ID for the same chat key):
+  ```
+  /new
+  /reset
+  ```
+
+If it keeps happening:
+- Enable or tune **session pruning** (`agents.defaults.contextPruning`) to trim old tool output.
+- Use a model with a larger context window.
+
+Docs: [Compaction](/concepts/compaction), [Session pruning](/concepts/session-pruning), [Session management](/concepts/session).
+
 ### Do I need to add a “bot account” to a WhatsApp group?

 No. Clawdbot runs on **your own account**, so if you’re in the group, Clawdbot can see it.
@@ -693,6 +863,59 @@ Model "provider/model" is not allowed. Use /model to list available models.
 That error is returned **instead of** a normal reply. Fix: add the model to
 `agents.defaults.models`, remove the allowlist, or pick a model from `/model list`.

+### Why do I see “Unknown model: minimax/MiniMax-M2.1”?
+
+This means the **provider isn’t configured** (no MiniMax provider config or auth
+profile was found), so the model can’t be resolved. A fix for this detection is
+in **2026.1.12** (unreleased at the time of writing).
+
+Fix checklist:
+1) Upgrade to **2026.1.12** (or run from source `main`), then restart the gateway.
+2) Make sure MiniMax is configured (wizard or JSON), or that a MiniMax API key
+   exists in env/auth profiles so the provider can be injected.
+3) Use the exact model id (case‑sensitive): `minimax/MiniMax-M2.1` or
+   `minimax/MiniMax-M2.1-lightning`.
+4) Run:
+   ```bash
+   clawdbot models list
+   ```
+   and pick from the list (or `/model list` in chat).
+
+See [MiniMax](/providers/minimax) and [Models](/concepts/models).
+
+### Can I use MiniMax as my default and OpenAI for complex tasks?
+
+Yes. Use **MiniMax as the default** and switch models **per session** when needed.
+Fallbacks are for **errors**, not “hard tasks,” so use `/model` or a separate agent.
+
+**Option A: switch per session**
+```json5
+{
+  env: { MINIMAX_API_KEY: "sk-...", OPENAI_API_KEY: "sk-..." },
+  agents: {
+    defaults: {
+      model: { primary: "minimax/MiniMax-M2.1" },
+      models: {
+        "minimax/MiniMax-M2.1": { alias: "minimax" },
+        "openai/gpt-5.2": { alias: "gpt" }
+      }
+    }
+  }
+}
+```
+
+Then:
+```
+/model gpt
+```
+
+**Option B: separate agents**
+- Agent A default: MiniMax
+- Agent B default: OpenAI
+- Route by agent or use `/agent` to switch
+
+Docs: [Models](/concepts/models), [Multi-Agent Routing](/concepts/multi-agent), [MiniMax](/providers/minimax), [OpenAI](/providers/openai).
+
 ### Are opus / sonnet / gpt built‑in shortcuts?

 Yes. Clawdbot ships a few default shorthands (only applied when the model exists in `agents.defaults.models`):
@@ -932,6 +1155,8 @@ Fix:
 Fix:
 - Start Tailscale on that host (so it has a 100.x address), or
 - Switch to `gateway.bind: "loopback"` / `"lan"`.
+  
+Note: `tailnet` is legacy and is migrated to `auto` by Doctor. Prefer `gateway.bind: "auto"` when using Tailscale.

 ### Can I run multiple Gateways on the same host?

@@ -951,6 +1176,29 @@ Quick setup (recommended):

 Profiles also suffix service names (`com.clawdbot.<profile>`, `clawdbot-gateway-<profile>.service`, `Clawdbot Gateway (<profile>)`).

+### What does “invalid handshake” / code 1008 mean?
+
+The Gateway is a **WebSocket server**, and it expects the very first message to
+be a `connect` frame. If it receives anything else, it closes the connection
+with **code 1008** (policy violation).
+
+Common causes:
+- You opened the **HTTP** URL in a browser (`http://...`) instead of a WS client.
+- You used the wrong port or path.
+- A proxy or tunnel stripped auth headers or sent a non‑Gateway request.
+
+Quick fixes:
+1) Use the WS URL: `ws://<host>:18789` (or `wss://...` if HTTPS).
+2) Don’t open the WS port in a normal browser tab.
+3) If auth is on, include the token/password in the `connect` frame.
+
+If you’re using the CLI or TUI, the URL should look like:
+```
+clawdbot tui --url ws://<host>:18789 --token <token>
+```
+
+Protocol details: [Gateway protocol](/gateway/protocol).
+
 ## Logging and debugging

 ### Where are logs?
@@ -1115,6 +1363,94 @@ clawdbot providers login
 3) Check GitHub issues or Discord
 4) Temporary workaround: check out an older commit

+### npm install fails (allow-build-scripts / missing tar or yargs). What now?
+
+If you’re running from source, use the repo’s package manager: **pnpm** (preferred).
+The repo declares `packageManager: "pnpm@…"`, and pnpm patches are tracked in `pnpm.patchedDependencies`.
+
+Typical recovery:
+```bash
+git status   # ensure you’re in the repo root
+pnpm install
+pnpm build
+pnpm clawdbot doctor
+clawdbot daemon restart
+```
+
+Why: pnpm is the configured package manager for this repo, and the dependency
+patching workflow relies on it.
+
+### How do I switch between git installs and npm installs?
+
+Use the **website installer** and select the install method with a flag. It
+upgrades in place and rewrites the gateway service to point at the new install.
+
+Switch **to git install**:
+```bash
+curl -fsSL https://clawd.bot/install.sh | bash -s -- --install-method git --no-onboard
+```
+
+Switch **to npm global**:
+```bash
+curl -fsSL https://clawd.bot/install.sh | bash
+```
+
+Notes:
+- The git flow only rebases if the repo is clean. Commit or stash changes first.
+- After switching, run:
+  ```bash
+  clawdbot doctor
+  clawdbot daemon restart
+  ```
+
+### Telegram block streaming isn’t splitting text between tool calls. Why?
+
+Block streaming only sends **completed text blocks**. Common reasons you see a single message:
+- `agents.defaults.blockStreamingDefault` is still `"off"`.
+- `telegram.blockStreaming` is set to `false`.
+- `telegram.streamMode` is `partial` or `block` **and draft streaming is active**
+  (private chat + topics). Draft streaming disables block streaming in that case.
+- Your `minChars` / coalesce settings are too high, so chunks get merged.
+- The model emits one large text block (no mid‑reply flush points).
+
+Fix checklist:
+1) Put block streaming settings under `agents.defaults`, not the root.
+2) Set `telegram.streamMode: "off"` if you want real multi‑message block replies.
+3) Use smaller chunk/coalesce thresholds while debugging.
+
+See [Streaming](/concepts/streaming).
+
+### Discord doesn’t reply in my server even with `requireMention: false`. Why?
+
+`requireMention` only controls mention‑gating **after** the channel passes allowlists.
+By default `discord.groupPolicy` is **allowlist**, so guild channels must be explicitly enabled.
+
+Fix checklist:
+1) Set `discord.groupPolicy: "open"` **or** add the guild/channel allowlist.
+2) Use **numeric channel IDs** in `discord.guilds.<guildId>.channels`.
+3) Ensure the bot has **Message Content Intent** and channel permissions.
+4) Run `clawdbot providers status --probe` for audit hints.
+
+Docs: [Discord](/providers/discord), [Providers troubleshooting](/providers/troubleshooting).
+
+### Cloud Code Assist API error: invalid tool schema (400). What now?
+
+This is almost always a **tool schema compatibility** issue. The Cloud Code Assist
+endpoint accepts a strict subset of JSON Schema. Clawdbot scrubs/normalizes tool
+schemas in current `main`, but the fix is not in the last release yet (as of
+January 13, 2026).
+
+Fix checklist:
+1) **Update Clawdbot**:
+   - If you can run from source, pull `main` and restart the gateway.
+   - Otherwise, wait for the next release that includes the schema scrubber.
+2) Avoid unsupported keywords like `anyOf/oneOf/allOf`, `patternProperties`,
+   `additionalProperties`, `minLength`, `maxLength`, `format`, etc.
+3) If you define custom tools, keep the top‑level schema as `type: "object"` with
+   `properties` and simple enums.
+
+See [Tools](/tools) and [TypeBox schemas](/concepts/typebox).
+
 ## Answer the exact question from the screenshot/chat log

 **Q: “What’s the default model for Anthropic with an API key?”**
--- a/docs/start/getting-started.md
+++ b/docs/start/getting-started.md
@@ -79,7 +79,7 @@ What you’ll choose:
 - **Auth**: OpenAI Code (Codex) subscription (OAuth) or API keys. For Anthropic we recommend an API key; `claude setup-token` is also supported.
 - **Providers**: WhatsApp QR login, Telegram/Discord bot tokens, etc.
 - **Daemon**: background install (launchd/systemd; WSL2 uses systemd)
-  - **Runtime**: Node (recommended; required for WhatsApp) or Bun (faster, but incompatible with WhatsApp)
+  - **Runtime**: Node (recommended; required for WhatsApp/Telegram). Bun is **not recommended**.
 - **Gateway token**: the wizard generates one by default (even on loopback) and stores it in `gateway.auth.token`.

 Wizard doc: [Wizard](/start/wizard)
@@ -110,11 +110,8 @@ clawdbot gateway --port 18789 --verbose
 Dashboard (local loopback): `http://127.0.0.1:18789/`
 If a token is configured, paste it into the Control UI settings (stored as `connect.params.auth.token`).

-⚠️ **WhatsApp + Bun warning:** Baileys (WhatsApp Web library) uses a WebSocket
-path that is currently incompatible with Bun and can cause memory corruption on
-reconnect. If you use WhatsApp, run the Gateway with **Node** until this is
-resolved. Baileys: https://github.com/WhiskeySockets/Baileys · Bun issue:
-https://github.com/oven-sh/bun/issues/5951
+⚠️ **Bun warning (WhatsApp + Telegram):** Bun has known issues with these
+providers. If you use WhatsApp or Telegram, run the Gateway with **Node**.

 ## 4) Pair + connect your first chat surface

--- a/docs/start/hubs.md
+++ b/docs/start/hubs.md
@@ -27,7 +27,7 @@ Use these hubs to discover every page, including deep dives and reference docs t
 - [Docker](/install/docker)
 - [Nix](/install/nix)
 - [Updating / rollback](/install/updating)
- [Bun workflow](/install/bun)
+- [Bun workflow (experimental)](/install/bun)

 ## Core concepts

--- a/docs/start/onboarding.md
+++ b/docs/start/onboarding.md
@@ -64,7 +64,7 @@ Onboarding requests TCC permissions needed for:

 ## 5) CLI (optional)

-The app can install the global `clawdbot` CLI via npm/pnpm/bun so terminal
+The app can install the global `clawdbot` CLI via npm/pnpm so terminal
 workflows and launchd tasks work out of the box.

 ## 6) Onboarding chat (dedicated session)
--- a/docs/start/wizard.md
+++ b/docs/start/wizard.md
@@ -119,7 +119,7 @@ Tip: `--json` does **not** imply non-interactive mode. Use `--non-interactive` (
   - Linux (and Windows via WSL2): systemd user unit
     - Wizard attempts to enable lingering via `loginctl enable-linger <user>` so the Gateway stays up after logout.
     - May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.
-   - **Runtime selection:** Node (recommended; required for WhatsApp) or Bun (faster, but incompatible with WhatsApp).
+   - **Runtime selection:** Node (recommended; required for WhatsApp/Telegram). Bun is **not recommended**.

 7) **Health check**
   - Starts the Gateway (if needed) and runs `clawdbot health`.
@@ -127,7 +127,7 @@ Tip: `--json` does **not** imply non-interactive mode. Use `--non-interactive` (

 8) **Skills (recommended)**
   - Reads the available skills and checks requirements.
-   - Lets you choose a node manager: **npm / pnpm / bun**.
+   - Lets you choose a node manager: **npm / pnpm** (bun not recommended).
   - Installs optional dependencies (some use Homebrew on macOS).

 9) **Finish**