diff --git a/docs/start/faq.md b/docs/start/faq.md index 7dca8ee87..7d6824eb5 100644 --- a/docs/start/faq.md +++ b/docs/start/faq.md @@ -60,7 +60,6 @@ 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) - [Do nodes run a gateway daemon?](#do-nodes-run-a-gateway-daemon) - - [Can I run a headless node host without the macOS app?](#can-i-run-a-headless-node-host-without-the-macos-app) - [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) @@ -406,7 +405,7 @@ You have three supported patterns: Run the Gateway where the macOS binaries exist, then connect from Linux in [remote mode](#how-do-i-run-clawdbot-in-remote-mode-client-connects-to-a-gateway-elsewhere) or over Tailscale. The skills load normally because the Gateway host is macOS. **Option B - use a macOS node (no SSH).** -Run the Gateway on Linux, pair a macOS node (menubar app), and configure **Exec approvals** (Settings → Exec approvals) to "Ask" or "Always Allow". Clawdbot can treat macOS-only skills as eligible when the required binaries exist on the node. The agent runs those skills via the `nodes` tool. If you choose "Ask", selecting "Always Allow" in the prompt adds that command to the allowlist. +Run the Gateway on Linux, pair a macOS node (menubar app), and set **Node Run Commands** to "Always Ask" or "Always Allow" on the Mac. Clawdbot can treat macOS-only skills as eligible when the required binaries exist on the node. The agent runs those skills via the `nodes` tool. If you choose "Always Ask", approving "Always Allow" in the prompt adds that command to the allowlist. **Option C - proxy macOS binaries over SSH (advanced).** Keep the Gateway on Linux, but make the required CLI binaries resolve to SSH wrappers that run on a Mac. Then override the skill to allow Linux so it stays eligible. @@ -502,14 +501,23 @@ is writable (read-only sandboxes skip it). See [Memory](/concepts/memory). ### Does semantic memory search require an OpenAI API key? -Only if you use **remote embeddings** (OpenAI). Codex OAuth covers -chat/completions and does **not** grant embeddings access, so **signing in with -Codex (OAuth or the Codex CLI login)** does not help for semantic memory search. -Remote memory search still needs a real OpenAI API key (`OPENAI_API_KEY` or -`models.providers.openai.apiKey`). If you’d rather stay local, set -`memorySearch.provider = "local"` (and optionally `memorySearch.fallback = -"none"`). We support **remote or local embedding models** — see [Memory](/concepts/memory) -for the setup details. +Only if you use **OpenAI embeddings**. Codex OAuth covers chat/completions and +does **not** grant embeddings access, so **signing in with Codex (OAuth or the +Codex CLI login)** does not help for semantic memory search. OpenAI embeddings +still need a real API key (`OPENAI_API_KEY` or `models.providers.openai.apiKey`). + +If you don’t set a provider explicitly, Clawdbot auto-selects a provider when it +can resolve an API key (auth profiles, `models.providers.*.apiKey`, or env vars). +It prefers OpenAI if an OpenAI key resolves, otherwise Gemini if a Gemini key +resolves. If neither key is available, memory search stays disabled until you +configure it. If you have a local model path configured and present, Clawdbot +prefers `local`. + +If you’d rather stay local, set `memorySearch.provider = "local"` (and optionally +`memorySearch.fallback = "none"`). If you want Gemini embeddings, set +`memorySearch.provider = "gemini"` and provide `GEMINI_API_KEY` (or +`memorySearch.remote.apiKey`). We support **OpenAI, Gemini, or local** embedding +models — see [Memory](/concepts/memory) for the setup details. ## Where things live on disk @@ -743,23 +751,6 @@ to the gateway (iOS/Android nodes, or macOS “node mode” in the menubar app). A full restart is required for `gateway`, `bridge`, `discovery`, and `canvasHost` changes. -### Can I run a headless node host without the macOS app? - -Yes. The headless node host is a **command-only** node that exposes `system.run` / `system.which` -without any UI. It has no screen/camera/notify support (use the macOS app for those). - -Start it: -```bash -clawdbot node start --host --port 18790 -``` - -Notes: -- Pairing is still required (`clawdbot nodes pending` → `clawdbot nodes approve `). -- Exec approvals still apply via `~/.clawdbot/exec-approvals.json`. -- If prompts are enabled but no companion UI is reachable, `askFallback` decides (default: deny). - -Docs: [Node CLI](/cli/node), [Nodes](/nodes), [Exec approvals](/tools/exec-approvals). - ### Is there an API / RPC way to apply config? Yes. `config.apply` validates + writes the full config and restarts the Gateway as part of the operation. @@ -898,19 +889,14 @@ Send `/new` or `/reset` as a standalone message. See [Session management](/conce ### Do sessions reset automatically if I never send `/new`? -Yes. By default sessions reset daily at **4:00 AM local time** on the gateway host. -You can also add an idle window; when both daily and idle resets are configured, -whichever expires first starts a new session id on the next message. This does -not delete transcripts — it just starts a new session. +Yes. Sessions expire after `session.idleMinutes` (default **60**). The **next** +message starts a fresh session id for that chat key. This does not delete +transcripts — it just starts a new session. ```json5 { session: { - reset: { - mode: "daily", - atHour: 4, - idleMinutes: 240 - } + idleMinutes: 240 } } ```