恢复非活跃会话

通过应用、Web UI 或 CLI 恢复非活跃 Kaiwu 会话，无需重新开始。

会话恢复允许你继续运行处于非活跃状态的 Kaiwu 会话。其工作方式是：请求提供商后端重新打开同一个提供商会话，随后将该提供商会话重新连接到同一个 Kaiwu 会话。

当设备离线时向可恢复的非活跃会话发送消息，该功能目前仅在开发构建版本中提供，尚不是已正式发布的约定规范。

这不同于以下操作：

附加（Attach）：通过活跃终端或提供商主机，重新连接到仍在本地运行的会话
浏览直连会话：打开 Kaiwu 尚未接管的提供商原生会话
恢复会话：通过恢复智能体已有的会话来启动新的 Kaiwu 会话（参见继续会话）
启动新会话：创建全新的提供商会话，不使用厂商恢复功能

Kaiwu 中“恢复”的含义

在 Kaiwu 中，恢复是一个严格的工作流：

Kaiwu 找到现有的 Kaiwu 会话
Kaiwu 检查该会话是否真正支持厂商恢复
Kaiwu 请求后端/提供商恢复同一个厂商会话
若厂商恢复失败，Kaiwu 会显示错误，而不会静默启动新会话

这种严谨的处理方式至关重要，因为它能确保会话身份唯一，并保持会话记录来源的单一真实性。

当一个已同步的 Kaiwu 会话恢复时，Kaiwu 会继续现有的会话，而不会仅仅因为你恢复了它就再次导入一遍历史记录。

会话何时可恢复

会话仅在同时满足以下所有条件时才可恢复：

该会话是由 Kaiwu 管理的普通会话
当前处于非活跃状态
未归档
Kaiwu 的会话元数据中存有有效的提供商恢复 ID
所选后端/提供商支持该会话的恢复
当前设置未停用该后端

若上述任一检查未通过，Kaiwu 都会将该会话视为不可恢复，并在界面或 CLI 中明确提示。

客户端与 Web 端行为

在客户端或 Web 界面中，非活跃会话仅在可恢复时才允许输入内容。

常见行为表现：

非活跃 + 可恢复 + 设备可达：你可以发送消息；Kaiwu 会尝试恢复会话，或根据你的自动恢复策略将其置于队列中
非活跃 + 可恢复 + 设备离线：你仍可发送消息；Kaiwu 会将消息保留在“待处理”队列中，仅在该发送操作已被授权在设备可用时处理的前提下，才会在重新连接后启动会话
非活跃 + 不可恢复：禁用输入

当设备不可用时，会话会持续显示为离线。输入框上方的横幅会明确说明：排队的消息是在等待自动恢复、依偏好设置保持排队状态，还是在启动失败后需要手动重试。

在设置 → 会话 → 消息发送中，发送后自动恢复用于控制后续向非活跃会话发送消息的行为。默认选项仅在设备在线时会在设备可达时立即尝试一次，但绝不会暂存授权以供稍后重启。你也可以选择立即恢复或待设备上线后恢复或从不自动恢复。修改此设置不会取消先前发送操作已请求的恢复任务。

CLI 行为

Kaiwu CLI 提供了两个主要的恢复工作流。

列出会话

KAIWU session list

默认情况下，该命令会输出一个表格，包含：

缩短后的会话 ID
智能体
最后更新时间
活跃状态
恢复状态
标题
工作目录路径

常用命令变体：

KAIWU session list --resumable
KAIWU session list --plain
KAIWU session list --json

用法说明：

使用 --resumable 仅显示当前可恢复的会话
使用 --plain 查看旧版的单行输出格式
使用 --json 方便编写脚本

交互式恢复

KAIWU resume

在真正的 TTY 终端中，Kaiwu 会打开交互式选择器，按近期活跃度排序显示可恢复的非活跃会话。

如果你的终端不支持交互式选择器，Kaiwu 会提示你使用 KAIWU session list --resumable，然后再通过 ID 进行恢复。

按 ID 恢复

KAIWU resume <session-id>

你可以传入完整的会话 ID 或无歧义的前缀。

随后 Kaiwu 会执行以下操作：

解析会话
验证其处于非活跃状态、未归档且可恢复
恢复会话的工作目录
恢复提供商会话
将该提供商会话重新连接到同一个 Kaiwu 会话

如果会话已处于活跃状态、已归档、缺少工作目录或不支持厂商恢复，该命令将执行失败并给出明确的错误提示。

CLI 表格中的恢复状态

RESUME 列提供简明概述：

yes：可恢复
no(unsupported)：该智能体/后端不支持厂商恢复
no(missing-id)：会话缺少 Kaiwu 所需的提供商恢复 ID
no(disabled)：该后端支持恢复，但你当前的设置已将其禁用
no(off)：账户设置已完全禁用该后端

Codex 专属行为

Kaiwu 中的 Codex 恢复通常使用默认的 App Server 路径。显式选择 ACP 时，ACP 恢复依然可用。

重点说明：

Kaiwu 中的 Codex 现已默认使用 App Server
旧版 mcp_resume 行为已被移除
如果你主动将 Codex 改回普通 MCP，仍可在该路径上启动全新会话，但不支持厂商恢复
对于新建的 Codex 会话，Kaiwu 不会从默认的 App Server 路径静默回退；若需使用其他后端，请显式选择 ACP 或 MCP
App Server 是默认的可恢复路径；显式选择 ACP 时依然有效
针对显式发起的恢复操作，Kaiwu 保持严格校验，会直接报错而不是静默降级回退

因此，对于 Codex 而言，“能否恢复此会话”取决于会话元数据，以及当前后端路径是否支持该会话的恢复。

恢复与附加的区别

当会话处于非活跃状态，且提供商支持重新打开该提供商会话时，使用恢复（resume）。

当会话仍在本地运行，且你想重新连接到该运行进程时，使用附加（attach）：

KAIWU attach <session-id>

如果不确定如何选择：

本地会话仍在运行时，使用 attach
会话处于非活跃状态但想继续进行时，使用 resume

根据会话的启动方式，“附加”可能有不同的含义：

tmux 重新附加，
聚焦到现有的 Windows Terminal 或控制台宿主，
或者在提供商支持时，使用提供商原生的附加流程。

恢复与直连会话的区别

直连会话是提供商原生会话，Kaiwu 可以检查或跟踪，但尚未完全接管其控制权。

针对这些会话：

通过直连会话流程进行浏览/打开
通过接管 + 导入完成同步/导入
会话成为已同步的 Kaiwu 会话且具有有效的厂商恢复元数据后，才适用常规的 Kaiwu 恢复流程

无法恢复时的排查步骤

如果会话无法恢复，请检查：

会话是非活跃状态，还是其实已经在运行？
会话是否已归档？
会话是否属于你预期的提供商/后端？
你当前是否位于正确的 Kaiwu 服务器/账户配置下？
针对 Codex，所选的恢复路径是否可用（默认为 App Server，显式选择时为 ACP）？
所属设备是否在线且可与 Kaiwu 通信？