Agent Council

Agent Council

Complete toolkit for creating and managing autonomous AI agents with Discord integration for OpenClaw.

What This Skill Does

Agent Creation:

• -Creates autonomous AI agents with self-contained workspaces
• -Generates SOUL.md (personality & responsibilities)
• -Generates HEARTBEAT.md (cron execution logic)
• -Sets up memory system (hybrid architecture)
• -Configures gateway automatically
• -Binds agents to Discord channels (optional)
• -Sets up daily memory cron jobs (optional)

Discord Channel Management:

• -Creates Discord channels via API
• -Configures OpenClaw gateway allowlists
• -Sets channel-specific system prompts
• -Renames channels and updates references
• -Optional workspace file search

Installation

Install from ClawHub
clawhub install agent-council

Or manual install
cp -r . ~/.openclaw/skills/agent-council/
openclaw gateway config.patch --raw '{
  "skills": {
    "entries": {
      "agent-council": {"enabled": true}
    }
  }
}'

Part 1: Agent Creation

Quick Start

scripts/create-agent.sh \
  --name "Watson" \
  --id "watson" \
  --emoji "🔬" \
  --specialty "Research and analysis specialist" \
  --model "anthropic/claude-opus-4-5" \
  --workspace "$HOME/agents/watson" \
  --discord-channel "1234567890"

Workflow

#### 1. Gather Requirements

Ask the user:

• -Agent name (e.g., "Watson")
• -Agent ID (lowercase, hyphenated, e.g., "watson")
• -Emoji (e.g., "🔬")
• -Specialty (what the agent does)
• -Model (which LLM to use)
• -Workspace (where to create agent files)
• -Discord channel ID (optional)

#### 2. Run Creation Script

scripts/create-agent.sh \
  --name "Agent Name" \
  --id "agent-id" \
  --emoji "🤖" \
  --specialty "What this agent does" \
  --model "provider/model-name" \
  --workspace "/path/to/workspace" \
  --discord-channel "1234567890"  # Optional

The script automatically:

• -✅ Creates workspace with memory subdirectory
• -✅ Generates SOUL.md and HEARTBEAT.md
• -✅ Updates gateway config (preserves existing agents)
• -✅ Adds Discord channel binding (if specified)
• -✅ Restarts gateway to apply changes
• -✅ Prompts for daily memory cron setup

#### 3. Customize Agent

After creation:

• -SOUL.md - Refine personality, responsibilities, boundaries
• -HEARTBEAT.md - Add periodic checks and cron logic
• -Workspace files - Add agent-specific configuration

Agent Architecture

Self-contained structure:

agents/
├── watson/
│   ├── SOUL.md              # Personality and responsibilities
│   ├── HEARTBEAT.md         # Cron execution logic
│   ├── memory/              # Agent-specific memory
│   │   ├── 2026-02-01.md   # Daily memory logs
│   │   └── 2026-02-02.md
│   └── .openclaw/
│       └── skills/          # Agent-specific skills (optional)

Memory system:

• -Agent-specific memory: <workspace>/memory/YYYY-MM-DD.md
• -Shared memory access: Agents can read shared workspace
• -Daily updates: Optional cron job for summaries

Cron jobs:

If your agent needs scheduled tasks:

1. Create HEARTBEAT.md with execution logic

2. Add cron jobs with --session <agent-id>

3. Document in SOUL.md

Examples

Research agent:

scripts/create-agent.sh \
  --name "Watson" \
  --id "watson" \
  --emoji "🔬" \
  --specialty "Deep research and competitive analysis" \
  --model "anthropic/claude-opus-4-5" \
  --workspace "$HOME/agents/watson" \
  --discord-channel "1234567890"

Image generation agent:

scripts/create-agent.sh \
  --name "Picasso" \
  --id "picasso" \
  --emoji "🎨" \
  --specialty "Image generation and editing specialist" \
  --model "google/gemini-3-flash-preview" \
  --workspace "$HOME/agents/picasso" \
  --discord-channel "9876543210"

