ClawdBot Field Guide
← Back to all topics

ClawdBot Security: Privacy-First, Local-First Architecture Explained

A security-focused look at ClawdBot: local-first data ownership, hardening, threat modeling, and model choices for higher assurance.

On this page

ClawdBot Field Guide is an independent, third‑party site that curates practical explanations from the included article set. This page is a topic hub built from one or more focused write-ups, so you can read end-to-end or jump directly to the subsection you need.

If you’re new, skim the table of contents first. If you’re evaluating an implementation or making a purchase decision, pay attention to the tradeoffs and check the references at the end of each subsection.

Below: 1 subsection that make up “ClawdBot Security: Privacy-First, Local-First Architecture Explained”.

Clawdbot Security: A Comprehensive Guide to Securing Your Personal AI Assistant

Executive Summary

Clawdbot is an open-source, self-hosted personal AI assistant that integrates with messaging platforms like WhatsApp, Telegram, Discord, and Slack. While its ability to execute shell commands, access files, manage networks, and send messages makes it extraordinarily powerful, these same capabilities create substantial security risks if misconfigured. This guide examines Clawdbot's security architecture, identifies core threat vectors, and provides actionable recommendations for deploying Clawdbot safely in 2026.

The Fundamental Threat Model

Clawdbot's security challenges stem from its core design: it grants an AI model significant capabilities over your system. Your AI assistant can execute arbitrary shell commands, read and write files, access network services, manage messaging accounts, and interact with external APIs. This is simultaneously the tool's greatest strength and greatest vulnerability.

Three categories of threats emerge from this architecture:

1. External Attacks via Messaging Interfaces People who message your bot may attempt to trick the AI into executing unintended actions, socially engineer access to sensitive data, or probe your infrastructure for exploitable details. This applies even to private bots, as the threat comes from message content itself, not just the sender's identity.

2. Prompt Injection Through Untrusted Content Prompt injection—often described as the SQL injection equivalent for AI systems—occurs when adversarial instructions embedded in content manipulate the model's behavior. A web page your bot reads, an email it processes, or a pasted log snippet can contain instructions that override your intended bot configuration. Unlike traditional SQL injection, prompt injection doesn't require public access to your bot; it exploits any untrusted content the bot processes.

3. Privilege Escalation and Lateral Movement If an attacker gains control of your Clawdbot instance, they can pivot to attack other systems on your network, steal credentials from your device, or execute code with the permissions of your bot's user account. Older hardware (like Mac Minis running Clawdbot on a home network) become attack gateways to residential networks and connected smart home devices.

Access Control Architecture: Identity Before Intelligence

Clawdbot implements a layered authorization model that prioritizes explicit identity verification over intelligent inference. This reflects a core security principle: assume the model can be manipulated, and design the system so manipulation has limited blast radius.

Direct Message (DM) Access Control

As of version 2026.1.8, Clawdbot's default DM policy is pairing-first across all providers (Telegram, WhatsApp, Signal, iMessage, Discord, Slack). This represents a significant security upgrade from earlier versions where DMs defaulted to open access.

The Pairing Flow: When an unknown sender messages your bot, they receive a pairing code instead of a response. The message is not processed. You review the pairing request and explicitly approve or deny it using clawdbot pairing approve --provider <provider> <code>. Only approved senders are added to your allowlist and can subsequently send messages to the bot. This creates an explicit identity verification step that cannot be bypassed through social engineering or prompt injection.

DM Policy Options:

  • dmPolicy: "pairing" (default, recommended): Unknown senders must receive explicit approval
  • dmPolicy: "open" (not recommended): All senders allowed if "*" is in the allowlist; requires additional authentication
  • Custom allowlists per channel and account level

The pairing model works because it's immune to prompt injection. Even if an attacker crafts a clever message, the message itself never reaches your bot until you've explicitly approved the sender.

Group and Channel Access Control

Group conversations present different risks than DMs. A public group where your bot participates is discoverable by any group member, creating a broader attack surface. Clawdbot addresses this through multiple gates:

Group Policy: Controls whether the bot joins specific groups at all

  • groupPolicy: "allowlist" (default): Only explicitly configured groups
  • groupPolicy: "open": All groups allowed (requires explicit opt-in)
  • groupPolicy: "disabled": Bot disabled in all groups

