ClawdBot Integration

Overview

Agentic AI integrates with ClawdBot to execute real-world commands like sending messages, checking emails, playing music, and more. The integration uses the OpenClaw Gateway WebSocket protocol to communicate with ClawdBot’s agent system.

ClawdBot is a separate project that provides an LLM-powered agent with skills for interacting with external services. Learn more at ClawdBot GitHub.

Integration Architecture

Communication Methods

Agentic AI supports two methods for communicating with ClawdBot:

Method 1: Direct CLI Execution (Current)

The ConversationBrain executes ClawdBot commands directly via subprocess:

# conversation_brain.py:140
cmd = [
    "clawdbot", "agent",
    "--session-id", "agent:main:main",
    "--message", processed_command,
    "--timeout", "90",
]

process = await asyncio.create_subprocess_exec(
    *cmd,
    stdout=asyncio.subprocess.PIPE,
    stderr=asyncio.subprocess.PIPE,
    env={**os.environ, 'GOG_ACCOUNT': '[email protected]'},
)

stdout, stderr = await asyncio.wait_for(
    process.communicate(),
    timeout=95
)

response_text = stdout.decode('utf-8').strip()

Advantages:

Simple, direct communication
No additional infrastructure needed
Immediate response capture
Works with existing ClawdBot CLI

Disadvantages:

Higher overhead per command (new process)
No persistent agent session
Limited to local ClawdBot installation

Method 2: WebSocket Gateway (Optional)

Communicate via the OpenClaw Gateway WebSocket protocol:

# gateway/client.py:16
class GatewayClient:
    async def connect(self) -> None:
        self._ws = await websockets.connect(
            "ws://127.0.0.1:18789",
            ping_interval=30,
            ping_timeout=10,
        )
        
    async def send_message(self, message: GatewayMessage) -> None:
        rpc_message = {
            "jsonrpc": "2.0",
            "id": self._message_id,
            "method": "sessions_send",
            "params": {
                "message": message.to_dict(),
            },
        }
        await self._ws.send(json.dumps(rpc_message))

Advantages:

Persistent connection (lower latency)
Supports remote ClawdBot instances
Event-driven architecture
Automatic reconnection with backoff

Disadvantages:

Requires OpenClaw Gateway running
More complex setup
Asynchronous response handling

The current implementation uses Method 1 (Direct CLI) for simplicity. The Gateway client code exists but is disabled by default in call_manager.py:89-99.

ClawdBot Session Management

Session Identifier

Commands are sent to a specific ClawdBot agent session:

clawdbot agent --session-id agent:main:main

Session ID Format: agent:main:main

First part: agent (agent type)
Second part: main (primary session)
Third part: main (sub-session)

The session ID ensures commands go to the correct ClawdBot instance, especially important if running multiple agents.

Starting ClawdBot Agent

Before using Agentic AI, start the ClawdBot agent:

# Start the agent in the background
clawdbot agent --session-id agent:main:main &

# Or run in a separate terminal
clawdbot agent --session-id agent:main:main

The agent will:

