docs: update faq and install guidance
This commit is contained in:
Peter Steinberger
@@ -257,12 +257,12 @@ Options:
|
||||
- `--tailscale-reset-on-exit`
|
||||
- `--install-daemon`
|
||||
- `--no-install-daemon` (alias: `--skip-daemon`)
|
||||
- `--daemon-runtime <node|bun>`
|
||||
- `--daemon-runtime <node|bun>` (bun not recommended for WhatsApp/Telegram)
|
||||
- `--skip-providers`
|
||||
- `--skip-skills`
|
||||
- `--skip-health`
|
||||
- `--skip-ui`
|
||||
- `--node-manager <npm|pnpm|bun>`
|
||||
- `--node-manager <npm|pnpm|bun>` (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`
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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@<version>
|
||||
pnpm add -g clawdbot@<version>
|
||||
```
|
||||
|
||||
```bash
|
||||
bun add -g clawdbot@<version>
|
||||
```
|
||||
|
||||
Tip: to see the current published version, run `npm view clawdbot version`.
|
||||
|
||||
Then restart + re-run doctor:
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -20,7 +20,7 @@ You need Node 22+ on the Mac, then install `clawdbot` globally:
|
||||
npm install -g clawdbot@<version>
|
||||
```
|
||||
|
||||
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)
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.<id>.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"`).
|
||||
|
||||
|
||||
@@ -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
|
||||
```
|
||||
|
||||
@@ -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.)
|
||||
|
||||
@@ -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?”**
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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**
|
||||
|
||||
@@ -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 `<workspace>/skills` and will pick them up in the **next** session. If you already use `~/.clawdbot/skills` or bundled skills, workspace skills take precedence.
|
||||
|
||||
@@ -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.<skillKey>`: per-skill overrides.
|
||||
|
||||
Per-skill fields:
|
||||
|
||||
@@ -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.
|
||||
|
||||
---
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user