Configuration Guide

Configure Clawdbot to work exactly how you want

Minimal Configuration

Minimal ~/.clawdbot/clawdbot.json (model + defaults):

Configuration File 
{
  "agent": {
    "model": "anthropic/claude-opus-4-5"
  }
}

Model Selection & Authentication

Recommended: Anthropic Pro/Max (100/200) + Opus 4.5 for long-context strength and better prompt-injection resistance.

Subscriptions (OAuth):

  • Anthropic (Claude Pro/Max)
  • OpenAI (ChatGPT/Codex)

While any model is supported, Anthropic Pro/Max + Opus 4.5 is strongly recommended. You can configure model failover and auth profile rotation (OAuth vs API keys) with fallbacks.

Model configuration supports:

  • Multiple model providers (Anthropic, OpenAI, Gemini, local models)
  • Model failover for reliability
  • OAuth authentication for subscriptions
  • API key authentication
  • Profile rotation and fallbacks

    • Workspace & Skills

    Clawdbot stores all its data in a workspace directory:

  • Workspace root: ~/clawd (configurable via agents.defaults.workspace)
  • Injected prompt files: AGENTS.md, SOUL.md, TOOLS.md
  • Skills: ~/clawd/skills/<skill>/SKILL.md
  • Memory files: Daily notes formatted in Markdown that Clawdbot auto-generates each day

    • The workspace is just folders and Markdown files on your machine. You can edit them directly, search them with tools like Raycast, or integrate them with Obsidian.

    Security Model

    Important: Clawdbot connects to real messaging surfaces. Treat inbound DMs as untrusted input.

    Default Behavior

  • Default: Tools run on the host for the main session, so the agent has full access when it's just you.
  • Group/channel safety: Set agents.defaults.sandbox.mode: "non-main" to run non-main sessions (groups/channels) inside per-session Docker sandboxes; bash then runs in Docker for those sessions.

    • Sandbox Configuration

    Sandbox defaults:

  • Allowlist: bash, process, read, write, edit, sessions_list, sessions_history, sessions_send, sessions_spawn
  • Denylist: browser, canvas, nodes, cron, discord, gateway

    • Run clawdbot doctor to surface risky/misconfigured DM policies.

    Default DM Access (Security)

    Default behavior on Telegram/WhatsApp/Signal/iMessage/Microsoft Teams/Discord/Google Chat/Slack:

  • DM pairing (dmPolicy="pairing" / channels.discord.dm.policy="pairing" / channels.slack.dm.policy="pairing"): Unknown senders receive a short pairing code and the bot does not process their message.
  • Approve with: clawdbot pairing approve <channel> <code> (then the sender is added to a local allowlist store).
  • Public inbound DMs require an explicit opt-in: set dmPolicy="open" and include "*" in the channel allowlist (allowFrom / channels.discord.dm.allowFrom / channels.slack.dm.allowFrom).

    • Gateway Configuration

    The Gateway is the control plane for Clawdbot. Key configuration options:

  • Port: Default is 18789, configurable via gateway.port
  • Bind address: Default is 127.0.0.1 (loopback), configurable via gateway.bind
  • Tailscale: Configure gateway.tailscale.mode for Serve/Funnel access
  • Authentication: Set gateway.auth.mode for password or token auth

    • Agent Configuration

    Configure agent behavior and defaults:

  • Model: Set default model via agent.model
  • Thinking level: Configure thinking depth for GPT-5.2 + Codex models
  • Verbose mode: Enable detailed output
  • Session management: Configure session isolation, activation modes, queue modes

    • Next Steps