Skip to content

LeoYeAI/agent-master-skills / skills/bengii-gemini-fix

openclaw

Flagged

Comprehensive 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.

FileKindSize
README.mdmarkdown7.5 KB
README_CN.mdmarkdown7.3 KB
SKILL.mdskill md18.7 KB
_meta.jsonconfig286 B
references/acp_agents.mdmarkdown12.6 KB
references/agent_runtime.mdmarkdown5.6 KB
references/architecture.mdmarkdown3.8 KB
references/automation.mdmarkdown5.8 KB
references/bonjour.mdmarkdown3.3 KB
references/browser.mdmarkdown8.5 KB
references/channel_routing.mdmarkdown4.0 KB
references/channel_troubleshooting.mdmarkdown11.6 KB
references/channels.mdmarkdown6.2 KB
references/clawhub.mdmarkdown3.6 KB
references/config_reference.mdmarkdown11.2 KB
references/diffs_firecrawl.mdmarkdown3.3 KB
references/elevated.mdmarkdown2.8 KB
references/exec.mdmarkdown6.5 KB
references/exec_approvals.mdmarkdown3.1 KB
references/gateway_internals.mdmarkdown7.7 KB
references/gateway_ops.mdmarkdown9.6 KB
references/heartbeat.mdmarkdown4.9 KB
references/hooks.mdmarkdown14.6 KB
references/install.mdmarkdown4.1 KB
references/llm_task.mdmarkdown2.6 KB
references/lobster.mdmarkdown7.8 KB
references/media.mdmarkdown4.2 KB
references/memory.mdmarkdown11.9 KB
references/model_failover.mdmarkdown3.1 KB
references/multi_agent.mdmarkdown4.4 KB
references/nodes.mdmarkdown8.8 KB
references/openprose.mdmarkdown2.6 KB
references/pairing.mdmarkdown3.1 KB
references/pdf_tool.mdmarkdown3.5 KB
references/platforms.mdmarkdown2.7 KB
references/plugins.mdmarkdown6.9 KB
references/polls.mdmarkdown2.2 KB
references/presence_discovery.mdmarkdown2.2 KB
references/providers.mdmarkdown6.0 KB
references/queue.mdmarkdown2.1 KB
references/remote_access.mdmarkdown4.7 KB
references/sandboxing.mdmarkdown5.6 KB
references/secrets.mdmarkdown5.4 KB
references/security.mdmarkdown24.5 KB
references/sessions.mdmarkdown8.9 KB
references/skills.mdmarkdown4.4 KB
references/slash_commands.mdmarkdown5.1 KB
references/streaming.mdmarkdown1.8 KB
references/subagents.mdmarkdown12.3 KB
references/thinking.mdmarkdown2.8 KB
references/tools.mdmarkdown13.3 KB
references/tui.mdmarkdown4.0 KB
references/voice.mdmarkdown2.7 KB
references/web_tools.mdmarkdown2.7 KB
references/web_ui.mdmarkdown4.5 KB

references/channels.md

View on GitHub
# OpenClaw Channel Reference

## Table of Contents