Health tracking agent:

scripts/create-agent.sh \
  --name "Nurse Joy" \
  --id "nurse-joy" \
  --emoji "💊" \
  --specialty "Health tracking and wellness monitoring" \
  --model "anthropic/claude-opus-4-5" \
  --workspace "$HOME/agents/nurse-joy" \
  --discord-channel "5555555555"

Part 2: Discord Channel Management

Channel Creation

#### Quick Start

python3 scripts/setup-channel.py \
  --name research \
  --context "Deep research and competitive analysis"

#### Workflow

1. Run setup script:

python3 scripts/setup-channel.py \
  --name <channel-name> \
  --context "<channel-purpose>" \
  [--category-id <discord-category-id>]

2. Apply gateway config (command shown by script):

openclaw gateway config.patch --raw '{"channels": {...}}'

#### Options

With category:

python3 scripts/setup-channel.py \
  --name research \
  --context "Deep research and competitive analysis" \
  --category-id "1234567890"

Use existing channel:

python3 scripts/setup-channel.py \
  --name personal-finance \
  --id 1466184336901537897 \
  --context "Personal finance management"

Channel Renaming

#### Quick Start

python3 scripts/rename-channel.py \
  --id 1234567890 \
  --old-name old-name \
  --new-name new-name

#### Workflow

1. Run rename script:

python3 scripts/rename-channel.py \
  --id <channel-id> \
  --old-name <old-name> \
  --new-name <new-name> \
  [--workspace <workspace-dir>]

2. Apply gateway config if systemPrompt needs updating (shown by script)

3. Commit workspace file changes (if --workspace used)

#### With Workspace Search

python3 scripts/rename-channel.py \
  --id 1234567890 \
  --old-name old-name \
  --new-name new-name \
  --workspace "$HOME/my-workspace"

This will:

• -Rename Discord channel via API
• -Update gateway config systemPrompt
• -Search and update workspace files
• -Report files changed for git commit

Complete Multi-Agent Setup

Full workflow from scratch:

1. Create Discord channel
python3 scripts/setup-channel.py \
  --name research \
  --context "Deep research and competitive analysis" \
  --category-id "1234567890"

(Note the channel ID from output)

2. Apply gateway config for channel
openclaw gateway config.patch --raw '{"channels": {...}}'

3. Create agent bound to that channel
scripts/create-agent.sh \
  --name "Watson" \
  --id "watson" \
  --emoji "🔬" \
  --specialty "Deep research and competitive analysis" \
  --model "anthropic/claude-opus-4-5" \
  --workspace "$HOME/agents/watson" \
  --discord-channel "1234567890"

Done! Agent is created and bound to the channel

Configuration

Discord Category ID

Option 1: Command line

python3 scripts/setup-channel.py \
  --name channel-name \
  --context "Purpose" \
  --category-id "1234567890"

Option 2: Environment variable

export DISCORD_CATEGORY_ID="1234567890"
python3 scripts/setup-channel.py --name channel-name --context "Purpose"

Finding Discord IDs

Enable Developer Mode:

• -Settings → Advanced → Developer Mode

Copy IDs:

• -Right-click channel → Copy ID
• -Right-click category → Copy ID

Scripts Reference

create-agent.sh

Arguments:

• ---name (required) - Agent name
• ---id (required) - Agent ID (lowercase, hyphenated)
• ---emoji (required) - Agent emoji
• ---specialty (required) - What the agent does
• ---model (required) - LLM to use (provider/model-name)
• ---workspace (required) - Where to create agent files
• ---discord-channel (optional) - Discord channel ID to bind

Output:

• -Creates agent workspace
• -Generates SOUL.md and HEARTBEAT.md
• -Updates gateway config
• -Optionally creates daily memory cron

setup-channel.py

Arguments:

• ---name (required) - Channel name
• ---context (required) - Channel purpose/context
• ---id (optional) - Existing channel ID
• ---category-id (optional) - Discord category ID

