How do I install the Clawdbot Config skill?

Run npx skillmds@latest add diegosouzapw/clawdbot-config in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Clawdbot Config skill do?

Comprehensive Clawdbot configuration and skills system management. Use when working with Clawdbot setup, configuration files, creating/modifying AgentSkills-compatible skills with YAML frontmatter, troubleshooting agent behavior, managing channels, workspace, sandbox, or multi-agent routing. It is listed under AI & ML on SkillMD.

Is Clawdbot Config safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: CAUTION, Skill Scanner: PASS. Capability flags: makes network calls, reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Clawdbot Config?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Clawdbot Config free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Clawdbot Config?

diegosouzapw (@diegosouzapw) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Clawdbot Config by diegosouzapw — Agent Skill

Name: Clawdbot Config
Rating: 4.2 (5 reviews)
Author: diegosouzapw

Clawdbot Configuration Expert

Expert guidance for Clawdbot's configuration system, skills management, and agent setup.

When to Use This Skill

Use this skill when you need to:

Configure Clawdbot: Set up ~/.clawdbot/clawdbot.json with agents, channels, gateway, or tools
Create Skills: Build AgentSkills-compatible SKILL.md with proper YAML frontmatter and metadata
Manage Skills: Configure skill loading, gating, environment injection, or installation
Troubleshoot: Diagnose configuration issues, skill loading problems, or agent behavior
Understand System: Learn about workspace structure, bootstrap files, or session management
Deep Dive: Access complete documentation archive (370+ files) for channels, automation, webhooks, cron jobs, gateway protocols, platform-specific guides, and advanced features

Quick Decision Tree

Need to configure Clawdbot?
├─ Setting up for first time? → See "Quick Start Guide"
├─ Managing skills? → See "Skills Management"
├─ Configuring channels? → See "Channel Configuration"
├─ Setting up remote access? → See "Remote Gateway Setup"
└─ Creating a skill? → See "Creating Skills"

Need examples?
└─ See references/config-examples.md for common patterns

Need deep documentation?
├─ Channel-specific setup? → See references/repomix-output.xml (channels/)
├─ Automation (cron, webhooks)? → See references/repomix-output.xml (automation/)
├─ Gateway protocols? → See references/repomix-output.xml (gateway/)
├─ Platform guides? → See references/repomix-output.xml (platforms/)
└─ CLI reference? → See references/repomix-output.xml (cli/)

Quick Start Guide

Initial Setup

Create minimal config (~/.clawdbot/clawdbot.json):

{
  "agents": {
    "defaults": {
      "workspace": "~/Projects/my-agent-workspace"
    }
  },
  "channels": {
    "whatsapp": {
      "allowFrom": ["+1555555YOUR_NUMBER"]
    }
  }
}

Initialize workspace:

clawdbot setup

This creates bootstrap files:

AGENTS.md - Operating instructions
SOUL.md - Persona and boundaries
TOOLS.md - Tool usage notes
IDENTITY.md - Agent identity
USER.md - User profile

Pair WhatsApp:

clawdbot channels login

Start gateway:

clawdbot gateway

Configuration File Location

Primary: ~/.clawdbot/clawdbot.json
Override: CLAWDBOT_CONFIG_PATH environment variable
Format: JSONC (JSON with Comments)

Core Configuration Areas

1. Agents Configuration

Controls the embedded agent runtime.

Minimal:

{
  "agents": {
    "defaults": {
      "workspace": "~/Projects/my-workspace",
      "model": "anthropic/claude-sonnet-4"
    }
  }
}

With sandbox:

{
  "agents": {
    "defaults": {
      "workspace": "~/Projects/my-workspace",
      "sandbox": {
        "enabled": true,
        "docker": {
          "image": "clawdbot/sandbox:latest",
          "setupCommand": "apt-get update && apt-get install -y python3-pip",
          "env": {
            "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}"
          }
        }
      }
    }
  }
}

Key fields:

workspace (required): Agent's working directory
model: Primary model (format: provider/model)
sandbox: Docker isolation configuration
blockStreamingDefault: Streaming behavior ("on" | "off")

See references/config-schema.md for complete options.

2. Skills Configuration

Manage skill loading, filtering, and configuration.

Basic:

{
  "skills": {
    "allowBundled": ["gemini", "browser"],
    "entries": {
      "gemini": {
        "enabled": true,
        "apiKey": "${GEMINI_API_KEY}"
      }
    }
  }
}

Advanced:

