q quicktuiv1 获取应用

FAQ

常见问题

按主题分组的完整 FAQ：安装、服务端、会话、iOS 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 的绝对路径（安装服务时的进程环境，或写入配置文件）。注册服务时，QuickTUI 也可能把发现到的绝对路径写入配置，以便 launchd/systemd 在非常规 PATH 下仍能找到 tmux。

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

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

检测到已有 server 二进制后进入升级模式：停止服务、暂存新二进制、用 --version 做合理性检查、原子替换，失败自动回滚。已有配置键（token、地址、TERM、LANG、会话后端、QUICKTUI_TMUX_BIN / QUICKTUI_QSCN_BIN 等）全部保留。

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

服务端 · 服务

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

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

常用键：

编辑后重启服务：

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

# Linux
systemctl --user restart quicktui

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

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

两条路径：

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

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

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

查看状态：

# macOS / Linux
quicktui-server --check-upgrade

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

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 — QuickTUI 提示"token is required"。

确保配置文件中有非空 token：

QUICKTUI_TOKEN=…

默认路径：~/.config/quicktui/config（Windows：%USERPROFILE%\.config\quicktui\config）。也可在命令行传 --token。serve 使用 flag > 配置文件；仅设置进程环境变量对普通 quicktui-server 进程不够。

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

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

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

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

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

QUICKTUI_TERM=xterm-256color

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

--term xterm-256color

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

服务端无法启动或附加会话后端（macOS/Linux 为 tmux，Windows 为 qscn）。查看日志见 Q.11。tmux：若设置了 QUICKTUI_TMUX_BIN，必须是指向真实 tmux 的绝对路径；也请确认 QUICKTUI_TERM 与 QUICKTUI_LANG。Windows：确认 QUICKTUI_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 键服务无专用日志文件。
# 优先 --restart-service（覆盖两种模式）。可选状态检查：
schtasks /Query /TN QuickTUI /V /FO LIST
reg query "HKCU\Software\Microsoft\Windows\CurrentVersion\Run" /v QuickTUI
& "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" --restart-service
# 前台运行（先卸载已安装服务）：
& "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" --uninstall-service
& "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" --config "$env:USERPROFILE\.config\quicktui\config"

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

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

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

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

手动方式：

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

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

安装时：

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

# Windows（PowerShell）
& ([scriptblock]::Create((irm https://quicktui.ai/q.ps1))) --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 回退），二进制与本地状态仍留在磁盘上。需要彻底清理时，卸载后再删除：

删除配置目录会永久丢弃 access token 与已配对设备。

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

文件浏览受配置项 QUICKTUI_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。

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

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

排查步骤：

  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 / qscn）

Q.16 — 会话列表为空。

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

tmux new-session -s mysession

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

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 / 缩放会叠加：每个中间宽度再把一帧陈旧画面推进历史。上游跟踪：

修复。 用 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

iOS App 与浏览器

Q.19 — 什么是 access token？

保存在 QUICKTUI_TOKEN 中的密钥 — 用于保护服务端 HTTP API 与浏览器登录。安装时设定（之后也可用安装器的 --token / --rotate-token）。在电脑上查看：

# macOS / Linux
cat ~/.config/quicktui/config
# 或
quicktui-server --dump-token

# Windows（PowerShell）
Get-Content $env:USERPROFILE\.config\quicktui\config
# 或
& "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" --dump-token

浏览器客户端：打开 http://<host>:8022，按提示粘贴一次 access token。

原生 App 配对：不要粘贴 access token。在电脑上运行：

# macOS / Linux
quicktui-server --pair-qrcode
# 可选：--browser

# Windows
& "$env:LOCALAPPDATA\QuickTUI\quicktui-server.exe" --pair-qrcode

再在 App 中扫描。配对使用 QR 内的短期 pairing code，不是 access token。Windows 安装目录通常不在 PATH 中 — 请用上面的完整路径。

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

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

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

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

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

浏览器登录的 access token 请妥善保密；不要把 pairing code 或 token 贴到公开渠道。

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

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

刷新会话列表，再打开已有会话或新建一个。

相关链接