From 6f4cd7485ff495fa4a10ae413b78f2fc4c3628ec Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 6 Jan 2026 20:56:12 +0000 Subject: [PATCH] docs: update FAQ auth paths + add clawtributor --- README.md | 2 +- docs/faq.md | 99 ++++++++++++++++++++++++++++------------------------- 2 files changed, 54 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 3048cf42c..35500d4b2 100644 --- a/README.md +++ b/README.md @@ -452,5 +452,5 @@ Thanks to all clawtributors: scald sreekaransrinath ratulsarna osolmaz conhecendocontato hrdwdmrbl jayhickey jamesgroat gtsifrikas djangonavarro220 azade-c andranik-sahakyan adamgall jalehman jarvis-medmatic mneves75 regenrek tobiasbischoff MSch obviyus dbhurley - Asleep123 Iamadig imfing kitze nachoiacovino VACInc cash-echo-bot claude kiranjd pcty-nextgen-service-account + Asleep123 Iamadig imfing kitze nachoiacovino VACInc cash-echo-bot claude kiranjd pcty-nextgen-service-account minghinmatthewlam

diff --git a/docs/faq.md b/docs/faq.md index f38315d36..db6e205ed 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -14,14 +14,16 @@ Everything lives under `~/.clawdbot/`: | Path | Purpose | |------|---------| | `~/.clawdbot/clawdbot.json` | Main config (JSON5) | -| `~/.clawdbot/credentials/oauth.json` | OAuth credentials (Anthropic/OpenAI, etc.) | -| `~/.clawdbot/agent/auth-profiles.json` | Auth profiles (OAuth + API keys) | -| `~/.clawdbot/agent/auth.json` | Runtime API key cache (managed automatically) | -| `~/.clawdbot/credentials/` | WhatsApp/Telegram auth tokens | +| `~/.clawdbot/credentials/oauth.json` | Legacy OAuth import (copied into auth profiles on first use) | +| `~/.clawdbot/agents//agent/auth-profiles.json` | Auth profiles (OAuth + API keys) | +| `~/.clawdbot/agents//agent/auth.json` | Runtime auth cache (managed automatically) | +| `~/.clawdbot/credentials/` | Provider auth state (e.g. `whatsapp//creds.json`) | | `~/.clawdbot/agents/` | Per-agent state (agentDir + sessions) | | `~/.clawdbot/agents//sessions/` | Conversation history & state (per agent) | | `~/.clawdbot/agents//sessions/sessions.json` | Session metadata (per agent) | +Legacy single-agent path: `~/.clawdbot/agent/*` (migrated by `clawdbot doctor`). + Your **workspace** (AGENTS.md, memory files, skills) is separate — configured via `agent.workspace` in your config (default: `~/clawd`). ### What platforms does Clawdbot run on? @@ -38,7 +40,7 @@ Some features are platform-specific: ### What are the minimum system requirements? -**Basically nothing!** The gateway is very lightweight — all heavy compute happens on Anthropic's servers. +**Basically nothing!** The gateway is very lightweight — heavy compute happens on your model provider’s servers (Anthropic/OpenAI/etc.). - **RAM:** 512MB-1GB is enough (community member runs on 1GB VPS!) - **CPU:** 1 core is fine for personal use @@ -142,9 +144,9 @@ Or set `CLAWDBOT_LOAD_SHELL_ENV=1` (timeout: `CLAWDBOT_SHELL_ENV_TIMEOUT_MS=1500 ### Does enterprise OAuth work? -**Not currently.** Enterprise accounts use SSO which requires a different auth flow that pi-coding-agent doesn't support yet. +**Not currently.** Enterprise accounts use SSO which requires a different auth flow that Clawdbot’s OAuth login doesn’t support yet. -**Workaround:** Ask your enterprise admin to provision an API key via the Anthropic console, then use that with `ANTHROPIC_API_KEY`. +**Workaround:** Ask your enterprise admin to provision an API key (Anthropic or OpenAI) and use it via `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`. ### OAuth callback not working (containers/headless)? @@ -192,7 +194,15 @@ OAuth needs the callback to reach the machine running the CLI. Options: ### Can I run Clawdbot in Docker? -There's no official Docker setup yet, but it works. Key considerations: +Yes — Docker is optional but supported. Recommended: run the setup script: + +```bash +./docker-setup.sh +``` + +It builds the image, runs onboarding + login, and starts Docker Compose. For manual steps and sandbox notes, see `docs/docker.md`. + +Key considerations: - **WhatsApp login:** QR code works in terminal — no display needed. - **Persistence:** Mount `~/.clawdbot/` and your workspace as volumes. @@ -219,7 +229,7 @@ pnpm clawdbot gateway bash /app/start.sh ``` -Docker support is on the roadmap — PRs welcome! +For more detail, see `docs/docker.md`. ### Can I run Clawdbot headless on a VPS? @@ -299,7 +309,7 @@ See [Groups](https://docs.clawd.bot/groups) for details. ### How much context can Clawdbot handle? -Claude Opus has a 200k token context window, and Clawdbot uses **autocompaction** — older conversation gets summarized to stay under the limit. +Context window depends on the model. Clawdbot uses **autocompaction** — older conversation gets summarized to stay under the limit. Practical tips: - Keep `AGENTS.md` focused, not bloated. @@ -366,7 +376,7 @@ If you send an image but your Clawd doesn't "see" it, check these: Not all models support images! Check `agent.model` in your config: -- ✅ Vision: `claude-opus-4-5`, `claude-sonnet-4-5`, `claude-haiku-4-5`, `gpt-5.2`, `gpt-4o`, `gemini-pro` +- ✅ Vision (examples): `anthropic/claude-opus-4-5`, `anthropic/claude-sonnet-4-5`, `anthropic/claude-haiku-4-5`, `openai/gpt-5.2`, `openai/gpt-4o`, `google/gemini-3-pro-preview`, `google/gemini-3-flash-preview` - ❌ No vision: Most local LLMs (Llama, Mistral), older models, text-only configs **2. Is media being downloaded?** @@ -487,24 +497,16 @@ Headless/system services are not configured out of the box. The gateway runs under a supervisor that auto-restarts it. You need to stop the supervisor, not just kill the process. -**macOS (launchd)** +**macOS (Clawdbot.app)** + +- Quit the menu bar app to stop the gateway. +- For debugging, restart via the app (or `scripts/restart-mac.sh` when working in the repo). +- To inspect launchd state: `launchctl print gui/$UID | grep clawdbot` + +**macOS (CLI launchd service, if installed)** ```bash -# Check if running -launchctl list | grep clawdbot - -# Stop (disable does NOT stop a running job) clawdbot gateway stop - -# Stop and disable -launchctl disable gui/$UID/com.clawdbot.gateway -launchctl bootout gui/$UID/com.clawdbot.gateway - -# Re-enable later -launchctl enable gui/$UID/com.clawdbot.gateway -launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.clawdbot.gateway.plist - -# Or just restart clawdbot gateway restart ``` @@ -536,8 +538,11 @@ pm2 delete clawdbot launchctl disable gui/$UID/com.clawdbot.gateway launchctl bootout gui/$UID/com.clawdbot.gateway 2>/dev/null -# Linux: stop systemd service -sudo systemctl disable --now clawdbot +# Linux: stop systemd user service +systemctl --user disable --now clawdbot-gateway.service + +# Linux (system-wide unit, if installed) +sudo systemctl disable --now clawdbot-gateway.service # Kill any remaining processes pkill -f "clawdbot" @@ -560,18 +565,19 @@ Quick reference (send these in chat): | Command | Action | |---------|--------| +| `/help` | Show available commands | | `/status` | Health + session info | | `/new` or `/reset` | Reset the session | -| `/compact` | Compact session context | - -Slash commands are owner-only (gated by `whatsapp.allowFrom` and command authorization on other surfaces). +| `/compact [notes]` | Compact session context | +| `/restart` | Restart Clawdbot | +| `/activation mention\|always` | Group activation (owner-only) | | `/think ` | Set thinking level (off\|minimal\|low\|medium\|high) | | `/verbose on\|off` | Toggle verbose mode | | `/elevated on\|off` | Toggle elevated bash mode (approved senders only) | -| `/activation mention\|always` | Group activation (owner-only) | | `/model ` | Switch AI model (see below) | -| `/queue instant\|batch\|serial` | Message queuing mode | +| `/queue ` | Queue mode (see below) | +Slash commands are owner-only (gated by `whatsapp.allowFrom` and command authorization on other surfaces). Commands are only recognized when the entire message is the command (slash required; no plain-text aliases). Full list + config: https://docs.clawd.bot/slash-commands @@ -619,8 +625,8 @@ If you don't want to use Anthropic directly, you can use alternative providers: ```json5 { agent: { - model: { primary: "openrouter/anthropic/claude-sonnet-4" }, - models: { "openrouter/anthropic/claude-sonnet-4": {} }, + model: { primary: "openrouter/anthropic/claude-sonnet-4-5" }, + models: { "openrouter/anthropic/claude-sonnet-4-5": {} }, env: { OPENROUTER_API_KEY: "sk-or-..." } } } @@ -651,11 +657,8 @@ If you get weird errors after switching models, try `/think off` and `/new` to r ### How do I stop/cancel a running task? -Send `/stop` to immediately abort the current agent run. Other stop words also work: -- `/stop` -- `/abort` -- `/esc` -- `/exit` +Send one of these **as a standalone message** (no slash): `stop`, `abort`, `esc`, `wait`, `exit`. +These are abort triggers, not slash commands. For background processes (like Codex), use: ``` @@ -664,8 +667,10 @@ process action:kill sessionId:XXX You can also configure `routing.queue.mode` to control how new messages interact with running tasks: - `steer` — New messages redirect the current task -- `interrupt` — Kills current run, starts fresh -- `collect` — Queues messages for after +- `followup` — Run messages one at a time +- `collect` — Batch messages, reply once after things settle +- `steer-backlog` — Steer now, process backlog afterward +- `interrupt` — Abort current run, start fresh ### Does Codex CLI use my ChatGPT Pro subscription or API credits? @@ -688,11 +693,13 @@ If you have a ChatGPT subscription, use browser auth to avoid API charges! Use `/queue` to control how messages sent in quick succession are handled: -- **`/queue instant`** — New messages interrupt/steer the current response -- **`/queue batch`** — Messages queue up, processed after current turn -- **`/queue serial`** — One at a time, in order +- **`/queue steer`** — New messages steer the current response +- **`/queue collect`** — Batch messages, reply once after things settle +- **`/queue followup`** — One at a time, in order +- **`/queue steer-backlog`** — Steer now, process backlog afterward +- **`/queue interrupt`** — Abort current run, start fresh -If you tend to send multiple short messages, `/queue instant` feels most natural. +If you tend to send multiple short messages, `/queue steer` feels most natural. ---