# OpenClaw Session 与上下文机制分析

> 分析时间：2026-03-12
> 目标：理解 session/上下文机制，优化大模型服务商请求

---

## 一、核心概念区分

### 1.1 两个 ID

| 概念 | 作用 | 示例 |
|------|------|------|
| **Session Key** | 对话路由/隔离桶 | `agent:val:telegram:direct:8745444509` |
| **Session ID** | 具体 transcript 文件 | `79d11a95-d110-4593-bcb2-ea204c324059` |

- **Session Key** 决定"你在哪个对话中"
- **Session ID** 决定"这个对话的历史文件是哪个"

### 1.2 两个 Token 概念

| 概念 | 含义 | 来源 |
|------|------|------|
| **Context Window** | 模型上下文窗口上限 | 模型定义（kimi-k2.5: 262,144） |
| **maxTokens** | 单次生成回复上限 | 配置文件（当前: 32,768） |

---

## 二、上下文构成（Context = 发给模型的一切）

```
┌─────────────────────────────────────────────────────────┐
│                     Context Window                      │
│  ┌─────────────────────────────────────────────────┐   │
│  │  System Prompt (每次重建)                        │   │
│  │  ├── Tool list + descriptions                   │   │
│  │  ├── Skills list (元数据)                       │   │
│  │  ├── Runtime info (时间/主机/模型)              │   │
│  │  └── Project Context (注入的 workspace 文件)    │   │
│  └─────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────┐   │
│  │  Conversation History (JSONL transcript)        │   │
│  │  ├── User messages                              │   │
│  │  ├── Assistant messages                         │   │
│  │  ├── Tool calls + results                       │   │
│  │  ├── Compaction summaries                       │   │
│  │  └── Attachments (images/files)                 │   │
│  └─────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────┐   │
│  │  Tool Schemas (JSON)                            │   │
│  │  └── 每个工具的 JSON schema（不可见但计入）     │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
```

### 2.1 System Prompt 细分

| 组件 | 大小估算 | 说明 |
|------|----------|------|
| Tool list text | ~1,000 chars | 工具名称和简短描述 |
| Tool schemas (JSON) | ~32,000 chars | **最大开销之一** |
| Skills list | ~2,000 chars | 12 个技能元数据 |
| Project Context | 变化大 | 注入的 workspace 文件 |

### 2.2 Project Context 注入

默认注入的文件（如存在）：
- `AGENTS.md`
- `SOUL.md`
- `IDENTITY.md`
- `USER.md`
- `TOOLS.md`
- `HEARTBEAT.md`

**截断规则：**
- 单文件上限: `bootstrapMaxChars` (默认 20,000 chars)
- 总上限: `bootstrapTotalMaxChars` (默认 150,000 chars)

---

## 三、Session 生命周期

### 3.1 Session 重置触发

| 触发方式 | 说明 |
|----------|------|
| **Daily Reset** | 默认凌晨 4:00，新消息创建新 Session ID |
| **Idle Reset** | 空闲超过 `idleMinutes`，新消息创建新 Session ID |
| **手动 Reset** | `/new` 或 `/reset` 命令 |
| **Per-type override** | `resetByType` 可针对 direct/group/thread 不同策略 |

### 3.2 DM Scope（直聊隔离策略）

| 模式 | Session Key 格式 | 适用场景 |
|------|------------------|----------|
| `main` (默认) | `agent:<id>:main` | 单用户，跨设备连续性 |
| `per-peer` | `agent:<id>:dm:<peerId>` | 多用户隔离 |
| `per-channel-peer` | `agent:<id>:<channel>:dm:<peerId>` | 多用户推荐 |
| `per-account-channel-peer` | `agent:<id>:<channel>:<account>:dm:<peerId>` | 多账户推荐 |

---

## 四、上下文控制机制

### 4.1 Compaction（压缩）

