Openclaw Multi Channel AI Assistant

OpenClaw Multi-Channel AI Assistant

Skill by ara.so — Hermes Skills collection.

OpenClaw is a self-hosted multi-channel AI assistant platform that connects Web control UI, chat channels (WhatsApp, Telegram, Discord, Slack, Signal, Feishu, etc.), nodes, tools, and AI models through a unified Gateway architecture. This skill covers installation, configuration, channel setup, AI provider integration, plugin development, and troubleshooting.

What OpenClaw Does

• Unified Gateway: Central control plane that routes messages between channels, nodes, and AI agents
• Multi-Channel Support: 20+ chat platforms including WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Feishu, Teams, Matrix
• Multi-Model Support: Anthropic Claude, OpenAI GPT, DeepSeek, Qwen, Kimi, GLM, Ollama, and more
• Tool System: Browser automation, code execution, skills, sub-agents
• Plugin Architecture: Hooks, adapters, and extensible agent framework
• Mobile Nodes: Remote execution nodes for distributed AI workflows
• Web UI: Browser-based control panel for configuration and monitoring

Installation

Quick Start (Docker)

# Clone the repository
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# Copy environment template
cp .env.example .env

# Edit .env with your configuration
# Required: OPENAI_API_KEY or ANTHROPIC_API_KEY
nano .env

# Start with Docker Compose
docker-compose up -d

# Access Web UI at http://localhost:3000

Node.js Installation

# Prerequisites: Node.js 18+ and npm
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with API keys and settings

# Start Gateway
npm run gateway:start

# Start Web UI (separate terminal)
npm run web:start

# Start a channel adapter (example: Telegram)
npm run channel:telegram

Cloud Deployment

# Deploy to VPS (Ubuntu/Debian)
curl -fsSL https://get.openclaw.ai | bash

# Or use the official installer
wget https://github.com/openclaw/openclaw/releases/latest/download/install.sh
chmod +x install.sh
./install.sh

# Follow prompts to configure Gateway, channels, and models

Core Architecture

Gateway Configuration

The Gateway is the central hub. Configure in config/gateway.yaml:

gateway:
  host: 0.0.0.0
  port: 3000
  secret: ${GATEWAY_SECRET}
  
channels:
  - type: telegram
    enabled: true
    token: ${TELEGRAM_BOT_TOKEN}
  
  - type: whatsapp
    enabled: true
    provider: baileys  # or twilio
    
  - type: discord
    enabled: true
    token: ${DISCORD_BOT_TOKEN}

models:
  - provider: anthropic
    model: claude-3-5-sonnet-20241022
    apiKey: ${ANTHROPIC_API_KEY}
    
  - provider: openai
    model: gpt-4-turbo
    apiKey: ${OPENAI_API_KEY}
    
  - provider: ollama
    model: llama3
    baseURL: http://localhost:11434

agent:
  defaultModel: claude-3-5-sonnet-20241022
  temperature: 0.7
  maxTokens: 4096
  contextWindow: 200000
  
memory:
  provider: sqlite  # or postgres, redis
  retentionDays: 30
  
tools:
  browser: true
  codeExecution: false  # requires sandboxed environment
  webSearch: true

Environment Variables

Create .env file:

# Gateway
GATEWAY_SECRET=your-secure-random-secret
GATEWAY_PORT=3000

# AI Providers
ANTHROPIC_API_KEY=sk-ant-xxxxx
OPENAI_API_KEY=sk-xxxxx
DEEPSEEK_API_KEY=sk-xxxxx

# Channels - Telegram
TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

# Channels - Discord
DISCORD_BOT_TOKEN=MTk4NjIy...

# Channels - WhatsApp (Baileys)
WHATSAPP_SESSION_PATH=./sessions/whatsapp

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/openclaw
# or
DATABASE_URL=sqlite:./data/openclaw.db

# Memory
MEMORY_PROVIDER=sqlite
MEMORY_RETENTION_DAYS=30

# Tools
ENABLE_BROWSER_TOOL=true
ENABLE_CODE_EXECUTION=false
SEARXNG_URL=http://localhost:8080

CLI Commands

Gateway Management

# Start Gateway server
npm run gateway:start
# or
./openclaw gateway start

# Check Gateway status
./openclaw gateway status

# Reload configuration without restart
./openclaw gateway reload

