clawdbot/docs/configuration.md

summary, read_when

summary	read_when
All configuration options for ~/.clawdis/clawdis.json with examples	Adding or modifying config fields

Configuration 🔧

CLAWDIS reads an optional JSON5 config from ~/.clawdis/clawdis.json (comments + trailing commas allowed).

If the file is missing, CLAWDIS uses safe-ish defaults (embedded Pi agent + per-sender sessions + workspace ~/clawd). You usually only need a config to:

• restrict who can trigger the bot (inbound.allowFrom)
• tune group mention behavior (inbound.groupChat)
• set the agent’s workspace (inbound.workspace)
• tune the embedded agent (inbound.agent) and session behavior (inbound.session)
• set the agent’s identity (identity)

Minimal config (recommended starting point)

{
  inbound: {
    allowFrom: ["+15555550123"],
    workspace: "~/clawd"
  }
}

Common options

identity

Optional agent identity used for defaults and UX. This is written by the macOS onboarding assistant.

If set, CLAWDIS derives defaults (only when you haven’t set them explicitly):

• inbound.responsePrefix from identity.emoji
• inbound.groupChat.mentionPatterns from identity.name (so “@Samantha” works in groups)

{
  identity: { name: "Samantha", theme: "helpful sloth", emoji: "🦥" }
}

logging

• Default log file: /tmp/clawdis/clawdis-YYYY-MM-DD.log
• If you want a stable path, set logging.file to /tmp/clawdis/clawdis.log.

{
  logging: { level: "info", file: "/tmp/clawdis/clawdis.log" }
}

inbound.allowFrom

Allowlist of E.164 phone numbers that may trigger auto-replies.

{
  inbound: { allowFrom: ["+15555550123", "+447700900123"] }
}

inbound.groupChat

Group messages default to require mention (either metadata mention or regex patterns).

{
  inbound: {
    groupChat: {
      requireMention: true,
      mentionPatterns: ["@clawd", "clawdbot", "clawd"],
      historyLimit: 50
    }
  }
}

inbound.workspace

Sets the single global workspace directory used by the agent for file operations.

Default: ~/clawd.

{
  inbound: { workspace: "~/clawd" }
}

inbound.agent

Controls the embedded agent runtime (provider/model/thinking/verbose/timeouts).

{
  inbound: {
    workspace: "~/clawd",
    agent: {
      provider: "anthropic",
      model: "claude-opus-4-5",
      thinkingDefault: "low",
      verboseDefault: "off",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      heartbeatMinutes: 30,
      contextTokens: 200000
    }
  }
}

inbound.session

Controls session scoping, idle expiry, reset triggers, and where the session store is written.

{
  inbound: {
    session: {
      scope: "per-sender",
      idleMinutes: 60,
      resetTriggers: ["/new"],
      store: "~/.clawdis/sessions/sessions.json",
      mainKey: "main"
    }
  }
}

browser (clawd-managed Chrome)

Clawdis can start a dedicated, isolated Chrome/Chromium instance for clawd and expose a small loopback control server.

Defaults:

• enabled: true
• control URL: http://127.0.0.1:18791 (CDP uses 18792)
• profile color: #FF4500 (lobster-orange)
• Note: the control server is started by the running gateway (Clawdis.app menubar, or clawdis gateway).

{
  browser: {
    enabled: true,
    controlUrl: "http://127.0.0.1:18791",
    color: "#FF4500",
    // Advanced:
    // headless: false,
    // attachOnly: false,
  }
}

Template variables

Template placeholders are expanded in inbound.transcribeAudio.command (and any future templated command fields).

Variable	Description
{{Body}}	Full inbound message body
{{BodyStripped}}	Body with group mentions stripped (best default for agents)
{{From}}	Sender identifier (E.164 for WhatsApp; may differ per surface)
{{To}}	Destination identifier
{{MessageSid}}	Provider message id (when available)
{{SessionId}}	Current session UUID
{{IsNewSession}}	"true" when a new session was created
{{MediaUrl}}	Inbound media pseudo-URL (if present)
{{MediaPath}}	Local media path (if downloaded)
{{MediaType}}	Media type (image/audio/document/…)
{{Transcript}}	Audio transcript (when enabled)
{{ChatType}}	"direct" or "group"
{{GroupSubject}}	Group subject (best effort)
{{GroupMembers}}	Group members preview (best effort)
{{SenderName}}	Sender display name (best effort)
{{SenderE164}}	Sender phone number (best effort)
{{Surface}}	Surface hint (whatsapp

Cron (Gateway scheduler)

Cron is a Gateway-owned scheduler for wakeups and scheduled jobs. See Cron + wakeups for the full RFC and CLI examples.

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2
  }
}

---

Next: Agent Runtime 🦞