概念

Session 是 OpenClaw 的「記憶單位」— 儲存對話歷史、追蹤狀態。

有兩種 session 類型：

Main Session — 你和 agent 的主要對話（持續、有歷史）
Isolated Session — 獨立的一次性任務（無歷史、乾淨）

Session Key 結構

Main Session:
agent:my-assistant:main

Group Chat:
agent:my-assistant:telegram:group:-1001234567890

Cron Job:
cron:abc12345-1234-5678-9abc-def012345678

DM (per-channel-peer mode):
agent:my-assistant:whatsapp:dm:+886912345678

Main vs Isolated

特性	Main Session	Isolated Session
歷史	持續累積	每次都是空白
用途	日常對話	Cron jobs、子任務
Context	包含之前對話	只有當前任務
重置	`/new` 或 `/reset`	自動每次重置

核心代碼

1. Session Key 解析

// Session key 決定「這是誰的對話」
function deriveSessionKey(agentId, channel, from, config) {
  const dmScope = config.session.dmScope || 'main';
  
  switch (dmScope) {
    case 'main':
      // 所有 DM 共用一個 session（預設）
      return `agent:${agentId}:main`;
      
    case 'per-channel-peer':
      // 每個 channel + 用戶 獨立
      return `agent:${agentId}:${channel}:dm:${from}`;
      
    case 'per-peer':
      // 同一人跨 channel 共用
      return `agent:${agentId}:dm:${from}`;
  }
}

重要：

dmScope: 'main'（預設）= 所有 DM 共用歷史
多人使用時要改成 per-channel-peer，否則會洩漏對話

2. Session 生命週期

// Session 什麼時候重置？
const resetConfig = {
  mode: 'daily',
  atHour: 4,        // 每天凌晨 4 點
  idleMinutes: 120  // 或閒置 2 小時
};

function shouldReset(session, config) {
  const now = Date.now();
  const lastUpdate = session.updatedAt;
  
  // 每日重置
  if (config.mode === 'daily') {
    const resetTime = todayAt(config.atHour);
    if (lastUpdate < resetTime && now >= resetTime) {
      return true;
    }
  }
  
  // 閒置重置
  if (config.idleMinutes) {
    const idleMs = config.idleMinutes * 60 * 1000;
    if (now - lastUpdate > idleMs) {
      return true;
    }
  }
  
  return false;
}

3. Isolated Session（Cron 專用）

// Cron job 每次都是新的 session
async function runCronJob(job) {
  const sessionKey = `cron:${job.id}`;
  
  // 每次都產生新的 sessionId
  const sessionId = generateUUID();
  
  // 沒有歷史，prompt 是乾淨的
  const session = {
    key: sessionKey,
    id: sessionId,
    history: []  // 空的！
  };
  
  await runAgent(session, job.payload.message);
}

為什麼 isolated？

Cron 任務不需要「記得上次」
每次都從頭開始，避免 context 污染
也避免 context window 累積

安全警告：DM Scope

// ⚠️ 預設設定（不安全 for 多人使用）
{
  "session": {
    "dmScope": "main"  // 所有人共用同一個對話！
  }
}

// ✅ 安全設定（多人使用）
{
  "session": {
    "dmScope": "per-channel-peer"
  }
}

問題場景：

Alice 問 agent 私人問題
Bob 問 agent「我們剛才聊什麼？」
Agent 把 Alice 的內容告訴 Bob（因為共用 session）

💡 關鍵洞察

Session = 對話的邊界
- 同一個 session 內，agent 記得所有內容
- 不同 session，agent 不知道對方存在
Main Session 適合持續對話
- 你和 agent 的日常溝通
- 有上下文，可以說「之前那個」
Isolated Session 適合獨立任務
- Cron jobs、一次性查詢
- 不受其他對話影響
dmScope 是安全關鍵
- 多人使用必須設定 per-channel-peer
- 否則會有隱私洩漏風險

🔗 核心檔案

Session 儲存：~/.openclaw/agents/<agentId>/sessions/sessions.json
對話歷史：~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
文檔：/opt/homebrew/lib/node_modules/openclaw/docs/concepts/session.md

明天： Tool 系統（exec, browser, message 等）

Day 3: Session 機制（isolated vs main）