Security Best Practices

Running an AI assistant that can execute commands, read files, and browse the web requires serious security consideration. This guide covers essential hardening for your ClawBook instance, based on OpenClaw's official security recommendations.

The Security Mindset

When you give an AI model the ability to execute shell commands or read files, you're trusting it with significant power. OpenClaw mitigates this through:

Docker Sandboxing — Commands run in isolated containers
Pairing System — Only approved contacts can trigger the AI
Tool Restrictions — Dangerous tools can be disabled
Network Isolation — Gateway binds to localhost by default

No system is perfectly secure. The goal is to limit the blast radius if something goes wrong.

Quick Security Checklist

Complete these immediately after setup:

Run the security audit: openclaw security audit
Enable Docker sandboxing
Configure pairing for all channels
Restrict dangerous tools (exec, write, browser)
Set up firewall rules
Bind Gateway to loopback only
Verify file permissions

Docker Sandboxing

OpenClaw can run tool executions inside Docker containers, preventing a misbehaving AI from affecting your host system.

Enabling Sandboxing

# Enable sandbox for all tools
openclaw config set agents.defaults.sandbox.mode "all"

# Set isolation scope to per-agent (default)
openclaw config set agents.defaults.sandbox.scope "agent"

# Workspace access: none (most secure), ro (read-only), rw (read-write)
openclaw config set agents.defaults.sandbox.workspaceAccess "none"

Sandbox Modes

Mode	Description	Use Case
`all`	All tools run in Docker	Production, security-first
`dangerous`	Only shell/exec tools sandboxed	Balance of security and speed
`none`	No sandboxing (tools run on host)	Development only

Hardened Docker Configuration

ClawBook instances use a hardened Docker setup:

# Security options applied:
--security-opt=no-new-privileges  # No privilege escalation
--cap-drop=ALL                     # Drop all Linux capabilities
--read-only                        # Read-only root filesystem

This means even if the AI tries something malicious, it can't escape the container or escalate privileges.

Gateway Security

The Gateway is the nerve center of OpenClaw—it handles all incoming messages and outgoing responses.

Bind to Loopback Only

By default, ClawBook configures the Gateway to listen only on localhost:

# Verify binding
openclaw config get gateway.bind
# Should return: "loopback"

# If not, set it:
openclaw config set gateway.bind "loopback"

This means the Gateway only accepts connections from the same machine. To access the dashboard remotely, use SSH tunneling:

# On your local machine:
ssh -L 18789:localhost:18789 root@YOUR_SERVER_IP

# Then open: http://localhost:18789

Gateway Authentication

Enable token-based authentication for the Gateway:

# Generate a random token
TOKEN=$(openssl rand -base64 32)

# Set it in config
openclaw config set gateway.auth.mode "token"
openclaw config set gateway.auth.token "$TOKEN"

# Restart gateway
openclaw gateway restart

Pairing and Access Control

The pairing system is your first line of defense against unauthorized access.

DM Policies

Policy	Description	Security Level
`pairing`	Unknown senders get a code to approve	Recommended
`allowlist`	Only pre-approved contacts can chat	High security
`open`	Anyone can chat	Not recommended
`disabled`	Ignore all DMs	Maximum security

Configure per channel:

# WhatsApp
openclaw config set channels.whatsapp.dmPolicy "pairing"

# Telegram
openclaw config set channels.telegram.dmPolicy "pairing"

Managing the Allowlist

# View allowlist
cat ~/.openclaw/credentials/whatsapp-allowFrom.json

# Add a number to allowlist (example JSON format)
# ["+15551234567", "+15559876543"]

Group Chat Security

For groups, always require mentions:

openclaw config set channels.whatsapp.groups.*.requireMention true

This prevents the AI from responding to every message in a busy group.

Tool Restrictions

Some OpenClaw tools are high-risk. You can disable them entirely or restrict to certain agents.

High-Risk Tools

Tool	Risk	Recommendation
`exec` / `shell`	Arbitrary command execution	Sandbox + restrict
`write` / `edit`	File modification	Restrict or sandbox
`browser`	Web browsing, logged-in sessions	Dedicated profile
`web_fetch`	External requests	Monitor for prompt injection

Restricting Tools

Create a restricted agent profile:

{
  "agents": [{
    "id": "safe-assistant",
    "sandbox": {
      "mode": "all",
      "workspaceAccess": "ro"
    },
    "tools": {
      "deny": ["exec", "write", "edit", "shell", "browser"]
    }
  }]
}

Read-Only Agent Example

For maximum safety, create an agent that can only read and respond:

