docs: add comprehensive configuration examples guide
This commit is contained in:
Dave Onkels
committed by
Peter Steinberger
Peter Steinberger
parent
3c20e72e33
commit
18c67ca831
@@ -570,6 +570,7 @@
|
||||
"gateway/pairing",
|
||||
"gateway/gateway-lock",
|
||||
"gateway/configuration",
|
||||
"gateway/configuration-examples",
|
||||
"gateway/background-process",
|
||||
"gateway/health",
|
||||
"gateway/heartbeat",
|
||||
|
||||
553
docs/gateway/configuration-examples.md
Normal file
553
docs/gateway/configuration-examples.md
Normal 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.
|
||||
@@ -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`)
|
||||
- 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
|
||||
|
||||
The Gateway exposes a JSON Schema representation of the config via `config.schema` for UI editors.
|
||||
|
||||
@@ -149,6 +149,7 @@ Example:
|
||||
- [Docs hubs (all pages linked)](https://docs.clawd.bot/start/hubs)
|
||||
- [FAQ](https://docs.clawd.bot/start/faq) ← *common questions answered*
|
||||
- [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)
|
||||
- [Multi-agent routing](https://docs.clawd.bot/concepts/multi-agent)
|
||||
- [Updating / rollback](https://docs.clawd.bot/install/updating)
|
||||
|
||||
@@ -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/)
|
||||
- [FAQ](https://docs.clawd.bot/start/faq)
|
||||
- [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)
|
||||
- [Showcase](https://docs.clawd.bot/start/showcase)
|
||||
- [Lore](https://docs.clawd.bot/start/lore)
|
||||
|
||||
Reference in New Issue
Block a user