From 629ce4454d5d3a1e3fbd4ab9d0877b9bc9370f3f Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sun, 25 Jan 2026 04:04:14 +0000 Subject: [PATCH] docs: add tips + clawd-to-clawd faq --- docs/channels/index.md | 2 ++ docs/concepts/memory.md | 1 + docs/gateway/security.md | 2 ++ docs/help/faq.md | 38 ++++++++++++++++++++++++++++++++++++++ docs/tools/subagents.md | 4 ++++ 5 files changed, 47 insertions(+) diff --git a/docs/channels/index.md b/docs/channels/index.md index ee8a281d1..52e963b87 100644 --- a/docs/channels/index.md +++ b/docs/channels/index.md @@ -32,6 +32,8 @@ Text is supported everywhere; media and reactions vary by channel. ## Notes - Channels can run simultaneously; configure multiple and Clawdbot will route per chat. +- Fastest setup is usually **Telegram** (simple bot token). WhatsApp requires QR pairing and + stores more state on disk. - Group behavior varies by channel; see [Groups](/concepts/groups). - DM pairing and allowlists are enforced for safety; see [Security](/gateway/security). - Telegram internals: [grammY notes](/channels/grammy). diff --git a/docs/concepts/memory.md b/docs/concepts/memory.md index 81320e112..f913a0ce1 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). +- 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/security.md b/docs/gateway/security.md index dd679c29f..48e3fa59c 100644 --- a/docs/gateway/security.md +++ b/docs/gateway/security.md @@ -29,6 +29,8 @@ Clawdbot is both a product and an experiment: you’re wiring frontier-model beh - where the bot is allowed to act - what the bot can touch +Start with the smallest access that still works, then widen it as you gain confidence. + ### What the audit checks (high level) - **Inbound access** (DM policies, group policies, allowlists): can strangers trigger the bot? diff --git a/docs/help/faq.md b/docs/help/faq.md index 313c74d0b..4b87c9ab4 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -85,6 +85,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - [Remote gateways + nodes](#remote-gateways-nodes) - [How do commands propagate between Telegram, the gateway, and nodes?](#how-do-commands-propagate-between-telegram-the-gateway-and-nodes) - [How can my agent access my computer if the Gateway is hosted remotely?](#how-can-my-agent-access-my-computer-if-the-gateway-is-hosted-remotely) + - [Can two Clawdbots talk to each other (local + VPS)?](#can-two-clawdbots-talk-to-each-other-local--vps) - [Is there a benefit to using a node on my personal laptop instead of SSH from a VPS?](#is-there-a-benefit-to-using-a-node-on-my-personal-laptop-instead-of-ssh-from-a-vps) - [Do nodes run a gateway service?](#do-nodes-run-a-gateway-service) - [Is there an API / RPC way to apply config?](#is-there-an-api-rpc-way-to-apply-config) @@ -230,6 +231,9 @@ This installs Clawdbot **from a git checkout**, so the agent can read the code + reason about the exact version you are running. You can always switch back to stable later by re-running the installer without `--install-method git`. +Tip: ask the agent to **plan and supervise** the fix (step-by-step), then execute only the +necessary commands. That keeps changes small and easier to audit. + If you discover a real bug or fix, please file a GitHub issue or send a PR: https://github.com/clawdbot/clawdbot/issues https://github.com/clawdbot/clawdbot/pulls @@ -307,6 +311,9 @@ disk as enough for personal use, and note that a **Raspberry Pi 4 can run it**. If you want extra headroom (logs, media, other services), **2GB is recommended**, but it’s not a hard minimum. +Tip: a small Pi/VPS can host the Gateway, and you can pair **nodes** on your laptop/phone for +local screen/camera/canvas or command execution. See [Nodes](/nodes). + ### Can I migrate my setup to a new machine (Mac mini) without redoing onboarding? Yes. Copy the **state directory** and **workspace**, then run Doctor once. This @@ -973,6 +980,9 @@ 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). +Tip: if you want a durable behavior or preference, ask the bot to **write it into +AGENTS.md or MEMORY.md** rather than relying on chat history. + See [Agent workspace](/concepts/agent-workspace) and [Memory](/concepts/memory). ### What’s the recommended backup strategy? @@ -1167,6 +1177,29 @@ pair devices you trust, and review [Security](/gateway/security). Docs: [Nodes](/nodes), [Gateway protocol](/gateway/protocol), [macOS remote mode](/platforms/mac/remote), [Security](/gateway/security). +### Can two Clawdbots talk to each other (local + VPS)? + +Yes. There is no built-in "bot-to-bot" bridge, but you can wire it up in a few +reliable ways: + +**Simplest:** use a normal chat channel both bots can access (Telegram/Slack/WhatsApp). +Have Bot A send a message to Bot B, then let Bot B reply as usual. + +**CLI bridge (generic):** run a script that calls the other Gateway with +`clawdbot agent --message ... --deliver`, targeting a chat where the other bot +listens. If one bot is on Railway/VPS, point your CLI at that remote Gateway +via SSH/Tailscale (see [Remote access](/gateway/remote)). + +Example pattern (run from a machine that can reach the target Gateway): +```bash +clawdbot agent --message "Hello from local bot" --deliver --channel telegram --reply-to +``` + +Tip: add a guardrail so the two bots do not loop endlessly (mention-only, channel +allowlists, or a "do not reply to bot messages" rule). + +Docs: [Remote access](/gateway/remote), [Agent CLI](/cli/agent), [Agent send](/tools/agent-send). + ### Is there a benefit to using a node on my personal laptop instead of SSH from a VPS? Yes — nodes are the first‑class way to reach your laptop from a remote Gateway, and they @@ -1515,6 +1548,11 @@ Models are referenced as `provider/model` (example: `anthropic/claude-opus-4-5`) MiniMax M2.1 has its own docs: [MiniMax](/providers/minimax) and [Local models](/gateway/local-models). +Rule of thumb: use the **best model you can afford** for high-stakes work, and a cheaper +model for routine chat or summaries. You can route models per agent and use sub-agents to +parallelize long tasks (each sub-agent consumes tokens). See [Models](/concepts/models) and +[Sub-agents](/tools/subagents). + Strong warning: weaker/over-quantized models are more vulnerable to prompt injection and unsafe behavior. See [Security](/gateway/security). diff --git a/docs/tools/subagents.md b/docs/tools/subagents.md index 9c6bd14ef..f2554e1be 100644 --- a/docs/tools/subagents.md +++ b/docs/tools/subagents.md @@ -26,6 +26,10 @@ Primary goals: - Keep the tool surface hard to misuse: sub-agents do **not** get session tools by default. - Avoid nested fan-out: sub-agents cannot spawn sub-agents. +Cost note: each sub-agent has its **own** context and token usage. For heavy or repetitive +tasks, set a cheaper model for sub-agents and keep your main agent on a higher-quality model. +You can configure this via `agents.defaults.subagents.model` or per-agent overrides. + ## Tool Use `sessions_spawn`: