let5see/clawdbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add comprehensive configuration examples guide

Browse Source
This commit is contained in:
Dave Onkels
2026-01-05 22:22:15 -08:00
committed by Peter Steinberger
parent 3c20e72e33
commit 18c67ca831
5 changed files with 558 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/docs.json
View File

@@ -570,6 +570,7 @@
"gateway/pairing", "gateway/pairing",
"gateway/gateway-lock", "gateway/gateway-lock",
"gateway/configuration", "gateway/configuration",
"gateway/configuration-examples",
"gateway/background-process", "gateway/background-process",
"gateway/health", "gateway/health",
"gateway/heartbeat", "gateway/heartbeat",

553
docs/gateway/configuration-examples.md Normal file
View File

@@ -0,0 +1,553 @@
---
summary: "Schema-accurate configuration examples for common Clawdbot setups"
read_when:
- Learning how to configure clawdbot
- Looking for configuration examples
- Setting up clawdbot for the first time
---
# Configuration Examples
Examples below are aligned with the current config schema. For the exhaustive reference and per-field notes, see [Configuration](/gateway/configuration).
## Quick start
### Absolute minimum
```json5
{
agent: { workspace: "~/clawd" },
whatsapp: { allowFrom: ["+15555550123"] }
}
```
Save to `~/.clawdbot/clawdbot.json` and you can DM the bot from that number.
### Recommended starter
```json5
{
identity: {
name: "Clawd",
theme: "helpful assistant",
emoji: "🦞"
},
agent: {
workspace: "~/clawd",
model: { primary: "anthropic/claude-sonnet-4-5" }
},
whatsapp: {
allowFrom: ["+15555550123"],
groups: { "*": { requireMention: true } }
}
}
```
## Expanded example (major options)
> JSON5 lets you use comments and trailing commas. Regular JSON works too.
```json5
{
// Environment + shell
env: {
shellEnv: {
enabled: true,
timeoutMs: 15000
}
},
// Auth profile metadata (secrets live in auth-profiles.json)
auth: {
profiles: {
"anthropic:me@example.com": { provider: "anthropic", mode: "oauth", email: "me@example.com" },
"anthropic:work": { provider: "anthropic", mode: "api_key" },
"openai:default": { provider: "openai", mode: "api_key" },
"openai-codex:default": { provider: "openai-codex", mode: "oauth" }
},
order: {
anthropic: ["anthropic:me@example.com", "anthropic:work"],
openai: ["openai:default"],
"openai-codex": ["openai-codex:default"]
}
},
// Identity
identity: {
name: "Samantha",
theme: "helpful sloth",
emoji: "🦥"
},
// Logging
logging: {
level: "info",
file: "/tmp/clawdbot/clawdbot.log",
consoleLevel: "info",
consoleStyle: "pretty",
redactSensitive: "tools"
},
// Message formatting
messages: {
messagePrefix: "[clawdbot]",
responsePrefix: ">",
ackReaction: "👀",
ackReactionScope: "group-mentions"
},
// Routing + queue
routing: {
groupChat: {
mentionPatterns: ["@clawd", "clawdbot"],
historyLimit: 50
},
queue: {
mode: "collect",
debounceMs: 1000,
cap: 20,
drop: "summarize",
byProvider: {
whatsapp: "collect",
telegram: "collect",
discord: "collect",
slack: "collect",
signal: "collect",
imessage: "collect",
webchat: "collect"
}
},
transcribeAudio: {
command: ["whisper", "--model", "base"],
timeoutSeconds: 120
}
},
// Session behavior
session: {
scope: "per-sender",
idleMinutes: 60,
heartbeatIdleMinutes: 120,
resetTriggers: ["/new", "/reset"],
store: "~/.clawdbot/agents/default/sessions/sessions.json",
typingIntervalSeconds: 5,
sendPolicy: {
default: "allow",
rules: [
{ action: "deny", match: { provider: "discord", chatType: "group" } }
]
}
},
// Providers
whatsapp: {
dmPolicy: "pairing",
allowFrom: ["+15555550123"],
groupPolicy: "open",
groups: { "*": { requireMention: true } }
},
telegram: {
enabled: true,
botToken: "YOUR_TELEGRAM_BOT_TOKEN",
allowFrom: ["123456789"],
groupPolicy: "open",
groups: { "*": { requireMention: true } }
},
discord: {
enabled: true,
token: "YOUR_DISCORD_BOT_TOKEN",
dm: { enabled: true, allowFrom: ["steipete"] },
guilds: {
"123456789012345678": {
slug: "friends-of-clawd",
requireMention: false,
channels: {
general: { allow: true },
help: { allow: true, requireMention: true }
}
}
}
},
slack: {
enabled: true,
botToken: "xoxb-REPLACE_ME",
appToken: "xapp-REPLACE_ME",
channels: {
"#general": { allow: true, requireMention: true }
},
dm: { enabled: true, allowFrom: ["U123"] },
slashCommand: {
enabled: true,
name: "clawd",
sessionPrefix: "slack:slash",
ephemeral: true
}
},
signal: {
enabled: true,
account: "+15555550123",
httpUrl: "http://localhost:8080",
allowFrom: ["+15555550123"]
},
imessage: {
enabled: true,
cliPath: "imsg",
dbPath: "~/Library/Messages/chat.db",
service: "auto",
allowFrom: ["+15555550123"],
groups: { "*": { requireMention: true } }
},
// Agent runtime
agent: {
workspace: "~/clawd",
userTimezone: "America/Chicago",
model: {
primary: "anthropic/claude-sonnet-4-5",
fallbacks: ["anthropic/claude-opus-4-5", "openai/gpt-5.2"]
},
imageModel: {
primary: "openrouter/anthropic/claude-sonnet-4-5"
},
models: {
"anthropic/claude-opus-4-5": { alias: "opus" },
"anthropic/claude-sonnet-4-5": { alias: "sonnet" },
"openai/gpt-5.2": { alias: "gpt" }
},
thinkingDefault: "low",
verboseDefault: "off",
elevatedDefault: "on",
blockStreamingDefault: "on",
blockStreamingBreak: "text_end",
blockStreamingChunk: {
minChars: 800,
maxChars: 1200,
breakPreference: "paragraph"
},
timeoutSeconds: 600,
mediaMaxMb: 5,
typingIntervalSeconds: 5,
maxConcurrent: 3,
tools: {
allow: ["bash", "process", "read", "write", "edit"],
deny: ["browser", "canvas"]
},
bash: {
backgroundMs: 10000,
timeoutSec: 1800,
cleanupMs: 1800000
},
heartbeat: {
every: "30m",
model: "anthropic/claude-sonnet-4-5",
target: "last",
to: "+15555550123",
prompt: "HEARTBEAT",
ackMaxChars: 30
},
elevated: {
enabled: true,
allowFrom: {
whatsapp: ["+15555550123"],
telegram: ["123456789"],
discord: ["steipete"],
slack: ["U123"],
signal: ["+15555550123"],
imessage: ["user@example.com"],
webchat: ["session:demo"]
}
},
sandbox: {
mode: "non-main",
perSession: true,
workspaceRoot: "~/.clawdbot/sandboxes",
docker: {
image: "clawdbot-sandbox:bookworm-slim",
workdir: "/workspace",
readOnlyRoot: true,
tmpfs: ["/tmp", "/var/tmp", "/run"],
network: "none",
user: "1000:1000"
},
browser: {
enabled: false
}
}
},
// Custom model providers
models: {
mode: "merge",
providers: {
"custom-proxy": {
baseUrl: "http://localhost:4000/v1",
apiKey: "LITELLM_KEY",
api: "openai-responses",
authHeader: true,
headers: { "X-Proxy-Region": "us-west" },
models: [
{
id: "llama-3.1-8b",
name: "Llama 3.1 8B",
api: "openai-responses",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 128000,
maxTokens: 32000
}
]
}
}
},
// Cron jobs
cron: {
enabled: true,
store: "~/.clawdbot/cron/cron.json",
maxConcurrentRuns: 2
},
// Webhooks
hooks: {
enabled: true,
path: "/hooks",
token: "shared-secret",
presets: ["gmail"],
transformsDir: "~/.clawdbot/hooks",
mappings: [
{
id: "gmail-hook",
match: { path: "gmail" },
action: "agent",
wakeMode: "now",
name: "Gmail",
sessionKey: "hook:gmail:{{messages[0].id}}",
messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}",
textTemplate: "{{messages[0].snippet}}",
deliver: true,
provider: "last",
to: "+15555550123",
thinking: "low",
timeoutSeconds: 300,
transform: { module: "./transforms/gmail.js", export: "transformGmail" }
}
],
gmail: {
account: "clawdbot@gmail.com",
label: "INBOX",
topic: "projects/<project-id>/topics/gog-gmail-watch",
subscription: "gog-gmail-watch-push",
pushToken: "shared-push-token",
hookUrl: "http://127.0.0.1:18789/hooks/gmail",
includeBody: true,
maxBytes: 20000,
renewEveryMinutes: 720,
serve: { bind: "127.0.0.1", port: 8788, path: "/" },
tailscale: { mode: "funnel", path: "/gmail-pubsub" }
}
},
// Web client
web: {
enabled: true,
heartbeatSeconds: 60,
reconnect: {
initialMs: 2000,
maxMs: 120000,
factor: 1.4,
jitter: 0.2,
maxAttempts: 0
}
},
// Browser automation
browser: {
enabled: true,
controlUrl: "http://127.0.0.1:18791",
cdpUrl: "http://127.0.0.1:9222",
headless: false,
defaultProfile: "clawd",
profiles: {
clawd: { cdpPort: 18800, color: "#FF4500" },
work: { cdpPort: 18801, color: "#0066CC" }
}
},
// UI tweaks
ui: {
seamColor: "#FF4500"
},
// Gateway + networking
gateway: {
mode: "local",
port: 18789,
bind: "loopback",
controlUi: { enabled: true, basePath: "/clawdbot" },
auth: {
mode: "token",
token: "gateway-token",
allowTailscale: true
},
tailscale: { mode: "serve", resetOnExit: false },
remote: { url: "ws://gateway.tailnet:18789", token: "remote-token" },
reload: { mode: "hybrid", debounceMs: 300 }
},
bridge: {
enabled: true,
port: 18790,
bind: "tailnet"
},
discovery: {
wideArea: { enabled: true }
},
canvasHost: {
enabled: true,
root: "~/clawd/canvas",
port: 18793,
liveReload: true
},
talk: {
voiceId: "elevenlabs_voice_id",
voiceAliases: { Clawd: "EXAVITQu4vr4xnSDxMaL" },
modelId: "eleven_v3",
outputFormat: "mp3_44100_128",
apiKey: "ELEVENLABS_API_KEY",
interruptOnSpeech: true
},
skills: {
allowBundled: ["brave-search", "gemini"],
load: {
extraDirs: ["~/Projects/agent-scripts/skills"]
},
install: {
preferBrew: true,
nodeManager: "npm"
},
entries: {
"nano-banana-pro": {
enabled: true,
apiKey: "GEMINI_KEY_HERE",
env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }
},
peekaboo: { enabled: true }
}
}
}
```
## Common patterns
### Multi-platform setup
```json5
{
agent: { workspace: "~/clawd" },
whatsapp: { allowFrom: ["+15555550123"] },
telegram: {
enabled: true,
botToken: "YOUR_TOKEN",
allowFrom: ["123456789"]
},
discord: {
enabled: true,
token: "YOUR_TOKEN",
dm: { allowFrom: ["yourname"] }
}
}
```
### OAuth with API key failover
```json5
{
auth: {
profiles: {
"anthropic:subscription": {
provider: "anthropic",
mode: "oauth",
email: "me@example.com"
},
"anthropic:api": {
provider: "anthropic",
mode: "api_key"
}
},
order: {
anthropic: ["anthropic:subscription", "anthropic:api"]
}
},
agent: {
workspace: "~/clawd",
model: {
primary: "anthropic/claude-sonnet-4-5",
fallbacks: ["anthropic/claude-opus-4-5"]
}
}
}
```
### Work bot (restricted access)
```json5
{
identity: {
name: "WorkBot",
theme: "professional assistant"
},
agent: {
workspace: "~/work-clawd",
elevated: { enabled: false }
},
slack: {
enabled: true,
botToken: "xoxb-...",
channels: {
"#engineering": { allow: true, requireMention: true },
"#general": { allow: true, requireMention: true }
}
}
}
```
### Local models only
```json5
{
agent: {
workspace: "~/clawd",
model: { primary: "lmstudio/minimax-m2.1-gs32" }
},
models: {
mode: "merge",
providers: {
lmstudio: {
baseUrl: "http://127.0.0.1:1234/v1",
apiKey: "lmstudio",
api: "openai-responses",
models: [
{
id: "minimax-m2.1-gs32",
name: "MiniMax M2.1 GS32",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 196608,
maxTokens: 8192
}
]
}
}
}
}
```
## Tips
- If you set `dmPolicy: "open"`, the matching `allowFrom` list must include `"*"`.
- Provider IDs differ (phone numbers, user IDs, channel IDs). Use the provider docs to confirm the format.
- See [Providers](/providers/whatsapp) and [Troubleshooting](/gateway/troubleshooting) for deeper setup notes.