{
  "skills": {
    "load": {
      "extraDirs": ["~/Projects/custom-skills/skills"],
      "watch": true,
      "watchDebounceMs": 250
    },
    "install": {
      "preferBrew": true,
      "nodeManager": "pnpm"
    },
    "entries": {
      "nano-banana-pro": {
        "enabled": true,
        "apiKey": "${GEMINI_API_KEY}",
        "config": {
          "model": "gemini-3-pro-image"
        }
      }
    }
  }
}

Skill precedence (highest to lowest):

<workspace>/skills
~/.clawdbot/skills
skills.load.extraDirs
Bundled skills

See references/skills-system.md for complete skills documentation.

3. Channels Configuration

Configure WhatsApp, Telegram, Discord, iMessage, and other channels.

WhatsApp:

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "allowFrom": ["+15555550123"],
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

Multi-channel:

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+15555550123"]
    },
    "telegram": {
      "enabled": true,
      "botToken": "${TELEGRAM_BOT_TOKEN}",
      "allowFrom": ["alice", "bob"]
    },
    "discord": {
      "enabled": true,
      "botToken": "${DISCORD_BOT_TOKEN}"
    }
  }
}

4. Gateway Configuration

WebSocket server and remote access.

Local (default):

{
  "gateway": {
    "port": 18789,
    "host": "127.0.0.1"
  }
}

Remote (Tailscale):

{
  "gateway": {
    "port": 18789,
    "bind": "tailnet",
    "auth": {
      "token": "${GATEWAY_AUTH_TOKEN}"
    }
  }
}

Start with:

clawdbot gateway --bind tailnet --token $GATEWAY_AUTH_TOKEN

5. Tools Configuration

Control tool behavior and permissions.

{
  "tools": {
    "exec": {
      "security": "ask",  // "allow" | "ask" | "deny"
      "applyPatch": true
    },
    "browser": {
      "enabled": true,
      "profilePath": "~/.clawdbot/browser-profile"
    }
  }
}

Skills Management

Creating a Skill

Skill structure:

my-skill/
├── SKILL.md          (required: frontmatter + instructions)
├── scripts/          (optional: executable code)
├── references/       (optional: detailed docs)
└── assets/           (optional: templates, files)

SKILL.md format:

---
name: my-skill
description: What the skill does and when to use it. Be specific about triggers.
metadata: {"clawdbot":{"requires":{"bins":["python3"],"env":["MY_API_KEY"]},"primaryEnv":"MY_API_KEY"}}
---

# My Skill

## Quick Start

Instructions for using this skill...

## Resources

Scripts: {baseDir}/scripts/process.py

Metadata for gating:

{
  "clawdbot": {
    "emoji": "🔧",
    "requires": {
      "bins": ["python3", "pip"],
      "anyBins": ["npm", "pnpm"],
      "env": ["MY_API_KEY"],
      "config": ["browser.enabled"]
    },
    "primaryEnv": "MY_API_KEY",
    "os": ["darwin", "linux"],
    "install": [
      {
        "id": "brew",
        "kind": "brew",
        "formula": "my-tool",
        "bins": ["my-tool"],
        "label": "Install My Tool (brew)"
      }
    ]
  }
}

Key principles:

description is the primary trigger mechanism
Metadata enables load-time filtering
Keep SKILL.md concise; use references/ for details
Test scripts by actually running them

Skill Locations

Per-agent (highest precedence):

<workspace>/skills/my-skill/SKILL.md

Shared (all agents):

~/.clawdbot/skills/my-skill/SKILL.md

Custom folders:

{
  "skills": {
    "load": {
      "extraDirs": ["~/Projects/custom-skills/skills"]
    }
  }
}

Configuring Skills

Enable/disable and provide API keys:

{
  "skills": {
    "entries": {
      "my-skill": {
        "enabled": true,
        "apiKey": "${MY_API_KEY}",
        "env": {
          "MY_API_KEY": "${MY_API_KEY}",
          "MY_ENDPOINT": "https://api.example.com"
        }
      },
      "disabled-skill": {
        "enabled": false
      }
    }
  }
}

Bundled skills allowlist:

{
  "skills": {
    "allowBundled": ["gemini", "browser", "peekaboo"]
  }
}

Skills in Sandbox

When agent is sandboxed, skills run inside Docker.

Requirements:

Binaries checked on host at load time
Binaries must exist in container at runtime
Install via setupCommand:

