技术研究 | 2026年6月

摘要

本文深入剖析OpenClaw AI网关的会话处理机制，涵盖会话生命周期管理、上下文压缩（Compaction）、模型故障切换（Fallback）、会话命令体系（/new与/reset）以及卡死恢复策略。通过分析源码文档与运行时行为，揭示了会话系统的设计哲学：在异步事件循环之上构建可靠的状态管理，平衡上下文窗口限制与长会话连续性，并通过多层容错机制应对模型提供商的不确定性。

一、会话生命周期

OpenClaw的会话系统围绕Session ID进行状态管理。每个会话从创建到销毁经历完整的生命周期，由Gateway统一调度。理解会话的生命周期是理解整个处理机制的基石。

1.1 会话的创建与路由

当用户发送第一条消息时，Gateway根据消息来源（渠道、用户ID、群组ID）解析或创建对应的会话。会话的路由策略由config中的session.dmScope控制：

per-peer模式（默认）：每个对话参与者拥有独立的会话，适用于私聊场景。同一个用户在Telegram、Discord、微信等不同渠道的会话互不干扰。

main模式：所有私聊消息路由到同一个Agent主会话，适用于需要保持单一上下文的场景。在此模式下，/new命令会退化为/reset行为，因为不能创建额外的主会话。

per-channel-peer和per-account-channel-peer模式：为群聊场景提供更精细的路由粒度，每个频道内的每个用户都有独立会话。

1.2 会话存储结构

每个会话对应两个关键文件：

文件	路径格式	说明
会话记录	<session-id>.jsonl	JSONL格式，只增不减，记录所有消息、工具调用、压缩事件
轨迹记录	<session-id>.trajectory.jsonl	更详细的工具执行轨迹，独立存储以避免主文件膨胀
会话索引	sessions.json	Session Key到Session ID的映射索引
索引锁	<session-id>.jsonl.lock	并发写入的锁文件

JSONL（JSON Lines）格式是OpenClaw会话存储的核心设计。每条记录单独一行JSON对象，支持追加写入而不需要解析整个文件。这种设计确保了高并发场景下的写入性能和可靠性。会话记录包含以下类型的条目：

条目类型	说明
session	会话元信息（创建时间、Agent ID等）
message/user	用户消息
message/assistant	助手回复
message/toolResult	工具调用结果
compaction	上下文压缩记录（含摘要）
model_change	模型切换记录
thinking_level_change	思维链级别变更记录

值得注意的是，compaction条目并非删除旧记录，而是在文件中追加一条包含摘要的JSON行。磁盘文件只增不减，仅保留所有历史信息。

1.3 会话绑定与会话键

在WebChat等渠道中，Session Key的格式通常为agent:main:dashboard:<uuid>。Gateway通过sessions.json将Channel消息的标识符映射到具体的Session ID。这种间接映射允许在同一会话上支持多个渠道入口，同时保持底层状态的一致性。

二、上下文压缩（Compaction）

Compaction是OpenClaw处理长会话的核心机制。大语言模型的上下文窗口有限（通常4K-200K token），如果会话持续累积而不压缩，迟早会超出限制。Compaction在不丢失关键信息的前提下，将历史对话压缩成摘要。

2.1 压缩触发时机

压缩并非手动执行的操作，而是由系统自动触发。触发条件包括：

上下文窗口接近上限：当累积的token数量接近模型上下文窗口时，系统自动发起压缩。/compact命令也提供手动触发的入口，可附带压缩指令调整摘要生成策略。

会话切换/重置：配置了session-memory hook的情况下，/new或/reset命令触发时，系统会自动将当前会话记忆保存到日常笔记文件中（memory/YYYY-MM-DD-HHMM.md）。

2.2 压缩的机制与效果

Compaction的工作原理可以概括为只读不删。在内存中，旧对话被压缩成一段摘要文本，释放token空间给新对话。但在磁盘上的.jsonl文件中，所有原始消息仍然完整保留。压缩记录本身也只是一条附加的JSON行，包含：

字段	说明
summary	摘要文本，包含决策、待办、约束等结构化信息
tokensBefore	压缩前的token数量
firstKeptEntryId	压缩后保留的第一条条目ID
fromHook	是否由hook触发
readFiles	压缩时读取的文件列表
modifiedFiles	压缩时修改的文件列表

这种机制带来的关键特性是：历史记录可追溯。即使经过多次压缩，原始对话仍然存储在磁盘上，可以通过会话历史工具回溯。这也意味着会话文件随着时间的推移会持续增长，需要配合会话维护策略（session.maintenance）进行定期清理。