Output:

• -Creates Discord channel (if doesn't exist)
• -Generates gateway config.patch command

rename-channel.py

Arguments:

• ---id (required) - Channel ID
• ---old-name (required) - Current channel name
• ---new-name (required) - New channel name
• ---workspace (optional) - Workspace directory to search

Output:

• -Renames Discord channel
• -Updates gateway systemPrompt (if needed)
• -Lists updated files (if workspace search enabled)

Gateway Integration

This skill integrates with OpenClaw's gateway configuration:

Agents:

{
  "agents": {
    "list": [
      {
        "id": "watson",
        "name": "Watson",
        "workspace": "/path/to/agents/watson",
        "model": {
          "primary": "anthropic/claude-opus-4-5"
        },
        "identity": {
          "name": "Watson",
          "emoji": "🔬"
        }
      }
    ]
  }
}

Bindings:

{
  "bindings": [
    {
      "agentId": "watson",
      "match": {
        "channel": "discord",
        "peer": {
          "kind": "channel",
          "id": "1234567890"
        }
      }
    }
  ]
}

Channels:

{
  "channels": {
    "discord": {
      "guilds": {
        "YOUR_GUILD_ID": {
          "channels": {
            "1234567890": {
              "allow": true,
              "requireMention": false,
              "systemPrompt": "Deep research and competitive analysis"
            }
          }
        }
      }
    }
  }
}

Agent Coordination

Your main agent coordinates with specialized agents using OpenClaw's built-in session management tools.

List Active Agents

See all active agents and their recent activity:

sessions_list({
  kinds: ["agent"],
  limit: 10,
  messageLimit: 3  // Show last 3 messages per agent
})

Send Messages to Agents

Direct communication:

sessions_send({
  label: "watson",  // Agent ID
  message: "Research the competitive landscape for X"
})

Wait for response:

sessions_send({
  label: "watson",
  message: "What did you find about X?",
  timeoutSeconds: 300  // Wait up to 5 minutes
})

Spawn Sub-Agent Tasks

For complex work, spawn a sub-agent in an isolated session:

sessions_spawn({
  agentId: "watson",  // Optional: use specific agent
  task: "Research competitive landscape for X and write a report",
  model: "anthropic/claude-opus-4-5",  // Optional: override model
  runTimeoutSeconds: 3600,  // 1 hour max
  cleanup: "delete"  // Delete session after completion
})

The sub-agent will:

1. Execute the task in isolation

2. Announce completion back to your session

3. Self-delete (if cleanup: "delete")

Check Agent History

Review what an agent has been working on:

sessions_history({
  sessionKey: "watson-session-key",
  limit: 50
})

Coordination Patterns

1. Direct delegation (Discord-bound agents):

• -User messages agent's Discord channel
• -Agent responds directly in that channel
• -Main agent doesn't need to coordinate

2. Programmatic delegation (main agent → sub-agent):

// Main agent delegates task
sessions_send({
  label: "watson",
  message: "Research X and update memory/research-X.md"
})

// Watson works independently, updates files
// Main agent checks later or Watson reports back

3. Spawn for complex tasks:

// For longer-running, isolated work
sessions_spawn({
  agentId: "watson",
  task: "Deep dive: analyze competitors A, B, C. Write report to reports/competitors.md",
  runTimeoutSeconds: 7200,
  cleanup: "keep"  // Keep session for review
})

4. Agent-to-agent communication:

Agents can send messages to each other:

// In Watson's context
sessions_send({
  label: "picasso",
  message: "Create an infographic from data in reports/research.md"
})

Best Practices

When to use Discord bindings:

• -✅ Domain-specific agents (research, health, images)
• -✅ User wants direct access to agent
• -✅ Agent should respond to channel activity

When to use sessions_send:

• -✅ Programmatic coordination
• -✅ Main agent delegates to specialists
• -✅ Need response in same session

When to use sessions_spawn:

• -✅ Long-running tasks (>5 minutes)
• -✅ Complex multi-step work
• -✅ Want isolation from main session
• -✅ Background processing

Example: Research Workflow

// Main agent receives request: "Research competitor X"

// 1. Check if Watson is active
const agents = sessions_list({ kinds: ["agent"] })

// 2. Delegate to Watson
sessions_send({
  label: "watson",
  message: "Research competitor X: products, pricing, market position. Write findings to memory/research-X.md"
})

// 3. Watson works independently:
//    - Searches web
//    - Analyzes data
//    - Updates memory file
//    - Reports back when done

// 4. Main agent retrieves results
const results = Read("agents/watson/memory/research-X.md")

// 5. Share with user
"Research complete! Watson found: [summary]"

Communication Flow

Main Agent (You) ↔ Specialized Agents:

User Request
    ↓
Main Agent (Claire)
    ↓
sessions_send("watson", "Research X")
    ↓
Watson Agent
    ↓
-Uses web_search
-Uses web_fetch
-Updates memory files
    ↓
Responds to main session
    ↓
Main Agent synthesizes and replies

Discord-Bound Agents:

User posts in #research channel
    ↓
Watson Agent (bound to channel)
    ↓
-Sees message directly
-Responds in channel
-No main agent involvement

Hybrid Approach:

User: "Research X" (main channel)
    ↓
Main Agent delegates to Watson
    ↓
Watson researches and reports back
    ↓
Main Agent: "Done! Watson found..."
    ↓
User: "Show me more details"
    ↓
Main Agent: "@watson post your full findings in #research"
    ↓
Watson posts detailed report in #research channel

Troubleshooting

Agent Creation Issues: "Agent not appearing in Discord"

• -Verify channel ID is correct
• -Check gateway config bindings section
• -Restart gateway: openclaw gateway restart

"Model errors"

• -Verify model name format: provider/model-name
• -Check model is available in gateway config

Channel Management Issues: "Failed to create channel"

• -Check bot has "Manage Channels" permission
• -Verify bot token in OpenClaw config
• -Ensure category ID is correct (if specified)

"Category not found"

• -Verify category ID is correct
• -Check bot has access to category
• -Try without category ID (creates uncategorized)

"Channel already exists"

• -Use --id <channel-id> to configure existing channel
• -Or script will auto-detect and configure it

Use Cases

• -Domain specialists - Research, health, finance, coding agents
• -Creative agents - Image generation, writing, design
• -Task automation - Scheduled monitoring, reports, alerts
• -Multi-agent systems - Coordinated team of specialized agents
• -Discord organization - Structured channels for different agent domains

Advanced: Multi-Agent Coordination

For larger multi-agent systems:

Coordination Patterns:

• -Main agent delegates tasks to specialists
• -Agents report progress and request help
• -Shared knowledge base for common information
• -Cross-agent communication via sessions_send

Task Management:

• -Integrate with task tracking systems
• -Route work based on agent specialty
• -Track assignments and completions

Documentation:

• -Maintain agent roster in main workspace
• -Document delegation patterns
• -Keep runbooks for common workflows

Best Practices

1. Organize channels in categories - Group related agent channels

2. Use descriptive channel names - Clear purpose from the name

3. Set specific system prompts - Give each channel clear context

4. Document agent responsibilities - Keep SOUL.md updated

5. Set up memory cron jobs - For agents with ongoing work

6. Test agents individually - Before integrating into team

7. Update gateway config safely - Always use config.patch, never manual edits

Requirements

Bot Permissions:

• -Manage Channels - To create/rename channels
• -View Channels - To read channel list
• -Send Messages - To post in channels

System:

• -OpenClaw installed and configured
• -Node.js/npm via nvm
• -Python 3.6+ (standard library only)
• -Discord bot token (for channel management)

See Also

• -OpenClaw documentation: https://docs.openclaw.ai
• -Multi-agent patterns: https://docs.openclaw.ai/agents
• -Discord bot setup: https://docs.openclaw.ai/channels/discord