diff --git a/docs/cli/index.md b/docs/cli/index.md index 80d364cf1..24ffe0f3e 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -257,12 +257,12 @@ Options: - `--tailscale-reset-on-exit` - `--install-daemon` - `--no-install-daemon` (alias: `--skip-daemon`) -- `--daemon-runtime ` +- `--daemon-runtime ` (bun not recommended for WhatsApp/Telegram) - `--skip-providers` - `--skip-skills` - `--skip-health` - `--skip-ui` -- `--node-manager ` +- `--node-manager ` (pnpm recommended; bun not recommended for Gateway runtime) - `--json` ### `configure` / `config` @@ -549,7 +549,7 @@ Notes: - `daemon status` supports `--no-probe`, `--deep`, and `--json` for scripting. - `daemon status` also surfaces legacy or extra gateway services when it can detect them (`--deep` adds system-level scans). Profile-named Clawdbot services are treated as first-class and aren't flagged as "extra". - `daemon status` prints which config path the CLI uses vs which config the daemon likely uses (service env), plus the resolved probe target URL. -- `daemon install` defaults to Node runtime; use `--runtime bun` only when WhatsApp is disabled. +- `daemon install` defaults to Node runtime; bun is **not recommended** (WhatsApp/Telegram bugs). - `daemon install` options: `--port`, `--runtime`, `--token`, `--force`. ### `logs` diff --git a/docs/cli/update.md b/docs/cli/update.md index 0b37b6d06..2b4b73d65 100644 --- a/docs/cli/update.md +++ b/docs/cli/update.md @@ -9,7 +9,7 @@ read_when: Safely update a **source checkout** (git install) of Clawdbot. -If you installed via **npm/pnpm/bun** (global install, no git metadata), use the package manager flow in [Updating](/install/updating). +If you installed via **npm/pnpm** (global install, no git metadata), use the package manager flow in [Updating](/install/updating). ## Usage @@ -32,7 +32,7 @@ High-level: 1. Requires a clean worktree (no uncommitted changes). 2. Fetches and rebases against `@{upstream}`. -3. Installs deps (pnpm/bun/npm depending on the checkout). +3. Installs deps (pnpm preferred; npm fallback). 4. Builds + builds the Control UI. 5. Runs `clawdbot doctor` as the final “safe update” check. diff --git a/docs/concepts/streaming.md b/docs/concepts/streaming.md index 6928ac917..09bfa8f64 100644 --- a/docs/concepts/streaming.md +++ b/docs/concepts/streaming.md @@ -92,6 +92,9 @@ This maps to: `*.blockStreaming` is explicitly set to `true`. Telegram can stream drafts (`telegram.streamMode`) without block replies. +Config location reminder: the `blockStreaming*` defaults live under +`agents.defaults`, not the root config. + ## Telegram draft streaming (token-ish) Telegram is the only provider with draft streaming: diff --git a/docs/gateway/tailscale.md b/docs/gateway/tailscale.md index 586c80dc0..1acbb2305 100644 --- a/docs/gateway/tailscale.md +++ b/docs/gateway/tailscale.md @@ -73,6 +73,8 @@ clawdbot gateway --tailscale funnel --auth password - `tailscale.mode: "funnel"` refuses to start unless auth mode is `password` to avoid public exposure. - Set `gateway.tailscale.resetOnExit` if you want Clawdbot to undo `tailscale serve` or `tailscale funnel` configuration on shutdown. +- Serve/Funnel only expose the **Gateway control UI + WS**. Node **bridge** traffic + uses the separate bridge port (default `18790`) and is **not** proxied by Serve. ## Tailscale prerequisites + limits diff --git a/docs/install/bun.md b/docs/install/bun.md index 3128443ad..e2989e4cb 100644 --- a/docs/install/bun.md +++ b/docs/install/bun.md @@ -1,13 +1,16 @@ --- -summary: "Bun workflow (preferred): installs, patches, and gotchas vs pnpm" +summary: "Bun workflow (experimental): installs, patches, and gotchas vs pnpm" read_when: - You want the fastest local dev loop (bun + watch) - You hit Bun install/patch/lifecycle script issues --- -# Bun +# Bun (experimental) -Goal: run this repo with **Bun** (optional) without losing pnpm patch behavior. +Goal: run this repo with **Bun** (optional, not recommended for WhatsApp/Telegram) +without losing pnpm patch behavior. + +⚠️ **Not recommended for Gateway runtime** (WhatsApp/Telegram bugs). Use Node for production. ## Status diff --git a/docs/install/updating.md b/docs/install/updating.md index 957004634..acce7ac63 100644 --- a/docs/install/updating.md +++ b/docs/install/updating.md @@ -9,9 +9,28 @@ read_when: Clawdbot is moving fast (pre “1.0”). Treat updates like shipping infra: update → run checks → restart → verify. +## Recommended: re-run the website installer (upgrade in place) + +The **preferred** update path is to re-run the installer from the website. It +detects existing installs, upgrades in place, and runs `clawdbot doctor` when +needed. + +```bash +curl -fsSL https://clawd.bot/install.sh | bash +``` + +Notes: +- Add `--no-onboard` if you don’t want the onboarding wizard to run again. +- For **source installs**, use: + ```bash + curl -fsSL https://clawd.bot/install.sh | bash -s -- --install-method git --no-onboard + ``` + The installer will `git pull --rebase` **only** if the repo is clean. +- For **global installs**, the script uses `npm install -g clawdbot@latest` under the hood. + ## Before you update -- Know how you installed: **global** (npm/pnpm/bun) vs **from source** (git clone). +- Know how you installed: **global** (npm/pnpm) vs **from source** (git clone). - Know how your Gateway is running: **foreground terminal** vs **supervised service** (launchd/systemd). - Snapshot your tailoring: - Config: `~/.clawdbot/clawdbot.json` @@ -29,10 +48,7 @@ npm i -g clawdbot@latest ```bash pnpm add -g clawdbot@latest ``` - -```bash -bun add -g clawdbot@latest -``` +We do **not** recommend Bun for the Gateway runtime (WhatsApp/Telegram bugs). Then: @@ -59,7 +75,7 @@ It runs a safe-ish update flow: - Fetches + rebases against the configured upstream. - Installs deps, builds, builds the Control UI, and runs `clawdbot doctor`. -If you installed via **npm/pnpm/bun** (no git metadata), `clawdbot update` will skip. Use “Update (global install)” instead. +If you installed via **npm/pnpm** (no git metadata), `clawdbot update` will skip. Use “Update (global install)” instead. ## Update (Control UI / RPC) @@ -93,7 +109,7 @@ pnpm clawdbot health Notes: - `pnpm build` matters when you run the packaged `clawdbot` binary ([`dist/entry.js`](https://github.com/clawdbot/clawdbot/blob/main/dist/entry.js)) or use Node to run `dist/`. -- If you run directly from TypeScript (`pnpm clawdbot ...` / `bun run clawdbot ...`), a rebuild is usually unnecessary, but **config migrations still apply** → run doctor. +- If you run directly from TypeScript (`pnpm clawdbot ...`), a rebuild is usually unnecessary, but **config migrations still apply** → run doctor. - Switching between global and git installs is easy: install the other flavor, then run `clawdbot doctor` so the gateway service entrypoint is rewritten to the current install. ## Always run: `clawdbot doctor` @@ -145,10 +161,6 @@ npm i -g clawdbot@ pnpm add -g clawdbot@ ``` -```bash -bun add -g clawdbot@ -``` - Tip: to see the current published version, run `npm view clawdbot version`. Then restart + re-run doctor: diff --git a/docs/platforms/index.md b/docs/platforms/index.md index 15dd9ffd7..6501e1315 100644 --- a/docs/platforms/index.md +++ b/docs/platforms/index.md @@ -6,7 +6,8 @@ read_when: --- # Platforms -Clawdbot core is written in TypeScript, so the CLI + Gateway run anywhere Node or Bun runs. +Clawdbot core is written in TypeScript. **Node is the recommended runtime**. +Bun is not recommended for the Gateway (WhatsApp/Telegram bugs). Companion apps exist for macOS (menu bar app) and mobile nodes (iOS/Android). Windows and Linux companion apps are planned, but the Gateway is fully supported today. diff --git a/docs/platforms/linux.md b/docs/platforms/linux.md index 1f66144a4..d6cb44549 100644 --- a/docs/platforms/linux.md +++ b/docs/platforms/linux.md @@ -6,7 +6,8 @@ read_when: --- # Linux App -The Gateway is fully supported on Linux. The core is written in TypeScript, so it runs anywhere Node or Bun runs. +The Gateway is fully supported on Linux. **Node is the recommended runtime**. +Bun is not recommended for the Gateway (WhatsApp/Telegram bugs). Native Linux companion apps are planned. Contributions are welcome if you want to help build one. @@ -23,7 +24,7 @@ Step-by-step VPS guide: [exe.dev](/platforms/exe-dev) ## Install - [Getting Started](/start/getting-started) - [Install & updates](/install/updating) -- Optional flows: [Bun](/install/bun), [Nix](/install/nix), [Docker](/install/docker) +- Optional flows: [Bun (experimental)](/install/bun), [Nix](/install/nix), [Docker](/install/docker) ## Gateway - [Gateway runbook](/gateway) diff --git a/docs/platforms/mac/bundled-gateway.md b/docs/platforms/mac/bundled-gateway.md index 79758b9f0..20c8e1924 100644 --- a/docs/platforms/mac/bundled-gateway.md +++ b/docs/platforms/mac/bundled-gateway.md @@ -20,7 +20,7 @@ You need Node 22+ on the Mac, then install `clawdbot` globally: npm install -g clawdbot@ ``` -The macOS app’s **Install CLI** button runs the same flow via npm/pnpm/bun. +The macOS app’s **Install CLI** button runs the same flow via npm/pnpm (bun not recommended for Gateway runtime). ## Launchd (Gateway as LaunchAgent) diff --git a/docs/platforms/macos.md b/docs/platforms/macos.md index 5eea70548..abb3bd2d7 100644 --- a/docs/platforms/macos.md +++ b/docs/platforms/macos.md @@ -18,7 +18,7 @@ node. - Runs or connects to the Gateway (local or remote). - Exposes macOS‑only tools (Canvas, Camera, Screen Recording, `system.run`). - Optionally hosts **PeekabooBridge** for UI automation. -- Installs the global CLI (`clawdbot`) via npm/pnpm/bun on request. +- Installs the global CLI (`clawdbot`) via npm/pnpm on request (bun not recommended for the Gateway runtime). ## Local vs remote mode diff --git a/docs/providers/discord.md b/docs/providers/discord.md index f5b2a5ce7..b225106b6 100644 --- a/docs/providers/discord.md +++ b/docs/providers/discord.md @@ -174,6 +174,8 @@ Notes: - The bot lacks channel permissions (View/Send/Read History), or - Your config requires mentions and you didn’t mention it, or - Your guild/channel allowlist denies the channel/user. +- **`requireMention: false` but still no replies**: + - `discord.groupPolicy` defaults to **allowlist**; you must either set it to `"open"` or explicitly list the channel under `discord.guilds..channels`. - **Permission audits** (`providers status --probe`) only check numeric channel IDs. If you use slugs/names as `discord.guilds.*.channels` keys, the audit can’t verify permissions. - **DMs don’t work**: `discord.dm.enabled=false`, `discord.dm.policy="disabled"`, or you haven’t been approved yet (`discord.dm.policy="pairing"`). diff --git a/docs/providers/minimax.md b/docs/providers/minimax.md index ae6f0efdb..5336d5d8b 100644 --- a/docs/providers/minimax.md +++ b/docs/providers/minimax.md @@ -158,3 +158,24 @@ Use the interactive config wizard to set MiniMax without editing JSON: - Update pricing values in `models.json` if you need exact cost tracking. - See [/concepts/model-providers](/concepts/model-providers) for provider rules. - Use `clawdbot models list` and `clawdbot models set minimax/MiniMax-M2.1` to switch. + +## Troubleshooting + +### “Unknown model: minimax/MiniMax-M2.1” + +This usually means the **MiniMax provider isn’t configured** (no provider entry +and no MiniMax auth profile/env key found). A fix for this detection is in +**2026.1.12** (unreleased at the time of writing). Fix by: +- Upgrading to **2026.1.12** (or run from source `main`), then restarting the gateway. +- Running `clawdbot configure` and selecting **MiniMax M2.1**, or +- Adding the `models.providers.minimax` block manually, or +- Setting `MINIMAX_API_KEY` (or a MiniMax auth profile) so the provider can be injected. + +Make sure the model id is **case‑sensitive**: +- `minimax/MiniMax-M2.1` +- `minimax/MiniMax-M2.1-lightning` + +Then recheck with: +```bash +clawdbot models list +``` diff --git a/docs/providers/whatsapp.md b/docs/providers/whatsapp.md index 2926e44cc..4a2462fc9 100644 --- a/docs/providers/whatsapp.md +++ b/docs/providers/whatsapp.md @@ -310,4 +310,5 @@ WhatsApp can automatically send emoji reactions to incoming messages immediately - Fix: `clawdbot doctor` (or restart the gateway). If it persists, relink via `providers login` and inspect `clawdbot logs --follow`. **Bun runtime** -- WhatsApp uses Baileys; run the gateway with **Node** for WhatsApp. (See Getting Started runtime note.) +- Bun is **not recommended**. WhatsApp (Baileys) and Telegram are unreliable on Bun. + Run the gateway with **Node**. (See Getting Started runtime note.) diff --git a/docs/start/faq.md b/docs/start/faq.md index 35e8b62f7..fab2c7d4d 100644 --- 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 + ``` + +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-`). - 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 ` 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.`, `clawdbot-gateway-.service`, `Clawdbot Gateway ()`). +### 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://: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://:18789 --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..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?”** diff --git a/docs/start/getting-started.md b/docs/start/getting-started.md index 10c17e513..7ba5bd596 100644 --- 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 diff --git a/docs/start/hubs.md b/docs/start/hubs.md index e639674c1..b84c4696b 100644 --- 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 diff --git a/docs/start/onboarding.md b/docs/start/onboarding.md index 6be8c3124..0bc94fa62 100644 --- 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) diff --git a/docs/start/wizard.md b/docs/start/wizard.md index 7b9d7bcc9..62ca405be 100644 --- 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 ` 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** diff --git a/docs/tools/clawdhub.md b/docs/tools/clawdhub.md index 7a7716922..4d60698e7 100644 --- a/docs/tools/clawdhub.md +++ b/docs/tools/clawdhub.md @@ -42,10 +42,6 @@ npm i -g clawdhub pnpm add -g clawdhub ``` -```bash -bun add -g clawdhub -``` - ## How it fits into Clawdbot By default, the CLI installs skills into `./skills` under your current working directory. If a Clawdbot workspace is configured, `clawdhub` falls back to that workspace unless you override `--workdir` (or `CLAWDHUB_WORKDIR`). Clawdbot loads workspace skills from `/skills` and will pick them up in the **next** session. If you already use `~/.clawdbot/skills` or bundled skills, workspace skills take precedence. diff --git a/docs/tools/skills-config.md b/docs/tools/skills-config.md index e9eeb041c..392eca28c 100644 --- a/docs/tools/skills-config.md +++ b/docs/tools/skills-config.md @@ -20,7 +20,7 @@ All skills-related configuration lives under `skills` in `~/.clawdbot/clawdbot.j }, install: { preferBrew: true, - nodeManager: "npm" // npm | pnpm | yarn | bun + nodeManager: "npm" // npm | pnpm | yarn | bun (Gateway runtime still Node; bun not recommended) }, entries: { "nano-banana-pro": { @@ -44,6 +44,8 @@ All skills-related configuration lives under `skills` in `~/.clawdbot/clawdbot.j - `load.extraDirs`: additional skill directories to scan (lowest precedence). - `install.preferBrew`: prefer brew installers when available (default: true). - `install.nodeManager`: node installer preference (`npm` | `pnpm` | `yarn` | `bun`, default: npm). + This only affects **skill installs**; the Gateway runtime should still be Node + (Bun not recommended for WhatsApp/Telegram). - `entries.`: per-skill overrides. Per-skill fields: diff --git a/docs/tools/skills.md b/docs/tools/skills.md index 2e50b318b..e0a69746d 100644 --- a/docs/tools/skills.md +++ b/docs/tools/skills.md @@ -45,8 +45,9 @@ surface those skills teach. ## ClawdHub (install + sync) -ClawdHub is the public skills registry for Clawdbot. Use it to discover, -install, update, and back up skills. Full guide: [ClawdHub](/tools/clawdhub). +ClawdHub is the public skills registry for Clawdbot. Browse at +https://clawdhub.com. Use it to discover, install, update, and back up skills. +Full guide: [ClawdHub](/tools/clawdhub). Common flows: @@ -117,6 +118,8 @@ metadata: {"clawdbot":{"emoji":"♊️","requires":{"bins":["gemini"]},"install" Notes: - If multiple installers are listed, the gateway picks a **single** preferred option (brew when available, otherwise node). - Node installs honor `skills.install.nodeManager` in `clawdbot.json` (default: npm; options: npm/pnpm/yarn/bun). + This only affects **skill installs**; the Gateway runtime should still be Node + (Bun is not recommended for WhatsApp/Telegram). - Go installs: if `go` is missing and `brew` is available, the gateway installs Go via Homebrew first and sets `GOBIN` to Homebrew’s `bin` when possible. If no `metadata.clawdbot` is present, the skill is always eligible (unless @@ -201,6 +204,6 @@ See [Skills config](/tools/skills-config) for the full configuration schema. ## Looking for more skills? -Browse [ClawdHub](/tools/clawdhub). +Browse https://clawdhub.com. --- diff --git a/docs/web/tui.md b/docs/web/tui.md index 18e433857..9bc383b86 100644 --- a/docs/web/tui.md +++ b/docs/web/tui.md @@ -67,3 +67,6 @@ Use SSH tunneling or Tailscale to reach the Gateway WS. ## Notes - The TUI shows Gateway chat deltas (`event: chat`) and agent tool events. - It registers as a Gateway client with `mode: "tui"` for presence and debugging. +- The TUI uses the **Gateway’s** model/auth config and environment. If a model + token works in your shell but not in TUI, put it in `~/.clawdbot/.env` or + enable `env.shellEnv.enabled`, then restart the Gateway.