Knowledge/chat-topics/openclaw-session-routing-two-agent-proposal.md

OpenClaw session routing / two-agent proposal

Problem observed

Michael reported cross-channel bleed where parts of WebUI-originated conversation continuations were appearing in Telegram. This did not seem limited to heartbeat content; some leaked text looked like the tail end of a WebUI conversation.

Diagnosis summary

The issue appears more like shared main-agent/session routing bleed than a simple heartbeat-only bug.

Most suspicious current config factors:

• heartbeat configured under agents.defaults.heartbeat
• heartbeat target explicitly set to Telegram / 1411368290
• tools.sessions.visibility set to all
• single shared main agent serving multiple surfaces

Less suspicious / probably correct:

• session.dmScope = "per-channel-peer" looks like the right direction and should likely be kept.

Docs/research conclusion

OpenClaw docs indicate the official mechanism for channel-to-agent routing is:

• agents.list for agent definitions
• bindings for mapping inbound channels/accounts/peers to agents

Important doc takeaways:

• routing chooses one agent deterministically
• bindings can match by channel, account, peer, etc.
• WebChat attaches to the selected agent and defaults to that agent’s main session

Proposed separation model

Use two agents with the same workspace but different channel roles:

• telegram-main
• webui-main

Keep grok-cron as-is.

Intended behaviour

• Telegram inbound traffic binds to telegram-main
• WebUI/default interactive use binds to webui-main
• heartbeat lives only on telegram-main
• both agents may share the same workspace for files/projects

Config proposal file created

Saved comparison file:

• /home/openclaw/.openclaw/openclaw.two-agent-proposal.json

Live config was not overwritten.

Key proposed config changes

Remove heartbeat from defaults

Remove:

• agents.defaults.heartbeat

Replace main with two agents

New agent layout:

• telegram-main with heartbeat block
• webui-main marked default: true
• existing grok-cron retained

Add bindings

Add top-level:

"bindings": [
  {
    "agentId": "telegram-main",
    "match": {
      "channel": "telegram"
    }
  }
]

Current confidence

High confidence on the architectural direction:

• separate agents + bindings is the right OpenClaw-native way to reduce cross-channel bleed

Lower confidence on exact final production syntax until validated live, because the proposal has not yet been tested/restarted.

User preference / outcome

Michael preferred a separate comparison config file rather than changing the live config immediately. The proposed two-agent config was written out for comparison and reviewed in short diff form.