接入正在运行的会话

从 Kaiwu 应用启动会话，稍后在终端中接入，并在远程与本地控制之间自由切换。

本指南介绍如何在 Kaiwu 客户端中启动支持的会话，让其在设备上保持运行，之后再从终端重新连接该会话。

该工作流主要用于：

在离开终端时，从客户端界面启动会话；
稍后使用 kaiwu attach ⟦K2⟧ 重新连接；
在远程控制（来自 Kaiwu）与本地控制（来自终端中的提供商 TUI）之间切换同一会话。

适用场景

该工作流适用于以下场景：

从 Web 端或桌面客户端启动会话；
让智能体立即开始工作；
稍后返回，在同一设备的 Shell 中继续操作；
切回客户端，且不丢失会话历史记录。

常见示例：

从客户端启动 Codex 或 Claude 会话，稍后从终端接入；
从客户端启动 OpenCode 会话，之后在本地重新打开，无需创建第二个 Kaiwu 会话；
从界面开始任务，需要直接使用提供商原生 TUI 时运行 kaiwu attach ⟦K3⟧；
让会话在后台运行，稍后重新连接，而无需启动新会话。

接入机制

kaiwu attach 用于重新连接正在运行的会话。

kaiwu attach
kaiwu attach <session-id>

具体行为取决于会话的启动方式：

基于 tmux 的会话：Kaiwu 会将你重新接入运行中的 tmux 会话
Windows Terminal 会话：Kaiwu 会聚焦该会话现有的 Windows Terminal 宿主窗口
Windows 控制台会话：Kaiwu 会将现有的控制台宿主窗口置于前台
提供商原生接入会话：Kaiwu 会使用提供商自带的接入流程连接该会话

kaiwu attach 仅重连现有会话，不会启动新会话。

若在受支持的终端中运行不带会话 ID 的 kaiwu attach，Kaiwu 会打开活动会话的交互式列表：

当前设备上可接入的会话可供选择
可见但不可接入的活动会话将保持禁用状态，并附有说明
支持远程的提供商会话会标记为 remote；在接入前按 P 可检查连通性

已停止的会话不会显示在此选择器中。非活动会话请参阅 kaiwu resume。

环境要求

接入功能的支持情况取决于会话类型。

基于 tmux 的会话

这是在支持 tmux 的设备上，Claude 和 Codex 等提供商的经典接入流程。

要求：

会话必须运行在已安装并可用 Kaiwu CLI/守护进程的设备上；
必须在会话启动前启用 tmux 集成；
必须从运行该会话的同一台设备发起接入；
必须使用启动该会话时相同的 Kaiwu 账号或服务器配置。

客户端启动提供商进程后，tmux 会保持其在后台存活，以便 Kaiwu 稍后重新连接。

Windows 交互式宿主会话

在 Windows 上，tmux 通常不是最佳方案。Kaiwu 针对 Windows 专门提供了以下远程会话模式：

Hidden——最适合纯客户端远程使用
Windows Terminal——适合稍后返回并在 Windows Terminal 窗口中继续操作
Console——在常规的可见控制台宿主中启动会话

如果会话以 Windows Terminal 或 Console 模式启动，kaiwu attach ⟦K4⟧ 会聚焦该现有交互式宿主，而无需使用 tmux。

提供商原生接入会话

部分提供商可以通过自身的原生会话模型进行接入。

例如，OpenCode 无需依赖 tmux 即可重新打开受支持的现有提供商会话。在实际操作中，这仍需要从能访问到底层 OpenCode 设备/会话的终端环境中发起接入。

选择客户端启动会话的运行方式

启用基于 tmux 的启动模式

当设备支持 tmux 且希望创建基于 tmux 的可接入会话时，请使用此模式。

在客户端中：

打开设置
打开会话
启用 tmux integration 选项

启用后，从客户端启动的新支持会话会在 tmux 内运行，方便 Kaiwu 稍后重新接入。

选择 Windows 默认模式

对于 Windows 设备：

打开设置
打开会话
在 Windows 区域中，选择默认的远程会话模式：
- Hidden
- Windows Terminal
- Console

你还可以在以下两处对默认设置进行更细粒度的调整：

按设备指定：打开设备详情页面，覆盖该设备的全局 Windows 模式
按会话指定：在新建会话流程中，当选定设备为 Windows 时，通过 Windows 模式标签进行设置

优先级顺序为：

单个会话设置
设备覆盖设置
全局 Windows 默认设置

典型流程

最常见的流程如下：

在 Kaiwu 客户端中启动会话
在远程模式下正常使用
在所属设备上运行 kaiwu attach ⟦K5⟧
需要直接使用提供商 TUI 时，切换到本地模式
在终端中继续工作
稍后切回远程模式，在客户端中继续操作

