docs: update FAQ auth paths + add clawtributor

2026-01-06 20:56:12 +00:00
parent ff5d6d15ba
commit 6f4cd7485f
2 changed files with 54 additions and 47 deletions
--- 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/<agentId>/agent/auth-profiles.json` | Auth profiles (OAuth + API keys) |
+| `~/.clawdbot/agents/<agentId>/agent/auth.json` | Runtime auth cache (managed automatically) |
+| `~/.clawdbot/credentials/` | Provider auth state (e.g. `whatsapp/<accountId>/creds.json`) |
 | `~/.clawdbot/agents/` | Per-agent state (agentDir + sessions) |
 | `~/.clawdbot/agents/<agentId>/sessions/` | Conversation history & state (per agent) |
 | `~/.clawdbot/agents/<agentId>/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 <level>` | 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 <name>` | Switch AI model (see below) |
-| `/queue instant\|batch\|serial` | Message queuing mode |
+| `/queue <mode>` | 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.

 ---