FAQ

常见问题

按主题分组的完整 FAQ：安装、服务端、会话、移动 App 与浏览器。

安装

Q.01 — 安装时校验和验证失败。

通常是下载中断或损坏 — 重新运行安装脚本即可。若持续出错，可能是发布资源刚更新，稍等几分钟重试。

也请检查是否有中间人拦截 HTTPS 流量（例如企业代理）。

Q.02 — 未安装 tmux 或版本过旧。

macOS / Linux：会话后端为 tmux 3.2 或更高版本。安装器不会代装 tmux — 请用系统包管理器自行安装（brew、apt、yum、dnf 等）后重新运行安装器。若安装或注册服务时报 “tmux not found” 或版本过低，请先升级 tmux。

可选覆盖：把安装器进程环境变量 QUICKTUI_TMUX_BIN 设为有效 tmux 的绝对路径，或在配置文件中写入 tmux_bin。注册服务时，QuickTUI 也可能把发现到的绝对路径写入配置，以便 launchd/systemd 在非常规 PATH 下仍能找到 tmux。

Windows：默认后端是 qscn（qscreen），不是 tmux。安装器会自动下载并安装 qscn 到 %LOCALAPPDATA%\QuickTUI\，并写入 session_backend = "qscn" 与 qscn_bin。Windows 上不需要 tmux。

Q.03 — 重新运行安装脚本会发生什么？

检测到已有 server 二进制后进入升级模式：停止服务、暂存新二进制并执行版本健全性检查、原子替换，失败自动回滚。已有配置键（地址、TERM、LANG、会话后端、tmux_bin / qscn_bin 等）全部保留。

二进制路径：macOS/Linux 为 ~/.local/bin/quicktui-server；Windows 为 %LOCALAPPDATA%\QuickTUI\quicktui-server.exe。

服务端 · 服务

Q.04 — 配置文件里可以配置什么？

默认路径：~/.config/quicktui-server-v2/config.toml（Windows：%USERPROFILE%\.config\quicktui-server-v2\config.toml）。已安装服务以 serve --config 指向该文件启动。普通 quicktui-server serve 进程也会加载该文件（或 --config 指定路径）。serve 取值优先级：CLI flag > 配置文件键 > 内置默认。进程环境变量不参与 serve 配置（仅服务安装等少数旁路会读进程 env）。

常用键：

• addr — 监听地址（默认 0.0.0.0:8022）
• term — 会话 TERM（默认 xterm-256color）
• lang — 会话 LANG（默认 en_US.UTF-8）
• session_backend — tmux（非 Windows 默认）或 qscn（Windows 默认）
• tmux_bin / tmux_socket — tmux 二进制覆盖与 socket（tmux 后端）
• qscn_bin / qscn_socket — qscn 二进制与 socket（Windows / qscn 后端）
• files_enabled — 文件浏览器开关（true/false；默认关闭，需在 App 中启用）
• chat_transcript_retention_days — Agent 对话保留天数（默认 2；0 关闭清理）
• debug / verbose — 日志开关
• update_channel / update_region — 最近成功升级的 channel/region（通常由服务端写入）

编辑后重启服务：

# macOS
launchctl kickstart -k gui/$(id -u)/ai.quicktui

# Linux
systemctl --user restart quicktui

# Windows — 优先用完整路径（quicktui-server 不一定在 PATH）
& "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" service restart

Q.05 — 服务端升级与重启如何工作？

两条路径：

重新运行安装脚本 — 原子替换、失败回滚、配置保留。Windows 上这是二进制升级的支持路径。

服务端自更新（macOS / Linux） — App/API 路径（POST /v2/api/update）下载并替换二进制，但不会自动重启；可在 App/浏览器重启、调用 POST /v2/api/restart，或重启系统服务。CLI quicktui-server upgrade install 会升级并重启已安装服务。Windows 不支持 upgrade install — 请重新运行安装器（irm https://quicktui.ai/q.ps1 | iex）。

升级 / 重启 / 关停相互串行：重启进行中时新升级请求会被拒绝，反之亦然。

查看状态：

# macOS / Linux
quicktui-server upgrade check

# Windows
& "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" upgrade check

Q.06 — 可以不安装就验证服务端环境吗？

可以 — 运行环境预检，不安装、不写入服务端配置：

# macOS / Linux
curl -fsSL https://quicktui.ai/q.sh | sh -s -- check