2.3 压缩事件的Hook支持

OpenClaw提供了before_compaction和after_compaction两类Hook，允许插件在压缩前后执行自定义逻辑。例如，可以在压缩前将关键信息持久化到外部存储，或在压缩后更新索引。Hook可以访问压缩事件的上下文信息，包括会话ID、Token数量、待办事项等。

三、模型故障切换（Fallback）

在大模型应用中，模型提供商的服务不可用是常见故障场景。OpenClaw设计了多层故障切换机制，确保在模型调用失败时自动降级到备用模型。

3.1 Fallback配置模型

Fallback链通过config中的model配置对象的对象形式启用：

静态配置：在agents.defaults.model或agents.list[].model中配置为对象形式，包含primary主模型和fallbacks备用模型数组。支持无限层级嵌套（fallback可以有自己的fallbacks）。

字符串配置：model配置为字符串值时，系统进入严格模式——不使用任何备选方案。这是早期版本的配置方式，在新版本中推荐使用对象形式。

3.2 Fallback触发条件

Fallback并非对所有错误都触发。系统对以下错误触发降级：

网络错误：连接超时、DNS解析失败、TLS握手失败等网络层面的故障。

HTTP错误：服务端返回5xx状态码（服务不可用、网关超时等），不触发4xx客户端错误（如认证失败、请求格式错误）。

超时错误：模型调用超过配置的超时时间未返回。

格式错误（incomplete_result）：模型返回了不完整的响应，例如因达到输出长度限制（max_tokens）被截断，未生成完整的结束标记。系统检测到回复不完整后判定为格式错误，触发fallback。

模型不存在的错误：指定的模型ID在当前提供商中不可用。

3.3 Fallback不会触发的场景

以下场景fallback不会自动激活：

配额/速率限制：配额超额（如5小时速率限制、按量计费用完等）通常返回429状态码，系统会等待而不是切换模型。这类限制是临时性的，等待后会自动恢复。

流式响应卡死：模型已经开始流式返回（SSE），但中途停止发送数据。此时Gateway已在接收流数据，session处于活动状态，fallback不会触发中断。

会话级别的模型锁定：当前会话通过聊天中切换模型或参数命令锁定了特定模型，此时session-level的pin会阻止fallback生效——因为这是用户的显式选择。

3.4 Fallback实例分析

以下是一个来自生产环境的真实Fallback案例，展示了完整的故障切换链路。

时间：2026年6月24日 11:58-12:01

会话ID：bc3afb45-8a34-453a-b731-4e78c79546eb

触发原因：模型因达到输出长度限制（max_tokens）被截断，返回不完整的响应。

Fallback链配置：primary为handai/deepseek-v4-flash，fallbacks为[deepseek/deepseek-v4-flash, alibaba/deepseek-v4-flash]。

3.4.1 Fallback执行过程

步骤	时间	Provider	模型	结果	原因
1	11:58:23	handai	deepseek-v4-flash	失败	stopReason=length，输出被截断，incomplete_result
2	11:59:26	deepseek	deepseek-v4-flash	失败	同上（同一模型，不同API入口，同样限制）
3	12:01:01	alibaba	deepseek-v4-flash	成功	阿里云入口配置了更高的输出长度限制

关键日志片段：

incomplete turn detected: provider=handai/deepseek-v4-flash stopReason=length hasLastAssistant=yes hasCurrentAttemptAssistant=yes payloads=1 tools=0 replaySafe=yes compactions=0 reasoningRetries=0/2 emptyRetries=0/1 missingAssistantRetries=0/1 – surfacing error to user

该日志揭示了系统的内部处理逻辑：

stopReason=length：模型因达到输出长度限制被强制截断，这是incomplete_result的根本原因。

hasLastAssistant=yes / hasCurrentAttemptAssistant=yes：模型确实生成了部分回复内容，但内容不完整。

reasoningRetries=0/2 / emptyRetries=0/1 / missingAssistantRetries=0/1：系统内置的重试机制（思维链重试、空响应重试、缺失助手回复重试）均未触发，因为模型确实返回了内容，只是不完整。

3.4.2 技术分析

handai/deepseek-v4-flash和deepseek/deepseek-v4-flash两个入口指向同一模型，但API网关的max_tokens默认值配置不同。handai和deepseek入口的默认输出长度限制较低，导致模型在生成较长回复时被截断。而alibaba入口的max_tokens默认值更高，允许模型完整输出。

