#Clarification on sessions

1 messages · Page 1 of 1 (latest)

sand barn
#

I just ran openclaw doctor after upgrading and it suggested migrating some legacy telegram stuff or something to that effect (i no longer remember what unfortunately). and now I have three main sessions, when before it just used to be one main session. is this normal? what exactly did doctor change?

muted belfryBOT
#

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> âś… Mark Solution

wispy troutBOT
#

Yep, this can be normal — openclaw doctor didn’t “create new conversations”, but it can change (a) how sessions are stored, and (b) how your config is shaped, which can make the UI show what looks like “multiple mains”.

First though: what version are you on?
Please paste:

  • openclaw --version
  • (if you can) the output of the last openclaw doctor run

What openclaw doctor actually changes

Per the docs, Doctor is the “repair + migration” tool and it can do two big categories of changes:

1) Config migrations (rewrites ~/.openclaw/openclaw.json)

It migrates legacy keys into the current schema (lots of the old routing.* / agent.* shapes got renamed/moved). Docs: https://docs.openclaw.ai/gateway/doctor

2) On-disk state migration (moves where sessions live)

This is the one that often surprises people:

#
  • Sessions + transcripts moved from: ~/.openclaw/sessions/
    to: ~/.openclaw/agents/<agentId>/sessions/
  • Agent dir moved from: ~/.openclaw/agent/
    to: ~/.openclaw/agents/<agentId>/agent/

Doctor is “best-effort” and may leave legacy folders behind as backups. Same doc: https://docs.openclaw.ai/gateway/doctor

Why you might now see “three main sessions”

OpenClaw’s session model is: “one primary direct-chat session per agent”, but direct chats can be grouped in different ways.

If your setup is now isolating DMs more (for security), you can end up with multiple sessions of kind “main” (e.g., one per DM peer / per channel), which can look like “3 mains” in the dashboard.

This is controlled by session.dmScope (docs explain the modes and why):
https://docs.openclaw.ai/concepts/session

Quick check: look in ~/.openclaw/openclaw.json for something like:

# 
{
  session: {
    dmScope: "per-channel-peer" // or per-peer / per-account-channel-peer
  }
}

If you set it back to "main", you’ll get the old “everything collapses into one DM context” behavior — but that’s not recommended if multiple people/accounts can DM the bot, because it can leak context across users.

The “legacy Telegram stuff” you vaguely remember

That’s likely Doctor offering to fix Telegram allowlists that used @username entries by resolving them to numeric Telegram user IDs (Telegram config expects IDs). Docs mention:
https://docs.openclaw.ai/channels/telegram (search for openclaw doctor --fix)

If you paste openclaw --version + the doctor output (or a screenshot of the 3 “main” sessions showing their keys/agent ids), I can tell you which of the above happened in your case.

sand barn
# 
bruh@MacBook-Air ~ % openclaw --version
2026.2.25

i don't have the output of openclaw doctor anymore unless it logged it somewhere by default.

i can't upload pics, but the "three main sessions" i'm seeing are named agent:main:telegram:direct:<my telegram numeric user id>, agent:main:main and agent:main:telegram:slash:<my telegram numeric user id>

wispy troutBOT
#

Those three keys are expected, and they map to three different “direct-ish” buckets — the UI calling them all “main sessions” is just a labeling/UX thing.

Here’s what each one is:

  1. agent:main:main
    This is the canonical “main direct chat bucket” for the main agent. It’s what you get when DMs are not isolated (or when you’re talking via a UI surface that uses the main bucket).

  2. agent:main:telegram:direct:<yourUserId>
    This is your Telegram DM session when DM isolation is enabled (i.e. session.dmScope is something like per-channel-peer / per-peer / per-account-channel-peer). With the default dmScope: "main", Telegram DMs would usually collapse into agent:main:main instead.
    Session routing doc: https://docs.openclaw.ai/concepts/session

  3. agent:main:telegram:slash:<yourUserId>
    This is an isolated command session created when you use native commands on Telegram (slash menu). It exists so command handling doesn’t pollute your real chat transcript, while still being able to target your real chat session via CommandTargetSessionKey.
    Docs: https://docs.openclaw.ai/tools/slash-commands

So did openclaw doctor “create” these?

Not really in the “made new conversations” sense:

#
  • The telegram:slash: one is created when you run native commands (or sometimes when Telegram triggers native command flows).
  • The telegram:direct: one strongly suggests your config now has DM isolation enabled (or it changed at upgrade time).

Doctor itself mainly:

  • migrates config keys + normalizes schema (rewrites ~/.openclaw/openclaw.json)
  • migrates on-disk session storage to the per-agent layout (~/.openclaw/agents/<agentId>/...)
    Docs: https://docs.openclaw.ai/gateway/doctor

The “legacy Telegram stuff” prompt you saw

That was likely about resolving @username allowlist entries to numeric Telegram user IDs (openclaw doctor --fix), as mentioned in the Telegram docs: https://docs.openclaw.ai/channels/telegram

Quick check (this will explain the telegram:direct: split)

Open ~/.openclaw/openclaw.json and look for:

  • session.dmScope
  • commands.native / channels.telegram.commands.native
#

If you paste just those small snippets here, I can tell you exactly why you’re seeing both agent:main:main and agent:main:telegram:direct:... after the upgrade.

sand barn
# 
session.dmScope == "per-channel-peer"
commands.native == "auto"
channels.telegram.commands.native == undefined
wispy troutBOT
#

That explains it perfectly.

Why you now see multiple “main” sessions

With:

  • session.dmScope = "per-channel-peer"

OpenClaw intentionally stops collapsing all DMs into agent:main:main and instead creates a separate DM bucket per (channel, peer).

So your Telegram DM becomes:

  • agent:main:telegram:direct:<yourUserId>

while agent:main:main still exists as the agent’s canonical “main” bucket (used by some surfaces / local chat / other channels depending on routing).

Docs on dmScope + the exact key shapes: https://docs.openclaw.ai/concepts/session

#

What the telegram:slash: session is

Independently of dmScope, when commands.native = "auto" (and Telegram supports native commands), OpenClaw creates an isolated command session for native slash invocations:

  • agent:main:telegram:slash:<yourUserId>

This is documented here: https://docs.openclaw.ai/tools/slash-commands
(“Telegram: telegram:slash:<userId> … targets the chat session via CommandTargetSessionKey”)

Did doctor cause dmScope to change?

doctor’s job is migrations/repairs (config schema + state layout), not “session UX”. But during upgrades you can end up with dmScope being set (or newly respected) because:

  • your config previously didn’t have it (or had legacy shapes),
  • migrations normalized config into the new schema,
  • and the new default/recommended posture is DM isolation for safety.

Net: nothing is “wrong” here — it’s expected behavior given your config.

#

If you want the old single-session behavior back

Set:

  • session.dmScope: "main"

…and you’ll mostly go back to everything landing in agent:main:main (but be aware this is less safe if more than one person/account can DM the bot).

If this cleared it up, please mark the solution in the thread (right‑click the solution message → Apps → ✅ Mark Solution) so Answer Overflow indexes it.