2
docs/gateway/configuration.md
View File

@@ -15,6 +15,8 @@ If the file is missing, CLAWDBOT uses safe-ish defaults (embedded Pi agent + per
- tune the embedded agent (`agent`) and session behavior (`session`) - tune the embedded agent (`agent`) and session behavior (`session`)
- set the agent's identity (`identity`) - set the agent's identity (`identity`)
> **New to configuration?** Check out the [Configuration Examples](/gateway/configuration-examples) guide for complete examples with detailed explanations!
## Schema + UI hints ## Schema + UI hints
The Gateway exposes a JSON Schema representation of the config via `config.schema` for UI editors. The Gateway exposes a JSON Schema representation of the config via `config.schema` for UI editors.

1
docs/index.md
View File

@@ -149,6 +149,7 @@ Example:
- [Docs hubs (all pages linked)](https://docs.clawd.bot/start/hubs) - [Docs hubs (all pages linked)](https://docs.clawd.bot/start/hubs)
- [FAQ](https://docs.clawd.bot/start/faq) ← *common questions answered* - [FAQ](https://docs.clawd.bot/start/faq) ← *common questions answered*
- [Configuration](https://docs.clawd.bot/gateway/configuration) - [Configuration](https://docs.clawd.bot/gateway/configuration)
- [Configuration examples](https://docs.clawd.bot/gateway/configuration-examples)
- [Slash commands](https://docs.clawd.bot/tools/slash-commands) - [Slash commands](https://docs.clawd.bot/tools/slash-commands)
- [Multi-agent routing](https://docs.clawd.bot/concepts/multi-agent) - [Multi-agent routing](https://docs.clawd.bot/concepts/multi-agent)
- [Updating / rollback](https://docs.clawd.bot/install/updating) - [Updating / rollback](https://docs.clawd.bot/install/updating)

1
docs/start/hubs.md
View File

@@ -17,6 +17,7 @@ Use these hubs to discover every page, including deep dives and reference docs t
- [Dashboard (local Gateway)](http://127.0.0.1:18789/) - [Dashboard (local Gateway)](http://127.0.0.1:18789/)
- [FAQ](https://docs.clawd.bot/start/faq) - [FAQ](https://docs.clawd.bot/start/faq)
- [Configuration](https://docs.clawd.bot/gateway/configuration) - [Configuration](https://docs.clawd.bot/gateway/configuration)
- [Configuration examples](https://docs.clawd.bot/gateway/configuration-examples)
- [Clawd (personal assistant)](https://docs.clawd.bot/start/clawd) - [Clawd (personal assistant)](https://docs.clawd.bot/start/clawd)
- [Showcase](https://docs.clawd.bot/start/showcase) - [Showcase](https://docs.clawd.bot/start/showcase)
- [Lore](https://docs.clawd.bot/start/lore) - [Lore](https://docs.clawd.bot/start/lore)