Discord User Bot Client for OpenClaw WebSocket Channel

A Python client that bridges Discord user accounts with OpenClaw's WebSocket channel plugin using discord.py-self.

⚠️ Warning: This project uses discord.py-self which automates Discord user accounts. User automation is against Discord's Terms of Service. Use at your own risk. For production use, consider using the official Discord Bot API instead.

Features

• Full WebSocket Protocol Support - Complete implementation of OpenClaw WebSocket protocol
• Capabilities Negotiation - Automatic handshake and capability exchange
• Message Types - Text, images, files, voice, reactions, threads, typing indicators
• State Persistence - SQLite database for mappings, pairing codes, and allowlist
• Reconnection - Automatic reconnection with exponential backoff
• Rate Limiting - Built-in rate limiting to avoid Discord detection
• DM Security - Configurable security modes: open, allowlist, or paired

Requirements

• Python 3.10+
• Discord user token (see below)
• OpenClaw WebSocket server running

Installation

From Source

# Clone the repository
git clone https://github.com/your-repo/discord-openclaw-client.git
cd discord-openclaw-client

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

Using pip

pip install discord-openclaw-client

Configuration

Configuration File

Copy config.example.yaml to config.yaml and edit:

cp config.example.yaml config.yaml

Edit config.yaml:

discord:
  token: "YOUR_DISCORD_USER_TOKEN"  # Required
  channels:
    - 123456789012345678  # Optional: channels to monitor
  rate_limit: 1.0

openclaw:
  websocket_url: "ws://localhost:8765/ws"
  api_key: "sk_test_your_api_key"  # Required

database:
  path: "./state.db"

logging:
  level: "INFO"
  format: "text"

features:
  enable_reactions: true
  enable_typing: true
  enable_threads: true
  enable_voice: false
  dm_security: "paired"  # "open", "allowlist", or "paired"

Environment Variables

Alternatively, use environment variables:

export DISCORD_TOKEN="your_discord_token"
export OPENCLAW_WS_URL="ws://localhost:8765/ws"
export OPENCLAW_API_KEY="your_api_key"
export DATABASE_PATH="./state.db"
export LOG_LEVEL="INFO"

Getting a Discord User Token

⚠️ Security Note: Never share your Discord token. It provides full access to your account.

1. Open Discord in your browser
2. Open Developer Tools (F12)
3. Go to Network tab
4. Send a message or interact with Discord
5. Find a request and look for the Authorization header
6. Copy the token value

Usage

Running the Client

# With config file
discord-openclaw -c config.yaml

# Or with environment variables
discord-openclaw

DM Security Modes

• open - Accept all DMs (not recommended)
• allowlist - Only accept DMs from allowlisted users
• paired - Only accept DMs from users who completed pairing

Pairing Flow

When dm_security is set to paired, users must pair their Discord account:

1. User sends a message to the Discord account
2. Bot responds with pairing instructions
3. User enters pairing code in OpenClaw
4. After successful pairing, messages are relayed

Database Schema

The client uses SQLite for persistence:

• user_mappings - Discord ID ↔ WebSocket user ID mappings
• pairing_codes - Temporary pairing codes
• allowlist - Allowed Discord users
• connection_state - Key-value state store
• message_log - Debug message log

API Reference

WebSocket Messages

From OpenClaw

{
  "type": "message",
  "to": "discord:123456789",
  "content": {
    "type": "text",
    "text": "Hello!"
  }
}

To OpenClaw

{
  "type": "message",
  "from": "discord:123456789",
  "content": {
    "type": "text",
    "text": "Hello back!"
  },
  "metadata": {
    "discord_id": "123456789",
    "channel_id": "987654321",
    "message_id": "111222333"
  }
}

Development

Running Tests

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# With coverage
pytest --cov=src

Code Style

# Format code
ruff format .

# Check linting
ruff check .

# Type checking
mypy src

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Discord API   │────▶│  DiscordClient  │────▶│   StateManager  │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                               │                         │
                               ▼                         ▼
                        ┌─────────────────┐     ┌─────────────────┐
                        │  MessageMapper  │────▶│     Database    │
                        └─────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌─────────────────┐     ┌─────────────────┐
                        │ WebSocketClient │────▶│   OpenClaw WS   │
                        └─────────────────┘     └─────────────────┘

Troubleshooting

Connection Issues

• Check that OpenClaw WebSocket server is running
• Verify API key is correct
• Check network connectivity

Discord Token Issues

• Token may have expired - get a new one
• Account may be flagged for automation
• Try using a different account

Rate Limiting

If you're getting rate limited:

• Increase rate_limit value in config
• Reduce message frequency
• Consider using official Discord Bot API instead

License

MIT License - See LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

Disclaimer

This project is for educational and personal use only. Using automated user accounts violates Discord's Terms of Service. The authors are not responsible for any consequences of using this software, including but not limited to account suspension or termination.

For production use, please consider using the official Discord Bot API instead.