守护进程

什么是守护进程？

Kaiwu 守护进程（daemon）是一个轻量后台进程，用于确保 Kaiwu 在你的设备上始终处于可用状态。

实际上，正是在它的支持下，Kaiwu 才能在未打开终端的情况下启动并管理会话。对于远程启动（例如通过 App 或 Web 界面触发）等功能而言，守护进程尤为关键：它在你的计算机上接收该请求，并在本地拉起会话。

它还能协助 CLI 完成以下操作：

• 保持长时间运行的会话处于活跃状态
• 重新连接并管理已有会话
• 无需保持终端处于打开状态，即可支持远程控制与编排功能

内置终端支持

App 内的内置终端同样依赖守护进程。

借助守护进程，Kaiwu 能够：

• 在你的设备上创建终端会话；
• 在页面刷新或切换导航后，重新连接到原终端；
• 将终端输出实时串流回 App 界面；
• 在 App 中调整终端窗口大小或重启终端。

若守护进程未运行或设备无法连接，内置终端将无法工作。

完整指南：内置终端。

提供商认证支持

提供商设置中的登录流程同样依赖守护进程，因为 Kaiwu 需要在目标设备上实际执行对应提供商的 CLI。

守护进程使 Kaiwu 可以：

• 在所选设备上执行提供商登录命令
• 将提供商的终端输出实时串流回 App
• 自动识别登录过程中输出的 URL
• 在登录流程结束后，刷新设备本地的认证状态

完整指南：提供商认证。

本地记忆检索支持

本地记忆检索功能也依赖守护进程。

守护进程使 Kaiwu 能够：

• 构建设备本地的记忆索引
• 在后台维护轻量或深度的会话记录索引
• 在设备上运行可选的本地嵌入模型
• 从 App 或 Web 界面查询本地索引

记忆索引保存在守护进程本地，因此检索范围仅限于运行该守护进程的具体设备。

完整指南：本地记忆检索。

守护进程何时运行？

运行方式主要有两种：

• 按需运行：需要时手动启动（部分 CLI 命令也会自动将其启动）。
• 常驻运行（推荐）：将其安装为用户服务，登录系统后自动启动并在后台持续运行。

为何推荐常驻运行：

• 确保你的设备随时准备好远程启动会话。
• 避免因守护进程未启动而导致“为什么无法启动会话”的困扰。
• 在无头服务器（或需要远程控制的笔记本电脑）上可获得最顺畅的使用体验。

常用命令

kaiwu daemon status
kaiwu daemon start
kaiwu daemon stop
kaiwu daemon list
kaiwu daemon logs

发布通道

守护进程会遵循该设备上安装的 CLI / 运行时通道：

• stable CLI 安装 -> stable（稳定版）守护进程 / 运行时
• preview CLI 安装 -> preview（预览版）守护进程 / 运行时
• dev CLI 安装 -> dev（开发版）守护进程 / 运行时

这意味着各公开通道对应的命令为：

kaiwu daemon install
hprev daemon install
hdev daemon install

同样，更新命令也与通道一一对应：

kaiwu self update
hprev self update
hdev self update

目前没有独立的公开守护进程安装入口，守护进程随设备上对应的 CLI 通道一同分发与安装。

多版本并行安装（stable / preview / dev）

你可以并行安装全部三个公开通道（kaiwu、hprev 与 hdev），它们彼此独立，不会相互覆盖。

守护进程的运行时状态以通道为隔离作用域，其系统服务（LaunchAgent / systemd / 计划任务）也使用通道专用的服务标识符。 如需查看当前平台上具体对应的服务名称、标签或单元，请运行：

kaiwu daemon service paths
hprev daemon service paths
hdev daemon service paths

建议：对于特定的服务器配置文件，除非有明确需要同时运行多个守护进程，否则建议仅启用单一通道的守护进程服务。

常驻运行：安装为用户服务

为当前默认的服务器配置文件安装：

kaiwu daemon install

高级生命周期管理（及试运行预览）：

kaiwu daemon service status
kaiwu daemon service install --dry-run
kaiwu daemon service restart

各平台说明：

• macOS：LaunchAgent
• Linux：systemd --user
• Windows：计划任务（用户级别）

卸载服务：

kaiwu daemon uninstall

在 Windows 上，kaiwu daemon service paths 会输出计划任务的名称以及包装脚本的路径。

无头环境认证（无 TTY）

在无头服务器（或任何无法使用交互式 TTY 的环境）中，请运行：

kaiwu auth login --no-open --method web

该命令会打印授权 URL，并等待你在浏览器中完成授权（授权请求可能会超时；若超时，请重新执行该命令）。

推荐做法：通过 SSH 进行远程配对

如果你拥有 SSH 访问权限，并希望获得端到端全自动体验（包含发起请求、授权审批以及凭据写入），可以在已通过认证的设备上运行：

kaiwu auth pair-remote --ssh user@host --json

这在配置无头服务器时尤为高效：直接在已登录的设备上完成连接授权，无需手动复制和粘贴 URL。

故障排查

• 查看状态：kaiwu daemon status
• 查看日志：kaiwu daemon logs
• 服务路径：kaiwu daemon service paths