From ede51451918fbbc7a5a0f62e1c70014b73927f8c Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sun, 25 Jan 2026 04:33:14 +0000 Subject: [PATCH] docs: sweep support troubleshooting updates --- docs/channels/telegram.md | 7 +++++++ docs/channels/troubleshooting.md | 1 + docs/concepts/memory.md | 1 + docs/gateway/configuration.md | 3 +++ docs/help/faq.md | 6 +++++- docs/tui.md | 8 ++++++++ 6 files changed, 25 insertions(+), 1 deletion(-) diff --git a/docs/channels/telegram.md b/docs/channels/telegram.md index 6251e5530..f88f50bb6 100644 --- a/docs/channels/telegram.md +++ b/docs/channels/telegram.md @@ -120,6 +120,13 @@ You can add custom commands to the menu via config: } ``` +## Troubleshooting + +- `setMyCommands failed` in logs usually means outbound HTTPS/DNS is blocked to `api.telegram.org`. +- If you see `sendMessage` or `sendChatAction` failures, check IPv6 routing and DNS. + +More help: [Channel troubleshooting](/channels/troubleshooting). + Notes: - Custom commands are **menu entries only**; Clawdbot does not implement them unless you handle them elsewhere. - Command names are normalized (leading `/` stripped, lowercased) and must match `a-z`, `0-9`, `_` (1–32 chars). diff --git a/docs/channels/troubleshooting.md b/docs/channels/troubleshooting.md index 6eed5265d..a62f9e27e 100644 --- a/docs/channels/troubleshooting.md +++ b/docs/channels/troubleshooting.md @@ -22,3 +22,4 @@ clawdbot channels status --probe ## Telegram quick fixes - Logs show `HttpError: Network request for 'sendMessage' failed` or `sendChatAction` → check IPv6 DNS. If `api.telegram.org` resolves to IPv6 first and the host lacks IPv6 egress, force IPv4 or enable IPv6. See [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting). +- Logs show `setMyCommands failed` → check outbound HTTPS and DNS reachability to `api.telegram.org` (common on locked-down VPS or proxies). diff --git a/docs/concepts/memory.md b/docs/concepts/memory.md index f913a0ce1..3d9996593 100644 --- a/docs/concepts/memory.md +++ b/docs/concepts/memory.md @@ -31,6 +31,7 @@ These files live under the workspace (`agents.defaults.workspace`, default - Decisions, preferences, and durable facts go to `MEMORY.md`. - Day-to-day notes and running context go to `memory/YYYY-MM-DD.md`. - If someone says "remember this," write it down (do not keep it in RAM). +- This area is still evolving. It helps to remind the model to store memories; it will know what to do. - If you want something to stick, **ask the bot to write it** into memory. ## Automatic memory flush (pre-compaction ping) diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md index e9212e692..67701f946 100644 --- a/docs/gateway/configuration.md +++ b/docs/gateway/configuration.md @@ -46,6 +46,9 @@ better forms without hard-coding config knowledge. Use `config.apply` to validate + write the full config and restart the Gateway in one step. It writes a restart sentinel and pings the last active session after the Gateway comes back. +Warning: `config.apply` replaces the **entire config**. If you want to change only a few keys, +use `config.patch` or `clawdbot config set`. Keep a backup of `~/.clawdbot/clawdbot.json`. + Params: - `raw` (string) — JSON5 payload for the entire config - `baseHash` (optional) — config hash from `config.get` (required when a config already exists) diff --git a/docs/help/faq.md b/docs/help/faq.md index ef3658096..ef283be30 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -1013,7 +1013,9 @@ is writable (read-only sandboxes skip it). See [Memory](/concepts/memory). Ask the bot to **write the fact to memory**. Long-term notes belong in `MEMORY.md`, short-term context goes into `memory/YYYY-MM-DD.md`. -If it keeps forgetting, verify the Gateway is using the same workspace on every run. +This is still an area we are improving. It helps to remind the model to store memories; +it will know what to do. If it keeps forgetting, verify the Gateway is using the same +workspace on every run. Docs: [Memory](/concepts/memory), [Agent workspace](/concepts/agent-workspace). @@ -1375,6 +1377,8 @@ else is removed. Recover: - Restore from backup (git or a copied `~/.clawdbot/clawdbot.json`). - If you have no backup, re-run `clawdbot doctor` and reconfigure channels/models. +- If this was unexpected, file a bug and include your last known config or any backup. +- A local coding agent can often reconstruct a working config from logs or history. Avoid it: - Use `clawdbot config set` for small changes. diff --git a/docs/tui.md b/docs/tui.md index 4d094dc6b..569e26764 100644 --- a/docs/tui.md +++ b/docs/tui.md @@ -118,6 +118,14 @@ Other Gateway slash commands (for example, `/context`) are forwarded to the Gate - `--deliver`: Deliver assistant replies to the provider (default off) - `--thinking `: Override thinking level for sends - `--timeout-ms `: Agent timeout in ms (defaults to `agents.defaults.timeoutSeconds`) + +## Troubleshooting + +No output after sending a message: +- Run `/status` in the TUI to confirm the Gateway is connected and idle/busy. +- Check the Gateway logs: `clawdbot logs --follow`. +- Confirm the agent can run: `clawdbot status` and `clawdbot models status`. +- If you expect messages in a chat channel, enable delivery (`/deliver on` or `--deliver`). - `--history-limit `: History entries to load (default 200) ## Troubleshooting