LeoYeAI/agent-master-skills / skills/bengii-gemini-fix
openclaw
FlaggedComprehensive guide for installing, configuring, operating, and troubleshooting OpenClaw — a self-hosted, multi-channel AI agent gateway. Use when the user asks about OpenClaw setup, configuration, channel management (WhatsApp/Telegram/Discord/Slack/iMessage/etc.), model provider setup, Gateway operations, multi-agent routing, security hardening, troubleshooting, or any maintenance task related to their local OpenClaw installation. Also use when encountering errors from `openclaw` CLI commands or the Gateway daemon.
references/channel_troubleshooting.md
View on GitHub# OpenClaw Channel Troubleshooting Reference
Per-channel deep diagnostics and failure signatures. Use this when messages aren't flowing or channels behave unexpectedly.
## Table of Contents
- [Universal Command Ladder](#universal-command-ladder)
- [WhatsApp Deep Troubleshooting](#whatsapp-deep-troubleshooting)
- [Telegram Deep Troubleshooting](#telegram-deep-troubleshooting)
- [Discord Deep Troubleshooting](#discord-deep-troubleshooting)
- [Slack Deep Troubleshooting](#slack-deep-troubleshooting)
- [Pairing System](#pairing-system)
- [Group Chat Troubleshooting](#group-chat-troubleshooting)
## Universal Command Ladder
Always start here:
```bash
openclaw status # 1. Quick overview
openclaw gateway status # 2. Daemon running? RPC ok?
openclaw logs --follow # 3. Watch for errors
openclaw doctor # 4. Config/service diagnostics
openclaw channels status --probe # 5. Per-channel probes
```
Expected healthy output:
- `Runtime: running`
- `RPC probe: ok`
- Channel probes show `connected/ready`
## WhatsApp Deep Troubleshooting
### Setup
```bash
# Step 1: Configure access policy
openclaw config set channels.whatsapp.dmPolicy '"pairing"'
openclaw config set channels.whatsapp.allowFrom '["+15551234567"]' --json
# Step 2: Link via QR
openclaw channels login --channel whatsapp
# For specific account:
openclaw channels login --channel whatsapp --account work
# Step 3: Start and approve
openclaw gateway
openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>
```
### Deployment Patterns
| Pattern | Config | Notes |
|---|---|---|
| Dedicated number (recommended) | `dmPolicy: "allowlist"` | Separate WhatsApp identity |
| Personal number | `dmPolicy: "allowlist"`, `selfChatMode: true` | Add your own number to `allowFrom` |
### Failure Signatures
| Symptom | Log Hint | Fix |
|---|---|---|
| Not linked / QR required | No creds on disk | `openclaw channels login --channel whatsapp` |
| Linked but disconnected / reconnect loop | Connection drops | `openclaw doctor`, check logs, try re-login |
| No replies to DMs | `pairing request` | Check `openclaw pairing list whatsapp`, approve sender |
| Group messages ignored | `drop guild message (mention required)` | Check `requireMention`, `groupPolicy`, `groupAllowFrom`, `groups` allowlist |
| No active listener when sending | Outbound send fails | Ensure gateway is running and WhatsApp socket is active |
| Self-chat confusion | Messages to yourself loop | Use dedicated number, or set `selfChatMode: true` |
### WhatsApp Config Keys
- Access: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`
- Delivery: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `sendReadReceipts`, `ackReaction`
- Multi-account: `accounts.<id>.enabled`, `accounts.<id>.authDir`
- Operations: `configWrites`, `debounceMs`
- Credential path: `~/.openclaw/credentials/whatsapp/<accountId>/creds.json`
### Runtime Model
- Gateway owns the WhatsApp socket and reconnect loop
- Only one session per Gateway (Baileys constraint)
- Status and broadcast chats (`@status`, `@broadcast`) are ignored
- Use Bun runtime with caution — Node.js recommended for WhatsApp
## Telegram Deep Troubleshooting
### Setup
```bash
# Step 1: Create bot with @BotFather
# /newbot → get token
# Step 2: Configure
openclaw config set channels.telegram.enabled true --json
openclaw config set channels.telegram.botToken '"123:abc"' --json
# Or use env: TELEGRAM_BOT_TOKEN=...
# Step 3: BotFather settings
# /setprivacy → Disable (for group messages without @mention)
# /setjoingroups → Allow (for group adds)
# Step 4: Start and approve
openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>
```
### Finding User IDs
Telegram user IDs are numeric. Find yours:
- Forward a message from yourself to @userinfobot
- Or use `openclaw pairing list telegram` to see pending IDs
### Failure Signatures
| Symptom | Log Hint | Fix |
|---|---|---|
| Bot doesn't respond to group messages | `mention required` | `requireMention=false` + BotFather `/setprivacy` → Disable, then remove+re-add bot to group |
| Bot not seeing messages at all | No inbound logs | Check `channels.telegram.groups` has `"*"`, verify bot in group |
| `/start` gets no reply | `pairing request` | `openclaw pairing list telegram`, approve sender |
| Commands partially work | `pairing` / `allowFrom` | Authorize sender identity even when `groupPolicy: "open"` |
| `setMyCommands failed` | DNS/HTTPS error | Check outbound access to `api.telegram.org` |
| `TypeError: fetch failed` | Network error | Recoverable — OpenClaw retries. If persistent, use proxy |
| IPv6 connectivity issues | Intermittent failures | Set `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` |
| Allowlist with `@username` not working | Username mismatch | Use numeric ID, not `@username`. Run `openclaw doctor --fix` |
### Telegram Proxy
For VPS with unstable egress:
```json5
{
channels: {
telegram: {
proxy: "socks5://user:pass@proxy-host:1080",
},
},
}
```
### Telegram Network Env Overrides
```bash
OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1 # Force IPv4
OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first # IPv4 preference
```
Validate DNS: `dig +short api.telegram.org A && dig +short api.telegram.org AAAA`
### Telegram Features
- Streaming: `channels.telegram.streaming` → `off | partial | block | progress`
- Custom commands via `channels.telegram.customCommands`
- Native commands: `commands.native: "auto"` (default for Telegram)
- Forum topics isolate sessions with `:topic:<threadId>`
## Discord Deep Troubleshooting
### Setup
```bash
# Step 1: Create Discord app
# Discord Developer Portal → New Application → Bot → Message Content Intent
# Step 2: Enable required intents
# - Message Content Intent (REQUIRED)
# - Server Members Intent (recommended)
# Step 3: Generate invite URL with scopes: bot, applications.commands
# Permissions: View Channels, Send Messages, Read Message History, Embed Links, Attach Files
# Step 4: Enable Developer Mode
# User Settings → Advanced → Developer Mode → On
# Right-click server → Copy Server ID
# Right-click avatar → Copy User ID
# Step 5: Configure OpenClaw
openclaw config set channels.discord.token '"YOUR_BOT_TOKEN"' --json
openclaw config set channels.discord.enabled true --json
openclaw gateway restart
# Step 6: Approve pairing
openclaw pairing list discord
openclaw pairing approve discord <CODE>
```
### Guild Workspace Setup
```json5
{
channels: {
discord: {
groupPolicy: "allowlist",
guilds: {
YOUR_SERVER_ID: {
requireMention: true, // false to respond to all messages
users: ["YOUR_USER_ID"], // Who can interact
},
},
},
},
}
```
### Failure Signatures
| Symptom | Log Hint | Fix |
|---|---|---|
| Bot offline in Discord | No connection | Check token, verify `enabled: true` |
| Bot ignores guild messages | `mention required` | Set `requireMention: false` for the guild |
| Bot ignores DMs | `pairing request` | `openclaw pairing list discord`, approve |
| Group DMs ignored | `groupEnabled=false` | Default behavior — group DMs aren't supported by default |
| Slash commands not registered | `commands.native` mismatch | Ensure `commands.native: "auto"` |
| Commands visible but "not authorized" | Auth policy | Expected — commands enforce OpenClaw auth even when visible in UI |
| Missing Message Content | No content in logs | Enable **Message Content Intent** in Developer Portal |
### Discord Runtime Model
- Reply routing is deterministic: Discord in → Discord out
- Guild channels isolated: `agent:<agentId>:discord:channel:<channelId>`
- DMs share main session by default (`session.dmScope=main`)
- Native slash commands: isolated sessions with `CommandTargetSessionKey`
## Slack Deep Troubleshooting
### Setup (Socket Mode)
```bash
# Step 1: Create Slack app
# Enable Socket Mode
# Create App Token (xapp-...) with connections:write
# Install app → copy Bot Token (xoxb-...)
# Step 2: Subscribe events
# app_mention, message.channels, message.groups, message.im, message.mpim
# reaction_added, reaction_removed, member_joined_channel, etc.
# Step 3: Configure
```
```json5
{
channels: {
slack: {
enabled: true,
mode: "socket", // or "http"
appToken: "xapp-...",
botToken: "xoxb-...",
},
},
}
```
### Slack App Manifest
Copy-paste ready manifest for quick setup — see the full manifest in the Slack section of the OpenClaw docs.
Key scopes needed:
- `chat:write`, `channels:history`, `channels:read`
- `groups:history`, `im:history`, `mpim:history`
- `users:read`, `app_mentions:read`, `assistant:write`
- `reactions:read`, `reactions:write`, `pins:read`, `pins:write`
- `emoji:read`, `commands`, `files:read`, `files:write`
### Failure Signatures
| Symptom | Log Hint | Fix |
|---|---|---|
| No replies in channels | `groupPolicy` | Check channel allowlist, `requireMention`, per-channel users |
| DMs ignored | `dm.enabled`, `dmPolicy` | Check `channels.slack.dm.enabled`, pairing/allowlist |
| Socket mode not connecting | Connection error | Verify `appToken`, check network |
| HTTP mode not receiving | Webhook error | Check signing secret, webhook path, Slack Request URLs |
| Slash commands not firing | `commands.native` | Enable `channels.slack.commands.native: true` or `slashCommand.enabled: true` |
## Pairing System
### DM Pairing
When `dmPolicy: "pairing"` (default), unknown senders receive a one-time code:
- 8 characters, uppercase, no ambiguous chars (0O1I)
- Expires after 1 hour
- Max 3 pending requests per channel (additional requests ignored)
- Bot only sends pairing message once per ~hour per sender
```bash
openclaw pairing list --channel <channel>
openclaw pairing approve <channel> <CODE>
```
### Node Device Pairing
For iOS/Android/macOS/headless nodes:
```bash
# Via Telegram (recommended for iOS)
# Send pairing command to bot
# Approve
openclaw pairing list --channel <channel> --type node
openclaw pairing approve --type node <CODE>
```
### Pairing State
- DM pairings stored in channel allow-store
- Merged with configured `allowFrom`
- If no allowlist configured, linked self number is allowed by default
- Outbound `fromMe` DMs are never auto-paired
## Group Chat Troubleshooting
### Message Flow Decision Tree
```
groupPolicy? disabled → DROP
groupPolicy? allowlist → group in allowlist? NO → DROP
requireMention? YES → mentioned? NO → store for context only
OTHERWISE → REPLY
```
### Common Issues
| Issue | Check | Fix |
|---|---|---|
| All group messages ignored | `groupPolicy: "disabled"` | Change to `"allowlist"` or `"open"` |
| Specific group ignored | Missing from `groups` allowlist | Add group ID or use `"*"` |
| Only mentioned messages get replies | `requireMention: true` | Set `false` or use `/activation always` |
| Sender blocked in group | `groupAllowFrom` / `groupPolicy: "allowlist"` | Add sender to `groupAllowFrom` |
### Mention Gating Config
```json5
{
channels: {
whatsapp: {
groups: {
"*": { requireMention: true },
"123@g.us": { requireMention: false }, // Specific group override
},
},
},
agents: {
list: [{
id: "main",
groupChat: {
mentionPatterns: ["@openclaw", "openclaw"],
historyLimit: 50,
},
}],
},
}
```
### Per-Group Tool Restrictions
```json5
{
channels: {
telegram: {
groups: {
"*": { tools: { deny: ["exec"] } },
"-1001234567890": {
tools: { deny: ["exec", "read", "write"] },
toolsBySender: {
"id:123456789": { alsoAllow: ["exec"] }, // Admin override
},
},
},
},
},
}
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |