Session 是 OpenClaw 中对话状态的核心载体。理解 Session 的隔离模式、生命周期和维护策略，对于多用户部署、多频道管理至关重要。
Session Key 映射规则
| 场景 | Session Key |
|---|---|
| DM（默认 main 模式） | agent:<agentId>:main |
| DM（per-channel-peer） | agent:<agentId>:<channel>:dm:<peerId> |
| 群组/频道 | agent:<agentId>:<channel>:group:<id> |
| Telegram 论坛主题 | agent:<agentId>:telegram:group:<id>:topic:<threadId> |
| Cron 任务 | cron:<jobId> |
| Webhook | hook:<uuid> |
DM 隔离模式（dmScope）
控制不同用户的私信如何分组到 Session：
| 模式 | 适用场景 | Session Key 格式 |
|---|---|---|
main（默认） | 单用户，所有 DM 共享上下文 | agent:<id>:main |
per-peer | 多用户，按发送者隔离 | agent:<id>:dm:<peerId> |
per-channel-peer | 多用户多频道，推荐 | agent:<id>:<channel>:dm:<peerId> |
per-account-channel-peer | 多账号多频道 | agent:<id>:<channel>:<accountId>:dm:<peerId> |
安全警告：多用户必须开启隔离
如果你的 Agent 可以接收多个用户的 DM，必须开启安全 DM 模式。
默认设置的安全问题：
- Alice 向 Agent 说了私密内容
- Bob 问「我们之前聊了什么？」
- 因为共享同一 Session，Agent 可能用 Alice 的上下文回答 Bob
修复方法：
json
{
"session": {
"dmScope": "per-channel-peer"
}
}需要开启的场景：
- 配对审批了多个用户
- DM 白名单有多个条目
- 设置了
dmPolicy: "open" - 多个手机号或账号可以发消息给 Agent
bash
# 验证 DM 安全配置
openclaw security audit跨频道身份关联（identityLinks）
同一个人在多个频道发消息时，合并为同一个 Session：
json
{
"session": {
"dmScope": "per-channel-peer",
"identityLinks": {
"alice": ["telegram:123456789", "discord:987654321012345678"],
"bob": ["whatsapp:+8613800138000", "slack:U1234567890"]
}
}
}Session 重置策略
每日重置（默认）
默认每天 凌晨 4 点（Gateway 所在机器时区） 重置：
json
{
"session": {
"reset": {
"mode": "daily",
"atHour": 4
}
}
}空闲重置
超过指定分钟无活动则重置：
json
{
"session": {
"reset": {
"mode": "idle",
"idleMinutes": 120
}
}
}按类型差异化重置
json
{
"session": {
"resetByType": {
"thread": { "mode": "daily", "atHour": 4 },
"direct": { "mode": "idle", "idleMinutes": 240 },
"group": { "mode": "idle", "idleMinutes": 120 }
}
}
}按频道差异化重置
json
{
"session": {
"resetByChannel": {
"discord": { "mode": "idle", "idleMinutes": 10080 }
}
}
}手动重置命令
在对话中发送：
/new— 开启新 Session，可附带消息或模型切换（/new claude-opus-4-6）/reset— 重置 Session/stop— 中止当前运行，清除排队的跟进消息，停止所有子 Agent
Session 维护（防止存储无限增长）
默认配置
| 参数 | 默认值 | 说明 |
|---|---|---|
mode | warn | 仅警告，不清理 |
pruneAfter | 30d | 超过 30 天的条目标记为过期 |
maxEntries | 500 | 最大保留条目数 |
rotateBytes | 10mb | sessions.json 超过此大小时轮转 |
生产环境推荐配置
json
{
"session": {
"maintenance": {
"mode": "enforce",
"pruneAfter": "45d",
"maxEntries": 800,
"rotateBytes": "20mb",
"resetArchiveRetention": "14d"
}
}
}大型部署（加硬盘上限）
json
{
"session": {
"maintenance": {
"mode": "enforce",
"pruneAfter": "14d",
"maxEntries": 2000,
"maxDiskBytes": "2gb",
"highWaterBytes": "1.6gb"
}
}
}手动触发维护
bash
# 预览（不执行）
openclaw sessions cleanup --dry-run
openclaw sessions cleanup --dry-run --json # JSON 格式详细输出
# 执行清理
openclaw sessions cleanup --enforce检查 Session 状态
bash
# 查看当前 Session 概览
openclaw status
# 列出所有 Session（JSON 格式）
openclaw sessions --json
# 仅显示最近活跃的 Session
openclaw sessions --active 60 # 60 分钟内活跃
# 在聊天中查看
/status # 查看上下文用量、思考/详细模式等
/context list # 查看系统提示和注入的工作区文件
/context detail # 查看最大的上下文贡献者发送策略（sendPolicy）
按 Session 类型屏蔽特定消息投递：
json
{
"session": {
"sendPolicy": {
"rules": [
{ "action": "deny", "match": { "channel": "discord", "chatType": "group" } },
{ "action": "deny", "match": { "keyPrefix": "cron:" } }
],
"default": "allow"
}
}
}运行时覆盖（仅限所有者）：
/send on
/send off
/send inherit
Session 存储位置
- Store 文件：
~/.openclaw/agents/<agentId>/sessions/sessions.json - 转录文件：
~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl
Gateway 是 Session 状态的唯一真相来源。远程模式下，Session 存储在远程 Gateway 主机上。
原文：Session Management - OpenClaw | 来源：OpenClaw 官方文档