# View Gateway logs
./openclaw gateway logs --tail 100

Channel Management

# List available channels
./openclaw channels list

# Start a specific channel adapter
./openclaw channel start telegram
./openclaw channel start whatsapp
./openclaw channel start discord

# Stop a channel
./openclaw channel stop telegram

# Channel authentication (WhatsApp)
./openclaw channel auth whatsapp
# Scan QR code with WhatsApp mobile app

Node Management

# Register a new node
./openclaw node register --name "mobile-node-1" --type mobile

# List active nodes
./openclaw node list

# Start a node
./openclaw node start mobile-node-1

# Node health check
./openclaw node health mobile-node-1

Plugin Management

# List installed plugins
./openclaw plugin list

# Install a plugin
./openclaw plugin install @openclaw/plugin-calendar

# Create new plugin scaffold
./openclaw plugin create my-custom-plugin

# Enable/disable plugin
./openclaw plugin enable my-custom-plugin
./openclaw plugin disable my-custom-plugin

Channel Adapter Implementation

Creating a Custom Channel Adapter

// plugins/channels/my-channel/index.js
import { ChannelAdapter } from '@openclaw/core';

export default class MyChannelAdapter extends ChannelAdapter {
  constructor(config) {
    super(config);
    this.client = null;
  }

  async initialize() {
    // Initialize your channel client
    this.client = new MyChannelClient({
      token: this.config.token,
      apiUrl: this.config.apiUrl
    });

    // Set up incoming message handler
    this.client.on('message', this.handleIncomingMessage.bind(this));
    
    await this.client.connect();
    this.logger.info('MyChannel adapter initialized');
  }

  async handleIncomingMessage(rawMessage) {
    // Normalize to OpenClaw message format
    const message = {
      id: rawMessage.id,
      channelType: 'my-channel',
      channelUserId: rawMessage.sender.id,
      text: rawMessage.content,
      timestamp: rawMessage.timestamp,
      metadata: {
        chatId: rawMessage.chat.id,
        messageType: rawMessage.type
      }
    };

    // Route to Gateway for Agent processing
    await this.routeToAgent(message);
  }

  async sendMessage(sessionKey, response) {
    // Extract channel-specific routing info
    const { chatId } = this.extractRoutingInfo(sessionKey);
    
    // Send through channel API
    await this.client.sendMessage({
      chatId,
      text: response.text,
      attachments: response.attachments
    });
  }

  async cleanup() {
    if (this.client) {
      await this.client.disconnect();
    }
  }
}

// Plugin manifest
export const manifest = {
  name: 'my-channel',
  version: '1.0.0',
  type: 'channel-adapter',
  requiredConfig: ['token'],
  optionalConfig: ['apiUrl']
};

Register Channel in Gateway

// config/channels.js
import MyChannelAdapter from './plugins/channels/my-channel/index.js';

export const channelRegistry = {
  telegram: TelegramAdapter,
  whatsapp: WhatsAppAdapter,
  discord: DiscordAdapter,
  'my-channel': MyChannelAdapter
};

Agent Configuration & Tools

Custom Agent Prompt

// config/agent.js
export const agentConfig = {
  systemPrompt: `You are a helpful AI assistant with access to various tools.
  
Available tools:
- browser: Navigate websites and extract information
- webSearch: Search the internet using SearXNG
- executeCode: Run Python code (sandboxed)

Guidelines:
- Be concise but helpful
- Always cite sources when using web search
- Ask for confirmation before executing code
- Respect user privacy`,

  model: 'claude-3-5-sonnet-20241022',
  temperature: 0.7,
  maxTokens: 4096,
  
  // Tool configuration
  tools: {
    browser: {
      enabled: true,
      timeout: 30000,
      userAgent: 'OpenClaw/1.0'
    },
    webSearch: {
      enabled: true,
      searxngUrl: process.env.SEARXNG_URL,
      maxResults: 5
    },
    codeExecution: {
      enabled: false, // Requires secure sandbox
      languages: ['python', 'javascript'],
      timeout: 10000
    }
  },
  
  // Memory configuration
  memory: {
    enabled: true,
    contextWindow: 50, // Last 50 messages
    summarization: true,
    summaryThreshold: 30
  }
};

Implementing a Custom Tool

// plugins/tools/weather-tool.js
import { Tool } from '@openclaw/core';