**触发条件：**
```
contextTokens > contextWindow - reserveTokens
```

**工作方式：**
1. 将旧对话压缩成摘要 entry
2. 摘要持久化到 JSONL
3. 保留 `keepRecentTokens` 的最近消息

**配置示例：**
```json5
{
  compaction: {
    enabled: true,
    reserveTokens: 16384,    // 剩余多少 token 时触发
    keepRecentTokens: 20000, // 保留最近多少 token
  },
}
```

**Memory Flush：**
- 在 compaction 前，运行静默 turn 写入持久化记忆
- 防止 compaction 丢失关键上下文

### 4.2 Session Pruning（裁剪）

**工作方式：**
- 仅移除旧的 **toolResult**
- **不修改** JSONL transcript
- 仅影响当前请求的 in-memory context

**适用模型：** 主要是 Anthropic API（配合 prompt caching）

**配置示例：**
```json5
{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl",
        ttl: "5m",
        keepLastAssistants: 3,
      },
    },
  },
}
```

### 4.3 文件截断

**控制点：**
- `bootstrapMaxChars`: 单文件上限 (20,000)
- `bootstrapTotalMaxChars`: 总上限 (150,000)

---

## 五、当前配置分析

### 5.1 已知配置

| 配置项 | 当前值 | 说明 |
|--------|--------|------|
| 模型 | lkeap/kimi-k2.5 | |
| Context Window | 262,144 tokens | 模型上下文窗口 |
| maxTokens | 32,768 | 单次生成上限 |
| 当前已用 | ~16,648 tokens | session tokens |

### 5.2 潜在问题点

1. **Tool Schemas 开销大**
   - 浏览器工具 schema ~9,812 chars
   - exec 工具 schema ~6,240 chars
   - 所有工具 schema ~32,000 chars (~8,000 tokens)

2. **Project Context 可能膨胀**
   - 多个 workspace 文件注入
   - 单文件 20,000 chars 上限可能不够精确控制

3. **Compaction 配置未知**
   - reserveTokens 和 keepRecentTokens 需要检查

---

## 六、优化建议

### 6.1 减少每次请求的 Token

| 优化点 | 方法 | 预估节省 |
|--------|------|----------|
| **Tool Schemas** | 限制可用工具列表 | ~5,000-10,000 tokens |
| **Project Context** | 精简注入文件，或调低 `bootstrapMaxChars` | 变化大 |
| **Skills List** | 减少安装的技能数量 | ~500-1,000 tokens |

### 6.2 控制上下文增长

| 优化点 | 方法 |
|--------|------|
| **Session Pruning** | 启用 `contextPruning.mode: "cache-ttl"` |
| **Compaction 阈值** | 调低 `reserveTokens` 更早触发压缩 |
| **Idle Reset** | 设置合理的 `idleMinutes`，长空闲后重置 |

### 6.3 监控与调试

```bash
# 查看上下文详情
/context detail

# 查看会话状态
/status

# 手动压缩
/compact

# 查看所有 session
openclaw sessions --json
```

---

## 七、需要进一步检查的配置

```bash
# 查看完整配置
cat ~/.openclaw/openclaw.json | jq '.agents.defaults'

# 查看 compaction 配置
cat ~/.openclaw/openclaw.json | jq '.agents.defaults.compaction'

# 查看 session 配置
cat ~/.openclaw/openclaw.json | jq '.session'
```

---

## 八、服务商限制应对

如果服务商限制请求频率或 token 消耗：

1. **减少单次请求大小**
   - 精简工具列表
   - 控制注入文件大小
   - 启用 session pruning

2. **控制请求频率**
   - 合理设置 session reset 策略
   - 避免频繁 /new 或长时间会话

3. **监控用量**
   - 定期检查 `/status` 和 `/context detail`
   - 关注 token 使用趋势

---

*文档版本: v1.0*
*生成时间: 2026-03-12 09:00 GMT+8*