docs: move troubleshooting items from faq
This commit is contained in:
Peter Steinberger
@@ -169,6 +169,20 @@ The agent was interrupted mid-response.
|
|||||||
|
|
||||||
**Fix:** Just send another message. The session continues.
|
**Fix:** Just send another message. The session continues.
|
||||||
|
|
||||||
|
### "Agent failed before reply: Unknown model: anthropic/claude-haiku-3-5"
|
||||||
|
|
||||||
|
Clawdbot intentionally rejects **older/insecure models** (especially those more
|
||||||
|
vulnerable to prompt injection). If you see this error, the model name is no
|
||||||
|
longer supported.
|
||||||
|
|
||||||
|
**Fix:**
|
||||||
|
- Pick a **latest** model for the provider and update your config or model alias.
|
||||||
|
- If you’re unsure which models are available, run `clawdbot models list` or
|
||||||
|
`clawdbot models scan` and choose a supported one.
|
||||||
|
- Check gateway logs for the detailed failure reason.
|
||||||
|
|
||||||
|
See also: [Models CLI](/cli/models) and [Model providers](/concepts/model-providers).
|
||||||
|
|
||||||
### Messages Not Triggering
|
### Messages Not Triggering
|
||||||
|
|
||||||
**Check 1:** Is the sender allowlisted?
|
**Check 1:** Is the sender allowlisted?
|
||||||
@@ -306,6 +320,139 @@ Clawdbot keeps conversation history in memory.
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Common troubleshooting
|
||||||
|
|
||||||
|
### “All models failed” — what should I check first?
|
||||||
|
|
||||||
|
- **Credentials** present for the provider(s) being tried (auth profiles + env vars).
|
||||||
|
- **Model routing**: confirm `agents.defaults.model.primary` and fallbacks are models you can access.
|
||||||
|
- **Gateway logs** in `/tmp/clawdbot/…` for the exact provider error.
|
||||||
|
- **Model status**: use `/model status` (chat) or `clawdbot models status` (CLI).
|
||||||
|
|
||||||
|
### I’m running on my personal WhatsApp number — why is self-chat weird?
|
||||||
|
|
||||||
|
Enable self-chat mode and allowlist your own number:
|
||||||
|
|
||||||
|
```json5
|
||||||
|
{
|
||||||
|
channels: {
|
||||||
|
whatsapp: {
|
||||||
|
selfChatMode: true,
|
||||||
|
dmPolicy: "allowlist",
|
||||||
|
allowFrom: ["+15555550123"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
See [WhatsApp setup](/channels/whatsapp).
|
||||||
|
|
||||||
|
### WhatsApp logged me out. How do I re‑auth?
|
||||||
|
|
||||||
|
Run the login command again and scan the QR code:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
clawdbot channels login
|
||||||
|
```
|
||||||
|
|
||||||
|
### Build errors on `main` — what’s the standard fix path?
|
||||||
|
|
||||||
|
1) `git pull origin main && pnpm install`
|
||||||
|
2) `pnpm clawdbot doctor`
|
||||||
|
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"`.
|
||||||
|
- `channels.telegram.blockStreaming` is set to `false`.
|
||||||
|
- `channels.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 `channels.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 `channels.discord.groupPolicy` is **allowlist**, so guilds must be explicitly enabled.
|
||||||
|
If you set `channels.discord.guilds.<guildId>.channels`, only the listed channels are allowed; omit it to allow all channels in the guild.
|
||||||
|
|
||||||
|
Fix checklist:
|
||||||
|
1) Set `channels.discord.groupPolicy: "open"` **or** add a guild allowlist entry (and optionally a channel allowlist).
|
||||||
|
2) Use **numeric channel IDs** in `channels.discord.guilds.<guildId>.channels`.
|
||||||
|
3) Put `requireMention: false` **under** `channels.discord.guilds` (global or per‑channel).
|
||||||
|
Top‑level `channels.discord.requireMention` is not a supported key.
|
||||||
|
4) Ensure the bot has **Message Content Intent** and channel permissions.
|
||||||
|
5) Run `clawdbot channels status --probe` for audit hints.
|
||||||
|
|
||||||
|
Docs: [Discord](/channels/discord), [Channels troubleshooting](/channels/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).
|
||||||
|
|
||||||
## macOS Specific Issues
|
## macOS Specific Issues
|
||||||
|
|
||||||
### App Crashes when Granting Permissions (Speech/Mic)
|
### App Crashes when Granting Permissions (Speech/Mic)
|
||||||
|
|||||||
@@ -117,16 +117,6 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
|
|||||||
- [Chat commands, aborting tasks, and “it won’t stop”](#chat-commands-aborting-tasks-and-it-wont-stop)
|
- [Chat commands, aborting tasks, and “it won’t stop”](#chat-commands-aborting-tasks-and-it-wont-stop)
|
||||||
- [How do I stop/cancel a running task?](#how-do-i-stopcancel-a-running-task)
|
- [How do I stop/cancel a running task?](#how-do-i-stopcancel-a-running-task)
|
||||||
- [Why does it feel like the bot “ignores” rapid‑fire messages?](#why-does-it-feel-like-the-bot-ignores-rapidfire-messages)
|
- [Why does it feel like the bot “ignores” rapid‑fire messages?](#why-does-it-feel-like-the-bot-ignores-rapidfire-messages)
|
||||||
- [Common troubleshooting](#common-troubleshooting)
|
|
||||||
- [“All models failed” — what should I check first?](#all-models-failed-what-should-i-check-first)
|
|
||||||
- [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
|
## First 60 seconds if something's broken
|
||||||
|
|
||||||
@@ -1501,139 +1491,6 @@ Queue mode controls how new messages interact with an in‑flight run. Use `/que
|
|||||||
|
|
||||||
You can add options like `debounce:2s cap:25 drop:summarize` for followup modes.
|
You can add options like `debounce:2s cap:25 drop:summarize` for followup modes.
|
||||||
|
|
||||||
## Common troubleshooting
|
|
||||||
|
|
||||||
### “All models failed” — what should I check first?
|
|
||||||
|
|
||||||
- **Credentials** present for the provider(s) being tried (auth profiles + env vars).
|
|
||||||
- **Model routing**: confirm `agents.defaults.model.primary` and fallbacks are models you can access.
|
|
||||||
- **Gateway logs** in `/tmp/clawdbot/…` for the exact provider error.
|
|
||||||
- **`/model status`** to see current configured models + shorthands.
|
|
||||||
|
|
||||||
### I’m running on my personal WhatsApp number — why is self-chat weird?
|
|
||||||
|
|
||||||
Enable self-chat mode and allowlist your own number:
|
|
||||||
|
|
||||||
```json5
|
|
||||||
{
|
|
||||||
channels: {
|
|
||||||
whatsapp: {
|
|
||||||
selfChatMode: true,
|
|
||||||
dmPolicy: "allowlist",
|
|
||||||
allowFrom: ["+15555550123"]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
See [WhatsApp setup](/channels/whatsapp).
|
|
||||||
|
|
||||||
### WhatsApp logged me out. How do I re‑auth?
|
|
||||||
|
|
||||||
Run the login command again and scan the QR code:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
clawdbot channels login
|
|
||||||
```
|
|
||||||
|
|
||||||
### Build errors on `main` — what’s the standard fix path?
|
|
||||||
|
|
||||||
1) `git pull origin main && pnpm install`
|
|
||||||
2) `pnpm clawdbot doctor`
|
|
||||||
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"`.
|
|
||||||
- `channels.telegram.blockStreaming` is set to `false`.
|
|
||||||
- `channels.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 `channels.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 `channels.discord.groupPolicy` is **allowlist**, so guilds must be explicitly enabled.
|
|
||||||
If you set `channels.discord.guilds.<guildId>.channels`, only the listed channels are allowed; omit it to allow all channels in the guild.
|
|
||||||
|
|
||||||
Fix checklist:
|
|
||||||
1) Set `channels.discord.groupPolicy: "open"` **or** add a guild allowlist entry (and optionally a channel allowlist).
|
|
||||||
2) Use **numeric channel IDs** in `channels.discord.guilds.<guildId>.channels`.
|
|
||||||
3) Put `requireMention: false` **under** `channels.discord.guilds` (global or per‑channel).
|
|
||||||
Top‑level `channels.discord.requireMention` is not a supported key.
|
|
||||||
4) Ensure the bot has **Message Content Intent** and channel permissions.
|
|
||||||
5) Run `clawdbot channels status --probe` for audit hints.
|
|
||||||
|
|
||||||
Docs: [Discord](/channels/discord), [Channels troubleshooting](/channels/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
|
## Answer the exact question from the screenshot/chat log
|
||||||
|
|
||||||
**Q: “What’s the default model for Anthropic with an API key?”**
|
**Q: “What’s the default model for Anthropic with an API key?”**
|
||||||
|
|||||||
Reference in New Issue
Block a user