# Windows（PowerShell）
& ([scriptblock]::Create((irm https://quicktui.ai/q.ps1))) check

Q.07 — 如何配对另一台设备？

在 macOS/Linux 的 server 机器上运行 quicktui-server pairing qrcode；Windows PowerShell 运行 & "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" pairing qrcode，再用原生 App 扫描短期有效的二维码。桌面环境可加 --browser 显示像素二维码；用 --select-address 选择检测到的地址，或在 TLS 代理后使用 --debug-addr https://your.domain。当前 CLI 流程只支持能扫描二维码的原生 App 配对新设备，尚不提供 Web 或 Desktop 新设备配对所需的完整 payload 导出。配对会注册设备公钥并固定 server identity，不会创建或泄露 root token。

Q.08 — 无法连接 — connection refused。

先检查服务：

# macOS
launchctl print gui/$(id -u)/ai.quicktui

# Linux
systemctl --user status quicktui

# Windows（计划任务；若没有，可能是 HKCU Run 回退）
schtasks /Query /TN QuickTUI
reg query "HKCU\Software\Microsoft\Windows\CurrentVersion\Run" /v QuickTUI

优先用 service restart / service uninstall（%LOCALAPPDATA%\QuickTUI\ 完整路径）— 同时覆盖计划任务与 Run 键模式。若跳过了服务注册，请用相同配置与地址启动 quicktui-server（或传 serve --debug-addr）。若服务已在运行，请确认防火墙或隧道放通了 addr 对应的端口。

Q.09 — 当 TERM=xterm-ghostty 时，文字渲染错乱。

在 tmux 后端上，服务端 tmux 在 TERM=xterm-ghostty 下无法正确渲染 — Ghostty 自己的 terminfo 不适用于远端会话里的 tmux。

改用广泛支持的 TERM。在配置文件中：

term = "xterm-256color"

然后重启服务。一次性 serve 命令则用：

quicktui-server serve --term xterm-256color

Q.10 — 打开会话时出现 PTY spawn failed / internal server error。

服务端无法启动或附加会话后端（macOS/Linux 为 tmux 或 Herdr，Windows 为 qscn）。查看日志见 Q.11。tmux：若设置了 tmux_bin，必须是指向真实 tmux 的绝对路径；也请确认 term 与 lang。Windows：确认 qscn_bin 指向可用的 qscn.exe（必要时重跑安装器）。

Q.11 — 如何查看服务端日志？

# macOS
tail -f ~/Library/Logs/QuickTUI/stdout.log \
        ~/Library/Logs/QuickTUI/stderr.log

# Linux
journalctl --user -u quicktui -f

# Windows — 计划任务 / Run 键服务无专用日志文件。
# 优先 service restart（覆盖两种模式）。可选状态检查：
schtasks /Query /TN QuickTUI /V /FO LIST
reg query "HKCU\Software\Microsoft\Windows\CurrentVersion\Run" /v QuickTUI
& "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" service restart
# 前台运行（先卸载已安装服务）：
& "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" service uninstall
& "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" serve --config "$env:USERPROFILE\.config\quicktui-server-v2\config.toml"

Windows 上请优先用 service restart，不要手写 schtasks /End 后立刻 /Run — 服务端会等待旧进程退出再释放端口。临时前台运行结束后，用同一完整路径执行 service install 重新注册服务。

若手动启动 quicktui-server，输出在你启动它的那个终端。

Q.12 — 如何修改监听地址或端口？

服务方式：编辑配置文件中的 addr，然后重启（见 Q.04）。

手动方式：

# macOS / Linux
quicktui-server serve --debug-addr 0.0.0.0:9000

# Windows
& "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" serve --debug-addr 0.0.0.0:9000

安装时：

# macOS / Linux
curl -fsSL https://quicktui.ai/q.sh | sh -s -- install --channel stable \
  --addr 127.0.0.1 --port 9000

# Windows（PowerShell）
& ([scriptblock]::Create((irm https://quicktui.ai/q.ps1))) install --channel stable --addr 127.0.0.1 --port 9000

--addr 接受 IPv4 地址、主机名，或 http(s)://host:port 形式的 URL（scheme 只是书写便利，服务端仍以明文 HTTP 监听）。IPv6 字面量必须用方括号并自带端口，例如 --addr "[::1]:9000"；裸写 ::1 会被拒绝。--port 仅在 --addr 尚未包含端口时生效。

Q.13 — 如何卸载 QuickTUI？

# macOS / Linux
curl -fsSL https://quicktui.ai/q.sh | sh -s -- uninstall

# Windows（PowerShell）
$qps1 = "$env:TEMP\q.ps1"; irm https://quicktui.ai/q.ps1 -OutFile $qps1
powershell -File $qps1 uninstall

卸载只会停止并注销服务（launchd / systemd user unit / Windows 计划任务 QuickTUI 或 HKCU Run 回退），二进制与本地状态仍留在磁盘上。需要彻底清理时，卸载后再删除：

• macOS / Linux：~/.local/bin/quicktui-server（二进制）与 ~/.config/quicktui-server-v2（配置、配对 identity、已配对设备与本地状态）。
• Windows：%LOCALAPPDATA%\QuickTUI（二进制 / qscn）与 %USERPROFILE%\.config\quicktui-server-v2（配置、配对 identity、已配对设备与本地状态）。

删除配置目录会永久丢弃 server identity 与全部已配对设备，所有客户端都必须重新配对。

Q.14 — macOS 文件浏览器访问 桌面 / 文稿 / 下载 等目录会卡住。

文件浏览受配置项 files_enabled 控制（默认关闭，需在 App 中启用 Files，服务端 API 会写入 true）。若 Files 未启用，请先在客户端打开。

macOS 通过 TCC（隐私权限子系统）保护 桌面、文稿、下载、iCloud Drive 等系统目录。QuickTUI 服务以后台 launchd agent 形式运行，无 UI 上下文，无法触发系统授权弹窗，因此访问这些目录会静默挂起直到请求超时。

解决方法 — 给 server 二进制加完全磁盘访问权限：

1. 打开 系统设置 → 隐私与安全性 → 完全磁盘访问。
2. 点 + 号。在文件选择器中按 Cmd+Shift+G，输入 ~/.local/bin，选中 quicktui-server。
3. 确保 quicktui-server 旁边的开关已启用。
4. 回到 QuickTUI 客户端，点警告条上的 已授权, 重测。无需重启服务。

若 重测 仍然失败，重启服务：

launchctl kickstart -k gui/$(id -u)/ai.quicktui

为什么没有自动授权弹窗： macOS 仅对带 UI 上下文的进程（Finder、终端、Dock 启动的 App）显示 TCC 授权弹窗。后台 launchd agent 无 UI，授权弹窗永远不会显示，系统会静默拒绝直到用户手动加白名单。

Q.15 — Linux 文件浏览器提示 "permission denied" 或返回 403。

文件浏览受 files_enabled 控制（默认关闭，需在 App 中启用后服务端写入 files_enabled = true）。若客户端显示 Files 未启用，请先在客户端打开。

QuickTUI 服务以你当前用户（通常是 systemd --user）身份运行，只能读到该用户拥有 POSIX 读+执行权限的路径。常见原因：

• 权限位。 文件 0600 / 目录 0700 模式只有所有者能读。用 ls -ld /path 检查。
• 父目录缺少 x 位。 即使目标文件 world-readable，server 也需要每一级祖先目录有 execute 权限才能 traverse。
• POSIX ACL。 getfacl /path 可能显示显式 deny 条目覆盖了普通权限位。
• 用户错误。 如果某次用 sudo 启动过 server，后又切回普通用户，残留文件可能 root 所有。stat /path 看 owner。
• SELinux（RHEL / Fedora / Rocky）。 即便权限位正确，MAC 也可能拦截。若 SELinux 可能拦截，用 ausearch -m AVC -ts recent / getenforce 排查，再修正文件 context 或添加限定策略模块，而不是全局关闭强制模式。
• AppArmor / Snap 隔离（Ubuntu）。 若你用 snap 安装 quicktui-server，它读不到 snap home 之外的文件。推荐安装路径是 ~/.local/bin/quicktui-server（无 confinement）。
• 挂载选项。 noexec 或只读挂载在某些操作上会表现为 EACCES。用 findmnt /path 检查。

排查步骤：

1. 对失败路径及每一级父目录跑 ls -ld /full/path/to/dir。确认 server 运行用户对目录有 r-x，对文件有 r--。
2. 确认服务运行用户：systemctl --user show quicktui -p MainPID，再 ps -o user= -p <PID>。
3. 调权限：chmod o+rx /path（共享路径），或用 ACL setfacl -m u:<user>:rx /path（选择性授权）。
4. SELinux 拦截时，加文件 context label 或用 audit2allow 生成策略模块 — 参考你的发行版 SELinux 文档。
5. 客户端点 已授权, 重测。无需重启服务。

仍失败时复现操作并查看日志：journalctl --user -u quicktui -f。

会话（tmux / Herdr / qscn）

Q.16 — 会话列表为空。

QuickTUI 列出配置后端中的会话（macOS/Linux 为 tmux 或 Herdr，Windows 为 qscn）。tmux 或 qscn 后端下，若尚无会话，从 App 或浏览器点 New Session 创建。macOS/Linux 也可在电脑上创建命名 tmux 会话：

tmux new-session -s mysession

Windows 请优先用 App 的 New Session；后端是 qscn，不是 tmux。

Herdr 后端下没有 New Session：QuickTUI 只列出、聚焦和接入 Herdr 会话，请在 Herdr 里启动或创建 workspace，它会随即出现在列表中。

Q.17 — 在 tmux 里跑 Claude Code 一段时间后，scrollback 出现重复或错位的文字。

适用于会话后端为 tmux 的情况（macOS/Linux 常见）。

现象。 在 tmux pane 里使用 Claude Code（或类似 TUI 工具，如 OpenAI Codex CLI、aider）后，回看 tmux 历史出现重复帧、列错位或旧渲染碎片。重启 QuickTUI 服务不会修复桌面侧 tmux — 只有 tmux clear-history 能清掉。

原因。 Claude Code 的 TUI 基于 Ink 渲染库。当渲染区域超出终端视口（或每次全屏重绘）时，Ink 渲染循环会发出 CSI 3 J（"Erase Saved Lines"）并在主屏幕缓冲区整屏重绘 — 且没有 DECSET 2026（同步输出）括号。tmux 处理这些部分帧并写入 pane scrollback。随后的 SIGWINCH / 缩放会叠加：每个中间宽度再把一帧陈旧画面推进历史。上游跟踪：

• #29937 — Terminal rendering corruption in tmux
• #49086 — Resize duplicates banner/content in scrollback
• #37283 — TUI flicker / missing DECSET 2026

修复。 用 fullscreen 模式跑 Claude Code — 切到备用屏幕缓冲区（类似 vim / htop），不再碰 scrollback。需要 Claude Code v2.1.89+：

/tui fullscreen

v2.1.89 — v2.1.109 用环境变量：

CLAUDE_CODE_NO_FLICKER=1 claude

清理已损坏的 scrollback。 乱码已在 tmux pane 历史里，只能清历史：

tmux clear-history

然后用 fullscreen 模式重新启动 Claude Code。首次选中主屏幕上跑着 Claude Code（或其他已知 TUI 工具）的 pane 时，QuickTUI 客户端也会弹出提示横幅。

Q.18 — 终端应用输入框里反复出现 11;rgb:2828/2c2c/3434 这类乱码。

多见于 tmux 后端、多个客户端附着同一会话时。

现象。 多个客户端（例如本机终端 + QuickTUI App 或浏览器）附着同一 tmux 会话时，终端应用的输入框反复填入类似 11;rgb:2828/2c2c/3434 的乱码 — 有时连着好几串。

原因。 部分终端应用通过 OSC 10/11/12 查询自动探测颜色主题（“当前前景/背景/光标颜色是什么？”）。tmux 把查询转给外层终端，再把答复路由回 pane。多客户端时，答复可能落在应用对该答复的短暂解析窗口之后，于是应用把原始转义字节当键入写进输入框。这是应用侧问题，不是 QuickTUI 缺陷 — 例如 Claude Code 跟踪为 #12910 — OSC terminal color query responses leak into input buffer。

修复。

1. 给受影响应用固定主题，不要自动探测。Claude Code 里跑 /theme，选固定的 light 或 dark。
2. 其他 TUI 工具同样关闭自动终端颜色 / 主题探测。
3. 可选：在 ~/.tmux.conf 加上下面一行，减少 tmux 下转义序列碎片化：

   set -s escape-time 100

Q.19 — QuickTUI 支持 Herdr 吗？

支持，限 macOS/Linux，需要 Herdr v0.8.0（当前已验证的版本）。在配置文件里设置后端并重启服务：

session_backend = "herdr"
herdr_bin = "/absolute/path/to/herdr"

写 session_backends = "tmux,herdr" 可同时列出 tmux 与 Herdr 会话。QuickTUI 只负责列出、聚焦和接入 Herdr 会话，workspace 请在 Herdr 里创建和管理。截至 2026 年 8 月，Herdr 后端随 preview 通道的服务端发布（install --channel preview）。iPhone、iPad 和浏览器客户端只连接 QuickTUI 服务端，不会直接连接 Herdr。参见iPhone 和 iPad 上的 tmux 与 Herdr。

移动 App 与浏览器

Q.20 — 设备认证如何保护连接？

QuickTUI 使用设备配对，不再使用 root access token 或 browser token 登录。短期 pairing code 用于注册客户端公钥与固定的 server fingerprint。之后每次连接都会在当前加密握手内，通过绑定 transcript 的 device_pop_v1 证明客户端持有对应私钥；这份证明不能拿到另一条 E2E 连接上重放。

所有业务流量都走同一条固定 identity 的 client-server E2E 隧道。直连会端到端承载它；QuickTUI Relay 只转发不透明的加密帧，无法读取终端、文件或 Agent 流量。浏览器仅在 HTTPS 或 http://localhost:8022 这类 loopback origin 的 IndexedDB 中保存不可导出的 P-256 设备密钥；远程明文 HTTP origin 会安全失败。

使用已退役 root token 创建的 profile 必须重新配对。旧版每设备 bearer 只能在固定 identity 的 E2E 隧道内一次性迁移；客户端随后会先用 device_pop_v1 重新认证，再删除旧凭据。用 quicktui-server pairing devices list 列出设备，用 quicktui-server pairing devices revoke <device_id> 撤销设备；Windows PowerShell 请使用 $env:LOCALAPPDATA\QuickTUI\quicktui-server.exe 完整路径。被撤销的客户端会回到配对状态。

Q.21 — 可以通过公网连接吗？

可以。需要让电脑可从公网访问 — 通过 VPN、带 TLS 的反向代理、Tailscale / Cloudflare Tunnel 等隧道，或可选的 QuickTUI Relay 订阅（无法暴露主机时的云中继；在 App 中绑定，或在机器上执行 quicktui-server config relay set <qtrid> <ws-endpoint> — Windows 请用 %LOCALAPPDATA%\QuickTUI\ 下的完整路径）。机器本机 8022 上的 outer listener 使用明文 HTTP，但已配对业务流量仍位于 client-server E2E 隧道内。不要把原始 8022 端口直接暴露到公网；若在反向代理或隧道后终结 TLS，请指向 http://127.0.0.1:8022，App 里填公网 HTTPS 域名，通常不写端口；:443 等价可用。公网 HTTPS 地址不要写 :8022。

在 TLS 或隧道后生成配对二维码时，把公开 base URL 写入 QR（能力探测仍用配置里的本地监听地址）：

# macOS / Linux
quicktui-server pairing qrcode --debug-addr https://your.domain

# Windows
& "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" pairing qrcode --debug-addr https://your.domain

Pairing code 是短期凭据；不要把二维码或配对内容贴到公开渠道。

Q.22 — App 或浏览器提示 "Session not found"。

这直接来自服务端 — 会话已关闭、被重命名，或会话后端（tmux / Herdr / qscn）未在运行。

刷新会话列表，再打开已有会话。tmux 或 qscn 后端下也可用 New Session 新建；Herdr 后端下请在 Herdr 里启动或重建 workspace，再刷新列表。

Q.23 — Agent 通知会发送哪些数据，如何关闭？

Agent 通知需要你按设备主动开启。操作系统权限与该设备的通知注册是两项独立控制；每台 QuickTUI server 另有 server-wide 偏好，用于控制已注册设备是否接收通知、选择待审批 / 任务完成 / 错误 / 会话结束类别，以及选择正文可选字段。

默认通知正文只说明事件类别。你还可以允许显示 Agent 类型、项目名、会话名及任务或错误摘要。正文没有用于发送完整终端输出、源代码、凭据、完整提示词或完整 Agent 回复的字段；但所选名称和摘要仍可能包含你或 Agent 提供的文字。

投递及打开通知仍需要 route-only 数据，例如已绑定设备 ID、routing mode、类别、notification ID/revision、collapse ID、发送时间，以及 Agent runtime/session/interaction 引用或紧凑 locator。这些不是显示字段，不受正文开关控制。内部用于 Relay 重试和去重的 request ID 不会发给设备。你的 server 会在本地保存通知偏好与设备注册，再把所选正文、route-only 数据和设备 push token 经 QuickTUI Relay 转发给 APNs 或 FCM。Relay 不会持久化 push token 或 payload；有界且短期的重试状态包括 Relay 和 request 标识、请求哈希、生命周期元数据及响应，但不包含 push token 或 notification payload。APNs 投递 iOS alert；FCM 则发送 data-only message，由 QuickTUI Android 应用处理后显示。

要停止通知，可撤销操作系统权限、关闭该设备的通知注册，或调整 server-wide 偏好。删除使用同一已配对设备凭据的最后一个本地 profile 时，客户端会请求撤销该凭据对应的远端 push registration。APNs 或 FCM 已接受的通知仍可能送达。完整披露见隐私政策。