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.
• Console output can be tuned separately via:
  • logging.consoleLevel (defaults to info, bumps to debug when --verbose)
  • logging.consoleStyle (pretty | compact | json)

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

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). You can switch to always-on activation.

{
  inbound: {
    groupChat: {
      activation: "mention", // mention | always
      mentionPatterns: ["@clawd", "clawdbot", "clawd"],
      historyLimit: 50
    }
  }
}

Notes:

• activation defaults to mention.
• requireMention is still supported for backwards compatibility (false ≈ activation: "always").

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"
    }
  }
}

skills (skill config/env)

Configure skill toggles and env injection. Applies to bundled skills and ~/.clawdis/skills (workspace skills still win on name conflicts).

Common fields per skill:

• enabled: set false to disable a skill even if it’s bundled/installed.
• env: environment variables injected for the agent run (only if not already set).
• apiKey: optional convenience for skills that declare a primary env var (e.g. nano-banana-pro → GEMINI_API_KEY).

Example:

{
  skills: {
    "nano-banana-pro": {
      apiKey: "GEMINI_KEY_HERE",
      env: {
        GEMINI_API_KEY: "GEMINI_KEY_HERE"
      }
    },
    peekaboo: { enabled: true },
    sag: { enabled: false }
  }
}

skillsInstall (installer preference)

Controls which installer is surfaced by the macOS Skills UI when a skill offers multiple install options. Defaults to brew when available and npm for node installs.

{
  skillsInstall: {
    preferBrew: true,
    nodeManager: "npm" // npm | pnpm | yarn
  }
}

skillsLoad

Additional skill directories to scan (lowest precedence). This is useful if you keep skills in a separate repo but want Clawdis to pick them up without copying them into the workspace.

{
  skillsLoad: {
    extraDirs: [
      "~/Projects/agent-scripts/skills",
      "~/Projects/oss/some-skill-pack/skills"
    ]
  }
}

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,
  }
}

gateway (Gateway server mode + bind)

Use gateway.mode to explicitly declare whether this machine should run the Gateway.

Defaults:

• mode: unset (treated as “do not auto-start”)
• bind: loopback

{
  gateway: {
    mode: "local", // or "remote"
    bind: "loopback",
    // controlUi: { enabled: true }
    // auth: { mode: "token" | "password" | "system" }
    // tailscale: { mode: "off" | "serve" | "funnel" }
  }
}

Notes:

• clawdis gateway refuses to start unless gateway.mode is set to local (or you pass the override flag).

Auth and Tailscale:

• gateway.auth.mode sets the handshake requirements (token, password, or system/PAM).
• When gateway.auth.mode is set, only that method is accepted (plus optional Tailscale headers).
• gateway.auth.password can be set here, or via CLAWDIS_GATEWAY_PASSWORD (recommended).
• gateway.auth.username defaults to the current OS user; override with CLAWDIS_GATEWAY_USERNAME.
• gateway.auth.allowTailscale controls whether Tailscale identity headers can satisfy auth.
• gateway.tailscale.mode: "serve" uses Tailscale Serve (tailnet only, loopback bind).
• gateway.tailscale.mode: "funnel" exposes the dashboard publicly; requires auth.
• gateway.tailscale.resetOnExit resets Serve/Funnel config on shutdown.

canvasHost (LAN/tailnet Canvas file server + live reload)

The Gateway serves a directory of HTML/CSS/JS over HTTP so iOS/Android nodes can simply canvas.navigate to it.

Default root: ~/clawd/canvas
Default port: 18793 (chosen to avoid the clawd browser CDP port 18792)
The server listens on the bridge bind host (LAN or Tailnet) so nodes can reach it.

The server:

• serves files under canvasHost.root
• injects a tiny live-reload client into served HTML
• watches the directory and broadcasts reloads over a WebSocket endpoint at /__clawdis/ws
• auto-creates a starter index.html when the directory is empty (so you see something immediately)
• also serves A2UI at /__clawdis__/a2ui/ and is advertised to nodes as canvasHostUrl (always used by nodes for Canvas/A2UI)

{
  canvasHost: {
    root: "~/clawd/canvas",
    port: 18793
  }
}

Disable with:

• config: canvasHost: { enabled: false }
• env: CLAWDIS_SKIP_CANVAS_HOST=1

bridge (node bridge server)

The Gateway can expose a simple TCP bridge for nodes (iOS/Android), typically on port 18790.

Defaults:

• enabled: true
• port: 18790
• bind: lan (binds to 0.0.0.0)

Bind modes:

• lan: 0.0.0.0 (reachable on any interface, including LAN/Wi‑Fi and Tailscale)
• tailnet: bind only to the machine’s Tailscale IP (recommended for Vienna ⇄ London)
• loopback: 127.0.0.1 (local only)
• auto: prefer tailnet IP if present, else lan

{
  bridge: {
    enabled: true,
    port: 18790,
    bind: "tailnet"
  }
}

discovery.wideArea (Wide-Area Bonjour / unicast DNS‑SD)

When enabled, the Gateway writes a unicast DNS-SD zone for _clawdis-bridge._tcp under ~/.clawdis/dns/ using the standard discovery domain clawdis.internal.

To make iOS/Android discover across networks (Vienna ⇄ London), pair this with:

• a DNS server on the gateway host serving clawdis.internal. (CoreDNS is recommended)
• Tailscale split DNS so clients resolve clawdis.internal via that server

One-time setup helper (gateway host):

clawdis dns setup --apply

{
  discovery: { wideArea: { enabled: true } }
}

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 🦞