{
  "agents": {
    "defaults": {
      "sandbox": {
        "docker": {
          "setupCommand": "apt-get update && apt-get install -y python3-pip && pip3 install ruff",
          "env": {
            "GEMINI_API_KEY": "${GEMINI_API_KEY}"
          }
        }
      }
    }
  }
}

Important: Global skills.entries.<skill>.env applies to host runs only. Use sandbox.docker.env for container.

Channel Configuration

Basic:

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "allowFrom": ["+15555550123"]
    }
  }
}

With groups:

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+15555550123", "+15555550124"],
      "groups": {
        "*": { 
          "requireMention": true 
        },
        // Specific group (use group JID)
        "120363012345678@g.us": {
          "requireMention": false
        }
      }
    }
  },
  "messages": {
    "groupChat": {
      "mentionPatterns": ["@clawd", "hey clawd"]
    }
  }
}

Pairing:

clawdbot channels login

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "${TELEGRAM_BOT_TOKEN}",
      "allowFrom": ["username1", "username2"]
    }
  }
}

Get bot token: Create bot with @BotFather

Discord

{
  "channels": {
    "discord": {
      "enabled": true,
      "botToken": "${DISCORD_BOT_TOKEN}",
      "allowFrom": ["user_id_1", "user_id_2"]
    }
  }
}

Setup: Create application at Discord Developer Portal

iMessage (macOS)

{
  "channels": {
    "imessage": {
      "enabled": true,
      "cliPath": "/opt/homebrew/bin/imsg",
      "dbPath": "~/Library/Messages/chat.db"
    }
  }
}

Install: brew install steipete/tap/imsg

Remote Gateway Setup

Tailscale

Install Tailscale: https://tailscale.com/download
Generate token:

clawdbot doctor --generate-gateway-token

Update config:

{
  "gateway": {
    "bind": "tailnet",
    "auth": {
      "token": "YOUR_TOKEN_HERE"
    }
  }
}

Start gateway:

clawdbot gateway --bind tailnet --token $GATEWAY_AUTH_TOKEN

Connect from remote:

export CLAWDBOT_GATEWAY_URL="ws://gateway-hostname.tailnet.ts.net:18789"
export CLAWDBOT_GATEWAY_TOKEN="your-token"

clawdbot tui

SSH Tunnel

On remote machine (run gateway):

clawdbot gateway

On local machine (create tunnel):

ssh -L 18789:localhost:18789 user@remote-host

# In another terminal
clawdbot tui

Multi-Agent Routing

Route different users/channels to specialized agents:

{
  "agents": {
    "defaults": {
      "workspace": "~/Clawdbot/main",
      "model": "anthropic/claude-sonnet-4"
    },
    "list": [
      {
        "id": "reviewer",
        "workspace": "~/Clawdbot/reviewer",
        "routes": [
          { "channel": "telegram", "peer": "alice" }
        ],
        "tools": {
          "write": false,
          "exec": { "security": "deny" }
        }
      },
      {
        "id": "analyst",
        "workspace": "~/Clawdbot/analyst",
        "routes": [
          { "channel": "discord", "peer": "123456789012345678" }
        ]
      }
    ]
  }
}

Routing rules:

Match by channel + peer
Each agent has isolated workspace and sessions
Agent-specific tool policies

Troubleshooting

Check Status

# Gateway reachability and quick summary
clawdbot status

# Show effective configuration
clawdbot configure --show

# Validate config syntax
clawdbot configure --validate

# Health checks and quick fixes
clawdbot doctor

# Deep health probes
clawdbot health --verbose

View Logs

# Tail gateway logs
clawdbot logs --follow

# View specific number of lines
clawdbot logs --lines 100

Common Issues

Gateway won't start:

Check if port is already in use: lsof -i :18789
Verify config syntax: clawdbot configure --validate
Check logs: clawdbot logs

Skills not loading:

Verify skill location: clawdbot skills list
Check metadata requirements (bins, env, config)
For sandboxed agents, ensure binaries exist in container

WhatsApp not responding:

Check allowFrom list includes your number
Verify QR code pairing: clawdbot channels login
Check channel status: clawdbot status

Remote connection fails:

Verify auth token is set correctly
Check gateway bind mode: clawdbot status
Test connectivity: curl http://gateway-host:18789/__health

References

Detailed Documentation

Config Schema: Complete configuration reference with all options
Skills System: In-depth skills documentation (metadata, gating, installation)
Config Examples: Practical examples for common use cases
Complete Documentation Archive: Full Clawdbot documentation (370+ files) including channels, automation, gateway, tools, platforms, and troubleshooting guides

