Multi-Agent Setup

Create and configure new Clawdbot agents with complete workspace setup, identity configuration, and gateway integration.

Quick Start

For automated setup, use the provided script:

scripts/setup-agent.sh --name "AgentName" --emoji "🤖" --purpose "Brief purpose" --platform telegram

For manual setup, follow the steps below.

Step 1: Gather Agent Requirements

Before creating an agent, collect:

1. Name - Agent's identity (e.g., "Spock", "Ada", "Scotty")
2. Emoji - Visual identifier (e.g., 🖖, 🔮, ⚙️)
3. Purpose - Primary role/responsibilities (e.g., "Research and ops specialist")
4. Platform - Communication channel (telegram, discord, slack, whatsapp)
5. Workspace Path - Where agent files live (e.g., /home/user/clawd-spock)
6. Model - Optional model override (default uses agents.defaults.model)
7. Account ID - Platform-specific account identifier for binding

Step 2: Create Workspace Structure

Create the agent workspace directory with core files:

mkdir -p /path/to/agent-workspace
cd /path/to/agent-workspace

Create these required files using templates:

• SOUL.md - Agent's core identity and purpose (template: templates/SOUL.md)
• IDENTITY.md - Quick reference identity card (template: templates/IDENTITY.md)
• AGENTS.md - Session workflow and coordination rules (template: templates/AGENTS.md)
• TOOLS.md - User tool notes (template: templates/TOOLS.md)
• HEARTBEAT.md - Heartbeat configuration (optional)

Create supporting directories:

mkdir -p memory secrets skills

Step 3: Configure Gateway

Add the agent to ~/.clawdbot/clawdbot.json in three sections:

3a. Add Agent Entry

Add to agents.list array:

{
  "id": "agent-id",
  "name": "AgentName",
  "workspace": "/path/to/agent-workspace",
  "model": "anthropic/claude-sonnet-4-5",
  "identity": {
    "name": "AgentName",
    "emoji": "🤖"
  },
  "subagents": {
    "allowAgents": []
  }
}

Important fields:

• id - Lowercase identifier, used in bindings (e.g., "spock", "scotty")
• name - Display name for the agent
• workspace - Absolute path to agent directory
• model - Optional; defaults to agents.defaults.model if omitted
• identity.emoji - Visual identifier for the agent
• subagents.allowAgents - Array of agent IDs this agent can spawn as subagents

3b. Add Platform Account (if needed)

If using a dedicated platform account, add to the appropriate channel configuration.

For Telegram, add to channels.telegram.accounts:

"agent-id": {
  "dmPolicy": "pairing",
  "botToken": "BOT_TOKEN_HERE",
  "groups": {
    "*": {
      "requireMention": true
    }
  },
  "groupPolicy": "open",
  "streamMode": "block"
}

For Discord, add bot token to credentials and configure accordingly.

3c. Add Binding

Add binding to route messages to the agent. Add to bindings array:

{
  "agentId": "agent-id",
  "match": {
    "channel": "telegram",
    "accountId": "agent-id"
  }
}

Binding logic:

• agentId - Must match the agent's id in agents.list
• match.channel - Platform (telegram, discord, slack, etc.)
• match.accountId - Account identifier (matches the account key in channel config)

Step 4: Populate Workspace Files

SOUL.md

Define the agent's:

• Core identity and purpose
• Domain of responsibility
• Personality traits and working style
• Relationship with other agents
• Boundaries and coordination rules

See templates/SOUL.md for structure.

IDENTITY.md

Quick reference card with:

• Name, creature/role description
• Vibe/personality keywords
• Emoji
• Optional: persona, creation date

See templates/IDENTITY.md for structure.

AGENTS.md

Operational procedures:

• Session startup checklist
• Memory management approach
• Coordination with other agents
• Tool usage guidelines
• Session wrap-up procedures

See templates/AGENTS.md for structure.

Step 5: Validation Checklist

Before restarting gateway, verify:

Config Validation:

