nullclaw channel

Manage and monitor messaging channels

The nullclaw channel command provides utilities for managing messaging channels, checking their health, and starting individual channels.

Subcommands

nullclaw channel status            # Show health of all configured channels
nullclaw channel start <name>      # Start a specific channel

channel status

Display the health and configuration status of all channels:

nullclaw channel status

Example Output

Channel Status:

✓ telegram (main)
  Status: connected
  Bot: @my_bot
  Allowed users: 2
  Uptime: 2h 15m

✓ discord (main)
  Status: connected
  Guild: My Server (123456789)
  Gateway: wss://gateway.discord.gg
  Uptime: 2h 15m

✗ signal (main)
  Status: not configured
  Error: signal-cli not found

○ nostr
  Status: disabled

Status Icons

• ✓ - Channel connected and healthy
• ✗ - Channel configured but not working
• ○ - Channel not configured or disabled

channel start

Start a specific channel by name:

nullclaw channel start telegram
nullclaw channel start discord
nullclaw channel start signal

This is useful for:

• Testing channel configuration
• Running a single channel without the full gateway
• Debugging connection issues

Example

$ nullclaw channel start telegram
Starting Telegram channel...
Bot connected: @my_nullclaw_bot
Listening for messages (long-polling)...
Press Ctrl+C to stop

Supported Channels

You can start any configured channel:

• telegram - Telegram bot (long-polling)
• discord - Discord bot (WebSocket)
• slack - Slack bot (Socket Mode or HTTP)
• signal - Signal messenger (signal-cli)
• nostr - Nostr relays (NIP-17 + NIP-04)
• irc - IRC networks
• matrix - Matrix homeserver
• whatsapp - WhatsApp Business API
• lark - Lark/Feishu
• line - LINE Messaging API
• mattermost - Mattermost
• qq - QQ
• onebot - OneBot protocol
• dingtalk - DingTalk
• email - Email (IMAP + SMTP)
• imessage - iMessage (macOS only)
• web - WebSocket relay
• maixcam - MaixCam device

Health Checks

The channel status command performs these checks:

1. Configuration: Is the channel configured in config.json?
2. Credentials: Are API keys/tokens present?
3. Connectivity: Can we connect to the service?
4. Authentication: Do credentials work?
5. Message flow: Can we receive/send messages?

Configuration

Channels are configured in ~/.nullclaw/config.json:

{
  "channels": {
    "telegram": {
      "accounts": {
        "main": {
          "bot_token": "123456:ABC-DEF...",
          "allow_from": ["alice", "bob"]
        }
      }
    },
    "discord": {
      "accounts": {
        "main": {
          "token": "MTA...",
          "guild_id": "123456789"
        }
      }
    }
  }
}

See Channel Configuration for details.

Examples

Check all channels

nullclaw channel status

Test Telegram configuration

nullclaw channel start telegram

Send a message to your bot. You should see:

Received message from alice: Hello!
Agent response: Hello! How can I help you?

Debug connection issues

# Start channel with verbose output
nullclaw channel start discord

# Check for connection errors
# Common issues:
# - Invalid token
# - Missing intents
# - Network restrictions

Troubleshooting

Telegram: “Invalid bot token”

Verify token with BotFather:

# Get bot info
curl https://api.telegram.org/bot<TOKEN>/getMe

Discord: “Gateway connection failed”

Check intents in Discord Developer Portal:

• MESSAGE_CONTENT (required)
• GUILD_MESSAGES (required)
• DIRECT_MESSAGES (required)

Signal: “signal-cli not found”

Install signal-cli:

# macOS
brew install signal-cli

# Linux
# See https://github.com/AsamK/signal-cli

Nostr: “nak not found”

Install nak:

# macOS/Linux
go install github.com/fiatjaf/nak@latest

See Also

• Channel Configuration - Config reference
• Telegram Guide - Telegram setup
• Discord Guide - Discord setup
• Nostr Guide - Nostr setup
• Gateway - Start all channels