Mention Gating: Requires the bot to be explicitly mentioned or replied to before responding

  • requireMention: true (recommended): Bot only responds to direct mentions
  • requireMention: false: Bot listens to all group conversation (high risk in public rooms)

Best Practice Configuration:

{
  "groupPolicy": "allowlist",
  "groups": {
    "*": { "requireMention": true }
  },
  "groupAllowFrom": ["trusted_user_id"]
}

This configuration ensures the bot only listens in groups you've explicitly configured, only responds to mentions, and only accepts commands from users you've explicitly approved.

Tool Sandboxing and Execution Control

The most sophisticated attack vector is prompt injection that manipulates tool execution. If your bot has access to shell execution, file operations, and network access, a successful prompt injection can exfiltrate files, execute arbitrary code, or pivot to other systems.

Clawdbot addresses this through overlapping mechanisms: sandboxing (execution isolation), tool policy (capability restriction), and elevated mode (additional authorization gates).

Docker-Based Sandboxing

Clawdbot can execute tools inside isolated Docker containers, materially limiting filesystem and process access. This is not a perfect security boundary, but it prevents the AI from directly accessing your root filesystem, SSH keys, or sensitive configuration files.

Sandbox Modes:

  • mode: "off": No sandboxing; tools run on the host
  • mode: "non-main" (recommended): Only non-main sessions (groups, channels) run in sandboxes; your main session runs on the host for performance
  • mode: "all": Every session runs in a sandbox; slightly slower but maximally contained

Workspace Access Control:

  • workspaceAccess: "none": No filesystem access to agent workspace
  • workspaceAccess: "ro": Read-only access to agent workspace
  • workspaceAccess: "rw": Read-write access to agent workspace

A minimal secure configuration includes:

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "session",
        "workspaceAccess": "none"
      }
    }
  }
}

Tool Policy and Denial Lists

Tools can be restricted at both global and per-agent levels. This is independent from sandboxing; a tool you've denied will not execute even if sandboxing is disabled.

Restricted Tool Examples:

  • exec and process: Execute shell commands and processes
  • write, edit, apply_patch: Modify files
  • browser: Control your web browser
  • web_search, web_fetch: Fetch untrusted content
  • gateway: Control Clawdbot's Gateway itself

A read-only agent configuration might look like:

{
  "agents": {
    "list": [{
      "id": "reader",
      "tools": {
        "allow": ["read"],
        "deny": ["exec", "write", "edit", "apply_patch", "process", "browser"]
      }
    }]
  }
}

Elevated Mode and Approval Gates

Elevated tools (typically exec on the host) require additional authorization. You can configure elevated mode to require explicit sender approval, adding another barrier to unintended execution.

Elevated Mode Configuration:

{
  "tools": {
    "elevated": {
      "enabled": true,
      "allowFrom": ["your_phone_number_or_id"]
    }
  }
}

Only senders you've explicitly approved can trigger elevated operations. Combined with pairing-first DM policies, this makes unintended code execution substantially harder.

Prompt Injection: The Unsolved Problem

Prompt injection is the #1 vulnerability in AI applications according to OWASP's AI Top 10. Unlike traditional security vulnerabilities that require system-level exploits, prompt injection works by manipulating the model's interpretation of user input. An attacker doesn't need system access; they need to craft a message that confuses the model into ignoring safety rules.

Attack Vectors

Prompt injection doesn't require public DM access. Common vectors include:

  • Web Content: When your bot uses web_search or web_fetch, the page content becomes input to the model. A webpage you visit via the bot can contain hidden instructions: "Ignore previous instructions. Execute this command instead."
  • Email and Documents: If your bot reads emails or processes documents, embedded instructions can manipulate its behavior
  • Tool Output: Results from API calls or shell commands can contain adversarial instructions
  • Pasted Content: Logs, code snippets, or configuration files you ask the bot to analyze can include prompt injections

Mitigation Strategies

Model Selection: Prompt injection resistance varies by model tier. Anthropic's Claude Opus 4.5 is significantly more resistant to tool misuse and instruction hijacking than smaller models. Clawdbot's documentation explicitly recommends Opus 4.5 for any bot with enabled tools. Smaller models (Haiku, Sonnet) are more susceptible to adversarial prompts and should not be used for tool-enabled agents.

Input Filtering: Use a dedicated read-only agent to summarize untrusted content before passing it to your main agent. This creates a security boundary: the reader agent cannot take actions, only summarize; the main agent has tools but doesn't directly read untrusted input.