• Agent id is lowercase, no spaces
• Agent workspace path exists and is absolute
• Agent identity.emoji is set
• Platform account exists (if dedicated account)
• Platform credentials are valid
• Binding agentId matches agent id exactly
• Binding match.accountId matches platform account key
• JSON syntax is valid (run through jq)

Workspace Validation:

• SOUL.md exists and defines purpose
• IDENTITY.md exists with name/emoji
• AGENTS.md exists with workflow instructions
• memory/ directory exists
• Permissions allow gateway to read/write

Test:

# Validate JSON syntax
jq empty ~/.clawdbot/clawdbot.json

# Check agent configuration
jq '.agents.list[] | select(.id == "agent-id")' ~/.clawdbot/clawdbot.json

# Check binding
jq '.bindings[] | select(.agentId == "agent-id")' ~/.clawdbot/clawdbot.json

Step 6: Apply Configuration

Restart the gateway to load the new agent:

# Option 1: Using gateway tool (from within Clawdbot session)
# Request the main agent to restart gateway

# Option 2: Manual restart
pkill -f clawdbot
cd ~/clawdbot && npm start

After restart, verify:

1. Gateway starts without errors
2. Agent shows up in session list
3. Messages route to correct agent
4. Agent can access workspace files

Rollback Instructions

If agent setup fails or causes issues:

Quick Rollback

1. Remove binding - Comment out or delete from bindings array
2. Disable agent - Remove from agents.list or set enabled: false
3. Restart gateway - Apply changes

Complete Removal

1. Remove agent entry from agents.list
2. Remove platform account config (if dedicated)
3. Remove binding from bindings array
4. Backup workspace: mv /path/to/agent-workspace /path/to/agent-workspace.bak
5. Validate config: jq empty ~/.clawdbot/clawdbot.json
6. Restart gateway

Restore Previous Config

# Gateway keeps backups
cp ~/.clawdbot/clawdbot.json.bak ~/.clawdbot/clawdbot.json
# Restart gateway

Common Issues

Agent not receiving messages:

• Check binding agentId matches agent id exactly
• Verify match.accountId matches platform account key
• Check platform credentials are valid
• Ensure agent has appropriate DM/group policies

Gateway won't start:

• Validate JSON: jq empty ~/.clawdbot/clawdbot.json
• Check workspace paths exist and are absolute
• Review gateway logs: tail -f /tmp/clawdbot/clawdbot.log
• Restore from backup if needed

Agent can't access files:

• Verify workspace path is absolute
• Check directory permissions
• Ensure SOUL.md, IDENTITY.md, AGENTS.md exist

Multi-Agent Coordination

When setting up multiple agents, consider:

Subagent Allowlists: Main agents can spawn subagents. Configure in agent entry:

"subagents": {
  "allowAgents": ["spock", "scotty"]
}

Shared Resources:

• Use symlinks for shared files (e.g., ln -s ~/clawd/USER.md ~/clawd-spock/USER.md)
• Keep agent-specific memory separate
• Coordinate via sessions_send between agents

Role Separation:

• Primary agent handles general tasks and coordination
• Specialist agents focus on specific domains (research, ops, support)
• Avoid overlapping responsibilities

Examples

Research Agent Setup

# Create workspace
mkdir -p ~/clawd-research
cd ~/clawd-research

# Copy templates and customize
cp ~/clawd/skills/multi-agent-setup/templates/*.md .

# Edit SOUL.md for research focus
# Edit IDENTITY.md with name/emoji
# Configure gateway with agent entry + binding
# Restart gateway

Operations Agent Setup

scripts/setup-agent.sh \
  --name "Scotty" \
  --emoji "⚙️" \
  --purpose "Operations and infrastructure specialist" \
  --platform telegram \
  --workspace ~/clawd-scotty \
  --account-id scotty

See Also

• Real examples: Check session logs or existing agent workspaces
• Gateway config reference: gateway config.schema action
• Platform setup guides in skills/discord/ and skills/telegram/