Windows

#1. 装上

要求：Windows 10 1809 以上或 Windows 11，x64 或 arm64。

在 PowerShell 里运行：

irm https://quetzal.plutokeating.beer/install.ps1 | iex

也可以在 下载页 下载 quetzal-<版本>-windows-x64-setup.exe（ARM 电脑用 arm64），双击运行。两种方式装的是同一个安装包：一行命令先核对发布签名与哈希，再静默运行它。

安装时会弹出一次管理员权限请求。下面几件事要管理员权限：

• 建一个低权限的本地用户 srt-sandbox，加上防火墙规则，让它只能经代理联网（ta 的命令以这个用户运行，见第 3 节）；
• 缺 Node.js（22.13 以上）、Git 或 Python 3 时，装上安装包里带的官方版本（Node.js 24、Git for Windows、Python 3.14）。它们装在 Program Files 里，沙箱用户才读得到；已经装了的不重装；
• 注册两个计划任务，在开机时（不用登录）和登录时拉起运行基座。

文件装在 %LOCALAPPDATA%\Quetzal：

%LOCALAPPDATA%\Quetzal\
├── home\                 家目录：配置、密钥、数据、灵魂目录（和 Linux 的 ~/.quetzal 一样）
├── runtime\<版本>\        运行基座；current.txt 指向正在用的版本，previous.txt 指向上一版
├── console\<版本>\        控制台（quetzal-console.exe）；current.txt 同上
├── bin\                  命令行 quetzal.cmd 与计划任务的启动器
└── node.txt              运行基座用的 node.exe 的位置

装好后控制台自动打开，向导带你登录、配模型，步骤和手机上一样。

#2. 它怎么一直在

• 开机就运行：计划任务 \Quetzal\Runtime-Boot 在开机时以你的身份启动运行基座（S4U，不保存密码）。电脑崩溃重启后即使没人登录，ta 也在后台运行，你照常能在手机上和 ta 说话、急停，提醒照常响。但这时 ta 不能执行命令：没人登录时，Windows 不允许以沙箱用户启动程序，ta 会说明原因。有人登录后，登录任务接过运行基座，在你的桌面会话里重新启动它，命令随之可用；注销后，开机任务在 5 分钟内又把它在后台接上。
• 登录后：托盘里出现 Quetzal，关掉窗口会收进托盘。开机任务里的运行基座看不到桌面，所以截图、通知、剪贴板、打开网页、播放声音、拍照、录音由托盘在登录后启动的「身体助手」完成。没人登录时，ta 会告诉你「需要有人登录桌面」。
• 崩溃重启：运行基座退出 3 秒后，守护进程把它重新拉起；10 分钟里反复退出就拉长等待。控制台「高级 · 运行」里的「守护」开关可以关掉这项功能。
• 升级：在控制台「关于」里点一下。安装包先关掉正在运行的 Quetzal（升级前会征得你的同意），装好后 40 秒内健康检查不通过就退回上一版。
• 卸载：开始菜单的「卸载 Quetzal」，或「设置 → 应用」。家目录 home\ 里的配置与记忆默认保留。

有些电脑的账户没有「作为批处理作业登录」的权限，注册不了开机任务。这时只有登录时的任务，开机后要有人登录，ta 才开始运行。安装日志里会写明这一点。

#3. ta 能碰到什么

ta 的命令在 PowerShell 里运行（有 PowerShell 7 用 7，否则用系统自带的 5.1），运行身份是安装时建的 srt-sandbox 用户。沙箱用的是 sandbox-runtime（Anthropic 开源，Apache-2.0）：

想让 ta 访问别的文件夹，在 home\config\quetzal.json 的 sandbox.share 里写上它的绝对路径，重启运行基座后生效。

沙箱没装好时（例如没同意那次管理员权限请求），ta 的命令一律不执行，控制台会提示你重新运行安装。

剩下的风险：

• 这台电脑上所有用 sandbox-runtime 的程序（例如 Claude Code）共用 srt-sandbox 用户。Quetzal 运行期间给它的授权，对这些程序也有效。
• 沙箱里的命令能解析域名（连接仍然被拦）；代理的令牌出现在命令行里，同一个登录会话的其他程序能读到。
• 安装包与沙箱程序 srt-win.exe 放在你的用户目录里。同一用户下已经在运行的恶意程序，可以在管理员权限请求弹出前替换它们。先按用户安装、再请求一次管理员权限的做法都有这个问题。
• 读文档、看图片的工具不经过沙箱。运行基座按文件的真实路径挡住密钥目录与保密库。

#4. 签名与智能应用控制

安装包、控制台和 srt-win.exe 都还没有代码签名（正在申请开源项目的免费签名）。文件的完整性由发布签名保证：每个版本的 SHA256SUMS 带 Ed25519 签名，一行命令安装时会先核对它。

• 浏览器下载的安装包，SmartScreen 会提示「Windows 已保护你的电脑」：点「更多信息」→「仍要运行」。
• 开着「智能应用控制」的电脑会直接拦下没有签名的程序，也不给「仍要运行」。一行命令会检测到这项设置，打开「Windows 安全中心 → 应用和浏览器控制 → 智能应用控制」请你关掉，然后继续安装。

#5. 命令行

quetzal status      # 版本、守护任务、局域网地址与证书指纹
quetzal open        # 打开控制台
quetzal logs        # 运行基座的日志（home\logs\runtime.log）
quetzal restart     # 重启运行基座
quetzal rollback    # 退回上一版
quetzal uninstall   # 卸载

#6. 还没有的

• 灵魂桥（Hermes、OpenClaw）不支持原生 Windows，请在 WSL2 里用 Linux 版。
• 桌面版的耳朵没有回声消除：ta 说话时不收音，也不能插嘴打断 ta。
• 拍照、录音受「设置 → 隐私和安全性 → 相机 / 麦克风」控制，要允许桌面应用使用。