Connect to OpenClaw Gateway (ws://127.0.0.1:18789)
Load configured skills
Wait for incoming commands

Supported Commands

ClawdBot skills enable various command types:

YouTube Commands

User: "Open YouTube and search for Zayn Dusk Till Dawn"
  ↓
ClawdBot: Uses YouTube skill
  ↓
Response: "Opening YouTube and searching for Zayn Dusk Till Dawn"

Spotify Commands

User: "Play Shape of You on Spotify"
  ↓
ClawdBot: Uses Spotify skill
  ↓
Response: "Playing Shape of You on Spotify"

Email Commands (GOG Skill)

User: "Check my emails"
  ↓
ClawdBot: Uses GOG (Gmail) skill
  ↓
Response: "You have 3 unread emails: 1 from John about..."

The GOG skill requires the GOG_ACCOUNT environment variable to be set to your Gmail address.

Messaging Commands

User: "Send hi to John on WhatsApp"
  ↓
ClawdBot: Uses WhatsApp skill
  ↓
Response: "Message sent to John on WhatsApp"

Web Search

User: "Search for nearby restaurants"
  ↓
ClawdBot: Uses web search skill
  ↓
Response: "Here are the top restaurants near you..."

Command Execution Flow

Implementation Details

Command Preprocessing

The brain processes commands before sending to ClawdBot:

# conversation_brain.py:134
processed_command = command.replace('\\n', '\n')

This handles cases where users say “new line” and it gets transcribed as \n (for email composition, etc.).

Environment Variables

Special environment variables are passed to ClawdBot:

env = {
    **os.environ,
    'GOG_ACCOUNT': '[email protected]',  # Gmail account for GOG skill
}

Make sure to configure skill-specific environment variables (like GOG_ACCOUNT) before using those features.

Response Filtering

ClawdBot output is filtered to remove noise:

# conversation_brain.py:169
lines = response_text.split('\n')
clean_lines = [
    line for line in lines
    if line.strip()
    and 'DeprecationWarning' not in line
    and not line.startswith('(node:')
    and not line.startswith('(Use `node')
]
response_text = '\n'.join(clean_lines).strip()

This ensures only the actual response is spoken to the user.

Timeout Handling

# conversation_brain.py:157
try:
    stdout, stderr = await asyncio.wait_for(
        process.communicate(),
        timeout=95  # 5 seconds more than ClawdBot's timeout
    )
except asyncio.TimeoutError:
    process.kill()
    return "I'm still working on that. It's taking longer than expected."

Commands timeout after 90 seconds to prevent hanging the call.

Gateway Client Details

For advanced use cases using the WebSocket gateway:

Connection Management

# gateway/client.py:64
async def connect(self) -> None:
    self._should_run = True
    
    while self._reconnect_attempts < self.max_reconnect_attempts:
        try:
            self._ws = await websockets.connect(
                self.url,
                ping_interval=30,
                ping_timeout=10,
            )
            self._is_connected = True
            
            # Start heartbeat and receive loops
            await self._heartbeat_loop()
            await self._receive_loop()
            
        except ConnectionRefusedError:
            # Exponential backoff reconnection
            delay = min(
                self.reconnect_base_delay * (2 ** self._reconnect_attempts),
                self.reconnect_max_delay,
            )
            await asyncio.sleep(delay)

Message Types

The gateway supports various message types (gateway/messages.py): CallStartedMessage:

{
    "type": "call_started",
    "call_id": "abc-123",
    "to_number": "+1234567890",
    "prompt": "System instruction...",
    "metadata": {}
}

CallEndedMessage:

{
    "type": "call_ended",
    "call_id": "abc-123",
    "duration": 180.5,
    "outcome": "completed",
    "full_transcript": "..."
}

HeartbeatMessage:

{
    "type": "heartbeat",
    "timestamp": 1234567890
}

JSON-RPC Protocol

Messages are sent using JSON-RPC 2.0:

# gateway/client.py:173
async def _send_rpc(self, message: GatewayMessage) -> None:
    rpc_message = {
        "jsonrpc": "2.0",
        "id": self._message_id,
        "method": "sessions_send",
        "params": {
            "message": message.to_dict(),
        },
    }
    await self._ws.send(json.dumps(rpc_message))

Response Format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "status": "delivered"
  }
}

Configuration

Gateway Settings

# config.yaml
gateway:
  url: "ws://127.0.0.1:18789"
  reconnect_max_attempts: 10
  reconnect_base_delay: 1.0
  reconnect_max_delay: 60.0

Telegram Integration

The brain requires Telegram chat ID for identifying the ClawdBot agent:

# config.yaml
telegram:
  enabled: true
  bot_token: ${TELEGRAM_BOT_TOKEN}
  chat_id: ${TELEGRAM_CHAT_ID}

The telegram_chat_id is used as the session identifier for routing commands to the correct ClawdBot agent instance.

Enabling Gateway Mode

To switch from CLI execution to Gateway mode: Step 1: Uncomment gateway client initialization in call_manager.py:

# call_manager.py:92 (currently commented)
self._gateway_client = GatewayClient(
    url=self.config.gateway.url,
    max_reconnect_attempts=self.config.gateway.reconnect_max_attempts,
    reconnect_base_delay=self.config.gateway.reconnect_base_delay,
    reconnect_max_delay=self.config.gateway.reconnect_max_delay,
)
self._gateway_task = asyncio.create_task(self._gateway_client.connect())

Step 2: Modify ConversationBrain to use gateway instead of subprocess (custom implementation needed). Step 3: Start OpenClaw Gateway:

# Start the gateway (ClawdBot includes this)
openclaw-gateway --port 18789

Best Practices

1. Natural Language Parsing

Let ClawdBot’s LLM handle command parsing:

# ✅ Good - send natural language
"Open YouTube and search for Zayn Dusk Till Dawn"

# ❌ Bad - over-process before sending
{"action": "youtube", "query": "Zayn Dusk Till Dawn"}

ClawdBot is designed to understand natural language, so don’t over-structure commands.

