From bf72a126d1dbd8045822fdd3c6af9d1f1121e2f4 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Fri, 16 Jan 2026 23:10:10 +0000 Subject: [PATCH] docs: add /help hub and Node/npm PATH guide --- CHANGELOG.md | 1 + docs/docs.json | 18 ++++++++- docs/gateway/authentication.md | 2 +- docs/help/faq.md | 32 +++++++++++++++ docs/help/index.md | 20 +++++++++ docs/help/troubleshooting.md | 59 +++++++++++++++++++++++++++ docs/index.md | 2 +- docs/install/index.md | 2 + docs/install/installer.md | 2 + docs/install/node.md | 74 ++++++++++++++++++++++++++++++++++ docs/platforms/exe-dev.md | 2 +- docs/start/hubs.md | 2 +- 12 files changed, 211 insertions(+), 5 deletions(-) create mode 100644 docs/help/faq.md create mode 100644 docs/help/index.md create mode 100644 docs/help/troubleshooting.md create mode 100644 docs/install/node.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 2e4dbc1bc..595e0b9fd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -32,6 +32,7 @@ - Cron: isolated cron jobs now start a fresh session id on every run to prevent context buildup. - Daemon: share profile/state-dir resolution across service helpers and honor `CLAWDBOT_STATE_DIR` for Windows task scripts. - Docs: clarify multi-gateway rescue bot guidance. (#969) — thanks @bjesuiter. +- Docs: add `/help` hub, Node/npm PATH sanity guide, and installer PATH warnings (for “installed but command not found” setups). (#861) - Agents: add Current Date & Time system prompt section with configurable time format (auto/12/24). - Agents: default to no narration for routine tool calls. (#1008) — thanks @cpojer. - Tools: normalize Slack/Discord message timestamps with `timestampMs`/`timestampUtc` while keeping raw provider fields. diff --git a/docs/docs.json b/docs/docs.json index b2e06dbf2..72b776b0a 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -733,6 +733,14 @@ "source": "/wizard", "destination": "/start/wizard" }, + { + "source": "/start/faq", + "destination": "/help" + }, + { + "source": "/start/faq/", + "destination": "/help" + }, { "source": "/oauth", "destination": "/concepts/oauth" @@ -752,7 +760,6 @@ "start/wizard", "start/setup", "start/pairing", - "start/faq", "start/clawd", "start/showcase", "start/hubs", @@ -760,10 +767,19 @@ "start/lore" ] }, + { + "group": "Help", + "pages": [ + "help/index", + "help/troubleshooting", + "help/faq" + ] + }, { "group": "Install & Updates", "pages": [ "install/index", + "install/node", "install/installer", "install/updating", "install/uninstall", diff --git a/docs/gateway/authentication.md b/docs/gateway/authentication.md index ff24cb1ed..5f6aa3723 100644 --- a/docs/gateway/authentication.md +++ b/docs/gateway/authentication.md @@ -44,7 +44,7 @@ clawdbot doctor If you’d rather not manage env vars yourself, the onboarding wizard can store API keys for daemon use: `clawdbot onboard`. -See [/start/faq](/start/faq) for details on env inheritance (`env.shellEnv`, +See [Help](/help) for details on env inheritance (`env.shellEnv`, `~/.clawdbot/.env`, systemd/launchd). ## Anthropic: Claude Code CLI setup-token (supported) diff --git a/docs/help/faq.md b/docs/help/faq.md new file mode 100644 index 000000000..2e56e791d --- /dev/null +++ b/docs/help/faq.md @@ -0,0 +1,32 @@ +--- +summary: "FAQ (concepts): what Clawdbot is and how it fits together" +read_when: + - You’re new and want the mental model + - You’re not debugging a specific error +--- + +# FAQ (concepts) + +If you’re here because something’s broken, start with: [Troubleshooting](/help/troubleshooting). + +## What is Clawdbot? + +Clawdbot is a personal AI assistant you run on your own devices. It replies on the messaging surfaces you already use (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, WebChat) and can also do voice + a live Canvas on supported platforms. The **Gateway** is the always‑on control plane; the assistant is the product. + +## What runtime do I need? + +Node **>= 22** is required. `pnpm` is recommended. Bun is **not recommended** for the Gateway. + +## What’s the recommended setup flow? + +Use the onboarding wizard: + +```bash +clawdbot onboard --install-daemon +``` + +Then use: + +```bash +clawdbot dashboard +``` diff --git a/docs/help/index.md b/docs/help/index.md new file mode 100644 index 000000000..5a4193c40 --- /dev/null +++ b/docs/help/index.md @@ -0,0 +1,20 @@ +--- +summary: "Help hub: common fixes, install sanity, and where to look when something breaks" +read_when: + - You’re new and want the “what do I click/run” guide + - Something broke and you want the fastest path to a fix +--- + +# Help + +If you want a quick “get unstuck” flow, start here: + +- **Troubleshooting:** [Start here](/help/troubleshooting) +- **Install sanity (Node/npm/PATH):** [Node.js + npm (PATH sanity)](/install/node) +- **Gateway issues:** [Gateway troubleshooting](/gateway/troubleshooting) +- **Logs:** [Logging](/logging) and [Gateway logging](/gateway/logging) +- **Repairs:** [Doctor](/gateway/doctor) + +If you’re looking for conceptual questions (not “something broke”): + +- [FAQ (concepts)](/help/faq) diff --git a/docs/help/troubleshooting.md b/docs/help/troubleshooting.md new file mode 100644 index 000000000..0b4b35789 --- /dev/null +++ b/docs/help/troubleshooting.md @@ -0,0 +1,59 @@ +--- +summary: "Troubleshooting hub: symptoms → checks → fixes" +read_when: + - You see an error and want the fix path + - The installer says “success” but the CLI doesn’t work +--- + +# Troubleshooting + +## First 60 seconds + +Run these in order: + +```bash +clawdbot status +clawdbot status --all +clawdbot daemon status +clawdbot logs --follow +clawdbot doctor +``` + +If the gateway is reachable, deep probes: + +```bash +clawdbot status --deep +``` + +## Common “it broke” cases + +### `clawdbot: command not found` + +Almost always a Node/npm PATH issue. Start here: + +- [Node.js + npm (PATH sanity)](/install/node) + +### Gateway “unauthorized”, can’t connect, or keeps reconnecting + +- [Gateway troubleshooting](/gateway/troubleshooting) +- [Gateway authentication](/gateway/authentication) + +### Daemon says running, but RPC probe fails + +- [Gateway troubleshooting](/gateway/troubleshooting) +- [Background process / daemon](/gateway/background-process) + +### Model/auth failures (rate limit, billing, “all models failed”) + +- [Models](/cli/models) +- [OAuth / auth concepts](/concepts/oauth) + +### When filing an issue + +Paste a safe report: + +```bash +clawdbot status --all +``` + +If you can, include the relevant log tail from `clawdbot logs --follow`. diff --git a/docs/index.md b/docs/index.md index cf991bb0b..c85600243 100644 --- a/docs/index.md +++ b/docs/index.md @@ -165,7 +165,7 @@ Example: - Start here: - [Docs hubs (all pages linked)](/start/hubs) - - [FAQ](/start/faq) ← *common questions answered* + - [Help](/help) ← *common fixes + troubleshooting* - [Configuration](/gateway/configuration) - [Configuration examples](/gateway/configuration-examples) - [Slash commands](/tools/slash-commands) diff --git a/docs/install/index.md b/docs/install/index.md index 8557852a8..f2eb6083d 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -9,6 +9,8 @@ read_when: Runtime baseline: **Node >=22**. +If the installer says it succeeded but you later see `clawdbot: command not found`, it’s usually a Node/npm PATH issue. See: [Node.js + npm (PATH sanity)](/install/node). + ## Recommended (installer script) ```bash diff --git a/docs/install/installer.md b/docs/install/installer.md index 12286be64..578a96d67 100644 --- a/docs/install/installer.md +++ b/docs/install/installer.md @@ -19,6 +19,8 @@ To see the current flags/behavior, run: curl -fsSL https://clawd.bot/install.sh | bash -s -- --help ``` +If the installer completes but `clawdbot` is not found in a new terminal, it’s usually a Node/npm PATH issue. See: [Node.js + npm (PATH sanity)](/install/node). + ## install.sh (recommended) What it does (high level): diff --git a/docs/install/node.md b/docs/install/node.md new file mode 100644 index 000000000..8987a859b --- /dev/null +++ b/docs/install/node.md @@ -0,0 +1,74 @@ +--- +summary: "Node.js + npm install sanity: versions, PATH, and global installs" +read_when: + - You installed Clawdbot but `clawdbot` is “command not found” + - You’re setting up Node.js/npm on a new machine + - `npm install -g ...` fails with permissions or PATH issues +--- + +# Node.js + npm (PATH sanity) + +Clawdbot’s runtime baseline is **Node 22+**. + +If you can run `npm install -g clawdbot@latest` but later see `clawdbot: command not found`, it’s almost always a **PATH** issue: the directory where npm puts global binaries isn’t on your shell’s PATH. + +## Quick diagnosis + +Run: + +```bash +node -v +npm -v +npm bin -g +echo "$PATH" +``` + +If the output of `npm bin -g` is **not** present inside `echo "$PATH"`, your shell can’t find global npm binaries (including `clawdbot`). + +## Fix: put npm’s global bin dir on PATH + +1) Find your global bin directory: + +```bash +npm bin -g +``` + +2) Add it to your shell startup file: + +- zsh: `~/.zshrc` +- bash: `~/.bashrc` + +Example (replace the path with your `npm bin -g` output): + +```bash +export PATH="/path/from/npm/bin/-g:$PATH" +``` + +Then open a **new terminal** (or run `rehash` in zsh / `hash -r` in bash). + +## Fix: avoid `sudo npm install -g` / permission errors (Linux) + +If `npm install -g ...` fails with `EACCES`, switch npm’s global prefix to a user-writable directory: + +```bash +mkdir -p "$HOME/.npm-global" +npm config set prefix "$HOME/.npm-global" +export PATH="$HOME/.npm-global/bin:$PATH" +``` + +Persist the `export PATH=...` line in your shell startup file. + +## Recommended Node install options + +You’ll have the fewest surprises if Node/npm are installed in a way that: + +- keeps Node updated (22+) +- makes `npm bin -g` stable and on PATH in new shells + +Common choices: + +- macOS: Homebrew (`brew install node`) or a version manager +- Linux: your preferred version manager, or a distro-supported install that provides Node 22+ +- Windows: official Node installer, `winget`, or a Windows Node version manager + +If you use a version manager (nvm/fnm/asdf/etc), ensure it’s initialized in the shell you use day-to-day (zsh vs bash) so the PATH it sets is present when you run installers. diff --git a/docs/platforms/exe-dev.md b/docs/platforms/exe-dev.md index 6692d9ab4..813c45da8 100644 --- a/docs/platforms/exe-dev.md +++ b/docs/platforms/exe-dev.md @@ -99,7 +99,7 @@ It can set up: - model provider config/login - Linux systemd **user** service (daemon) -If you’re doing OAuth on a headless VM: do OAuth on a normal machine first, then copy the auth profile to the VM (see [FAQ](/start/faq)). +If you’re doing OAuth on a headless VM: do OAuth on a normal machine first, then copy the auth profile to the VM (see [Help](/help)). ## 5) Remote access options diff --git a/docs/start/hubs.md b/docs/start/hubs.md index 19c4232c4..1e5b09d59 100644 --- a/docs/start/hubs.md +++ b/docs/start/hubs.md @@ -15,7 +15,7 @@ Use these hubs to discover every page, including deep dives and reference docs t - [Wizard](/start/wizard) - [Setup](/start/setup) - [Dashboard (local Gateway)](http://127.0.0.1:18789/) -- [FAQ](/start/faq) +- [Help](/help) - [Configuration](/gateway/configuration) - [Configuration examples](/gateway/configuration-examples) - [Clawdbot assistant (Clawd)](/start/clawd)