这个案例说明：同一模型通过不同Provider入口调用时，行为可能存在差异。Fallback链中配置多个Provider入口，不仅能应对服务不可用，还能规避单一入口的配置限制。

3.5 Fallback与Session状态的关系

Fallback的执行流程涉及会话状态的重新绑定：当fallback切换模型时，Gateway会更新当前会话的模型绑定。如果fallback链中的所有模型都不可用，会话会进入错误状态，需要手动干预。

对于定时任务（cron），如果发生LiveSessionModelSwitchError，系统会持久化切换后的provider、model和auth profile，并在重试时使用新配置。重试上限为两次，超过后放弃执行。

四、会话命令体系

OpenClaw提供了丰富的会话命令体系，用于管理会话生命周期和状态。每个命令在不同的运行模式下有不同的行为。

4.1 /new：创建新会话

/new命令将当前会话归档并创建全新的会话。归档后的会话仍然保留在sessions.json中，可以通过会话列表查询。命令的详细行为：

新会话ID生成：Gateway生成新的UUID作为会话ID，旧的会话ID被归档。归档后的会话不再接收新消息。

模型指定：/new <模型名>支持指定模型，如/new deepseek/deepseek-v4-flash。支持provider/model格式或单纯provider名称（模糊匹配）。

Control UI中的特殊行为：在WebChat/Control UI中，/new会在当前dashboard中创建并切换到新会话。但当session.dmScope为main模式时，/new退化为/reset行为。

Hook触发：如果启用了session-memory hook，/new触发时会自动保存当前会话的上下文摘要到记忆文件。

4.2 /reset：原地重置

/reset命令在当前的会话ID上清空上下文，但不改变会话绑定。这意味着群聊、线程等场景下的消息路由不会中断。关键特性：

原地重置：会话ID不变，用户无需重新建立会话绑定。群聊中的其他参与者不受影响。

Soft模式：/reset soft [message]支持保留会话记录，只重置运行状态。适用于需要保留调试信息但清除错误状态的场景。

合适的使用场景：模型上下文污染、会话陷入异常状态、需要快速恢复而不中断路由。不合适用于模型卡死——此时模型调用本身没有返回，/reset只是清空上下文，下次调用仍然会卡住。

4.3 /stop：终止当前运行

/stop是处理模型调用卡死的正确工具。它会向Gateway发送chat.abort信号，终止当前正在进行的模型调用。适用于以下场景：

模型响应时间过长，不想继续等待。

模型陷入工具调用循环，持续输出工具调用而不返回最终结果。

误触发了需要长时间处理的操作。

4.4 /model：切换当前会话模型

/model命令在当前会话中切换模型，不创建新会话也不清空上下文。与/new的区别在于：/new是创建新会话并归档旧会话，而/model只是修改当前会话的模型绑定。

/model default用于清除会话级别的模型覆盖，恢复到Agent默认配置。这在手动切到故障模型后需要恢复时特别有用。

五、会话卡死与恢复策略

会话卡死是实际运维中最常见的问题之一。理解卡死的根因和对应的恢复策略，是稳定运行OpenClaw的关键。

5.1 事件循环健康监控

OpenClaw Gateway基于Node.js异步事件循环运行。系统内置了完善的健康监控机制：

监控指标	配置项	说明
事件循环延迟	diagnostics.flags	记录event-loop delay、event-loop utilization、CPU core ratio
会话卡死警告	stuckSessionWarnMs	默认30s，无进展会话标记为long_running/stalled/stuck
会话卡死中止	stuckSessionAbortMs	默认5min（或3x warn），可中止的卡死会话会被drain恢复
内存压力快照	memoryPressureSnapshot	OOM前抓取V8堆、cgroup、活跃资源等诊断数据

5.2 卡死根因分析

模型调用卡死Gateway进程的原因可以归纳为以下几类：

5.2.1 事件循环饥饿

模型调用本身的HTTP请求是异步非阻塞的，不会阻塞事件循环。但模型返回后的流式响应（SSE）解析——特别是大量token涌入时——可能长时间占用事件循环。其他会话的消息排不上队，/stop命令发不出去，看起来就像Gateway卡死了。

5.2.2 工具调用死循环

模型返回工具调用runLoop是会话处理器的核心逻辑之一。如果模型陷入无限工具调用循环——不断输出工具调用而不输出最终回复——这个turn永远不会结束，会话一直被占用。

5.2.3 V8内存压力与GC停顿

大上下文模型返回极长响应时，V8堆内存飙升触发垃圾回收（GC）。GC期间事件循环暂停，所有会话都受影响。配置memoryPressureSnapshot可以在OOM前保留诊断数据。