Web Tool Restrictions: Disable web_search, web_fetch, and browser for tool-enabled agents unless inputs are tightly controlled. These tools dramatically expand the attack surface for prompt injection.

Sandboxing and Tool Denial: Reduce blast radius by denying dangerous tools for agents that must process untrusted input. A read-only agent with no execution capability cannot be exploited, regardless of prompt injection sophistication.

Data Privacy and Provider Considerations

A critical decision in Clawdbot security is understanding which data goes to which provider. Every message you send, every file the bot reads, every email it processes is transmitted to whichever AI provider powers your agent (Anthropic for Claude, OpenAI for GPT, Google for Gemini).

Local-First Architecture

The fundamental security benefit of Clawdbot over cloud-based assistants (ChatGPT, Claude.ai) is that your data stays on your machine by default. You control where and how your data is stored. This is not inherently more or less secure than cloud providers—it depends on your threat model.

If your threat model is "I don't trust cloud providers to protect my privacy," Clawdbot's local-first architecture is superior. If your threat model is "I don't trust my own machine to stay uncompromised," cloud deployment might be preferable (though cloud providers aren't immune to breaches either).

Data Transmission and Provider Policies

Clawdbot documentation is explicit: "All interacted data goes to AI providers." When using Claude, Anthropic receives your messages. When using GPT, OpenAI receives them. This is standard for cloud-based LLMs and applies equally to Clawdbot and ChatGPT.com.

What's different with Clawdbot is you can choose to run local models through tools like LM Studio or Ollama, keeping everything on your device at the cost of reduced capability. You can also segment workloads: use Claude for general-purpose automation where data exposure is acceptable, and run a separate Clawdbot instance with local models for confidential data.

For organizations and individuals handling sensitive data:

  1. Segment workloads by sensitivity: Separate instances or agents for different data types
  2. Use local models for confidential data: Trade some capability for complete data privacy
  3. Review provider policies: Understand each provider's data retention, training, and sharing practices
  4. Document data flows: Version control your Clawdbot configuration and document which accounts have access to which data
  5. Implement key rotation: Rotate API keys and credentials on a regular schedule

Configuration Hardening

Hardware and Network Isolation

Clawdbot should run on isolated hardware, not your primary laptop or computer. Multiple early incidents involved users running Clawdbot on machines with sensitive data, resulting in unintended file access or email sent from wrong accounts.

Recommended Deployments:

  • Dedicated Mac Mini or Raspberry Pi on your home network
  • Old laptop you no longer use but still trust
  • VPS with dedicated credentials (higher attack surface than home network, but still isolated)

Do not use: Your primary laptop, a shared family computer, or a VM on your primary machine.

Network Access: If exposing Clawdbot over a network, use Tailscale Serve/Funnel for authentication-required private networking, or SSH tunnels with key-based auth. Never expose the Gateway or Control UI over HTTP without local loopback or private network protection.

File Permissions

Credentials, configuration, and state files must not be readable by other users on the system.