接管本地控制由终端驱动。如需接管本地控制，请在所属设备上的终端中运行 kaiwu attach ⟦K6⟧ 进行接入。

当 Claude 或 Codex 会话处于本地模式时，如果你从客户端发送消息，Kaiwu 会先将其加入队列，而不会直接键入终端。若本地轮次仍在运行，Kaiwu 会等待当前轮次结束、中止或达到安全边界后，再将会话切回远程处理并投递队列中的消息。

远程控制与本地控制

同一会话可以在两种控制模式之间切换：

远程控制：在 Kaiwu 界面中交互，Kaiwu 在后台驱动提供商运行
本地控制：本地接入后，直接在提供商的原生终端 UI 中交互

这是同一会话内部的控制权切换，并非新建会话。会话记录、会话 ID 和会话设置均保持不变。

从远程切换到本地控制需在终端中运行 kaiwu attach 发起。当会话处于本地控制时，可从客户端请求切回远程控制。Kaiwu 可能会等待当前本地轮次执行完毕后再接管远程控制，因为强行向繁忙的终端 TUI 输入提示词可能会打断或中止提供商当前的工作。

支持的提供商

Claude

Claude 在 Kaiwu 中支持本地与远程控制。
在本地模式下，可直接使用常规的 Claude 终端 UI。
在 Claude 受本地控制期间从客户端发送的消息会进入队列，并在当前本地轮次达到安全停靠点后投递。
在配备 tmux 的设备上，通常使用基于 tmux 的接入。
在 Windows 上，请使用 Kaiwu 的 Windows 远程会话模式，而非依赖 tmux。
若启用了本地权限桥接，在会话已本地接入的情况下，部分权限提示仍可在 Kaiwu 中弹出。

另请参阅：Claude

Codex

Codex 支持在客户端中启动会话，随后再从终端接入。
接入后，你可以切换为本地控制，直接在 Codex TUI 中继续操作。
在 Codex 受本地控制期间从客户端发送的消息会进入队列，并在 Codex 完成、中止或退出当前本地轮次后投递。
在配备 tmux 的设备上，通常使用基于 tmux 的接入。
在 Windows 上，请使用 Kaiwu 的 Windows 远程会话模式，而非依赖 tmux。
切回远程模式后，Kaiwu 可重新接管，且会话不会丢失。

另请参阅：Codex

OpenCode

OpenCode 支持在客户端中启动会话，随后再从终端接入。
对于受支持的会话，Kaiwu 可以使用 OpenCode 原生接入流程，无需依赖 tmux。
OpenCode 采用共享本地控制模式，因此在接入 OpenCode TUI 的同时，客户端仍保持可写入状态。
在远程与本地/共享控制之间切换时，会话始终是同一个 Kaiwu 会话。

另请参阅：OpenCode

切换过程中的消息处理机制

Kaiwu 维护单一的标准会话状态。在模式切换期间：

会话记录历史保持共享；
权限模式随会话保持一致；
队列中的消息仍保留在会话中；
若会话未处于可立即处理状态，客户端发送的消息会在等待队列中排队。

这是预期行为，可避免在模式切换或重新连接期间丢失消息。

对于 Claude 和 Codex 的本地控制，等待队列还能保护当前终端轮次不受干扰。当提供商 TUI 处于繁忙状态时，Kaiwu 不会将排队的客户端消息发送至该 TUI，而是等待本地轮次完成或停止后，再恢复远程控制并在同一会话中处理队列中的消息。

故障排查

`kaiwu attach` 找不到会话

请检查以下几项：

会话在启动前是否配置为支持接入的模式；
会话是否在当前设备上启动；
是否已在同一 Kaiwu 服务器或账号下完成身份验证。

会话在客户端中成功启动，但稍后无法接入

通常由以下原因之一导致：

会话以不可接入的模式启动（如 Windows 上的 Hidden 模式）；
在基于 tmux 的设备上，会话未在 tmux 内启动；
Windows 交互式宿主已停止运行；
本地设备或会话所属权与接入请求不匹配。

在 Windows 上，`Windows Terminal` 不可用

若 Kaiwu 在该设备上无法使用 Windows Terminal：

安装或更新 Windows Terminal；或
改选 Console 或 Hidden 模式。

切换期间客户端短暂显示排队或等待状态

在本地 ↔ 远程切换过程中，出现短暂的“waiting”（等待中）、“pending”（待处理）或“resume”（恢复中）状态属于正常现象。Kaiwu 可能需要等待提供商进程、会话记录源或守护进程心跳稳定下来，界面才会完整呈现新模式。