export default class WeatherTool extends Tool {
  constructor() {
    super({
      name: 'getWeather',
      description: 'Get current weather for a location',
      parameters: {
        type: 'object',
        properties: {
          location: {
            type: 'string',
            description: 'City name or coordinates'
          },
          units: {
            type: 'string',
            enum: ['metric', 'imperial'],
            default: 'metric'
          }
        },
        required: ['location']
      }
    });
  }

  async execute({ location, units = 'metric' }) {
    const apiKey = process.env.WEATHER_API_KEY;
    const response = await fetch(
      `https://api.openweathermap.org/data/2.5/weather?q=${location}&units=${units}&appid=${apiKey}`
    );
    
    if (!response.ok) {
      throw new Error(`Weather API error: ${response.statusText}`);
    }
    
    const data = await response.json();
    
    return {
      location: data.name,
      temperature: data.main.temp,
      condition: data.weather[0].description,
      humidity: data.main.humidity,
      units
    };
  }
}

// Register tool
import { registerTool } from '@openclaw/core';
registerTool(new WeatherTool());

Agent with Tool Usage

// Example: Agent processing with tool invocation
import { Agent } from '@openclaw/core';

const agent = new Agent({
  model: 'claude-3-5-sonnet-20241022',
  apiKey: process.env.ANTHROPIC_API_KEY,
  tools: ['getWeather', 'webSearch', 'browser']
});

async function processUserMessage(message, sessionKey) {
  // Load conversation context
  const context = await agent.getContext(sessionKey);
  
  // Process with tool support
  const response = await agent.process({
    messages: [...context, { role: 'user', content: message }],
    sessionKey,
    toolChoice: 'auto' // Let agent decide when to use tools
  });
  
  // Response includes tool calls if any were made
  if (response.toolCalls) {
    console.log('Tools used:', response.toolCalls.map(t => t.name));
  }
  
  // Save to memory
  await agent.saveContext(sessionKey, response);
  
  return response.content;
}

Session & Context Management

Session Key Format

OpenClaw uses session keys to route conversations:

// Format: channel:channelUserId:chatId
const sessionKey = 'telegram:123456789:987654321';
const sessionKey = 'whatsapp:+1234567890:group123';
const sessionKey = 'discord:user123:channel456';

// Parse session key
function parseSessionKey(sessionKey) {
  const [channel, userId, chatId] = sessionKey.split(':');
  return { channel, userId, chatId };
}

// Create session key
function createSessionKey(channel, userId, chatId) {
  return `${channel}:${userId}:${chatId || userId}`;
}

Context Window Management

// services/context-manager.js
import { ContextManager } from '@openclaw/core';

const contextManager = new ContextManager({
  provider: 'sqlite',
  dbPath: './data/context.db',
  maxMessages: 50,
  summarizationThreshold: 30
});

// Store message
await contextManager.addMessage(sessionKey, {
  role: 'user',
  content: 'What is the weather in Tokyo?',
  timestamp: Date.now()
});

// Retrieve context with automatic summarization
const context = await contextManager.getContext(sessionKey, {
  maxTokens: 4000, // Token budget for context
  includeSummary: true
});

// Manual context pruning
await contextManager.pruneContext(sessionKey, {
  keepLast: 20,
  summarizeRest: true
});

// Clear context for session
await contextManager.clearContext(sessionKey);

Plugin Development

Plugin Hook System

// plugins/my-plugin/index.js
export default class MyPlugin {
  constructor(core) {
    this.core = core;
  }

  // Hook: Before message is sent to agent
  async onBeforeAgentProcess(message, context) {
    console.log('Processing message:', message.text);
    
    // Modify message or context
    if (message.text.includes('urgent')) {
      context.priority = 'high';
    }
    
    return { message, context };
  }

  // Hook: After agent response, before sending
  async onBeforeMessageSend(response, sessionKey) {
    // Add custom footer
    response.text += '\n\n_Powered by OpenClaw_';
    
    // Log analytics
    await this.logAnalytics(sessionKey, response);
    
    return response;
  }

  // Hook: On tool execution
  async onToolExecute(toolName, params, result) {
    console.log(`Tool ${toolName} executed with:`, params);
    return result;
  }

  async logAnalytics(sessionKey, response) {
    // Custom analytics logic
  }
}