2. Error Handling

Always handle execution failures gracefully:

try:
    response = await self._send_to_clawdbot_async(command)
    if response:
        await self._on_clawdbot_response(response)
except Exception as e:
    # Speak error to user naturally
    await self._on_clawdbot_response(
        f"Sorry, I encountered an error: {str(e)}"
    )

3. Timeout Configuration

Adjust timeouts based on expected skill execution time:

# Quick skills (search, simple queries)
timeout = 30

# Slow skills (email operations, file processing)
timeout = 90

# Very slow operations (large data processing)
timeout = 180

4. Skill-Specific Setup

Ensure environment variables and credentials are configured:

# .env file
GOG_ACCOUNT=[email protected]
SPOTIFY_CLIENT_ID=...
SPOTIFY_CLIENT_SECRET=...
YOUTUBE_API_KEY=...

Troubleshooting

ClawdBot Not Responding

Check if agent is running:

ps aux | grep "clawdbot agent"

Check gateway connection:

netstat -an | grep 18789

Test ClawdBot directly:

clawdbot agent --session-id agent:main:main --message "test"

Commands Timing Out

Increase timeout:

# conversation_brain.py:144
"--timeout", "120",  # Increase from 90 to 120

Check skill logs:

clawdbot logs --skill gog

Skills Not Working

Verify skill configuration:

clawdbot skills list
clawdbot skills status gog

Check environment variables:

import os
print(os.environ.get('GOG_ACCOUNT'))

Example Integrations

Custom Skill Integration

Create a custom ClawdBot skill for specialized commands:

// custom-skill.js
module.exports = {
  name: 'custom',
  description: 'Custom skill for Agentic AI',
  
  async execute(params) {
    // Your custom logic here
    return {
      success: true,
      message: 'Command executed successfully'
    };
  }
};

Multi-Agent Coordination

Run multiple ClawdBot agents for different purposes:

# Personal assistant agent
clawdbot agent --session-id agent:personal:main

# Work assistant agent
clawdbot agent --session-id agent:work:main

Route commands based on context in the ConversationBrain.

Architecture

See how ClawdBot fits into the overall system

Conversation Brain

Learn how commands are detected and routed

ClawdBot GitHub

Official ClawdBot documentation and setup

OpenClaw Gateway

WebSocket protocol documentation

Get Started

Core Concepts

Configuration

Usage Guides

Integrations

Troubleshooting

​Overview

​Integration Architecture

​Communication Methods

​Method 1: Direct CLI Execution (Current)

​Method 2: WebSocket Gateway (Optional)

​ClawdBot Session Management

​Session Identifier

​Starting ClawdBot Agent

​Supported Commands

​YouTube Commands

​Spotify Commands

​Email Commands (GOG Skill)

​Messaging Commands

​Web Search

​Command Execution Flow

​Implementation Details

​Command Preprocessing

​Environment Variables

​Response Filtering

​Timeout Handling

​Gateway Client Details

​Connection Management

​Message Types

​JSON-RPC Protocol

​Configuration

​Gateway Settings

​Telegram Integration

​Enabling Gateway Mode

​Best Practices

​1. Natural Language Parsing

​2. Error Handling

​3. Timeout Configuration

​4. Skill-Specific Setup

​Troubleshooting

​ClawdBot Not Responding

​Commands Timing Out

​Skills Not Working

​Example Integrations

​Custom Skill Integration

​Multi-Agent Coordination

​Related Documentation

Architecture

Conversation Brain

ClawdBot GitHub

OpenClaw Gateway

Build docs developers (and LLMs) love

Overview

Integration Architecture

Communication Methods

Method 1: Direct CLI Execution (Current)

Method 2: WebSocket Gateway (Optional)

ClawdBot Session Management

Session Identifier

Starting ClawdBot Agent

Supported Commands

YouTube Commands

Spotify Commands

Email Commands (GOG Skill)

Messaging Commands

Web Search

Command Execution Flow

Implementation Details

Command Preprocessing

Environment Variables

Response Filtering

Timeout Handling

Gateway Client Details

Connection Management

Message Types

JSON-RPC Protocol

Configuration

Gateway Settings

Telegram Integration

Enabling Gateway Mode

Best Practices

1. Natural Language Parsing

2. Error Handling

3. Timeout Configuration

4. Skill-Specific Setup

Troubleshooting

ClawdBot Not Responding

Commands Timing Out

Skills Not Working

Example Integrations

Custom Skill Integration

Multi-Agent Coordination

Related Documentation