5.2.4 HTTP连接池耗尽

大量会话同时调用同一个提供商时，HTTP连接池被占满，后续请求排队等待。如果部分慢响应长时间占用连接，新请求进不去，表现为全面卡死。

5.3 恢复策略对照表

症状	推荐操作	原理
模型转圈无响应	/stop	发送chat.abort终止当前run
模型超额/不可用	/model <其他模型>	切换会话模型，不影响会话绑定
上下文脏了	/reset	原地清空上下文，保持路由
需要彻底换会话	/new <其他模型>	归档旧会话，创建新会话
Gateway进程完全卡死	重启Gateway	清除所有进行中连接和内存状态
配置/模型变更不生效	/new 或 /reset	触发Gateway重新加载当前配置

5.4 为什么有时必须重启Gateway

重启Gateway是最后一个手段，但有时确实是唯一解。原因如下：

进行中的HTTP请求不响应中断：当模型调用挂起在HTTP协议层面（如TCP连接未收到任何响应），Node.js的异步模型无法通过chat.abort切断底层连接。

事件循环被GC或CPU密集任务阻塞：如果大量工具调用或数据解析占用了事件循环，/stop命令本身也无法被处理——因为它也需要通过事件循环传递。

连接池状态异常：HTTP连接池中的连接可能进入CLOSE_WAIT状态，新请求无法创建新连接，所有会话都不可用。

重启后：所有进行中的HTTP连接被断开，事件循环重置，V8堆清空，连接池重建，会话状态从磁盘重新加载。这是最彻底的恢复方式，适用于异常状况。

六、会话维护与清理

随着会话的持续运行，磁盘上的会话文件会不断增长。OpenClaw提供了自动化的会话维护机制。

6.1 自动维护策略

配置项session.maintenance支持以下清理策略：

模式	行为
warn（默认）	仅警告，不自动清理，适合确认安全后再清理
auto	自动清理过期会话
off	关闭自动维护

维护操作包括：按年龄清理（pruneAfter）超出保留期限的会话记录；按数量限制（maxSessions）保留最近N个会话，超出部分清理；磁盘预算（diskBudgetBytes）限制会话文件总大小；清理时同时清除主会话文件、compaction checkpoint文件和trajectory sidecar文件。

6.2 手动维护

通过openclaw sessions cleanup命令提供了精细的手动控制：

dry-run模式：预览会被清理的会话而不执行实际操作。以表格形式展示每会话的操作类型、年龄、模型等。

enforce参数：在warn模式下强制执行清理。

fix-missing参数：清理会话文件已丢失或为空的条目。fix-dm-scope参数：清理最新的路由策略变更后遗留的旧格式会话行。active-key保护：通过–active-key指定关键会话不被清理。

七、总结与最佳实践

OpenClaw的会话处理机制体现了几个核心设计理念：

异步非阻塞架构：基于Node.js事件循环，模型调用通过异步HTTP请求实现，避免阻塞主线程。这是系统高性能的基础，但也带来了事件循环饥饿的风险。

只增不删的持久化：JSONL文件的追加写入设计确保了数据安全和历史可追溯性，但也要求配合定期维护策略管理磁盘空间。Compaction通过摘要压缩减少内存占用，但磁盘文件完整保留。

多层容错：从HTTP层面的超时重试，到Fallback链的模型级故障切换，再到stuckSessionAbort的自动恢复机制，每一层覆盖不同的故障场景。

清晰的命令分层：/stop（终止）、/model（切换模型）、/reset（原地重置）、/new（新建会话）覆盖了从轻微到彻底的恢复需求，用户应根据具体症状选择正确的工具。

在实际运维中，建议遵循以下最佳实践：

1. 遇到模型卡死，先用/stop尝试终止，不成功再考虑后续操作。

2. 模型超额或不可用时，用/model或/new切换到备用模型，避免等待或重复尝试。

3. 配置合理的diagnostics.stuckSessionWarnMs和stuckSessionAbortMs，让系统自动识别和恢复卡死会话。

4. 定期执行openclaw sessions cleanup维护，配合dry-run预览确认清理范围。

5. 为fallbacks数组配置多个不同Provider入口的备用模型，避免单一入口的配置限制成为单点故障。

6. 当会话卡死严重影响使用时，重启Gateway是最彻底的解决方案，不应视作最后的无奈选择，而是体系化的恢复手段之一。

本文基于OpenClaw官方文档和运行时行为分析编写。文中提及的配置项和命令行为以对应版本的官方文档为准。