会话管理

会话（Session）是 OpenClaw 中消息上下文的基本单元。每个对话都发生在一个会话中，会话决定了 AI 的记忆范围、工具权限和行为配置。

会话模型

会话类型

类型	说明	工具权限
main	1:1 私聊会话	在宿主机上直接执行工具
group	群组/频道会话	可选 Docker 沙箱隔离
channel	按通道隔离	继承通道配置

会话 Key

Source: src/gateway/session-utils.ts

会话通过 sessionKey 唯一标识，key 由通道类型和账户 ID 派生：

// src/config/sessions.ts (simplified)
function deriveSessionKey(channel: string, accountId: string): string {
  return `${channel}:${normalizeAccountId(accountId)}`;
}

function normalizeAccountId(accountId: string): string {
  // Normalize E164 phone numbers, WhatsApp JIDs, etc.
}

会话存储

Source: src/config/sessions.ts

会话状态持久化到文件系统：

// src/config/sessions.ts (simplified)
function resolveStorePath(sessionKey: string): string {
  // ~/.openclaw/sessions/{sessionKey}/
}

function loadSessionStore(sessionKey: string): SessionStore {
  // Load from file system
}

function saveSessionStore(sessionKey: string, store: SessionStore): void {
  // Persist to file system
}

存储位置：~/.openclaw/sessions/{sessionKey}/

会话补丁

Source: src/gateway/sessions-patch.ts

通过 sessions.patch 方法可以动态修改会话配置：

可补丁的属性包括：

属性	类型	说明
model	string	AI 模型选择
thinkingLevel	string	思考级别（on/off/stream）
sandboxMode	boolean	沙箱模式
queueMode	string	消息队列模式
activationMode	string	激活方式（mention/always）

会话解析

Source: src/gateway/sessions-resolve.ts

当消息到达时，Gateway 需要解析出目标会话：

// src/gateway/sessions-resolve.ts (simplified)
function resolveSession(
  channel: string,
  chatType: "direct" | "group" | "channel",
  accountId: string
): ResolvedSession {
  // 1. Derive session key
  const sessionKey = deriveSessionKey(channel, accountId);

  // 2. Check if session exists
  // 3. Apply channel defaults
  // 4. Merge per-session overrides

  return { sessionKey, config };
}

激活模式

不同场景下 AI 是否响应消息由激活模式控制：

模式	说明	典型场景
always	响应所有消息	1:1 私聊
mention	仅在被 @ 时响应	群组聊天
command	仅响应命令	频道

文件系统会话工具

Source: src/gateway/session-utils.fs.ts

会话文件系统操作包括转录（transcript）管理和镜像持久化：

// src/gateway/session-utils.fs.ts (simplified)
// Session transcript persistence
// Mirrored transcript management
// Session cleanup and maintenance

会话类型定义

Source: src/gateway/session-utils.types.ts

// src/gateway/session-utils.types.ts (simplified)
interface SessionConfig {
  model?: string;
  thinkingLevel?: "on" | "off" | "stream";
  sandboxMode?: boolean;
  queueMode?: "fifo" | "fanout";
  activationMode?: "always" | "mention" | "command";
  // ...
}

小结

• 会话通过 sessionKey 唯一标识，key 由通道 + 账户 ID 派生
• 三种会话类型：main（1:1）、group（群组）、channel（通道级）
• 会话状态持久化到 ~/.openclaw/sessions/ 目录
• 支持通过 sessions.patch 动态修改配置（模型、思考级别、沙箱等）
• 激活模式控制 AI 是否响应：always / mention / command

下一章：配置系统