Managing Agent Sessions and Secure DMs

I’ve noticed a common issue when setting up agents: conversation bleed. It happens when your agent treats every incoming message as part of one giant chat, accidentally sharing private details with the wrong person. If you are building a multi-user bot, keeping those conversations separate is the first thing you should handle.

OpenClaw handles this through session management. By default, it uses one primary session per agent for direct chats, but you can change this behavior to ensure privacy and continuity.

What You’ll Need

• An active OpenClaw gateway setup.
• An agent ID already configured.
• Access to your ~/.openclaw/openclaw.json configuration file.

Quick Start: Enable Secure DM Mode

If your agent receives DMs from multiple people, you should enable secure DM mode. This prevents the model from using Alice’s context when answering Bob.

1. Open your ~/.openclaw/openclaw.json file.
2. Set the dmScope to per-channel-peer. This isolates sessions by both the channel and the sender.
3. Save the file.

~/.openclaw/openclaw.json

{
  session: {
    // Secure DM mode: isolate DM context per channel + sender.
    dmScope: "per-channel-peer",
  },
}

This setup ensures that even if two people message the same agent, they each get a fresh, private context.

How Sessions Work

The gateway is the source of truth for all session state. Whether you use the macOS app or WebChat, the client queries the gateway for session lists and token counts.

Session Mapping

OpenClaw maps different transports to specific session keys:

• Direct Chats: Controlled by dmScope. You can use main for continuity across all devices, or per-peer and per-channel-peer for isolation.
• Group Chats: These automatically isolate state using keys like agent:<agentId>:<channel>:group:<id>.
• Identity Links: If the same person contacts you from different platforms (like Telegram and Discord), use identityLinks to collapse those into one session.

{
  session: {
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
  }
}

Reset Policies

Sessions don’t last forever. By default, they reset at 4:00 AM local time on the gateway host. You can also configure an idle reset:

• Daily: Resets at a specific hour.
• Idle: Resets after a period of inactivity (e.g., idleMinutes: 120).
• Manual: Send /new or /reset in the chat to start a fresh session immediately.

Inspecting Sessions

I find it helpful to check the status of a session directly from the chat or the CLI.

• From Chat: Send /status to see context usage or /context list to see what is currently in the system prompt.
• From CLI: Use openclaw status to see the store path or openclaw sessions --json to dump all session entries.
• Aborting: If a model is stuck or looping, send /stop as a standalone message to kill the current run and clear the queue.

Troubleshooting

Problem: Context Leakage Alice messages the agent about a private medical appointment. Bob messages the agent asking “What were we talking about?” and the agent answers with Alice’s info.

• Solution: Your dmScope is likely set to main. Change it to per-channel-peer or per-peer in your config to isolate users.

Problem: Sessions not resetting when expected You set idleMinutes but the session is still active.

• Solution: OpenClaw evaluates expiry on the next inbound message. If you have both daily and idle resets configured, whichever one expires first will force the reset.

Problem: Remote UI shows wrong token counts The UI on your Mac doesn’t match the actual usage.

• Solution: In remote mode, the session store lives on the gateway host, not your local machine. Check the store file at ~/.openclaw/agents/<agentId>/sessions/sessions.json on the gateway.

If you have specific questions about your configuration, ask the AI Setup Assistant.

What’s Next

• Session Pruning
• Context Compaction
• Memory Management
• CLI Security Audit