Unified Session — One Agent, All Devices, Zero Context Loss
v1.3.0Unify all chat channels into one shared AI session for seamless cross-device continuity. Start a conversation on your laptop, continue from your phone — same...
Like a lobster shell, security has layers — review code before you run it.
License
SKILL.md
Unified Session
One agent. All your devices. Zero context loss.
Before After
┌──────────┐ ┌──────────┐ ┌──────────────────────┐
│ Telegram │ │ Webchat │ │ agent:main:main │
│ Session A│ │ Session B│ │ │
│ "Buy milk│ │ "What was│ │ Telegram ──┐ │
│ tomorrow│ │ I doing?│ │ Webchat ───┤ shared │
│ ..." │ │ 🤷" │ │ DingTalk ──┤ context │
└──────────┘ └──────────┘ │ Feishu ────┘ │
❌ Context lost │ │
└──────────────────────┘
✅ Full continuity
The Problem
You connected multiple channels to OpenClaw. Each one starts a separate conversation. You research something on your laptop via webchat, grab your phone, message from Telegram — and the agent has no idea what you were talking about.
This is the #1 pain point for single-user OpenClaw setups. The default config isolates channels for multi-user safety, but most people just want one personal AI that works everywhere.
The Fix
One config value: dmScope: "main". That's it.
┌─────────────────────────────────────────────────┐
│ session.dmScope: "main" │
│ │
│ All DMs from all channels → one session │
│ Replies auto-route back to source channel │
│ No manual switching. No context loss. │
└─────────────────────────────────────────────────┘
Quick Reference
| Setting | Value | Effect |
|---|---|---|
session.dmScope | "main" | All DMs → one shared session ✅ |
session.dmScope | "per-channel-peer" | Each channel isolated ❌ (default) |
Who Should Use This
✅ You're the only person talking to your agent ✅ You use 2+ channels (webchat + phone app) ✅ You want one continuous conversation across devices
⚠️ Do NOT use if multiple people DM your bot — context would leak between users
Setup
Step 1: Diagnose
cat ~/.openclaw/openclaw.json | python3 -c "
import json, sys
cfg = json.load(sys.stdin)
session = cfg.get('session', {})
dm_scope = session.get('dmScope', 'NOT SET')
print(f'Global dmScope: {dm_scope}')
channels = cfg.get('channels', {})
for name, ch in channels.items():
if not ch.get('enabled', True): continue
ch_dm = ch.get('dmScope', 'inherits global')
ok = '✅' if (dm_scope == 'main' and ch_dm in ('main', 'inherits global')) else '❌'
print(f' {ok} {name}: dmScope={ch_dm}')
if dm_scope == 'main':
bad = [n for n,c in channels.items() if c.get('enabled',True) and c.get('dmScope') not in (None,'main')]
if not bad: print('\\n✅ Unified session is already working!')
else: print(f'\\n❌ Fix these channels: {bad}')
else:
print(f'\\n❌ Set session.dmScope to \"main\"')
"
openclaw sessions # should show 1 session per agent
If the diagnosis says ✅, skip to Step 4 (Verify). Otherwise continue.
Step 2: Configure
Edit ~/.openclaw/openclaw.json:
{
// Add or update this:
"session": {
"dmScope": "main",
"mainKey": "main"
}
}
For each enabled channel, add "dmScope": "main":
// Only touch channels that exist in YOUR config
"channels": {
"telegram": { "dmScope": "main" },
"discord": { "dmScope": "main" },
"dingtalk-connector": { "dmScope": "main", "routing": [{"agent": "main"}] },
"feishu": { "dmScope": "main", "routing": [{"agent": "main"}] },
"whatsapp": { "dmScope": "main" },
"signal": { "dmScope": "main" },
"slack": { "dmScope": "main" }
}
Step 3: Restart
openclaw gateway restart
Step 4: Verify
Send a test message from each channel. After each one:
openclaw sessions # still 1 session? token count growing? ✅
The real test: tell the agent something from Channel A, then ask about it from Channel B. If it remembers — you're done.
Reply Routing
Replies go back to wherever the message came from. Automatic.
You message from Telegram → reply goes to Telegram
You message from webchat → reply goes to webchat
You message from DingTalk → reply goes to DingTalk
For cron/announce: output goes to the channel you last messaged from (lastRoute).
Troubleshooting
| Problem | Fix |
|---|---|
| Bot forgets when switching channels | Run diagnostic in Step 1. Likely dmScope not set to "main" |
| Messages from a channel don't arrive | openclaw gateway restart — connections silently drop |
| Multiple sessions still showing | Old sessions expire naturally. New messages use unified session |
| Cron output goes to wrong channel | Set delivery.channel explicitly in cron config |
Channel-Specific Notes
- DingTalk: Stream SDK connects to dynamic endpoints. Network changes (VPN, Wi-Fi) can break it silently. Gateway restart fixes it.
- Feishu: Ensure app is published and event subscription includes
im.message.receive_v1. - Telegram/Discord/WhatsApp: Generally stable. If messages stop, restart gateway.
Reverting
Want isolated sessions back? One change:
{ "session": { "dmScope": "per-channel-peer" } }
Then openclaw gateway restart.
Security
- This skill does NOT send data anywhere
- This skill does NOT modify system files outside OpenClaw config
- This skill does NOT require API keys or credentials
- All changes are to
~/.openclaw/openclaw.jsononly - Fully reversible
The only security consideration: with dmScope: "main", anyone who can DM your bot shares the same session. Fine for single-user. Switch to per-channel-peer if you add users.
Run openclaw security audit after setup to verify.
Feedback
- If useful:
clawhub star unified-session - Stay updated:
clawhub update unified-session
🇨🇳 中文说明
统一会话 — 一个 Agent，所有设备，上下文零丢失
在电脑上开始对话，拿起手机继续聊——同一个上下文，同一份记忆，无缝切换。
痛点
你给 OpenClaw 接了钉钉、飞书、Telegram、Discord、网页版……但每个渠道都是独立的对话。你在电脑上让 Agent 查个东西，出门掏出手机用钉钉问进度——它完全不记得你说过什么。
这是单用户 OpenClaw 部署的头号痛点。默认配置为了多用户安全做了渠道隔离，但大多数人只是想要一个随时随地都能用的私人 AI 助手。
解决方案
clawhub install unified-session
然后对你的 Agent 说：
"帮我设置统一会话，让所有渠道共享同一个对话"
一个配置项 dmScope: "main"，重启一次 Gateway，搞定。
你会得到
- ✅ 多端无缝衔接 — 电脑 ↔ 手机 ↔ 平板，任意 App
- ✅ 共享记忆 — 不管从哪个 App 发消息，Agent 都记得所有上下文
- ✅ 自动回复路由 — 从钉钉发消息 → 回复自动回钉钉；从飞书发 → 回飞书
- ✅ 全渠道支持 — 钉钉、飞书、Telegram、Discord、WhatsApp、Signal、Slack、网页版
- ✅ 一次配置，永久生效
- ✅ 完全可逆 — 随时切回独立会话
- ✅ 零外部依赖 — 不需要 API Key，不需要额外服务，不发送网络请求
适用场景
✅ 你是 Agent 的唯一用户（个人部署） ✅ 你用了 2 个以上渠道（网页版 + 手机 App） ✅ 你想要一个连续的对话跨所有设备
⚠️ 多人使用的机器人不适用 — 如果多人给你的 Agent 发私信，请保持渠道隔离（per-channel-peer），防止上下文泄露。
安全性
- 不连接外部服务，不需要 API Key，不发送网络请求
- 只修改
~/.openclaw/openclaw.json - 一个配置项即可完全回退
- 设置完成后建议运行
openclaw security audit检查
安装
clawhub install unified-session
详细步骤见上方英文部分的 Setup 章节，Agent 会自动引导你完成全部流程。
Files
2 totalComments
Loading comments…