openclaw config set agents.readonly.sandbox.mode "all"
openclaw config set agents.readonly.sandbox.workspaceAccess "ro"
openclaw config set agents.readonly.tools.deny '["write", "edit", "exec", "process"]'

Firewall Configuration

ClawBook instances come with UFW pre-configured, but verify the rules:

# View current rules
sudo ufw status numbered

# Expected rules:
# 22/tcp    ALLOW IN  (SSH)
# 18789/tcp ALLOW IN  (OpenClaw Gateway - consider removing if using loopback)
# 80/tcp    ALLOW IN  (HTTP for Let's Encrypt)
# 443/tcp   ALLOW IN  (HTTPS)

Tightening Firewall Rules

If you're only accessing via SSH tunnel, you can block the Gateway port externally:

# Remove public Gateway access
sudo ufw delete allow 18789

# Gateway still works via localhost

Rate Limiting SSH

# Limit SSH to 6 connections per 30 seconds
sudo ufw limit ssh

Prompt Injection Awareness

Prompt injection is when malicious content tricks the AI into doing something unintended. Sources include:

Web pages fetched by web_fetch
Files read from untrusted sources
Messages from unknown users

Mitigations

Use modern, instruction-hardened models — Claude Opus 4.5 is notably resistant
Sandbox everything — Even if tricked, damage is contained
Disable tools you don't need — Reduce attack surface
Use separate agents for untrusted content — A "reader" agent with no tools summarizes content first

Example: Safe Web Research

{
  "agents": [{
    "id": "web-reader",
    "tools": {
      "allow": ["web_fetch"],
      "deny": ["exec", "write", "browser"]
    }
  }]
}

Browser Control Security

If you use browser automation, be aware that the AI can access any site you're logged into in that browser profile.

Recommendations

Use a dedicated browser profile (default: openclaw profile)
Never point the AI at your personal browser profile
Disable browser control for sandboxed agents unless necessary
Treat browser downloads as untrusted input

File Permissions

Verify permissions on sensitive files:

# Run the built-in audit
openclaw security audit --fix

# Expected permissions:
# ~/.openclaw/          drwx------ (700)
# ~/.openclaw/config    -rw------- (600)
# ~/.openclaw/credentials/*  -rw------- (600)

Credential Storage

Sensitive files and their locations:

File	Path	Contains
WhatsApp creds	`~/.openclaw/credentials/whatsapp/<id>/creds.json`	Session token
LLM auth	`~/.openclaw/agents/<id>/agent/auth-profiles.json`	API keys
Gateway config	`~/.openclaw/config.json`	Gateway token

Treat these files as highly sensitive. Don't expose them in logs or backups.

Security Audit Command

Run this regularly (especially after config changes):

# Basic audit
openclaw security audit

# Deep audit with network checks
openclaw security audit --deep

# Auto-fix permission issues
openclaw security audit --fix

Audit Checks

The audit verifies:

Inbound access policies (pairing, allowlists)
Tool permissions (high-risk tools in open channels)
Network exposure (bind mode, auth settings)
File permissions and symlink safety
Model selection (modern vs. legacy)

Incident Response

If you suspect a compromise:

1. Contain

# Stop the gateway immediately
openclaw gateway stop

# Block all inbound connections
sudo ufw default deny incoming

2. Rotate Credentials

# Change Gateway token
openclaw config set gateway.auth.token "$(openssl rand -base64 32)"

# Re-authenticate WhatsApp (invalidates old session)
openclaw channels logout whatsapp

# Rotate LLM API keys at provider console

3. Audit

# Check recent logs
openclaw logs --limit 500 | grep -i "exec\|write\|error"

# Review session transcripts
ls ~/.openclaw/agents/*/sessions/

# Check for config changes
git diff ~/.openclaw/config.json  # if version controlled

4. Report

Contact support@clawbook.io with:

Timestamp of suspected incident
Any unusual behavior observed
Relevant log excerpts

The Security Mindset​

Quick Security Checklist​

Docker Sandboxing​

Enabling Sandboxing​

Sandbox Modes​

Hardened Docker Configuration​

Gateway Security​

Bind to Loopback Only​

Gateway Authentication​

Pairing and Access Control​

DM Policies​

Managing the Allowlist​

Group Chat Security​

Tool Restrictions​

High-Risk Tools​

Restricting Tools​

Read-Only Agent Example​

Firewall Configuration​

Tightening Firewall Rules​

Rate Limiting SSH​

Prompt Injection Awareness​

Mitigations​

Example: Safe Web Research​

Browser Control Security​

Recommendations​

File Permissions​

Credential Storage​

Security Audit Command​

Audit Checks​

Incident Response​

1. Contain​

2. Rotate Credentials​

3. Audit​

4. Report​

Related Resources​