Claude 统一终端
只需在 Kaiwu 与你共同驱动的真实终端中运行一次 Claude Code，而无需在应用后台运行独立的 Agent SDK 进程。
统一终端运行时会在你的设备上以终端会话形式运行 Claude Code，并由 Kaiwu App 直接驱动该会话。整个过程只存在一个 Claude Code 运行实例：你在 App 中看到的会话记录，正是终端里实时滚动的会话记录；而 Kaiwu 发送的提示词，也是直接输入到原本由你手动键入的输入框中。
这与 Kaiwu 默认运行 Claude 的方式不同。该功能默认处于关闭状态，需要手动开启。
Kaiwu 运行 Claude 的三种方式
| 运行时 | Kaiwu 如何驱动 Claude | 是否可以接入终端？ |
|---|---|---|
| Agent SDK（默认） | Kaiwu 在后台进程中通过 @anthropic-ai/claude-agent-sdk 运行 Claude，并以流式方式传入消息。 | 否。该模式下没有 Claude Code TUI。 |
| 统一终端 | Kaiwu 将 Claude Code 原生的 TUI 托管在 tmux、zellij 或 Windows 控制台宿主中，并将提示词直接写入其输入框。 | tmux 和 zellij 宿主均支持接入——KAIWU attach ⟦K1⟧ 会将你带入同一个窗口或窗格。 |
| 传统远程模式（回退方案） | Kaiwu 以流式输出格式启动 claude，并转发用于获取会话信息的 Hook。 | 否。 |
运行时的选择发生于提供商会话启动之际，并在该会话生命周期内保持固定。此后开启或关闭该设置只会影响下一次启动的 Claude 会话，不会改变当前正在运行的会话。
你所接入的终端，正是 App 正在驱动的那个 Claude Code 运行实例，你可以直接在其中键入内容。每次写入前，Kaiwu 都会读取输入框，确保 App 发送的消息绝不会覆盖你正在输入的内容——详见下文的草稿保护机制。关于 KAIWU attach 的常规工作机制，请参阅接入正在运行的会话。
各运行时下的引导与打断行为
引导与打断介绍了 Kaiwu 提供的两种忙碌时发送行为——引导与打断，但未提及底层实现。在底层，不同的 Claude 运行时表现各异。
在 Agent SDK 模式下，引导消息会被推入 SDK 的流式输入通道。Anthropic 的 Agent SDK 文档将此列为流式输入模式的优势之一：
排队消息：可发送多条按序处理的消息，并支持打断。
— Anthropic, Streaming Input
若选择打断，则会在推送消息前先调用 SDK 的打断接口，从而终止当前轮次并启动你的轮次。
在统一终端模式下，当当前轮次仍在生成时，引导消息会直接键入到运行中的 Claude Code 输入框内。Claude Code 会按照生成中手动输入的标准逻辑来处理：先将文本排队，待当前轮次结束后再行提交。一旦 Kaiwu 在屏幕上检测到 Claude 原生的排队消息横幅，待处理行就会切换为 Queued in Claude——这是终端层面的确凿依据，表明 Claude 已接收该文本，绝非主观猜测。
Kaiwu 不会盲目向终端写入内容。每次写入前，它都会读取屏幕；若当前正在生成的轮次是在不同权限模式下启动的，Kaiwu 会拒绝执行引导——因为 TUI 会静默忽略权限模式的变更，因此该消息会走延期路径，作为常规的新轮次运行。
草稿保护机制
输入框是一个共享操作区。当 App 决定投递消息时，你可能正好也在其中键入内容；简单的直接写入会导致 App 的提示词直接追加在你未写完的半句话之后，合并成一条损坏的提示词被一并提交。
因此，Kaiwu 在写入之前会对输入框状态进行分类判定：
- 空白——直接写入提示词。
- 包含 Kaiwu 之前自行输入的文本——清空该文本（最多重试两次），然后写入。
- 包含其他任何内容——绝不触碰。消息将被挂起并择机重试。
- 处于对话框、权限提示、选项列表或生成界面——同样挂起；当前屏幕并不属于输入框操作状态。
挂起的消息清晰可见，不会无声无息地卡住。待处理行会显示 Terminal draft is blocking delivery，并附带提示：“等待中：终端输入框中的草稿正在阻止投递。请在终端中清空草稿，或打断当前轮次。”如果阻塞一直持续，Kaiwu 会提供清空输入框选项；由于这会丢弃终端中键入的所有内容，因此执行前会弹出确认提示。
未经你的明确要求，Kaiwu 绝不会擅自清空非自身写入的草稿。
开启统一终端
- 打开设置
- 打开 AI 后端
- 打开 Claude Code
- 在统一终端运行时下方，开启使用统一终端运行时
如果界面上没有该设置项，说明你的服务器或部署环境中未提供统一终端运行时。该功能受服务端功能标记控制，遵循默认关闭原则，因此不可用时会直接隐藏而非显示报错界面。详见服务端功能标记。
开启后，请启动新的 Claude 会话。既有会话仍会保持最初启动时的运行时。
终端宿主
统一运行时需要一个能够承载 Claude Code TUI 并允许 Kaiwu 读取屏幕的终端宿主。你可以在终端宿主下进行选择：
- 自动（默认）——若
tmux可用则优先使用，否则使用 Kaiwu 内置的 zellij。 - tmux——使用系统安装的
tmux。 - zellij——使用 Kaiwu 内置的 zellij。
macOS 与 Linux
两种宿主均可正常工作。在自动模式下，只要安装了 tmux 就会优先使用，未安装时则回退到内置的 zellij，因此即使设备上没有 tmux，该运行时也能正常运行。若你显式选择了 zellij 但内置二进制文件不可用，Kaiwu 会回退到 tmux，而不是直接让会话失败。
两种宿主均支持接入：KAIWU attach ⟦K2⟧ 会直接将你带入 App 正在驱动的同一个 tmux 窗口或 zellij 窗格中。
Windows
在原生 Windows 上，Kaiwu 会在 Windows 控制台宿主中托管统一运行时，既不使用 tmux 也不使用 zellij：
- tmux 会被直接拒绝——原生 Windows 不支持 tmux。
- zellij 在原生 Windows 上会被拒绝，因为内置版本尚未在该平台通过验证；在 Windows ARM64 上也会被拒绝，因为上游尚未提供适用于该架构的 zellij 二进制文件。
这两种拒绝情况都会提示改用 WSL2，以便在 Windows 设备上运行由 tmux 或 zellij 托管的统一会话。在当前的 Windows 环境下，将终端宿主保持为自动即可正常运行。
统一终端专有设置
由于统一运行时能够识别 Claude 的对话框，Claude Code 下提供了两项专属设置。它们在其他运行时中不起作用。
恢复大型会话
恢复大型会话时，Claude Code 会询问具体恢复方式。恢复大型会话选项决定了 Kaiwu 如何应对这一询问：
- 每次询问（默认）——Kaiwu 会将该问题以用户操作的形式呈现在会话中，并等待你的选择。
- 从摘要恢复——使用 Claude 的摘要进行恢复，速度更快。
- 恢复完整会话——加载完整的会话上下文。
工作区信任
在执行目录中的代码前，Claude Code 会询问是否信任该文件夹，且在得到答复前会挂起所有 Hook——正因如此，Kaiwu 会直接处理该询问，而不走常规权限流程。
- 每次询问（默认）——在会话中完整展示信任询问。
- 始终信任 Kaiwu 工作区——对 Kaiwu 打开的工作区自动回答信任。
- 始终拒绝 Kaiwu 工作区——对这些工作区自动回答拒绝。
信任询问界面本身也提供了这两个“始终”选项，方便你在做出选择的同时直接将策略保存下来。
修改模型、思考程度与权限模式
Claude Code 自身的控件直接显示在屏幕上，因此 Kaiwu 会直接操纵这些控件，而无需重启 Claude。
- 模型与思考程度的修改方式是向终端中键入
/model和/effort，并对 Claude 弹出的确认对话框进行响应。这些变更会在下一次发送提示词前生效，不会影响当前正在运行的轮次。 - 权限模式的修改方式是轮换切换 Claude 原生的模式控件，并在每次按键后重新读取状态栏中的模式标记，直到标记匹配时停止。由于可选模式的集合并不固定，Kaiwu 会通过校验实际状态而非固定按键次数来确保准确。该修改可在轮次生成过程中生效。
这些实时控制功能本身同样受到特性管控。providers.claude.unifiedTerminal.tuiRuntimeControl 是一项遵循默认关闭原则的服务端特性，依赖于 providers.claude.unifiedTerminal；若服务端未声明支持该特性，即使运行时本身正常运作，这些控制也会回退至“需要重启”或“暂不支持”的状态。详见功能标记。
如果 Kaiwu 无法通过屏幕校验控件状态，它绝不会凭空猜测，而是在会话记录中发布一条通知：
Claude 统一终端已在运行。模型、权限、思考程度以及启动选项的变更将在 Claude 重启后生效；本次提示词已发送至当前的 Claude 终端会话。
统一运行时的限制与不支持项
- 最大思考 Token 数是 Agent SDK 独有的选项，在此处没有对应功能。Kaiwu 会提示已在未应用该选项的情况下发送了提示词。
- 文件检查点与
/rewind仅支持远程 Agent SDK。详见 Claude。 - 高级选项 (JSON) 仅作用于 Agent SDK 的查询选项，不会影响由终端托管的运行实例。
故障排查
Claude Code 设置中没有该选项
统一终端运行时受服务端功能标记控制。若你的服务器未启用该标记，整个配置分区都会被隐藏。
已开启该功能，但会话表现仍与此前一致
运行时是在提供商会话启动时选定的，并在该会话期间保持不变。请启动新的 Claude 会话。
会话因 Hook 激活错误而终止
Kaiwu 安装了 Claude Code 插件，用于将权限和生命周期事件路由至 App。如果 Claude 接受了终端输入却未能激活这些 Hook，Kaiwu 会主动终止会话，以避免出现虽然会话记录能正常镜像、但权限提示却卡在终端里的异常情况。请重启该会话。
消息提示正在等待终端草稿
终端输入框中存在未发送的文本。请在终端中清空该内容，或在待处理消息面板中使用清空输入框，也可以直接打断当前轮次。