Quick Reference

Config file: ~/.clawdbot/clawdbot.json

Commands:

clawdbot setup              # Initialize workspace
clawdbot gateway            # Start gateway
clawdbot configure --show   # View config
clawdbot status             # Check status
clawdbot doctor             # Health check
clawdbot skills list        # List skills
clawdbot channels login     # Pair WhatsApp

Model format: provider/model (e.g., anthropic/claude-sonnet-4)

Skill precedence: workspace → ~/.clawdbot/skills → extraDirs → bundled

Dashboard: http://127.0.0.1:18789/ (when gateway running)

Best Practices

Start minimal: Only configure what you need
Use allowFrom: Restrict channel access from the start
Separate concerns: Use config includes for modular setup
Version control: Track workspace bootstrap files (AGENTS.md, etc.)
Environment variables: Store API keys in env vars, not config
Test skills: Run scripts manually before deploying
Monitor logs: Use clawdbot logs --follow during development
Backup sessions: Sessions stored in ~/.clawdbot/agents/<agent>/sessions/

Using the Documentation Archive

The complete documentation archive (references/repomix-output.xml) contains 370+ markdown files covering:

Channels: WhatsApp, Telegram, Discord, iMessage (BlueBubbles), Signal, Slack, MS Teams, Matrix, and more
Automation: Cron jobs, webhooks, Gmail Pub/Sub integration, polling
Gateway: Remote access, Tailscale, authentication, health checks, sandboxing
Tools: Browser automation, elevated exec, Firecrawl, slash commands, subagents
Platforms: macOS, iOS, Android, Linux, Windows, Docker, Hetzner
Providers: Anthropic, OpenAI, GitHub Copilot, OpenRouter, Deepgram, and more
Concepts: Agent loop, sessions, memory, compaction, model failover, streaming
CLI: Complete command reference for all clawdbot commands

When to read the archive:

Setting up specific channels (e.g., BlueBubbles for iMessage, Telegram bots)
Configuring automation (cron jobs, webhooks, Gmail watch)
Troubleshooting channel-specific issues
Understanding gateway protocols and remote access
Platform-specific setup (macOS menu bar, iOS TestFlight, Android)
Advanced features (OAuth monitoring, voice wake, location commands)

How to use it:

The archive is XML-formatted with clear file paths
Search for specific topics (e.g., "telegram", "webhook", "sandbox")
Each file section includes the full path and line numbers
Cross-reference with the directory structure at the top

Getting Help

Documentation: https://docs.clawd.bot
GitHub: https://github.com/clawdbot/clawdbot
Skills Registry: https://clawdhub.com

Clawdbot Config

File contents

Clawdbot Configuration Expert

When to Use This Skill

Quick Decision Tree

Quick Start Guide

Initial Setup

Configuration File Location

Core Configuration Areas

1. Agents Configuration

2. Skills Configuration

3. Channels Configuration

4. Gateway Configuration

5. Tools Configuration

Skills Management

Creating a Skill

Skill Locations

Configuring Skills

Skills in Sandbox

Channel Configuration

WhatsApp

Telegram

Discord

iMessage (macOS)

Remote Gateway Setup

Tailscale

SSH Tunnel

Multi-Agent Routing

Troubleshooting

Check Status

View Logs

Common Issues

References

Detailed Documentation

Quick Reference

Best Practices

Using the Documentation Archive

Getting Help

Frequently asked questions

Clawdbot Config

File contents

Clawdbot Configuration Expert

When to Use This Skill

Quick Decision Tree

Quick Start Guide

Initial Setup

Configuration File Location

Core Configuration Areas

1. Agents Configuration

2. Skills Configuration

3. Channels Configuration

4. Gateway Configuration

5. Tools Configuration

Skills Management

Creating a Skill

Skill Locations

Configuring Skills

Skills in Sandbox

Channel Configuration

WhatsApp

Telegram

Discord

iMessage (macOS)

Remote Gateway Setup

Tailscale

SSH Tunnel

Multi-Agent Routing

Troubleshooting

Check Status

View Logs

Common Issues

References

Detailed Documentation

Quick Reference

Best Practices

Using the Documentation Archive

Getting Help

Related skills

Frequently asked questions

How do I install the Clawdbot Config skill?

What does the Clawdbot Config skill do?

Is Clawdbot Config safe to use?

Which AI agents work with Clawdbot Config?

Is Clawdbot Config free to use?

Who published Clawdbot Config?