export const manifest = {
  name: 'my-plugin',
  version: '1.0.0',
  hooks: [
    'onBeforeAgentProcess',
    'onBeforeMessageSend',
    'onToolExecute'
  ]
};

Plugin Configuration

# config/plugins.yaml
plugins:
  - name: my-plugin
    enabled: true
    config:
      customSetting: value
      
  - name: analytics-plugin
    enabled: true
    config:
      endpoint: https://analytics.example.com
      apiKey: ${ANALYTICS_API_KEY}
      
  - name: calendar-integration
    enabled: false

Advanced Configuration

Multi-Model Fallback

// config/models.js
export const modelConfig = {
  providers: [
    {
      name: 'primary',
      provider: 'anthropic',
      model: 'claude-3-5-sonnet-20241022',
      apiKey: process.env.ANTHROPIC_API_KEY,
      priority: 1
    },
    {
      name: 'fallback-1',
      provider: 'openai',
      model: 'gpt-4-turbo',
      apiKey: process.env.OPENAI_API_KEY,
      priority: 2
    },
    {
      name: 'fallback-2',
      provider: 'ollama',
      model: 'llama3',
      baseURL: 'http://localhost:11434',
      priority: 3
    }
  ],
  
  fallbackStrategy: 'priority', // or 'round-robin', 'random'
  retryAttempts: 3,
  timeoutMs: 30000
};

// Agent will automatically fallback on errors
import { Agent } from '@openclaw/core';
const agent = new Agent({ models: modelConfig });

Memory Backends

// SQLite (default)
export const memoryConfig = {
  provider: 'sqlite',
  path: './data/memory.db'
};

// PostgreSQL
export const memoryConfig = {
  provider: 'postgres',
  connectionString: process.env.DATABASE_URL,
  schema: 'openclaw_memory'
};

// Redis
export const memoryConfig = {
  provider: 'redis',
  host: process.env.REDIS_HOST || 'localhost',
  port: process.env.REDIS_PORT || 6379,
  password: process.env.REDIS_PASSWORD,
  db: 0,
  ttl: 2592000 // 30 days in seconds
};

Common Patterns

Multi-Channel Broadcasting

// Broadcast message to multiple channels
import { Gateway } from '@openclaw/core';

const gateway = new Gateway();

async function broadcast(message, channels) {
  const promises = channels.map(async ({ channel, userId }) => {
    const sessionKey = `${channel}:${userId}:${userId}`;
    await gateway.sendMessage(sessionKey, {
      text: message,
      metadata: { broadcast: true }
    });
  });
  
  await Promise.all(promises);
}

// Usage
await broadcast('System maintenance in 10 minutes', [
  { channel: 'telegram', userId: '123456' },
  { channel: 'discord', userId: '789012' },
  { channel: 'whatsapp', userId: '+1234567890' }
]);

Scheduled Tasks with Cron

// plugins/scheduler/index.js
import cron from 'node-cron';
import { Gateway } from '@openclaw/core';

export default class SchedulerPlugin {
  constructor(core) {
    this.core = core;
    this.gateway = new Gateway();
    this.jobs = [];
  }

  async initialize() {
    // Daily summary at 9 AM
    const dailySummary = cron.schedule('0 9 * * *', async () => {
      await this.sendDailySummary();
    });
    
    this.jobs.push(dailySummary);
    
    // Hourly reminder check
    const reminderCheck = cron.schedule('0 * * * *', async () => {
      await this.checkReminders();
    });
    
    this.jobs.push(reminderCheck);
  }

  async sendDailySummary() {
    const users = await this.core.getActiveUsers();
    
    for (const user of users) {
      const summary = await this.generateSummary(user);
      await this.gateway.sendMessage(user.sessionKey, {
        text: `📊 Daily Summary\n\n${summary}`
      });
    }
  }

  async checkReminders() {
    // Implementation
  }

  async cleanup() {
    this.jobs.forEach(job => job.stop());
  }
}

Webhook Integration

// services/webhook-handler.js
import express from 'express';
import { Gateway } from '@openclaw/core';

const app = express();
const gateway = new Gateway();

app.use(express.json());