- [Supported Channels](#supported-channels)
- [WhatsApp](#whatsapp)
- [Telegram](#telegram)
- [Discord](#discord)
- [Slack](#slack)
- [Signal](#signal)
- [iMessage / BlueBubbles](#imessage--bluebubbles)
- [Other Channels (Plugins)](#other-channels-plugins)
- [Channel CLI Commands](#channel-cli-commands)
- [Group Chat Configuration](#group-chat-configuration)
- [DM Access Policies](#dm-access-policies)
- [Multi-Account Channels](#multi-account-channels)
- [Troubleshooting](#troubleshooting)

## Supported Channels

### Built-in (core)

| Channel | Library | Auth Method | Notes |
|---|---|---|---|
| WhatsApp | Baileys (WhatsApp Web) | QR pairing | Most popular; stores state on disk |
| Telegram | grammY (Bot API) | Bot token | Fastest setup; supports groups |
| Discord | discord.js | Bot token + Gateway | Servers, channels, DMs |
| IRC | irc-framework | Server config | Channels + DMs |
| Slack | Bolt SDK | Workspace app | Workspace apps |
| Signal | signal-cli | signal-cli setup | Privacy-focused |
| BlueBubbles | REST API | macOS server | Recommended for iMessage |
| iMessage (legacy) | imsg CLI | macOS only | Deprecated — use BlueBubbles |

### Plugins (installed separately)

Feishu/Lark, Google Chat, Mattermost, Microsoft Teams, Synology Chat, LINE, Nextcloud Talk, Matrix, Nostr, Tlon, Twitch, Zalo, Zalo Personal.

Install plugins: `openclaw plugins install <name>`.

## WhatsApp

```bash
# Pair via QR code
openclaw channels login --channel whatsapp

# Check status
openclaw channels status --probe

# Logout
openclaw channels logout --channel whatsapp
```

Config:

```json5
{
  channels: {
    whatsapp: {
      enabled: true,
      allowFrom: ["+15555550123"],       // Phone numbers
      groups: {
        "*": { requireMention: true },   // Mention gating for all groups
      },
    },
  },
}
```

Key notes:
- Only one WhatsApp session per Gateway (Baileys constraint)
- QR pairing required; re-pair if session expires
- WhatsApp stores significant state on disk
- Group messages require mention by default (`requireMention`)

## Telegram

```bash
# Add bot with token
openclaw channels add --channel telegram --token <BOT_TOKEN>

# Or interactive
openclaw channels add --channel telegram
```

Config:

```json5
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",           // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"],         // Telegram user IDs
    },
  },
}
```

Get token from [@BotFather](https://t.me/BotFather).

## Discord

```bash
openclaw channels add --channel discord --token <BOT_TOKEN>
```

Config:

```json5
{
  channels: {
    discord: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",
    },
  },
}
```

Requirements:
- Create bot at [Discord Developer Portal](https://discord.com/developers/applications)
- Enable **Message Content Intent**
- Invite bot with proper permissions

## Slack

```json5
{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      signingSecret: "...",
    },
  },
}
```

Uses Bolt SDK; needs workspace app setup.

## Signal

Uses `signal-cli`. Requires separate signal-cli setup and registration.

## iMessage / BlueBubbles

**Recommended: BlueBubbles** (full feature support via REST API on macOS server).

Legacy iMessage via `imsg` CLI is deprecated.

## Other Channels (Plugins)

```bash
openclaw plugins list               # List available plugins
openclaw plugins install <name>     # Install a plugin
openclaw plugins info <name>        # Plugin details
openclaw plugins enable <name>      # Enable plugin
openclaw plugins disable <name>     # Disable plugin
openclaw plugins doctor             # Check plugin health
```

## Channel CLI Commands

```bash
openclaw channels list              # Show configured channels + auth
openclaw channels status            # Channel health (add --probe for extra checks)
openclaw channels logs              # Recent channel logs from gateway
openclaw channels add               # Wizard-style setup
openclaw channels remove            # Disable (--delete to remove config)
openclaw channels login             # Interactive login (WhatsApp)
openclaw channels logout            # Log out of channel
```

Flags:
- `--channel <name>`: whatsapp|telegram|discord|slack|signal|imessage|googlechat|mattermost|msteams
- `--account <id>`: Account ID (default: "default")
- `--name <label>`: Display name

## Group Chat Configuration

```json5
{
  agents: {
    list: [{
      id: "main",
      groupChat: {
        mentionPatterns: ["@openclaw", "openclaw"],
      },
    }],
  },
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },              // All groups
        "specific-group-id": { requireMention: false }, // Override
      },
    },
  },
}
```

## DM Access Policies

Set per-channel `dmPolicy`:

| Policy | Behavior |
|---|---|
| `"pairing"` (default) | Unknown senders get one-time pairing code |
| `"allowlist"` | Only senders in `allowFrom` |
| `"open"` | Allow all DMs (requires `allowFrom: ["*"]`) |
| `"disabled"` | Ignore all DMs |

Manage pairings:

```bash
openclaw pairing list --channel <channel>
openclaw pairing approve <id>
```

## Multi-Account Channels

Channels like Discord and Telegram support multiple bot accounts:

```bash
openclaw channels add --channel telegram --account alerts --name "Alerts Bot" --token $TOKEN
openclaw channels add --channel discord --account work --name "Work Bot" --token $TOKEN
openclaw channels remove --channel discord --account work --delete
```

When adding a non-default account to a channel using single-account config, OpenClaw auto-migrates to multi-account structure.

## Troubleshooting

### Messages Not Flowing

```bash
openclaw channels status --probe
openclaw pairing list --channel <channel>
openclaw config get channels
openclaw logs --follow
```

Check for:
- `mention required` — group mention policy filtering
- `pairing` / `pending approval` — sender not approved
- `missing_scope`, `Forbidden`, `401/403` — channel auth/permissions issue

### WhatsApp QR Issues

Re-pair: `openclaw channels login --channel whatsapp --verbose`

### Channels Run Simultaneously

All configured channels run at once; OpenClaw routes per chat automatically.
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall