name: 🐛 Bug Report
about: Create a report to help us improve
title: "[Bug] Multi-account Channel configuration causes message routing confusion without explicit bindings"
labels: bug, routing, channel
assignees: ''

Bug Description

When configuring a Channel with multiple accounts (accounts mode), if explicit binding rules are not defined for each account in the bindings configuration, messages may be routed to the wrong agent (cross-channel routing confusion).

Environment

• OpenClaw Version: 2026.2.23
• Channel Type: Telegram
• Configuration Mode: Multi-account (channels.telegram.accounts)

Reproduction Steps

Step 1: Configure Multi-account Channel

{
  "channels": {
    "telegram": {
      "enabled": true,
      "proxy": "http://127.0.0.1:7890",
      "accounts": {
        "default": {
          "botToken": "MAIN_BOT_TOKEN",
          "dmPolicy": "pairing"
        },
        "inkflow": {
          "botToken": "INKFLOW_BOT_TOKEN",
          "dmPolicy": "pairing"
        }
      }
    }
  }
}

Step 2: Configure Incomplete Bindings

{
  "bindings": [
    {
      "agentId": "inkflow",
      "match": {
        "channel": "telegram",
        "accountId": "inkflow"
      }
    }
  ]
}

Note: No binding rule for the main agent.

Step 3: Observed Behavior

Actual (Incorrect):

• Send message to @Mainbot → May route to inkflow agent ❌
• Send message to @InkFlowRobot → May route to main agent ❌
• Message routing is unstable and appears random

Expected:

• Send message to @Mainbot → Route to main agent ✅
• Send message to @InkFlowRobot → Route to inkflow agent ✅

Root Cause

When an account has no explicit binding, the routing logic may:

1. Fall back to default agent (main)
2. Or match another agent's binding
3. Result in unstable/unpredictable message routing

Solution Options

Option A: Enforce Explicit Configuration (Recommended)

Update documentation to clearly state: When using multi-account mode, explicit bindings MUST be configured for each account.

{
  "bindings": [
    {
      "agentId": "main",
      "match": {
        "channel": "telegram",
        "accountId": "default"
      }
    },
    {
      "agentId": "inkflow",
      "match": {
        "channel": "telegram",
        "accountId": "inkflow"
      }
    }
  ]
}

Option B: Configuration Validation

Add validation in openclaw doctor to warn about unbound accounts:

⚠️ Warning: telegram account 'default' has no binding rule
  → Add a binding or messages will route unpredictably

Option C: Auto Default Routing

When an account has no explicit binding, automatically route to default agent (main), but document this behavior clearly.

Working Configuration

{
  "agents": {
    "list": [
      {
        "id": "main",
        "model": "anthropic/claude-sonnet-4-6"
      },
      {
        "id": "inkflow",
        "workspace": "/root/.openclaw/workspace-writing",
        "agentDir": "/root/.openclaw/agents/inkflow/agent",
        "model": "bailian/qwen3.5-plus"
      }
    ]
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "proxy": "http://127.0.0.1:7890",
      "accounts": {
        "default": {
          "botToken": "${MAIN_TOKEN}",
          "dmPolicy": "pairing"
        },
        "inkflow": {
          "botToken": "${INKFLOW_TOKEN}",
          "dmPolicy": "pairing"
        }
      }
    }
  },
  "bindings": [
    {
      "agentId": "main",
      "match": {
        "channel": "telegram",
        "accountId": "default"
      }
    },
    {
      "agentId": "inkflow",
      "match": {
        "channel": "telegram",
        "accountId": "inkflow"
      }
    }
  ]
}

Impact

• Users configuring multi-account Channels
• Users migrating from single-account to multi-account (easy to miss binding configuration)
• Users creating new agents without synchronously updating bindings
• Potential security risk: sensitive messages may leak to wrong agents

Suggested Priority

1. High Priority: Documentation Update - Add ⚠️ WARNING to multi-account Channel configuration docs
2. Medium Priority: Configuration Validation - openclaw doctor should check for unbound accounts
3. Low Priority: Auto Default Routing - Automatically route unbound accounts to default agent

Related Documentation

• Channel Routing: https://docs.openclaw.ai/channels/channel-routing
• Multi-Agent Routing: https://docs.openclaw.ai/concepts/multi-agent

Additional Notes

This issue does not occur in single-account configuration, as the default account automatically routes to the default agent. However, in multi-account mode, explicit bindings MUST be configured for each account to prevent routing confusion.