// GitHub webhook
app.post('/webhooks/github', async (req, res) => {
  const event = req.headers['x-github-event'];
  const payload = req.body;
  
  if (event === 'push') {
    const message = `🔔 New push to ${payload.repository.full_name}\n` +
                   `Branch: ${payload.ref}\n` +
                   `Commits: ${payload.commits.length}\n` +
                   `Author: ${payload.pusher.name}`;
    
    // Send to configured channel
    await gateway.sendMessage(
      process.env.GITHUB_NOTIFICATION_SESSION,
      { text: message }
    );
  }
  
  res.status(200).send('OK');
});

app.listen(3001, () => {
  console.log('Webhook server running on port 3001');
});

Troubleshooting

Gateway Connection Issues

# Check Gateway is running
curl http://localhost:3000/health

# Check Gateway logs
tail -f logs/gateway.log

# Verify environment variables
./openclaw config verify

# Test channel connectivity
./openclaw channel test telegram

Channel Adapter Not Receiving Messages

// Enable debug logging
// config/gateway.yaml
logging:
  level: debug
  channels: true
  
// Or via environment
DEBUG=openclaw:channel:* npm run gateway:start

// Common issues:
// 1. Webhook not configured (Telegram, Discord)
// 2. Wrong bot token
// 3. Firewall blocking incoming connections
// 4. WhatsApp session expired (re-auth needed)

Memory/Context Issues

// Check context size
import { ContextManager } from '@openclaw/core';
const cm = new ContextManager();

const stats = await cm.getContextStats(sessionKey);
console.log('Messages:', stats.messageCount);
console.log('Estimated tokens:', stats.tokenCount);

// If context too large:
await cm.summarizeContext(sessionKey);

// Or reset completely:
await cm.clearContext(sessionKey);

Model API Errors

# Test API connectivity
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-3-5-sonnet-20241022","max_tokens":1024,"messages":[{"role":"user","content":"test"}]}'

# Check API key validity
./openclaw models test anthropic

# Enable model fallback
# config/agent.js
export const agentConfig = {
  enableFallback: true,
  fallbackModels: ['openai/gpt-4-turbo', 'ollama/llama3']
};

WhatsApp QR Code Not Appearing

# Clear WhatsApp session
rm -rf sessions/whatsapp/*

# Restart WhatsApp adapter with fresh auth
./openclaw channel stop whatsapp
./openclaw channel start whatsapp --fresh-auth

# Check logs for QR code
tail -f logs/whatsapp.log

# If using Docker, ensure terminal is attached
docker-compose logs -f whatsapp

Database Migration Issues

# Check current migration status
./openclaw db status

# Run pending migrations
./openclaw db migrate

# Rollback last migration
./openclaw db rollback

# Reset database (WARNING: deletes all data)
./openclaw db reset --confirm

Performance Optimization

// config/performance.js
export const performanceConfig = {
  // Enable response streaming for faster UX
  streaming: true,
  
  // Parallel tool execution
  parallelTools: true,
  maxParallelTools: 3,
  
  // Context caching (reduces API calls)
  contextCache: {
    enabled: true,
    ttl: 300, // 5 minutes
    maxSize: 100 // Cache 100 sessions
  },
  
  // Rate limiting per user
  rateLimit: {
    enabled: true,
    maxRequests: 50,
    windowMs: 60000 // 1 minute
  }
};

Production Deployment Checklist

# 1. Set secure secrets
GATEWAY_SECRET=$(openssl rand -hex 32)

# 2. Use environment-specific configs
NODE_ENV=production

# 3. Configure process manager
# pm2 ecosystem.config.js
module.exports = {
  apps: [{
    name: 'openclaw-gateway',
    script: './dist/gateway.js',
    instances: 2,
    exec_mode: 'cluster',
    env: {
      NODE_ENV: 'production'
    }
  }]
};

# 4. Set up monitoring
# - Health check endpoint: /health
# - Metrics endpoint: /metrics (Prometheus)
# - Logging: Winston + external aggregator

# 5. Enable HTTPS
# Use reverse proxy (nginx, Caddy) with SSL cert

# 6. Database backups
# PostgreSQL: pg_dump scheduled via cron
# SQLite: File-based backups

# 7. Update strategy
# Blue-green deployment or rolling updates
# Test in staging first

This skill covers OpenClaw installation, channel configuration, agent setup, plugin development, and production deployment. All code examples use environment variables for secrets and demonstrate real integration patterns.