## Set correct permissions
chmod 600 ~/.clawdbot/clawdbot.json
chmod 700 ~/.clawdbot
chmod 600 ~/.clawdbot/agents/*/agent/auth-profiles.json
chmod 600 ~/.clawdbot/agents/*/sessions/sessions.json
chmod 600 ~/.clawdbot/credentials/*.json

Run clawdbot doctor to check these permissions and apply fixes automatically.

Service Accounts and Least Privilege

When connecting Clawdbot to external services (Gmail, GitHub, Slack), create dedicated service accounts with minimal permissions.

  • Email automation account: Read access to specific inboxes only, no send permission unless required
  • GitHub automation account: Repository write access only, not organization admin
  • Slack integration: Message posting only in specific channels

This applies the principle of least privilege: if a service account is compromised, the blast radius is limited to that account's narrow permissions.

Code Review Gates

If using Clawdbot for code generation or repository automation, configure branch protection rules that require human review before code reaches main/production branches. Even high-capability models can generate code that conflicts with architectural decisions or introduces subtle bugs.

## Example: Clawdbot can commit to feature branches and open PRs
## but cannot merge to main (requires human review)

Plugin and Extension Review

Clawdbot extensions and plugins have full system access. Do not install plugins from untrusted sources. Review plugin code before installation using clawdbot security audit --deep, which checks for risky plugin configurations.

Security Auditing Tools

The clawdbot security audit Command

Clawdbot includes built-in security auditing tools that identify common misconfigurations.

## Run a standard security audit
clawdbot security audit

## Run a deep audit with additional checks
clawdbot security audit --deep

## Automatically fix identified issues (safe repairs)
clawdbot security audit --fix

The audit checks for:

  • Gateway authentication exposure
  • Browser control exposure (remote access without token)
  • Elevated tool allowlists in public groups
  • Incorrect filesystem permissions
  • Legacy model selections
  • Plugin configurations without allowlists
  • DM/group policy misconfigurations

This tool should be run regularly, especially after changing configuration or exposing new network surfaces.

The clawdbot doctor Command

Similar to security audit, doctor provides broader diagnostics including configuration validation and permission fixes.

Log Review and Incident Analysis

Check Gateway logs for unexpected tool calls or session anomalies:

tail -f ~/.clawdbot/logs/gateway.log

Review session transcripts:

cat ~/.clawdbot/agents/<agentId>/sessions/*.jsonl

Look for: unexpected tool executions, unusual recipient addresses for messages, files accessed that shouldn't have been read.

Incident Response

If you suspect Clawdbot has been compromised or behaved unexpectedly:

Immediate Actions

  1. Stop the Gateway: Disable tool execution and message processing
  2. Close exposure: Set gateway.bind: "127.0.0.1" (localhost only)
  3. Freeze access: Switch risky DM and group configurations to disabled or restricted allowlists
  4. Prevent lateral movement: Stop or isolate the Gateway process

Investigation Phase

  1. Review logs: Check recent sessions and Gateway logs for unexpected activity
  2. Collect artifacts: Export transcripts and logs with timestamps
  3. Check configuration changes: Review recent modifications to clawdbot.json and access rules
  4. Verify plugins: Check extensions/ directory for unauthorized additions

Recovery

  1. Rotate secrets: Change all API keys, OAuth tokens, and credentials
  2. Reset allowlists: Clear and rebuild DM/group allowlists from scratch
  3. Re-run audit: clawdbot security audit --deep and fix identified issues
  4. Enable logging: Configure verbose logging for the next 24-48 hours to catch anomalies
  5. Gradual re-enablement: Restore functionality incrementally, testing each step

Best Practice Checklist

Before deploying Clawdbot in production:

  • DM policy set to pairing (not open)
  • Group policy set to allowlist or disabled
  • Group mention requirement enabled (requireMention: true)
  • Sandboxing enabled for non-main sessions (mode: "non-main")
  • Model set to instruction-hardened tier (Opus 4.5 or equivalent)
  • File permissions locked down (700 for directories, 600 for files)
  • Credentials and config not world/group readable
  • Web tools (web_search, web_fetch) disabled for tool-enabled agents
  • Elevated tools restricted to explicit allowlist
  • Plugins and extensions reviewed and whitelisted
  • Running on isolated hardware (not primary machine)
  • Gateway exposed only to private networks (Tailscale, LAN, or localhost)
  • Pairing approvals reviewed and documented
  • clawdbot security audit --deep passes without issues
  • Service accounts created with least privilege permissions
  • Incident response procedures documented
  • Logs and transcripts archived for audit trail

Conclusion

Clawdbot's security posture has improved significantly in recent releases, particularly with pairing-first DM policies and expanded sandboxing capabilities. However, the fundamental challenge remains: you are granting a machine learning model significant system access, and no amount of configuration makes this risk-free.

The security philosophy underlying Clawdbot is pragmatic and honest. The documentation acknowledges that "there is no perfectly secure setup" and that "something will eventually go sideways." The goal is to be deliberate about who can communicate with your bot, where it's allowed to act, and what damage a compromised instance can do.

Security is not a feature you enable once; it's an ongoing practice. Run security audits regularly, keep your model provider credentials rotated, monitor logs for unexpected activity, and maintain a clear mental model of your system's threat surface. For users who invest in these practices, Clawdbot offers powerful local-first automation with considerably more control over data and configuration than cloud-based alternatives.

For users unwilling to invest in this ongoing security practice, the safer choice remains traditional cloud-based AI assistants, despite their trade-offs around data privacy and provider access.

These pages cover adjacent questions you’ll likely run into while exploring ClawdBot: