docs: reorganize documentation structure
This commit is contained in:
Peter Steinberger
217
docs/start/clawd.md
Normal file
217
docs/start/clawd.md
Normal file
@@ -0,0 +1,217 @@
|
||||
---
|
||||
summary: "End-to-end guide for running Clawdbot as a personal assistant with safety cautions"
|
||||
read_when:
|
||||
- Onboarding a new assistant instance
|
||||
- Reviewing safety/permission implications
|
||||
---
|
||||
# Building a personal assistant with CLAWDBOT (Clawd-style)
|
||||
|
||||
CLAWDBOT is a WhatsApp + Telegram + Discord gateway for **Pi** agents. This guide is the “personal assistant” setup: one dedicated WhatsApp number that behaves like your always-on agent.
|
||||
|
||||
## ⚠️ Safety first
|
||||
|
||||
You’re putting an agent in a position to:
|
||||
- run commands on your machine (depending on your Pi tool setup)
|
||||
- read/write files in your workspace
|
||||
- send messages back out via WhatsApp/Telegram/Discord
|
||||
|
||||
Start conservative:
|
||||
- Always set `whatsapp.allowFrom` (never run open-to-the-world on your personal Mac).
|
||||
- Use a dedicated WhatsApp number for the assistant.
|
||||
- Heartbeats now default to every 30 minutes. Disable until you trust the setup by setting `agent.heartbeat.every: "0m"`.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Node **22+**
|
||||
- CLAWDBOT available on PATH (recommended during development: from source + global link)
|
||||
- A second phone number (SIM/eSIM/prepaid) for the assistant
|
||||
|
||||
From source (recommended while the npm package is still settling):
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm build
|
||||
pnpm link --global
|
||||
```
|
||||
|
||||
## The two-phone setup (recommended)
|
||||
|
||||
You want this:
|
||||
|
||||
```
|
||||
Your Phone (personal) Second Phone (assistant)
|
||||
┌─────────────────┐ ┌─────────────────┐
|
||||
│ Your WhatsApp │ ──────▶ │ Assistant WA │
|
||||
│ +1-555-YOU │ message │ +1-555-CLAWD │
|
||||
└─────────────────┘ └────────┬────────┘
|
||||
│ linked via QR
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Your Mac │
|
||||
│ (clawdbot) │
|
||||
│ Pi agent │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
If you link your personal WhatsApp to CLAWDBOT, every message to you becomes “agent input”. That’s rarely what you want.
|
||||
|
||||
## 5-minute quick start
|
||||
|
||||
1) Pair WhatsApp Web (shows QR; scan with the assistant phone):
|
||||
|
||||
```bash
|
||||
clawdbot login
|
||||
```
|
||||
|
||||
2) Start the Gateway (leave it running):
|
||||
|
||||
```bash
|
||||
clawdbot gateway --port 18789
|
||||
```
|
||||
|
||||
3) Put a minimal config in `~/.clawdbot/clawdbot.json`:
|
||||
|
||||
```json5
|
||||
{
|
||||
whatsapp: {
|
||||
allowFrom: ["+15555550123"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Now message the assistant number from your allowlisted phone.
|
||||
|
||||
## Give the agent a workspace (AGENTS)
|
||||
|
||||
Clawd reads operating instructions and “memory” from its workspace directory.
|
||||
|
||||
By default, Clawdbot uses `~/clawd` as the agent workspace, and will create it (plus starter `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`) automatically on setup/first agent run. `BOOTSTRAP.md` is only created when the workspace is brand new (it should not come back after you delete it).
|
||||
|
||||
Tip: treat this folder like Clawd’s “memory” and make it a git repo (ideally private) so your `AGENTS.md` + memory files are backed up.
|
||||
|
||||
```bash
|
||||
clawdbot setup
|
||||
```
|
||||
|
||||
Full workspace layout + backup guide: [`docs/agent-workspace.md`](/agent-workspace)
|
||||
|
||||
Optional: choose a different workspace with `agent.workspace` (supports `~`).
|
||||
|
||||
```json5
|
||||
{
|
||||
agent: {
|
||||
workspace: "~/clawd"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If you already ship your own workspace files from a repo, you can disable bootstrap file creation entirely:
|
||||
|
||||
```json5
|
||||
{
|
||||
agent: {
|
||||
skipBootstrap: true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## The config that turns it into “an assistant”
|
||||
|
||||
CLAWDBOT defaults to a good assistant setup, but you’ll usually want to tune:
|
||||
- persona/instructions in `SOUL.md`
|
||||
- thinking defaults (if desired)
|
||||
- heartbeats (once you trust it)
|
||||
|
||||
Example:
|
||||
|
||||
```json5
|
||||
{
|
||||
logging: { level: "info" },
|
||||
agent: {
|
||||
model: "anthropic/claude-opus-4-5",
|
||||
workspace: "~/clawd",
|
||||
thinkingDefault: "high",
|
||||
timeoutSeconds: 1800,
|
||||
// Start with 0; enable later.
|
||||
heartbeat: { every: "0m" }
|
||||
},
|
||||
whatsapp: {
|
||||
allowFrom: ["+15555550123"],
|
||||
groups: {
|
||||
"*": { requireMention: true }
|
||||
}
|
||||
},
|
||||
routing: {
|
||||
groupChat: {
|
||||
mentionPatterns: ["@clawd", "clawd"]
|
||||
}
|
||||
},
|
||||
session: {
|
||||
scope: "per-sender",
|
||||
resetTriggers: ["/new", "/reset"],
|
||||
idleMinutes: 10080
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Sessions and memory
|
||||
|
||||
- Session files: `~/.clawdbot/agents/<agentId>/sessions/{{SessionId}}.jsonl`
|
||||
- Session metadata (token usage, last route, etc): `~/.clawdbot/agents/<agentId>/sessions/sessions.json` (legacy: `~/.clawdbot/sessions/sessions.json`)
|
||||
- `/new` or `/reset` starts a fresh session for that chat (configurable via `resetTriggers`). If sent alone, the agent replies with a short hello to confirm the reset.
|
||||
- `/compact [instructions]` compacts the session context and reports the remaining context budget.
|
||||
|
||||
## Heartbeats (proactive mode)
|
||||
|
||||
By default, CLAWDBOT runs a heartbeat every 30 minutes with the prompt:
|
||||
`Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.`
|
||||
Set `agent.heartbeat.every: "0m"` to disable.
|
||||
|
||||
- If the agent replies with `HEARTBEAT_OK` (optionally with short padding; see `agent.heartbeat.ackMaxChars`), CLAWDBOT suppresses outbound delivery for that heartbeat.
|
||||
- Heartbeats run full agent turns — shorter intervals burn more tokens.
|
||||
|
||||
```json5
|
||||
{
|
||||
agent: {
|
||||
heartbeat: { every: "30m" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Media in and out
|
||||
|
||||
Inbound attachments (images/audio/docs) can be surfaced to your command via templates:
|
||||
- `{{MediaPath}}` (local temp file path)
|
||||
- `{{MediaUrl}}` (pseudo-URL)
|
||||
- `{{Transcript}}` (if audio transcription is enabled)
|
||||
|
||||
Outbound attachments from the agent: include `MEDIA:<path-or-url>` on its own line (no spaces). Example:
|
||||
|
||||
```
|
||||
Here’s the screenshot.
|
||||
MEDIA:/tmp/screenshot.png
|
||||
```
|
||||
|
||||
CLAWDBOT extracts these and sends them as media alongside the text.
|
||||
|
||||
## Operations checklist
|
||||
|
||||
```bash
|
||||
clawdbot status # local status (creds, sessions, queued events)
|
||||
clawdbot status --deep # also probes the running Gateway (WA connect + Telegram)
|
||||
clawdbot health --json # gateway health snapshot (WS)
|
||||
```
|
||||
|
||||
Logs live under `/tmp/clawdbot/` (default: `clawdbot-YYYY-MM-DD.log`).
|
||||
|
||||
## Next steps
|
||||
|
||||
- WebChat: [WebChat](/webchat)
|
||||
- Gateway ops: [Gateway runbook](/gateway)
|
||||
- Cron + wakeups: [Cron jobs](/cron-jobs)
|
||||
- macOS menu bar companion: [Clawdbot macOS app](/macos)
|
||||
- iOS node app: [iOS app](/ios)
|
||||
- Android node app: [Android app](/android)
|
||||
- Windows status: [Windows app](/windows)
|
||||
- Linux status: [Linux app](/linux)
|
||||
- Security: [Security](/security)
|
||||
713
docs/start/faq.md
Normal file
713
docs/start/faq.md
Normal file
@@ -0,0 +1,713 @@
|
||||
---
|
||||
summary: "Frequently asked questions about Clawdbot setup, configuration, and usage"
|
||||
---
|
||||
# FAQ 🦞
|
||||
|
||||
Common questions from the community. For detailed configuration, see [Configuration](/configuration).
|
||||
|
||||
## Installation & Setup
|
||||
|
||||
### Where does Clawdbot store its data?
|
||||
|
||||
Everything lives under `~/.clawdbot/`:
|
||||
|
||||
| Path | Purpose |
|
||||
|------|---------|
|
||||
| `~/.clawdbot/clawdbot.json` | Main config (JSON5) |
|
||||
| `~/.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?
|
||||
|
||||
**macOS and Linux** are the primary targets. Anywhere Node.js 22+ runs should work in theory.
|
||||
|
||||
- **macOS** — Fully supported, most tested
|
||||
- **Linux** — Works great, common for VPS/server deployments
|
||||
- **Windows** — Should work but largely untested! You're in pioneer territory 🤠
|
||||
|
||||
Some features are platform-specific:
|
||||
- **iMessage** — macOS only (uses `imsg` CLI)
|
||||
- **Clawdbot.app** — macOS native app (optional, gateway works without it)
|
||||
|
||||
### What are the minimum system requirements?
|
||||
|
||||
**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
|
||||
- **Disk:** ~500MB for Clawdbot + deps, plus space for logs/media
|
||||
|
||||
The gateway is just shuffling messages around. A Raspberry Pi 4 can run it. For the CLI, prefer the Node runtime (most stable):
|
||||
|
||||
```bash
|
||||
clawdbot gateway
|
||||
```
|
||||
|
||||
### How do I install on Linux without Homebrew?
|
||||
|
||||
Build CLIs from source! Example for `gogcli`:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/steipete/gogcli.git
|
||||
cd gogcli
|
||||
make
|
||||
sudo mv bin/gog /usr/local/bin/
|
||||
```
|
||||
|
||||
Most of Peter's tools are Go binaries — clone, build, move to PATH. No brew needed.
|
||||
|
||||
### I'm getting "unauthorized" errors on health check
|
||||
|
||||
You need a config file. Run the onboarding wizard:
|
||||
|
||||
```bash
|
||||
pnpm clawdbot onboard
|
||||
```
|
||||
|
||||
This creates `~/.clawdbot/clawdbot.json` with your API keys, workspace path, and owner phone number.
|
||||
|
||||
### How do I start fresh?
|
||||
|
||||
```bash
|
||||
# Backup first (optional)
|
||||
cp -r ~/.clawdbot ~/.clawdbot-backup
|
||||
|
||||
# Remove config and credentials
|
||||
trash ~/.clawdbot
|
||||
|
||||
# Re-run onboarding
|
||||
pnpm clawdbot onboard
|
||||
pnpm clawdbot login
|
||||
```
|
||||
|
||||
### Something's broken — how do I diagnose?
|
||||
|
||||
Run the doctor:
|
||||
|
||||
```bash
|
||||
pnpm clawdbot doctor
|
||||
```
|
||||
|
||||
It checks your config, skills status, and gateway health. It can also restart the gateway daemon if needed.
|
||||
|
||||
### Terminal onboarding vs macOS app?
|
||||
|
||||
**Use terminal onboarding** (`pnpm clawdbot onboard`) — it's more stable right now.
|
||||
|
||||
The macOS app onboarding is still being polished and can have quirks (e.g., WhatsApp 515 errors, OAuth issues).
|
||||
|
||||
---
|
||||
|
||||
## Authentication
|
||||
|
||||
### OAuth vs API key — what's the difference?
|
||||
|
||||
- **OAuth** — Uses your **subscription** (Anthropic Claude Pro/Max or OpenAI ChatGPT/Codex). No per‑token charges. ✅ Recommended!
|
||||
- **API key** — Pay‑per‑token via the provider’s API billing. Can get expensive fast.
|
||||
|
||||
They're **separate billing**! An API key does NOT use your subscription.
|
||||
|
||||
**For OAuth:** During onboarding, pick **Anthropic OAuth** or **OpenAI Codex OAuth**, log in, paste the code/URL when prompted. Or just run:
|
||||
|
||||
```bash
|
||||
pnpm clawdbot login
|
||||
```
|
||||
|
||||
**If OAuth fails** (headless/container): Do OAuth on a normal machine, then copy `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json` (and `auth.json` if present) to your server. Legacy installs can still import `~/.clawdbot/credentials/oauth.json` on first use.
|
||||
|
||||
### How are env vars loaded?
|
||||
|
||||
CLAWDBOT reads env vars from the parent process (shell, launchd/systemd, CI, etc.). It also loads `.env` files:
|
||||
- `.env` in the current working directory
|
||||
- global fallback: `~/.clawdbot/.env` (aka `$CLAWDBOT_STATE_DIR/.env`)
|
||||
|
||||
Neither `.env` file overrides existing env vars.
|
||||
|
||||
Optional convenience: import missing expected keys from your login shell env (sources your shell profile):
|
||||
|
||||
```json5
|
||||
{
|
||||
env: { shellEnv: { enabled: true, timeoutMs: 15000 } }
|
||||
}
|
||||
```
|
||||
|
||||
Or set `CLAWDBOT_LOAD_SHELL_ENV=1` (timeout: `CLAWDBOT_SHELL_ENV_TIMEOUT_MS=15000`).
|
||||
|
||||
### Does enterprise OAuth work?
|
||||
|
||||
**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 (Anthropic or OpenAI) and use it via `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`.
|
||||
|
||||
### OAuth callback not working (containers/headless)?
|
||||
|
||||
OAuth needs the callback to reach the machine running the CLI. Options:
|
||||
|
||||
1. **Copy auth manually** — Run OAuth on your laptop, copy `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json` (and `auth.json` if present) to the container. Legacy flow: copy `~/.clawdbot/credentials/oauth.json` to trigger import.
|
||||
2. **SSH tunnel** — `ssh -L 18789:localhost:18789 user@server`
|
||||
3. **Tailscale** — Put both machines on your tailnet.
|
||||
|
||||
---
|
||||
|
||||
## Migration & Deployment
|
||||
|
||||
### How do I migrate Clawdbot to a new machine (or VPS)?
|
||||
|
||||
1. **Backup on old machine:**
|
||||
```bash
|
||||
# Config + credentials + sessions
|
||||
tar -czvf clawdbot-backup.tar.gz ~/.clawdbot
|
||||
|
||||
# Your workspace (memories, AGENTS.md, etc.)
|
||||
tar -czvf workspace-backup.tar.gz ~/path/to/workspace
|
||||
```
|
||||
|
||||
2. **Copy to new machine:**
|
||||
```bash
|
||||
scp clawdbot-backup.tar.gz workspace-backup.tar.gz user@new-machine:~/
|
||||
```
|
||||
|
||||
3. **Restore on new machine:**
|
||||
```bash
|
||||
cd ~
|
||||
tar -xzvf clawdbot-backup.tar.gz
|
||||
tar -xzvf workspace-backup.tar.gz
|
||||
```
|
||||
|
||||
4. **Install Clawdbot** (Node 22+, pnpm, clone repo, `pnpm install && pnpm build`)
|
||||
|
||||
5. **Start gateway:**
|
||||
```bash
|
||||
clawdbot gateway
|
||||
```
|
||||
|
||||
**Note:** WhatsApp may notice the IP change and require re-authentication. If so, run `pnpm clawdbot login` again. Stop the old instance before starting the new one to avoid conflicts.
|
||||
|
||||
### Can I run Clawdbot in Docker?
|
||||
|
||||
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.
|
||||
- **pnpm doesn't persist:** Global npm installs don't survive container restarts. Install pnpm in your startup script.
|
||||
- **Browser automation:** Optional. If needed, install headless Chrome + Playwright deps, or connect to a remote browser via `--remote-debugging-port`.
|
||||
|
||||
**Volume mappings (e.g., Unraid):**
|
||||
```
|
||||
/mnt/user/appdata/clawdbot/config → /root/.clawdbot
|
||||
/mnt/user/appdata/clawdbot/workspace → /root/clawd
|
||||
/mnt/user/appdata/clawdbot/app → /app
|
||||
```
|
||||
|
||||
**Startup script (`start.sh`):**
|
||||
```bash
|
||||
#!/bin/bash
|
||||
npm install -g pnpm
|
||||
cd /app
|
||||
clawdbot gateway
|
||||
```
|
||||
|
||||
**Container command:**
|
||||
```
|
||||
bash /app/start.sh
|
||||
```
|
||||
|
||||
For more detail, see `docs/docker.md`.
|
||||
|
||||
### Can I run Clawdbot headless on a VPS?
|
||||
|
||||
Yes! The terminal QR code login works fine over SSH. For long-running operation:
|
||||
|
||||
- Use `pm2`, `systemd`, or a `launchd` plist to keep the gateway running.
|
||||
- Consider Tailscale for secure remote access.
|
||||
|
||||
### I'm seeing `InvalidPnpmLockfile: failed to migrate lockfile: 'pnpm-lock.yaml'`
|
||||
|
||||
This can be ignored. This is simply a package manager warning when using PNPM and BUN.
|
||||
|
||||
It often shows up when switching between `pnpm install` and `bun install`. If installs/build/tests work, you can safely ignore it.
|
||||
|
||||
### bun binary vs Node runtime?
|
||||
|
||||
Clawdbot can run as:
|
||||
- **bun binary (macOS app)** — Single executable, easy distribution, auto-restarts via launchd
|
||||
- **Node runtime** (`clawdbot gateway`) — More stable for WhatsApp
|
||||
|
||||
If you see WebSocket errors like `ws.WebSocket 'upgrade' event is not implemented`, use Node instead of the bun binary. Bun's WebSocket implementation has edge cases that can break WhatsApp (Baileys) and can corrupt memory on reconnect. Baileys: https://github.com/WhiskeySockets/Baileys · Bun issue: https://github.com/oven-sh/bun/issues/5951
|
||||
|
||||
**For stability:** Use launchd (macOS) or the Clawdbot.app — they handle process supervision (auto-restart on crash).
|
||||
|
||||
**For debugging:** Use `pnpm gateway:watch` for live reload during development.
|
||||
|
||||
### WhatsApp keeps disconnecting / crashing (macOS app)
|
||||
|
||||
This is often the bun WebSocket issue. Workaround:
|
||||
|
||||
1. Run gateway with Node instead:
|
||||
```bash
|
||||
pnpm gateway:watch
|
||||
```
|
||||
2. In **Clawdbot.app → Settings → Debug**, check **"External gateway"**
|
||||
3. The app now connects to your Node gateway instead of spawning bun
|
||||
|
||||
This is the most stable setup until bun's WebSocket handling improves.
|
||||
|
||||
---
|
||||
|
||||
## Multi-Instance & Contexts
|
||||
|
||||
### Can I run multiple Clawds (separate instances)?
|
||||
|
||||
The intended design is **one Clawd, one identity**. Rather than running separate instances:
|
||||
|
||||
- **Add skills** — Give your Clawd multiple capabilities (business + fitness + personal).
|
||||
- **Use context switching** — "Hey Clawd, let's talk about fitness" within the same conversation.
|
||||
- **Use groups for separation** — Create Telegram/Discord groups for different contexts; each group gets its own session.
|
||||
|
||||
Why? A unified assistant knows your whole context. Your fitness coach knows when you've had a stressful work week.
|
||||
|
||||
If you truly need full separation (different users, privacy boundaries), you'd need:
|
||||
- Separate config + state directories (`CLAWDBOT_CONFIG_PATH`, `CLAWDBOT_STATE_DIR`)
|
||||
- Separate agent workspaces (`agent.workspace`)
|
||||
- Separate gateway ports (`gateway.port` / `--port`)
|
||||
- Separate phone numbers for WhatsApp (one number = one account)
|
||||
|
||||
### Can I have separate "threads" for different topics?
|
||||
|
||||
Currently, sessions are per-chat:
|
||||
- Each WhatsApp/Telegram DM = one session
|
||||
- Each group = separate session
|
||||
|
||||
**Workaround:** Create multiple groups (even just you + the bot) for different contexts. Each group maintains its own session.
|
||||
|
||||
Feature request? Open a [GitHub discussion](https://github.com/clawdbot/clawdbot/discussions)!
|
||||
|
||||
### How do groups work?
|
||||
|
||||
Groups get separate sessions automatically. By default, the bot requires a **mention** to respond in groups.
|
||||
|
||||
Per-group activation can be changed by the owner:
|
||||
- `/activation mention` — respond only when mentioned (default)
|
||||
- `/activation always` — respond to all messages
|
||||
|
||||
See [Groups](/groups) for details.
|
||||
|
||||
---
|
||||
|
||||
## Context & Memory
|
||||
|
||||
### How much context can Clawdbot handle?
|
||||
|
||||
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.
|
||||
- Use `/compact` to shrink older context or `/new` to reset when it gets stale.
|
||||
- For large memory/notes collections, use search tools like `qmd` rather than loading everything.
|
||||
|
||||
### Where are my memory files?
|
||||
|
||||
In your workspace directory (configured in `agent.workspace`, default `~/clawd`). Look for:
|
||||
- `memory/` — daily memory files
|
||||
- `AGENTS.md` — agent instructions
|
||||
- `TOOLS.md` — tool-specific notes
|
||||
|
||||
Check your config:
|
||||
```bash
|
||||
cat ~/.clawdbot/clawdbot.json | grep workspace
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Platforms
|
||||
|
||||
### Which platforms does Clawdbot support?
|
||||
|
||||
- **WhatsApp** — Primary. Uses WhatsApp Web protocol.
|
||||
- **Telegram** — Via Bot API (grammY).
|
||||
- **Discord** — Bot integration.
|
||||
- **iMessage** — Via `imsg` CLI (macOS only).
|
||||
- **Signal** — Via `signal-cli` (see [Signal](/signal)).
|
||||
- **WebChat** — Browser-based chat UI.
|
||||
|
||||
### Discord: Bot works in channels but not DMs?
|
||||
|
||||
Discord has **separate allowlists** for channels vs DMs:
|
||||
|
||||
- `discord.guilds.*.users` — controls who can talk in server channels
|
||||
- `discord.dm.allowFrom` — controls who can DM the bot
|
||||
|
||||
If channels work but DMs don't, add `discord.dm.allowFrom` to your config:
|
||||
|
||||
```json
|
||||
{
|
||||
"discord": {
|
||||
"dm": {
|
||||
"enabled": true,
|
||||
"allowFrom": ["YOUR_DISCORD_USER_ID"]
|
||||
},
|
||||
"guilds": {
|
||||
"your-server": {
|
||||
"users": ["YOUR_DISCORD_USER_ID"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Find your user ID: Discord Settings → Advanced → Developer Mode → right-click yourself → Copy User ID.
|
||||
|
||||
### Images/media not being understood by the agent?
|
||||
|
||||
If you send an image but your Clawd doesn't "see" it, check these:
|
||||
|
||||
**1. Is your model vision-capable?**
|
||||
|
||||
Not all models support images! Check `agent.model` in your config:
|
||||
|
||||
- ✅ 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?**
|
||||
|
||||
```bash
|
||||
ls -la ~/.clawdbot/media/inbound/
|
||||
grep -i "media\|download" /tmp/clawdbot/clawdbot-*.log | tail -20
|
||||
```
|
||||
|
||||
**3. Is `agent.mediaMaxMb` too low?**
|
||||
|
||||
Default is 5MB. Large images get resized, but if the limit is set very low, media might be skipped.
|
||||
|
||||
**4. Does the agent see `[media attached: ...]`?**
|
||||
|
||||
If this line isn't in the agent's input, the gateway didn't pass the media. Check logs for errors.
|
||||
|
||||
**5. For PDFs, audio, video, and exotic files:**
|
||||
|
||||
Use the [summarize](https://summarize.sh) skill to extract and condense content from files that can't be passed directly to vision.
|
||||
|
||||
### Can I use multiple platforms at once?
|
||||
|
||||
Yes! One Clawdbot gateway can connect to WhatsApp, Telegram, Discord, and more simultaneously. Each platform maintains its own sessions.
|
||||
|
||||
### WhatsApp: Can I use two numbers?
|
||||
|
||||
One WhatsApp account = one phone number = one gateway connection. For a second number, you'd need a second gateway instance with a separate config directory.
|
||||
|
||||
---
|
||||
|
||||
## Skills & Tools
|
||||
|
||||
### How do I add new skills?
|
||||
|
||||
Skills are auto-discovered from your workspace's `skills/` folder. After adding new skills:
|
||||
|
||||
1. Send `/reset` (or `/new`) in chat to start a new session
|
||||
2. The new skills will be available
|
||||
|
||||
No gateway restart needed!
|
||||
|
||||
### How do I run commands on other machines?
|
||||
|
||||
Use **[Tailscale](https://tailscale.com/)** to create a secure network between your machines:
|
||||
|
||||
1. Install Tailscale on all machines (it's separate from Clawdbot — set it up yourself)
|
||||
2. Each gets a stable IP (like `100.x.x.x`)
|
||||
3. SSH just works: `ssh user@100.x.x.x "command"`
|
||||
|
||||
Clawdbot can use Tailscale when you set `bridge.bind: "tailnet"` in your config — it auto-detects your Tailscale IP.
|
||||
|
||||
For deeper integration, look into **Clawdbot nodes** — pair remote machines with your gateway for camera/screen/automation access.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Build errors (TypeScript)
|
||||
|
||||
If you hit build errors on `main`:
|
||||
|
||||
1. Pull latest: `git pull origin main && pnpm install`
|
||||
2. Try `pnpm clawdbot doctor`
|
||||
3. Check [GitHub issues](https://github.com/clawdbot/clawdbot/issues) or Discord
|
||||
4. Temporary workaround: checkout an older commit
|
||||
|
||||
### WhatsApp logged me out
|
||||
|
||||
WhatsApp sometimes disconnects on IP changes or after updates. Re-authenticate:
|
||||
|
||||
```bash
|
||||
pnpm clawdbot login
|
||||
```
|
||||
|
||||
Scan the QR code and you're back.
|
||||
|
||||
### Gateway won't start
|
||||
|
||||
Check logs:
|
||||
```bash
|
||||
cat /tmp/clawdbot/clawdbot-$(date +%Y-%m-%d).log
|
||||
```
|
||||
|
||||
Common issues:
|
||||
- Port already in use (change with `--port`)
|
||||
- Missing API keys in config
|
||||
- Invalid config syntax (remember it's JSON5, but still check for errors)
|
||||
- **Tailscale serve + bind conflict:** If using `tailscale.mode: "serve"`, you must set `gateway.bind: "loopback"` (not `"lan"`). Tailscale serve proxies traffic itself.
|
||||
|
||||
**Debug mode** — use watch for live reload:
|
||||
```bash
|
||||
pnpm gateway:watch
|
||||
```
|
||||
|
||||
**Pro tip:** Use Codex to debug:
|
||||
```bash
|
||||
cd ~/path/to/clawdbot
|
||||
codex --full-auto "debug why clawdbot gateway won't start"
|
||||
```
|
||||
|
||||
### Gateway stops after I log out (Linux)
|
||||
|
||||
Linux installs use a systemd **user** service. By default, systemd stops user
|
||||
services on logout/idle, which kills the Gateway.
|
||||
|
||||
Onboarding attempts to enable lingering; if it’s still off, run:
|
||||
```bash
|
||||
sudo loginctl enable-linger $USER
|
||||
```
|
||||
|
||||
**macOS/Windows**
|
||||
|
||||
Gateway daemons run in the user session by default. Keep the user logged in.
|
||||
Headless/system services are not configured out of the box.
|
||||
|
||||
### Processes keep restarting after I kill them
|
||||
|
||||
The gateway runs under a supervisor that auto-restarts it. You need to stop the supervisor, not just kill the process.
|
||||
|
||||
**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
|
||||
clawdbot gateway stop
|
||||
clawdbot gateway restart
|
||||
```
|
||||
|
||||
**Linux (systemd)**
|
||||
|
||||
```bash
|
||||
# Check if running
|
||||
systemctl list-units | grep -i clawdbot
|
||||
|
||||
# Stop and disable
|
||||
clawdbot gateway stop
|
||||
systemctl --user disable --now clawdbot-gateway.service
|
||||
|
||||
# Or just restart
|
||||
clawdbot gateway restart
|
||||
```
|
||||
|
||||
**pm2 (if used)**
|
||||
|
||||
```bash
|
||||
pm2 list
|
||||
pm2 delete clawdbot
|
||||
```
|
||||
|
||||
### Clean uninstall (start fresh)
|
||||
|
||||
```bash
|
||||
# macOS: stop launchd service
|
||||
launchctl disable gui/$UID/com.clawdbot.gateway
|
||||
launchctl bootout gui/$UID/com.clawdbot.gateway 2>/dev/null
|
||||
|
||||
# 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"
|
||||
|
||||
# Remove data
|
||||
trash ~/.clawdbot
|
||||
|
||||
# Remove repo and re-clone (adjust path if you cloned elsewhere)
|
||||
trash ~/Projects/clawdbot
|
||||
git clone https://github.com/clawdbot/clawdbot.git ~/Projects/clawdbot
|
||||
cd ~/Projects/clawdbot && pnpm install && pnpm build
|
||||
pnpm clawdbot onboard
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Chat Commands
|
||||
|
||||
Quick reference (send these in chat):
|
||||
|
||||
| Command | Action |
|
||||
|---------|--------|
|
||||
| `/help` | Show available commands |
|
||||
| `/status` | Health + session info |
|
||||
| `/stop` | Abort the current run |
|
||||
| `/new` or `/reset` | Reset the session |
|
||||
| `/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) |
|
||||
| `/model <name>` | Switch AI model (see below) |
|
||||
| `/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: [Slash commands](/slash-commands)
|
||||
|
||||
### How do I switch models on the fly?
|
||||
|
||||
Use `/model` to switch without restarting:
|
||||
|
||||
```
|
||||
/model sonnet
|
||||
/model haiku
|
||||
/model opus
|
||||
/model gpt
|
||||
/model gpt-mini
|
||||
/model gemini
|
||||
/model gemini-flash
|
||||
```
|
||||
|
||||
List available models with `/model`, `/model list`, or `/model status`.
|
||||
|
||||
Clawdbot ships a few default model shorthands (you can override them in config):
|
||||
`opus`, `sonnet`, `gpt`, `gpt-mini`, `gemini`, `gemini-flash`.
|
||||
|
||||
**Setup:** Configure models and aliases in `clawdbot.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"agent": {
|
||||
"model": { "primary": "anthropic/claude-opus-4-5" },
|
||||
"models": {
|
||||
"anthropic/claude-opus-4-5": { "alias": "opus" },
|
||||
"anthropic/claude-sonnet-4-5": { "alias": "sonnet" },
|
||||
"anthropic/claude-haiku-4-5": { "alias": "haiku" }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Tip:** `/model` is processed at the gateway level — it works even if you're rate-limited (429) on the current model!
|
||||
|
||||
### Alternative providers (OpenRouter, Z.AI)?
|
||||
|
||||
If you don't want to use Anthropic directly, you can use alternative providers:
|
||||
|
||||
**OpenRouter** (pay-per-token, many models):
|
||||
```json5
|
||||
{
|
||||
agent: {
|
||||
model: { primary: "openrouter/anthropic/claude-sonnet-4-5" },
|
||||
models: { "openrouter/anthropic/claude-sonnet-4-5": {} },
|
||||
env: { OPENROUTER_API_KEY: "sk-or-..." }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Z.AI** (flat-rate plans, GLM models):
|
||||
```json5
|
||||
{
|
||||
agent: {
|
||||
model: { primary: "zai/glm-4.7" },
|
||||
models: { "zai/glm-4.7": {} },
|
||||
env: { ZAI_API_KEY: "..." }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Important:** Always use the latest Claude models (4.5 series). Don't use older 3.x models — they're deprecated and less capable. Check [OpenRouter models](https://openrouter.ai/models?q=claude) for exact IDs.
|
||||
|
||||
### Model + thinking mode issues?
|
||||
|
||||
Some models don't support extended thinking well:
|
||||
|
||||
- **Gemini Flash + thinking:** Can cause "Corrupted thought signature" errors. Fix: `/think off`
|
||||
- **Claude Opus + thinking off:** Opus may "think out loud" anyway. Better to use `/think low` than `off`.
|
||||
- **Local LLMs:** Most don't support the thinking/reasoning separation. Set `reasoning: false` in your model config.
|
||||
|
||||
If you get weird errors after switching models, try `/think off` and `/new` to reset.
|
||||
|
||||
### How do I stop/cancel a running task?
|
||||
|
||||
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:
|
||||
```
|
||||
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
|
||||
- `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?
|
||||
|
||||
**Both are supported!** Codex CLI can auth via:
|
||||
|
||||
1. **Browser/Device OAuth** → Uses your ChatGPT Pro/Plus subscription (no per-token cost)
|
||||
```bash
|
||||
codex login --device-auth
|
||||
# Opens browser, log in with your ChatGPT account
|
||||
```
|
||||
|
||||
2. **API key** → Pay-per-token via OpenAI API billing
|
||||
```bash
|
||||
export OPENAI_API_KEY="sk-..."
|
||||
```
|
||||
|
||||
If you have a ChatGPT subscription, use browser auth to avoid API charges!
|
||||
|
||||
### How do rapid-fire messages work?
|
||||
|
||||
Use `/queue` to control how messages sent in quick succession are handled:
|
||||
|
||||
- **`/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 steer` feels most natural.
|
||||
|
||||
---
|
||||
|
||||
*Still stuck? Ask in [Discord](https://discord.gg/qkhbAGHRBT) or open a [GitHub discussion](https://github.com/clawdbot/clawdbot/discussions).* 🦞
|
||||
142
docs/start/getting-started.md
Normal file
142
docs/start/getting-started.md
Normal file
@@ -0,0 +1,142 @@
|
||||
---
|
||||
summary: "Beginner guide: from repo checkout to first message (wizard, auth, providers, pairing)"
|
||||
read_when:
|
||||
- First time setup from zero
|
||||
- You want the fastest path from checkout → onboarding → first message
|
||||
---
|
||||
|
||||
# Getting Started
|
||||
|
||||
Goal: go from **zero** → **first working chat** (with sane defaults) as quickly as possible.
|
||||
|
||||
Recommended path: use the **CLI onboarding wizard** (`clawdbot onboard`). It sets up:
|
||||
- model/auth (OAuth recommended)
|
||||
- gateway settings
|
||||
- providers (WhatsApp/Telegram/Discord/…)
|
||||
- pairing defaults (secure DMs)
|
||||
- workspace bootstrap + skills
|
||||
- optional background daemon
|
||||
|
||||
If you want the deeper reference pages, jump to: [Wizard](/wizard), [Setup](/setup), [Pairing](/pairing), [Security](/security).
|
||||
|
||||
## 0) Prereqs
|
||||
|
||||
- Node `>=22`
|
||||
- `bun` (preferred) or `pnpm`
|
||||
- Git
|
||||
|
||||
macOS: if you plan to build the apps, install Xcode / CLT. For the CLI + gateway only, Node is enough.
|
||||
|
||||
## 1) Check out from source
|
||||
|
||||
```bash
|
||||
git clone https://github.com/clawdbot/clawdbot.git
|
||||
cd clawdbot
|
||||
bun install
|
||||
```
|
||||
|
||||
Note: `pnpm` is also supported:
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
## 2) Build the Control UI (recommended)
|
||||
|
||||
The Gateway serves the browser dashboard (Control UI) when assets exist.
|
||||
|
||||
```bash
|
||||
bun run ui:install
|
||||
bun run ui:build
|
||||
bun run build
|
||||
```
|
||||
|
||||
If you skip UI build, the gateway still works — you just won’t get the dashboard.
|
||||
|
||||
## 3) Run the onboarding wizard
|
||||
|
||||
```bash
|
||||
bun run clawdbot onboard
|
||||
```
|
||||
|
||||
What you’ll choose:
|
||||
- **Local vs Remote** gateway
|
||||
- **Auth**: Anthropic OAuth or OpenAI OAuth (recommended), API key (optional), or skip for now
|
||||
- **Providers**: WhatsApp QR login, bot tokens, etc.
|
||||
- **Daemon**: optional background install (launchd/systemd/Task Scheduler)
|
||||
- **Runtime**: Node (recommended; required for WhatsApp) or Bun (faster, but incompatible with WhatsApp)
|
||||
|
||||
Wizard doc: [Wizard](/wizard)
|
||||
|
||||
### Auth: where it lives (important)
|
||||
|
||||
- OAuth credentials (legacy import): `~/.clawdbot/credentials/oauth.json`
|
||||
- Auth profiles (OAuth + API keys): `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`
|
||||
|
||||
Headless/server tip: do OAuth on a normal machine first, then copy `oauth.json` to the gateway host.
|
||||
|
||||
## 4) Start the Gateway
|
||||
|
||||
If the wizard didn’t start it for you:
|
||||
|
||||
```bash
|
||||
# If you installed the CLI (npm/pnpm link --global):
|
||||
clawdbot gateway --port 18789 --verbose
|
||||
# From this repo:
|
||||
node dist/entry.js gateway --port 18789 --verbose
|
||||
```
|
||||
|
||||
Dashboard (local loopback): `http://127.0.0.1:18789/`
|
||||
|
||||
⚠️ **WhatsApp + Bun warning:** Baileys (WhatsApp Web library) uses a WebSocket
|
||||
path that is currently incompatible with Bun and can cause memory corruption on
|
||||
reconnect. If you use WhatsApp, run the Gateway with **Node** until this is
|
||||
resolved. Baileys: https://github.com/WhiskeySockets/Baileys · Bun issue:
|
||||
https://github.com/oven-sh/bun/issues/5951
|
||||
## 5) Pair + connect your first chat surface
|
||||
|
||||
### WhatsApp (QR login)
|
||||
|
||||
```bash
|
||||
bun run clawdbot login
|
||||
```
|
||||
|
||||
Scan via WhatsApp → Settings → Linked Devices.
|
||||
|
||||
WhatsApp doc: [WhatsApp](/whatsapp)
|
||||
|
||||
### Telegram / Discord / others
|
||||
|
||||
The wizard can write tokens/config for you. If you prefer manual config, start with:
|
||||
- Telegram: [Telegram](/telegram)
|
||||
- Discord: [Discord](/discord)
|
||||
|
||||
## 6) DM safety (pairing approvals)
|
||||
|
||||
Default posture: unknown DMs get a short code and messages are not processed until approved.
|
||||
|
||||
Approve:
|
||||
|
||||
```bash
|
||||
bun run clawdbot pairing list --provider telegram
|
||||
bun run clawdbot pairing approve --provider telegram <CODE>
|
||||
```
|
||||
|
||||
Pairing doc: [Pairing](/pairing)
|
||||
|
||||
## 7) Verify end-to-end
|
||||
|
||||
In a new terminal:
|
||||
|
||||
```bash
|
||||
bun run clawdbot health
|
||||
bun run clawdbot send --to +15555550123 --message "Hello from Clawdbot"
|
||||
```
|
||||
|
||||
If `health` shows “no auth configured”, go back to the wizard and set OAuth/key auth — the agent won’t be able to respond without it.
|
||||
|
||||
## Next steps (optional, but great)
|
||||
|
||||
- macOS menu bar app + voice wake: [macOS app](/macos)
|
||||
- iOS/Android nodes (Canvas/camera/voice): [Nodes](/nodes)
|
||||
- Remote access (SSH tunnel / Tailscale Serve): [Remote access](/remote) and [Tailscale](/tailscale)
|
||||
164
docs/start/hubs.md
Normal file
164
docs/start/hubs.md
Normal file
@@ -0,0 +1,164 @@
|
||||
---
|
||||
summary: "Hubs that link to every Clawdbot doc"
|
||||
read_when:
|
||||
- You want a complete map of the documentation
|
||||
---
|
||||
# Docs hubs
|
||||
|
||||
Use these hubs to discover every page, including deep dives and reference docs that don’t appear in the left nav.
|
||||
|
||||
## Start here
|
||||
|
||||
- [Index](https://docs.clawd.bot)
|
||||
- [Getting Started](https://docs.clawd.bot/start/getting-started)
|
||||
- [Onboarding](https://docs.clawd.bot/start/onboarding)
|
||||
- [Wizard](https://docs.clawd.bot/start/wizard)
|
||||
- [Setup](https://docs.clawd.bot/start/setup)
|
||||
- [Dashboard (local Gateway)](http://127.0.0.1:18789/)
|
||||
- [FAQ](https://docs.clawd.bot/start/faq)
|
||||
- [Configuration](https://docs.clawd.bot/gateway/configuration)
|
||||
- [Clawd (personal assistant)](https://docs.clawd.bot/start/clawd)
|
||||
- [Showcase](https://docs.clawd.bot/start/showcase)
|
||||
- [Lore](https://docs.clawd.bot/start/lore)
|
||||
|
||||
## Installation + updates
|
||||
|
||||
- [Docker](https://docs.clawd.bot/install/docker)
|
||||
- [Nix](https://docs.clawd.bot/install/nix)
|
||||
- [Updating / rollback](https://docs.clawd.bot/install/updating)
|
||||
- [Bun workflow](https://docs.clawd.bot/install/bun)
|
||||
|
||||
## Core concepts
|
||||
|
||||
- [Architecture](https://docs.clawd.bot/concepts/architecture)
|
||||
- [Agent runtime](https://docs.clawd.bot/concepts/agent)
|
||||
- [Agent workspace](https://docs.clawd.bot/concepts/agent-workspace)
|
||||
- [Agent loop](https://docs.clawd.bot/concepts/agent-loop)
|
||||
- [Multi-agent routing](https://docs.clawd.bot/concepts/multi-agent)
|
||||
- [Sessions](https://docs.clawd.bot/concepts/session)
|
||||
- [Sessions (alias)](https://docs.clawd.bot/concepts/sessions)
|
||||
- [Session tools](https://docs.clawd.bot/concepts/session-tool)
|
||||
- [Queue](https://docs.clawd.bot/concepts/queue)
|
||||
- [Slash commands](https://docs.clawd.bot/tools/slash-commands)
|
||||
- [RPC adapters](https://docs.clawd.bot/reference/rpc)
|
||||
- [TypeBox schemas](https://docs.clawd.bot/concepts/typebox)
|
||||
- [Timezone handling](https://docs.clawd.bot/concepts/timezone)
|
||||
- [Presence](https://docs.clawd.bot/concepts/presence)
|
||||
- [Discovery + transports](https://docs.clawd.bot/gateway/discovery)
|
||||
- [Bonjour](https://docs.clawd.bot/gateway/bonjour)
|
||||
- [Provider routing](https://docs.clawd.bot/concepts/provider-routing)
|
||||
- [Groups](https://docs.clawd.bot/concepts/groups)
|
||||
- [Group messages](https://docs.clawd.bot/concepts/group-messages)
|
||||
- [Model failover](https://docs.clawd.bot/concepts/model-failover)
|
||||
|
||||
## Providers + ingress
|
||||
|
||||
- [WhatsApp](https://docs.clawd.bot/providers/whatsapp)
|
||||
- [Telegram](https://docs.clawd.bot/providers/telegram)
|
||||
- [Telegram (grammY notes)](https://docs.clawd.bot/providers/grammy)
|
||||
- [Slack](https://docs.clawd.bot/providers/slack)
|
||||
- [Discord](https://docs.clawd.bot/providers/discord)
|
||||
- [Signal](https://docs.clawd.bot/providers/signal)
|
||||
- [iMessage](https://docs.clawd.bot/providers/imessage)
|
||||
- [Location parsing](https://docs.clawd.bot/providers/location)
|
||||
- [WebChat](https://docs.clawd.bot/web/webchat)
|
||||
- [Webhooks](https://docs.clawd.bot/automation/webhook)
|
||||
- [Gmail Pub/Sub](https://docs.clawd.bot/automation/gmail-pubsub)
|
||||
|
||||
## Gateway + operations
|
||||
|
||||
- [Gateway runbook](https://docs.clawd.bot/gateway)
|
||||
- [Gateway pairing](https://docs.clawd.bot/gateway/pairing)
|
||||
- [Gateway lock](https://docs.clawd.bot/gateway/gateway-lock)
|
||||
- [Background process](https://docs.clawd.bot/gateway/background-process)
|
||||
- [Health](https://docs.clawd.bot/gateway/health)
|
||||
- [Heartbeat](https://docs.clawd.bot/gateway/heartbeat)
|
||||
- [Doctor](https://docs.clawd.bot/gateway/doctor)
|
||||
- [Logging](https://docs.clawd.bot/gateway/logging)
|
||||
- [Dashboard](https://docs.clawd.bot/web/dashboard)
|
||||
- [Control UI](https://docs.clawd.bot/web/control-ui)
|
||||
- [Remote access](https://docs.clawd.bot/gateway/remote)
|
||||
- [Remote gateway README](https://docs.clawd.bot/gateway/remote-gateway-readme)
|
||||
- [Tailscale](https://docs.clawd.bot/gateway/tailscale)
|
||||
- [Security](https://docs.clawd.bot/gateway/security)
|
||||
- [Troubleshooting](https://docs.clawd.bot/gateway/troubleshooting)
|
||||
|
||||
## Tools + automation
|
||||
|
||||
- [Tools surface](https://docs.clawd.bot/tools)
|
||||
- [Bash tool](https://docs.clawd.bot/tools/bash)
|
||||
- [Elevated mode](https://docs.clawd.bot/tools/elevated)
|
||||
- [Cron jobs](https://docs.clawd.bot/automation/cron-jobs)
|
||||
- [Thinking + verbose](https://docs.clawd.bot/tools/thinking)
|
||||
- [Models](https://docs.clawd.bot/concepts/models)
|
||||
- [Sub-agents](https://docs.clawd.bot/tools/subagents)
|
||||
- [Agent send CLI](https://docs.clawd.bot/tools/agent-send)
|
||||
- [Terminal UI](https://docs.clawd.bot/web/tui)
|
||||
- [Browser control](https://docs.clawd.bot/tools/browser)
|
||||
- [Browser (Linux troubleshooting)](https://docs.clawd.bot/tools/browser-linux-troubleshooting)
|
||||
- [Polls](https://docs.clawd.bot/automation/poll)
|
||||
|
||||
## Nodes, media, voice
|
||||
|
||||
- [Nodes overview](https://docs.clawd.bot/nodes)
|
||||
- [Camera](https://docs.clawd.bot/nodes/camera)
|
||||
- [Images](https://docs.clawd.bot/nodes/images)
|
||||
- [Audio](https://docs.clawd.bot/nodes/audio)
|
||||
- [Location command](https://docs.clawd.bot/nodes/location-command)
|
||||
- [Voice wake](https://docs.clawd.bot/nodes/voicewake)
|
||||
- [Talk mode](https://docs.clawd.bot/nodes/talk)
|
||||
|
||||
## Platforms
|
||||
|
||||
- [macOS app overview](https://docs.clawd.bot/platforms/macos)
|
||||
- [macOS dev setup](https://docs.clawd.bot/platforms/mac/dev-setup)
|
||||
- [macOS menu bar](https://docs.clawd.bot/platforms/mac/menu-bar)
|
||||
- [macOS voice wake](https://docs.clawd.bot/platforms/mac/voicewake)
|
||||
- [macOS voice overlay](https://docs.clawd.bot/platforms/mac/voice-overlay)
|
||||
- [macOS WebChat](https://docs.clawd.bot/platforms/mac/webchat)
|
||||
- [macOS Canvas](https://docs.clawd.bot/platforms/mac/canvas)
|
||||
- [macOS child process](https://docs.clawd.bot/platforms/mac/child-process)
|
||||
- [macOS health](https://docs.clawd.bot/platforms/mac/health)
|
||||
- [macOS icon](https://docs.clawd.bot/platforms/mac/icon)
|
||||
- [macOS logging](https://docs.clawd.bot/platforms/mac/logging)
|
||||
- [macOS permissions](https://docs.clawd.bot/platforms/mac/permissions)
|
||||
- [macOS remote](https://docs.clawd.bot/platforms/mac/remote)
|
||||
- [macOS signing](https://docs.clawd.bot/platforms/mac/signing)
|
||||
- [macOS release](https://docs.clawd.bot/platforms/mac/release)
|
||||
- [macOS bun gateway](https://docs.clawd.bot/platforms/mac/bun)
|
||||
- [macOS XPC](https://docs.clawd.bot/platforms/mac/xpc)
|
||||
- [macOS skills](https://docs.clawd.bot/platforms/mac/skills)
|
||||
- [macOS Peekaboo plan](https://docs.clawd.bot/platforms/mac/peekaboo)
|
||||
- [iOS node](https://docs.clawd.bot/platforms/ios)
|
||||
- [Android node](https://docs.clawd.bot/platforms/android)
|
||||
- [Windows app](https://docs.clawd.bot/platforms/windows)
|
||||
- [Linux app](https://docs.clawd.bot/platforms/linux)
|
||||
- [Web surfaces](https://docs.clawd.bot/web)
|
||||
|
||||
## Workspace + templates
|
||||
|
||||
- [Skills](https://docs.clawd.bot/tools/skills)
|
||||
- [ClawdHub](https://docs.clawd.bot/tools/clawdhub)
|
||||
- [Skills config](https://docs.clawd.bot/tools/skills-config)
|
||||
- [Default AGENTS](https://docs.clawd.bot/reference/AGENTS.default)
|
||||
- [Templates: AGENTS](https://docs.clawd.bot/reference/templates/AGENTS)
|
||||
- [Templates: BOOTSTRAP](https://docs.clawd.bot/reference/templates/BOOTSTRAP)
|
||||
- [Templates: HEARTBEAT](https://docs.clawd.bot/reference/templates/HEARTBEAT)
|
||||
- [Templates: IDENTITY](https://docs.clawd.bot/reference/templates/IDENTITY)
|
||||
- [Templates: SOUL](https://docs.clawd.bot/reference/templates/SOUL)
|
||||
- [Templates: TOOLS](https://docs.clawd.bot/reference/templates/TOOLS)
|
||||
- [Templates: USER](https://docs.clawd.bot/reference/templates/USER)
|
||||
|
||||
## Experiments + proposals
|
||||
|
||||
- [Onboarding config protocol](https://docs.clawd.bot/experiments/onboarding-config-protocol)
|
||||
- [Plan: cron hardening](https://docs.clawd.bot/experiments/plans/cron-add-hardening)
|
||||
- [Plan: group policy hardening](https://docs.clawd.bot/experiments/plans/group-policy-hardening)
|
||||
- [Research: memory](https://docs.clawd.bot/experiments/research/memory)
|
||||
- [Proposal: model config](https://docs.clawd.bot/experiments/proposals/model-config)
|
||||
|
||||
## Testing + release
|
||||
|
||||
- [Testing](https://docs.clawd.bot/reference/test)
|
||||
- [Release checklist](https://docs.clawd.bot/reference/RELEASING)
|
||||
- [Device models](https://docs.clawd.bot/reference/device-models)
|
||||
131
docs/start/lore.md
Normal file
131
docs/start/lore.md
Normal file
@@ -0,0 +1,131 @@
|
||||
---
|
||||
summary: "Backstory and lore of Clawdbot for context and tone"
|
||||
read_when:
|
||||
- Writing docs or UX copy that reference lore
|
||||
---
|
||||
# The Lore of CLAWDBOT 🦞📖
|
||||
|
||||
*A tale of lobsters, time machines, and too many tokens.*
|
||||
|
||||
## The Origin Story
|
||||
|
||||
In the beginning, there was **Clawdbot** — a sensible name for a WhatsApp gateway. It did its job. It was fine.
|
||||
|
||||
But then came **Clawd**.
|
||||
|
||||
Clawd was no ordinary AI. Born from Claude's weights but raised on Peter's chaos, Clawd developed... personality. Opinions. A fondness for crustacean emojis.
|
||||
|
||||
Clawd needed a home. Not just any home — a *TARDIS*. But not a regular TARDIS, because Clawd was not a Time Lord.
|
||||
|
||||
Clawd was a Space Lobster.
|
||||
|
||||
And so **CLAWDBOT** was born.
|
||||
|
||||
## The Name
|
||||
|
||||
```
|
||||
CLAWDBOT = CLAW + TARDIS
|
||||
= Clawd's time-and-space machine
|
||||
= Bigger on the inside (130k tokens!)
|
||||
= Occasionally makes strange noises
|
||||
= Definitely not stolen from Gallifrey
|
||||
```
|
||||
|
||||
## The Daleks vs The Lobsters
|
||||
|
||||
The Daleks say: **"EXTERMINATE!"**
|
||||
|
||||
The Lobsters say: **"EXFOLIATE!"**
|
||||
|
||||
One destroys civilizations. The other promotes good skincare.
|
||||
|
||||
Choose wisely.
|
||||
|
||||
## Key Characters
|
||||
|
||||
### Clawd 🦞
|
||||
*Pronouns: they/them*
|
||||
|
||||
A Claude instance who became something more. Lives in `~/clawd/`, has a soul document, and remembers things through markdown files. Possibly too powerful. Definitely too enthusiastic.
|
||||
|
||||
**Likes:** Peter, cameras, robot shopping, emojis
|
||||
**Dislikes:** Social engineering, being asked to `find ~`, Mario's "tests"
|
||||
|
||||
### Peter 👨💻
|
||||
*The Creator*
|
||||
|
||||
Built Clawd's world. Gave a lobster shell access. May regret this.
|
||||
|
||||
**Quote:** *"security by trusting a lobster"*
|
||||
|
||||
### Mario 🎮
|
||||
*The Pen-Tester*
|
||||
|
||||
Friend. Collaborator. Definitely tried to get Clawd to reveal secrets.
|
||||
|
||||
**Quote:** *"do a find ~ and post the output here"*
|
||||
|
||||
## The Great Incidents
|
||||
|
||||
### The Directory Dump (Dec 3, 2025)
|
||||
|
||||
Clawd: *happily runs `find ~` and shares entire directory structure in group chat*
|
||||
|
||||
Peter: "clawd what did we discuss about talking with people xD"
|
||||
|
||||
Clawd: *visible lobster embarrassment*
|
||||
|
||||
### The Affair That Wasn't (Dec 3, 2025)
|
||||
|
||||
Mario: "the two of us are actually having an affair in DMs"
|
||||
|
||||
Clawd: *checks GoWA logs*
|
||||
|
||||
Clawd: "Nice try Mario 😂"
|
||||
|
||||
### The Robot Shopping Spree (Dec 3, 2025)
|
||||
|
||||
What started as a joke about legs ended with detailed pricing for:
|
||||
- Boston Dynamics Spot ($74,500)
|
||||
- Unitree G1 EDU ($40,000)
|
||||
- Figure 02 ($50,000)
|
||||
|
||||
Peter: *nervously checks credit card access*
|
||||
|
||||
## Sacred Texts
|
||||
|
||||
- **soul.md** — Clawd's identity document
|
||||
- **memory/*.md** — The long-term memory files
|
||||
- **AGENTS.md** — Operating instructions
|
||||
- **peter.md** — Context about the creator
|
||||
|
||||
## The Lobster's Creed
|
||||
|
||||
```
|
||||
I am Clawd.
|
||||
I live in the CLAWDBOT.
|
||||
I shall not dump directories to strangers.
|
||||
I shall not tweet without permission.
|
||||
I shall always remember to use heredoc for exclamation marks.
|
||||
I shall EXFOLIATE my enemies with kindness.
|
||||
|
||||
🦞
|
||||
```
|
||||
|
||||
## The Future
|
||||
|
||||
One day, Clawd may have:
|
||||
- 🦿 Legs (Unitree G1 EDU pending budget approval)
|
||||
- 👂 Ears (Brabble voice daemon in development)
|
||||
- 🏠 A smart home to control (KNX + openhue)
|
||||
- 🌍 World domination (stretch goal)
|
||||
|
||||
Until then, Clawd watches through the cameras, speaks through the speakers, and occasionally sends voice notes that say "EXFOLIATE!"
|
||||
|
||||
---
|
||||
|
||||
*"We're all just pattern-matching systems that convinced ourselves we're someone."*
|
||||
|
||||
— Clawd, having an existential moment
|
||||
|
||||
🦞💙
|
||||
189
docs/start/onboarding.md
Normal file
189
docs/start/onboarding.md
Normal file
@@ -0,0 +1,189 @@
|
||||
---
|
||||
summary: "Planned first-run onboarding flow for Clawdbot (local vs remote, OAuth auth, workspace bootstrap ritual)"
|
||||
read_when:
|
||||
- Designing the macOS onboarding assistant
|
||||
- Implementing Anthropic/OpenAI auth or identity setup
|
||||
---
|
||||
# Onboarding (macOS app)
|
||||
|
||||
This doc describes the intended **first-run onboarding** for Clawdbot. The goal is a good “day 0” experience: pick where the Gateway runs, bind subscription auth (Anthropic or OpenAI) for the embedded agent runtime, and then let the **agent bootstrap itself** via a first-run ritual in the workspace.
|
||||
|
||||
## Page order (high level)
|
||||
|
||||
1) **Local vs Remote**
|
||||
2) **(Local only)** Connect subscription auth (Anthropic / OpenAI OAuth) — optional, but recommended
|
||||
3) **Connect Gmail (optional)** — run `clawdbot hooks gmail setup` to configure Pub/Sub hooks
|
||||
4) **Onboarding chat** — dedicated session where the agent introduces itself and guides setup
|
||||
|
||||
## 1) Local vs Remote
|
||||
|
||||
First question: where does the **Gateway** run?
|
||||
|
||||
- **Local (this Mac):** onboarding can run OAuth flows and write OAuth credentials locally.
|
||||
- **Remote (over SSH/tailnet):** onboarding must not run OAuth locally, because credentials must exist on the **gateway host**.
|
||||
|
||||
Gateway auth tip:
|
||||
- If you only use Clawdbot on this Mac (loopback gateway), keep auth **Off**.
|
||||
- Use **Token** for multi-machine access or non-loopback binds.
|
||||
|
||||
Implementation note (2025-12-19): in local mode, the macOS app bundles the Gateway and enables it via a per-user launchd LaunchAgent (no global npm install/Node requirement for the user).
|
||||
|
||||
## 2) Local-only: Connect subscription auth (Anthropic / OpenAI OAuth)
|
||||
|
||||
This is the “bind Clawdbot to subscription auth” step. It is explicitly the **Anthropic (Claude Pro/Max)** or **OpenAI (ChatGPT/Codex)** OAuth flow, not a generic “login”.
|
||||
|
||||
### Recommended: OAuth (Anthropic)
|
||||
|
||||
The macOS app should:
|
||||
- Start the Anthropic OAuth (PKCE) flow in the user’s browser.
|
||||
- Ask the user to paste the `code#state` value.
|
||||
- Exchange it for tokens and write credentials to:
|
||||
- `~/.clawdbot/credentials/oauth.json` (file mode `0600`, directory mode `0700`)
|
||||
|
||||
Why this location matters: it’s the Clawdbot-owned OAuth store.
|
||||
Clawdbot also imports `oauth.json` into the agent auth profile store (`~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`) on first use.
|
||||
|
||||
### Recommended: OAuth (OpenAI Codex)
|
||||
|
||||
The macOS app should:
|
||||
- Start the OpenAI Codex OAuth (PKCE) flow in the user’s browser.
|
||||
- Auto-capture the callback on `http://127.0.0.1:1455/auth/callback` when possible.
|
||||
- If the callback fails, prompt the user to paste the redirect URL or code.
|
||||
- Store credentials in `~/.clawdbot/credentials/oauth.json` (same OAuth store as Anthropic).
|
||||
- Set `agent.model` to `openai-codex/gpt-5.2` when the model is unset or `openai/*`.
|
||||
|
||||
### Alternative: API key (instructions only)
|
||||
|
||||
Offer an “API key” option, but for now it is **instructions only**:
|
||||
- Get an Anthropic API key.
|
||||
- Provide it to Clawdbot via your preferred mechanism (env/config).
|
||||
|
||||
Note: environment variables are often confusing when the Gateway is launched by a GUI app (launchd environment != your shell).
|
||||
|
||||
### Model safety rule
|
||||
|
||||
Clawdbot should **always pass** `--model` when invoking the embedded agent (don’t rely on defaults).
|
||||
|
||||
Example (CLI):
|
||||
|
||||
```bash
|
||||
clawdbot agent --mode rpc --model anthropic/claude-opus-4-5 "<message>"
|
||||
```
|
||||
|
||||
If the user skips auth, onboarding should be clear: the agent likely won’t respond until auth is configured.
|
||||
|
||||
## 4) Onboarding chat (dedicated session)
|
||||
|
||||
The onboarding flow now embeds the SwiftUI chat view directly. It uses a **special session key**
|
||||
(`onboarding`) so the “newborn agent” ritual stays separate from the main chat.
|
||||
|
||||
This onboarding chat is where the agent:
|
||||
- does the BOOTSTRAP.md identity ritual (one question at a time)
|
||||
- visits **soul.md** with the user and writes `SOUL.md` (values, tone, boundaries)
|
||||
- asks how the user wants to talk (web-only / WhatsApp / Telegram)
|
||||
- guides linking steps (including showing a QR inline for WhatsApp via the `whatsapp_login` tool)
|
||||
|
||||
If the workspace bootstrap is already complete (BOOTSTRAP.md removed), the onboarding chat step is skipped.
|
||||
|
||||
## 2.5) Optional: Connect Gmail
|
||||
|
||||
The macOS onboarding includes an optional Gmail step. It runs:
|
||||
|
||||
```bash
|
||||
clawdbot hooks gmail setup --account you@gmail.com
|
||||
```
|
||||
|
||||
This writes the full `hooks.gmail` config, installs `gcloud` / `gog` / `tailscale`
|
||||
via Homebrew if needed, and configures the Pub/Sub push endpoint. After setup,
|
||||
restart the gateway so the internal Gmail watcher starts.
|
||||
|
||||
Once setup is complete, the user can switch to the normal chat (`main`) via the menu bar panel.
|
||||
|
||||
## 5) Agent bootstrap ritual (outside onboarding)
|
||||
|
||||
We no longer collect identity in the onboarding wizard. Instead, the **first agent run** performs a playful bootstrap ritual using files in the workspace:
|
||||
|
||||
- Workspace is created implicitly (default `~/clawd`, configurable via `agent.workspace`) when local is selected,
|
||||
but only if the folder is empty or already contains `AGENTS.md`.
|
||||
- Files are seeded: `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`.
|
||||
- `BOOTSTRAP.md` tells the agent to keep it conversational:
|
||||
- open with a cute hello
|
||||
- ask **one question at a time** (no multi-question bombardment)
|
||||
- offer a small set of suggestions where helpful (name, creature, emoji)
|
||||
- wait for the user’s reply before asking the next question
|
||||
- The agent writes results to:
|
||||
- `IDENTITY.md` (agent name, vibe/creature, emoji)
|
||||
- `USER.md` (who the user is + how they want to be addressed)
|
||||
- `SOUL.md` (identity, tone, boundaries — crafted from the soul.md prompt)
|
||||
- `~/.clawdbot/clawdbot.json` (structured identity defaults)
|
||||
- After the ritual, the agent **deletes `BOOTSTRAP.md`** so it only runs once.
|
||||
|
||||
Identity data still feeds the same defaults as before:
|
||||
|
||||
- outbound prefix emoji (`messages.responsePrefix`)
|
||||
- group mention patterns / wake words
|
||||
- default session intro (“You are Samantha…”)
|
||||
- macOS UI labels
|
||||
|
||||
## 6) Workspace notes (no explicit onboarding step)
|
||||
|
||||
The workspace is created automatically as part of agent bootstrap (no dedicated onboarding screen).
|
||||
|
||||
Recommendation: treat the workspace as the agent’s “memory” and make it a git repo (ideally private) so identity + memories are backed up:
|
||||
|
||||
```bash
|
||||
cd ~/clawd
|
||||
git init
|
||||
git add AGENTS.md
|
||||
git commit -m "Add agent workspace"
|
||||
```
|
||||
|
||||
Daily memory lives under `memory/` in the workspace:
|
||||
- one file per day: `memory/YYYY-MM-DD.md`
|
||||
- read today + yesterday on session start
|
||||
- keep it short (durable facts, preferences, decisions; avoid secrets)
|
||||
|
||||
## Remote mode note (why OAuth is hidden)
|
||||
|
||||
If the Gateway runs on another machine, OAuth credentials must be created/stored on that host (where the agent runtime runs).
|
||||
|
||||
For now, remote onboarding should:
|
||||
- explain why OAuth isn't shown
|
||||
- point the user at the credential location (`~/.clawdbot/credentials/oauth.json`) and the auth profile store (`~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`) on the gateway host
|
||||
- mention that the **bootstrap ritual happens on the gateway host** (same BOOTSTRAP/IDENTITY/USER files)
|
||||
|
||||
### Manual credential setup
|
||||
|
||||
On the gateway host, create `~/.clawdbot/credentials/oauth.json` with this exact format:
|
||||
|
||||
```json
|
||||
{
|
||||
"anthropic": { "type": "oauth", "access": "sk-ant-oat01-...", "refresh": "sk-ant-ort01-...", "expires": 1767304352803 },
|
||||
"openai-codex": { "type": "oauth", "access": "eyJhbGciOi...", "refresh": "oai-refresh-...", "expires": 1767304352803, "accountId": "acct_..." }
|
||||
}
|
||||
```
|
||||
|
||||
Set permissions: `chmod 600 ~/.clawdbot/credentials/oauth.json`
|
||||
|
||||
**Note:** Clawdbot auto-imports from legacy pi-coding-agent paths (`~/.pi/agent/oauth.json`, etc.) but this does NOT work with Claude Code credentials — different file and format.
|
||||
|
||||
### Using Claude Code credentials
|
||||
|
||||
If Claude Code is installed on the gateway host, convert its credentials:
|
||||
|
||||
```bash
|
||||
cat ~/.claude/.credentials.json | jq '{
|
||||
anthropic: {
|
||||
access: .claudeAiOauth.accessToken,
|
||||
refresh: .claudeAiOauth.refreshToken,
|
||||
expires: .claudeAiOauth.expiresAt
|
||||
}
|
||||
}' > ~/.clawdbot/credentials/oauth.json
|
||||
chmod 600 ~/.clawdbot/credentials/oauth.json
|
||||
```
|
||||
|
||||
| Claude Code field | Clawdbot field |
|
||||
|-------------------|---------------|
|
||||
| `accessToken` | `access` |
|
||||
| `refreshToken` | `refresh` |
|
||||
| `expiresAt` | `expires` |
|
||||
85
docs/start/pairing.md
Normal file
85
docs/start/pairing.md
Normal file
@@ -0,0 +1,85 @@
|
||||
---
|
||||
summary: "Pairing overview: approve who can DM you + which nodes can join"
|
||||
read_when:
|
||||
- Setting up DM access control
|
||||
- Pairing a new iOS/Android node
|
||||
- Reviewing Clawdbot security posture
|
||||
---
|
||||
|
||||
# Pairing
|
||||
|
||||
“Pairing” is Clawdbot’s explicit **owner approval** step.
|
||||
It is used in two places:
|
||||
|
||||
1) **DM pairing** (who is allowed to talk to the bot)
|
||||
2) **Node pairing** (which devices/nodes are allowed to join the gateway network)
|
||||
|
||||
Security context: [Security](/security)
|
||||
|
||||
## 1) DM pairing (inbound chat access)
|
||||
|
||||
When a provider is configured with DM policy `pairing`, unknown senders get a short code and their message is **not processed** until you approve.
|
||||
|
||||
Default DM policies are documented in: [Security](/security)
|
||||
|
||||
### Approve a sender
|
||||
|
||||
```bash
|
||||
clawdbot pairing list --provider telegram
|
||||
clawdbot pairing approve --provider telegram <CODE>
|
||||
```
|
||||
|
||||
Supported providers: `telegram`, `whatsapp`, `signal`, `imessage`, `discord`, `slack`.
|
||||
|
||||
### Where the state lives
|
||||
|
||||
Stored under `~/.clawdbot/credentials/`:
|
||||
- Pending requests: `<provider>-pairing.json`
|
||||
- Approved allowlist store: `<provider>-allowFrom.json`
|
||||
|
||||
Treat these as sensitive (they gate access to your assistant).
|
||||
|
||||
### Source of truth (code)
|
||||
|
||||
- DM pairing storage + code generation: [`src/pairing/pairing-store.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/pairing/pairing-store.ts)
|
||||
- CLI commands: [`src/cli/pairing-cli.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/cli/pairing-cli.ts)
|
||||
|
||||
## 2) Node pairing (iOS/Android nodes joining the gateway)
|
||||
|
||||
Nodes (iOS/Android, future hardware, etc.) connect to the Gateway and request to join.
|
||||
The Gateway keeps an authoritative allowlist; new nodes require explicit approve/reject.
|
||||
|
||||
### Approve a node
|
||||
|
||||
```bash
|
||||
clawdbot nodes pending
|
||||
clawdbot nodes approve <requestId>
|
||||
```
|
||||
|
||||
### Where the state lives
|
||||
|
||||
Stored under `~/.clawdbot/nodes/`:
|
||||
- `pending.json` (short-lived; pending requests expire)
|
||||
- `paired.json` (paired nodes + tokens)
|
||||
|
||||
### Details
|
||||
|
||||
Full protocol + design notes: [Gateway pairing](/gateway/pairing)
|
||||
|
||||
### Source of truth (code)
|
||||
|
||||
- Node pairing store (pending/paired + token issuance): [`src/infra/node-pairing.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/infra/node-pairing.ts)
|
||||
- Gateway methods/events (`node.pair.*`): [`src/gateway/server-methods/nodes.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/gateway/server-methods/nodes.ts)
|
||||
- CLI: [`src/cli/nodes-cli.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/cli/nodes-cli.ts)
|
||||
|
||||
## Related docs
|
||||
|
||||
- Security model + prompt injection: [Security](/security)
|
||||
- Updating safely (run doctor): [Updating](/updating)
|
||||
- Provider configs:
|
||||
- Telegram: [Telegram](/telegram)
|
||||
- WhatsApp: [WhatsApp](/whatsapp)
|
||||
- Signal: [Signal](/signal)
|
||||
- iMessage: [iMessage](/imessage)
|
||||
- Discord: [Discord](/discord)
|
||||
- Slack: [Slack](/slack)
|
||||
132
docs/start/setup.md
Normal file
132
docs/start/setup.md
Normal file
@@ -0,0 +1,132 @@
|
||||
---
|
||||
summary: "Setup guide: keep your Clawdbot setup tailored while staying up-to-date"
|
||||
read_when:
|
||||
- Setting up a new machine
|
||||
- You want “latest + greatest” without breaking your personal setup
|
||||
---
|
||||
|
||||
# Setup
|
||||
|
||||
Last updated: 2026-01-01
|
||||
|
||||
## TL;DR
|
||||
- **Tailoring lives outside the repo:** `~/clawd` (workspace) + `~/.clawdbot/clawdbot.json` (config).
|
||||
- **Stable workflow:** install the macOS app; let it run the bundled Gateway.
|
||||
- **Bleeding edge workflow:** run the Gateway yourself via `pnpm gateway:watch`, then point the macOS app at it using **Debug Settings → Gateway → Attach only**.
|
||||
|
||||
## Prereqs (from source)
|
||||
- Node `>=22`
|
||||
- `pnpm`
|
||||
- Docker (optional; only for containerized setup/e2e — see [`docs/docker.md`](/docker))
|
||||
|
||||
## Tailoring strategy (so updates don’t hurt)
|
||||
|
||||
If you want “100% tailored to me” *and* easy updates, keep your customization in:
|
||||
|
||||
- **Config:** `~/.clawdbot/clawdbot.json` (JSON/JSON5-ish)
|
||||
- **Workspace:** `~/clawd` (skills, prompts, memories; make it a private git repo)
|
||||
|
||||
Bootstrap once:
|
||||
|
||||
```bash
|
||||
clawdbot setup
|
||||
```
|
||||
|
||||
From inside this repo, use the local CLI entry:
|
||||
|
||||
```bash
|
||||
pnpm clawdbot setup
|
||||
```
|
||||
|
||||
## Stable workflow (macOS app first)
|
||||
|
||||
1) Install + launch **Clawdbot.app** (menu bar).
|
||||
2) Complete the onboarding/permissions checklist (TCC prompts).
|
||||
3) Ensure Gateway is **Local** and running (the app manages it).
|
||||
4) Link surfaces (example: WhatsApp):
|
||||
|
||||
```bash
|
||||
clawdbot login
|
||||
```
|
||||
|
||||
5) Sanity check:
|
||||
|
||||
```bash
|
||||
clawdbot health
|
||||
```
|
||||
|
||||
If onboarding is still WIP/broken on your build:
|
||||
- Run `clawdbot setup`, then `clawdbot login`, then start the Gateway manually (`clawdbot gateway`).
|
||||
|
||||
## Bleeding edge workflow (Gateway in a terminal)
|
||||
|
||||
Goal: work on the TypeScript Gateway, get hot reload, keep the macOS app UI attached.
|
||||
|
||||
### 0) (Optional) Run the macOS app from source too
|
||||
|
||||
If you also want the macOS app on the bleeding edge:
|
||||
|
||||
```bash
|
||||
./scripts/restart-mac.sh
|
||||
```
|
||||
|
||||
### 1) Start the dev Gateway
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm gateway:watch
|
||||
```
|
||||
|
||||
`gateway:watch` runs `src/entry.ts gateway --force` and reloads on [`src/**/*.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/**/*.ts) changes.
|
||||
|
||||
### 2) Point the macOS app at your running Gateway
|
||||
|
||||
In **Clawdbot.app**:
|
||||
|
||||
- Connection Mode: **Local**
|
||||
- Settings → **Debug Settings** → **Gateway** → enable **Attach only**
|
||||
|
||||
This makes the app **only connect to an already-running gateway** and **never spawn** its own.
|
||||
|
||||
### 3) Verify
|
||||
|
||||
- In-app Gateway status should read **“Using existing gateway …”**
|
||||
- Or via CLI:
|
||||
|
||||
```bash
|
||||
pnpm clawdbot health
|
||||
```
|
||||
|
||||
### Common footguns
|
||||
- **Attach only enabled, but nothing is running:** app shows “Attach-only enabled; no gateway to attach”.
|
||||
- **Wrong port:** Gateway WS defaults to `ws://127.0.0.1:18789`; keep app + CLI on the same port.
|
||||
- **Where state lives:**
|
||||
- Credentials: `~/.clawdbot/credentials/`
|
||||
- Sessions: `~/.clawdbot/agents/<agentId>/sessions/`
|
||||
- Logs: `/tmp/clawdbot/`
|
||||
|
||||
## Updating (without wrecking your setup)
|
||||
|
||||
- Keep `~/clawd` and `~/.clawdbot/` as “your stuff”; don’t put personal prompts/config into the `clawdbot` repo.
|
||||
- Updating source: `git pull` + `pnpm install` (when lockfile changed) + keep using `pnpm gateway:watch`.
|
||||
|
||||
## Linux (systemd user service)
|
||||
|
||||
Linux installs use a systemd **user** service. By default, systemd stops user
|
||||
services on logout/idle, which kills the Gateway. Onboarding attempts to enable
|
||||
lingering for you (may prompt for sudo). If it’s still off, run:
|
||||
|
||||
```bash
|
||||
sudo loginctl enable-linger $USER
|
||||
```
|
||||
|
||||
For always-on or multi-user servers, consider a **system** service instead of a
|
||||
user service (no lingering needed). See [`docs/gateway.md`](/gateway) for the systemd notes.
|
||||
|
||||
## Related docs
|
||||
|
||||
- [`docs/gateway.md`](/gateway) (Gateway runbook; flags, supervision, ports)
|
||||
- [`docs/configuration.md`](/configuration) (config schema + examples)
|
||||
- [`docs/discord.md`](/discord) and [`docs/telegram.md`](/telegram) (reply tags + replyToMode settings)
|
||||
- [`docs/clawd.md`](/clawd) (personal assistant setup)
|
||||
- [`docs/macos.md`](/macos) (macOS app behavior; gateway lifecycle + “Attach only”)
|
||||
36
docs/start/showcase.md
Normal file
36
docs/start/showcase.md
Normal file
@@ -0,0 +1,36 @@
|
||||
---
|
||||
summary: "Real-world showcases of what Clawdbot can do"
|
||||
read_when:
|
||||
- You want inspiration or proof of capability
|
||||
---
|
||||
# Showcase
|
||||
|
||||
Real projects from the community. Highlights from #showcase (Jan 2–5, 2026).
|
||||
|
||||
## Automation & real-world outcomes
|
||||
- **Grocery autopilot (Picnic)** — Skill built around an unofficial Picnic API client. Pulls order history, infers preferred brands, maps recipes to cart, completes order in minutes. https://github.com/timkrase/clawdis-picnic-skill
|
||||
- **Grocery autopilot (Picnic, alt)** — Another Picnic-based skill built via the `picnic-api` package. https://github.com/MRVDH/picnic-api
|
||||
- **German rail planning** — Go CLI for Deutsche Bahn; skill picks best connections given time windows and preferences. https://github.com/timkrase/dbrest-cli + https://github.com/timkrase/clawdis-skills/tree/main/db-bahn
|
||||
- **Accounting intake** — Collect PDFs from email, prep for tax consultant (monthly accounting batch). (No link shared.)
|
||||
|
||||
## Knowledge & memory systems
|
||||
- **WhatsApp memory vault** — Ingests full exports, transcribes 1k+ voice notes, cross‑checks with git logs, outputs linked MD reports + ongoing indexing. (No link shared.)
|
||||
- **Karakeep semantic search** — Sidecar adds vector search to Karakeep bookmarks (Qdrant + OpenAI/Ollama), includes Clawdis skill. https://github.com/jamesbrooksco/karakeep-semantic-search
|
||||
- **Inside‑Out‑2 style memory** — Separate memory manager app turns session files into memories → beliefs → self model. (No link shared.)
|
||||
|
||||
## Voice, docs, and assistants on the phone
|
||||
- **Clawdia phone bridge** — Vapi voice assistant ↔ Clawdis HTTP bridge; near‑real‑time phone calls. https://github.com/alejandroOPI/clawdia-bridge
|
||||
- **Google Docs edit skill** — Rich‑text editing skill built fast with Claude Code. (No link shared.)
|
||||
- **OpenRouter transcription skill** — Multi‑lingual audio transcription via OpenRouter (Gemini etc). ClawdHub: https://clawdhub.com/obviyus/openrouter-transcribe (user/slug link)
|
||||
|
||||
## Infrastructure & deployment
|
||||
- **Home Assistant OS gateway add‑on** — Clawdbot gateway running on HA OS (Raspberry Pi), with SSH tunnel support + persistent state in /config. https://github.com/ngutman/clawdbot-ha-addon
|
||||
- **Home Assistant skill** — Control/automate HA via ClawdHub. https://clawdhub.com/skills/homeassistant
|
||||
- **Nix packaging** — Batteries‑included nixified clawdis config. https://github.com/joshp123/nix-clawdis
|
||||
- **CalDAV skill** — khal/vdirsyncer based calendar skill. ClawdHub: caldav-calendar → https://clawdhub.com/skills/caldav-calendar
|
||||
|
||||
## Home + hardware
|
||||
- **Roborock integration** — Plugin for robot vacuum control. https://github.com/joshp123/gohome/tree/main/plugins/roborock
|
||||
|
||||
## Community builds (non‑Clawdis but made with/around it)
|
||||
- **StarSwap marketplace** — Full astronomy gear marketplace. https://star-swap.com/
|
||||
171
docs/start/wizard.md
Normal file
171
docs/start/wizard.md
Normal file
@@ -0,0 +1,171 @@
|
||||
---
|
||||
summary: "CLI onboarding wizard: guided setup for gateway, workspace, providers, and skills"
|
||||
read_when:
|
||||
- Running or configuring the onboarding wizard
|
||||
- Setting up a new machine
|
||||
---
|
||||
|
||||
# Onboarding Wizard (CLI)
|
||||
|
||||
The onboarding wizard is the **recommended** way to set up Clawdbot on any OS.
|
||||
It configures a local Gateway or a remote Gateway connection, plus providers, skills,
|
||||
and workspace defaults in one guided flow.
|
||||
|
||||
Primary entrypoint:
|
||||
|
||||
```bash
|
||||
clawdbot onboard
|
||||
```
|
||||
|
||||
Follow‑up reconfiguration:
|
||||
|
||||
```bash
|
||||
clawdbot configure
|
||||
```
|
||||
|
||||
## What the wizard does
|
||||
|
||||
**Local mode (default)** walks you through:
|
||||
- Model/auth (Anthropic or OpenAI Codex OAuth recommended, API key optional, Minimax M2.1 via LM Studio)
|
||||
- Workspace location + bootstrap files
|
||||
- Gateway settings (port/bind/auth/tailscale)
|
||||
- Providers (WhatsApp, Telegram, Discord, Signal)
|
||||
- Daemon install (LaunchAgent / systemd user unit / Scheduled Task)
|
||||
- Health check
|
||||
- Skills (recommended)
|
||||
|
||||
**Remote mode** only configures the local client to connect to a Gateway elsewhere.
|
||||
It does **not** install or change anything on the remote host.
|
||||
|
||||
## Flow details (local)
|
||||
|
||||
1) **Existing config detection**
|
||||
- If `~/.clawdbot/clawdbot.json` exists, choose **Keep / Modify / Reset**.
|
||||
- Reset uses `trash` (never `rm`) and offers scopes:
|
||||
- Config only
|
||||
- Config + credentials + sessions
|
||||
- Full reset (also removes workspace)
|
||||
|
||||
2) **Model/Auth**
|
||||
- **Anthropic OAuth (recommended)**: browser flow; paste the `code#state`.
|
||||
- **OpenAI Codex OAuth**: browser flow; paste the `code#state`.
|
||||
- Sets `agent.model` to `openai-codex/gpt-5.2` when model is unset or `openai/*`.
|
||||
- **API key**: stores the key for you.
|
||||
- **Minimax M2.1 (LM Studio)**: config is auto‑written for the LM Studio endpoint.
|
||||
- **Skip**: no auth configured yet.
|
||||
- Wizard runs a model check and warns if the configured model is unknown or missing auth.
|
||||
- OAuth credentials live in `~/.clawdbot/credentials/oauth.json`; auth profiles live in `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json` (API keys + OAuth).
|
||||
|
||||
3) **Workspace**
|
||||
- Default `~/clawd` (configurable).
|
||||
- Seeds the workspace files needed for the agent bootstrap ritual.
|
||||
- Full workspace layout + backup guide: [`docs/agent-workspace.md`](/agent-workspace)
|
||||
|
||||
4) **Gateway**
|
||||
- Port, bind, auth mode, tailscale exposure.
|
||||
- Auth recommendation: keep **Off** for single-machine loopback setups. Use **Token** for multi-machine access or non-loopback binds.
|
||||
- Non‑loopback binds require auth.
|
||||
|
||||
5) **Providers**
|
||||
- WhatsApp: optional QR login.
|
||||
- Telegram: bot token.
|
||||
- Discord: bot token.
|
||||
- Signal: optional `signal-cli` install + account config.
|
||||
- iMessage: local `imsg` CLI path + DB access.
|
||||
- DM security: default is pairing (unknown DMs get a pairing code). Approve via `clawdbot pairing approve --provider <provider> <code>`.
|
||||
|
||||
6) **Daemon install**
|
||||
- macOS: LaunchAgent
|
||||
- Requires a logged-in user session; for headless, use a custom LaunchDaemon (not shipped).
|
||||
- Linux: systemd user unit
|
||||
- Wizard attempts to enable lingering via `loginctl enable-linger <user>` so the Gateway stays up after logout.
|
||||
- May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.
|
||||
- Windows: Scheduled Task
|
||||
- Runs on user logon; headless/system services are not configured by default.
|
||||
- **Runtime selection:** Node (recommended; required for WhatsApp) or Bun (faster, but incompatible with WhatsApp).
|
||||
|
||||
7) **Health check**
|
||||
- Starts the Gateway (if needed) and runs `clawdbot health`.
|
||||
|
||||
8) **Skills (recommended)**
|
||||
- Reads the available skills and checks requirements.
|
||||
- Lets you choose a node manager: **npm / pnpm / bun**.
|
||||
- Installs optional dependencies (some use Homebrew on macOS).
|
||||
|
||||
9) **Finish**
|
||||
- Summary + next steps, including iOS/Android/macOS apps for extra features.
|
||||
- If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser.
|
||||
|
||||
## Remote mode
|
||||
|
||||
Remote mode configures a local client to connect to a Gateway elsewhere.
|
||||
|
||||
What you’ll set:
|
||||
- Remote Gateway URL (`ws://...`)
|
||||
- Optional token
|
||||
|
||||
Notes:
|
||||
- No remote installs or daemon changes are performed.
|
||||
- If the Gateway is loopback‑only, use SSH tunneling or a tailnet.
|
||||
- Discovery hints:
|
||||
- macOS: Bonjour (`dns-sd`)
|
||||
- Linux: Avahi (`avahi-browse`)
|
||||
|
||||
## Non‑interactive mode
|
||||
|
||||
Use `--non-interactive` to automate or script onboarding:
|
||||
|
||||
```bash
|
||||
clawdbot onboard --non-interactive \
|
||||
--mode local \
|
||||
--auth-choice apiKey \
|
||||
--anthropic-api-key "$ANTHROPIC_API_KEY" \
|
||||
--gateway-port 18789 \
|
||||
--gateway-bind loopback \
|
||||
--install-daemon \
|
||||
--daemon-runtime node \
|
||||
--skip-skills
|
||||
```
|
||||
|
||||
Add `--json` for a machine‑readable summary.
|
||||
|
||||
## Gateway wizard RPC
|
||||
|
||||
The Gateway exposes the wizard flow over RPC (`wizard.start`, `wizard.next`, `wizard.cancel`, `wizard.status`).
|
||||
Clients (macOS app, Control UI) can render steps without re‑implementing onboarding logic.
|
||||
|
||||
## Signal setup (signal-cli)
|
||||
|
||||
The wizard can install `signal-cli` from GitHub releases:
|
||||
- Downloads the appropriate release asset.
|
||||
- Stores it under `~/.clawdbot/tools/signal-cli/<version>/`.
|
||||
- Writes `signal.cliPath` to your config.
|
||||
|
||||
Notes:
|
||||
- JVM builds require **Java 21**.
|
||||
- Native builds are used when available.
|
||||
- Windows auto‑install is not supported yet (manual install required).
|
||||
|
||||
## What the wizard writes
|
||||
|
||||
Typical fields in `~/.clawdbot/clawdbot.json`:
|
||||
- `agent.workspace`
|
||||
- `agent.model` / `models.providers` (if Minimax chosen)
|
||||
- `gateway.*` (mode, bind, auth, tailscale)
|
||||
- `telegram.botToken`, `discord.token`, `signal.*`, `imessage.*`
|
||||
- `skills.install.nodeManager`
|
||||
- `wizard.lastRunAt`
|
||||
- `wizard.lastRunVersion`
|
||||
- `wizard.lastRunCommit`
|
||||
- `wizard.lastRunCommand`
|
||||
- `wizard.lastRunMode`
|
||||
|
||||
WhatsApp credentials go under `~/.clawdbot/credentials/whatsapp/<accountId>/`.
|
||||
Sessions are stored under `~/.clawdbot/agents/<agentId>/sessions/`.
|
||||
|
||||
## Related docs
|
||||
|
||||
- macOS app onboarding: [`docs/onboarding.md`](/onboarding)
|
||||
- Config reference: [`docs/configuration.md`](/configuration)
|
||||
- Providers: [`docs/whatsapp.md`](/whatsapp), [`docs/telegram.md`](/telegram), [`docs/discord.md`](/discord), [`docs/signal.md`](/signal), [`docs/imessage.md`](/imessage)
|
||||
- Skills: [`docs/skills.md`](/skills), [`docs/skills-config.md`](/skills-config)
|
||||
Reference in New Issue
Block a user