FAQ

常见问题

按主题分组的完整 FAQ：安装、服务端、连接与配对、会话、文件浏览、通知与 App。

• 安装
• 服务端
• 连接与配对
• 会话
• 文件浏览
• 通知
• App

安装

Q.01 — 安装时提示 sha256 校验失败。

安装器会校验服务端文件与签名，失败时提示 quicktui-server-… sha256 mismatch 或签名校验失败。

通常是下载中断或内容损坏，重新运行同一条安装命令即可。仍然失败时，换用另一个安装源（Global 或中国镜像）重试，并检查网络中是否有缓存或篡改下载内容的代理。

签名校验失败时请不要设法绕过，请把完整输出反馈给我们。

Q.02 — 需要先安装 Herdr 或 tmux 吗？

需要。QuickTUI 服务端至少需要 Herdr 或 tmux（3.2 及以上）其中一个，推荐使用 Herdr（原因见 Q.03）。

安装时如果电脑上已有其中一个，安装器会直接使用；两者都没有时，安装器会尝试从 Herdr 官方源自动安装 Herdr，装到 ~/.local/bin/herdr（以 root 安装时为 /root/.local/bin/herdr）。Windows 上只支持 Herdr，Microsoft Store 中的 QuickTUI Server 不会安装它，请先自行安装 Herdr（见 Q.04）。

自动安装失败时（例如网络无法访问 Herdr 官方源），安装器只给出警告，服务端照常安装，但在装好 Herdr 或 tmux 之前无法使用会话。请手动安装其中一个（见 Q.04 与 Q.05），再重新运行安装命令。

Q.03 — 为什么要使用 Herdr 或 tmux？

Herdr 和 tmux 都支持多个工作区，并能让会话在后台持续运行：只要电脑没有重启，你的 Agent 会话就会一直保持。

对于大多数用户，推荐使用 Herdr：它与 Agent 的集成更好，性能也更出色。如果你已经习惯 tmux，QuickTUI 同样完整支持 tmux。

Q.04 — 如何安装 Herdr？

# macOS / Linux
curl -fsSL https://herdr.dev/install.sh | sh

# Windows（PowerShell）
powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"

完整文档：herdr.dev/docs/install

Q.05 — 如何安装 tmux？

多数 Linux 发行版可以直接用包管理器安装，macOS 可以用 Homebrew：

# Debian / Ubuntu
sudo apt install tmux

# Fedora
sudo dnf install tmux

# macOS（Homebrew）
brew install tmux

QuickTUI 需要 tmux 3.2 及以上版本。其他系统见 tmux 安装文档。

tmux 不支持 Windows，Windows 上请使用 Herdr。

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

安装命令会原地升级已有的服务端：用新版本替换 QuickTUI 服务端并重启服务，替换失败时自动恢复原版本。

已配对的设备、服务端身份和现有配置（端口、会话后端等）都会保留，无需重新配对。

Q.07 — 可以在安装前检查或准备依赖吗？

macOS 和 Linux 上可以。check 只检查运行时依赖，不安装服务端、不写配置、不注册服务：

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

已安装服务端时，check 默认检查已安装的版本；尚未安装时，会临时下载并校验当前正式版服务端，据此检查运行时依赖，完成后自动删除。要检查指定的本地二进制，请用 --server 传入绝对路径，例如 check --server "$HOME/Downloads/quicktui-server"。已安装文件损坏时会报错，不会转而下载。

prepare 只安装缺失的依赖（如 Herdr），同样不安装服务端：

curl -fsSL https://quicktui.ai/q.sh | sh -s -- prepare

服务端

Q.08 — 如何修改服务端设置？

设置保存在 ~/.config/quicktui-server-v2/config.toml（Windows 为 %USERPROFILE%\.config\quicktui-server-v2\config.toml）。监听地址、TERM、LANG 和 tmux socket 可以用 config set 修改，它会写入配置并自动重启服务：

~/.local/bin/quicktui-server config set --addr 0.0.0.0:9000

其他配置项需要直接编辑配置文件，然后重启服务：

# macOS / Linux
~/.local/bin/quicktui-server service restart

# Linux（以 root 安装）
sudo /usr/local/bin/quicktui-server service restart

# Windows（PowerShell）
quicktui-server service restart

全部配置项及说明见安装指南的配置文件。

Q.09 — 如何升级或重启服务端？

最简单的方式是在 App 中升级：升级完成后会自动重启服务。

在 macOS 和 Linux 上也可以用命令升级；已是最新版本时不做任何改动：

~/.local/bin/quicktui-server upgrade check
~/.local/bin/quicktui-server upgrade install

以 root 安装时，把路径换成 /usr/local/bin/quicktui-server 并加 sudo。Windows 上由 Microsoft Store 自动更新服务端，App 和命令行都不会升级它。

只重启服务：

# macOS / Linux
~/.local/bin/quicktui-server service restart

# Linux（以 root 安装）
sudo /usr/local/bin/quicktui-server service restart

# Windows（PowerShell）
quicktui-server service restart

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

用 config set --addr 修改，服务会自动重启：

# macOS / Linux
~/.local/bin/quicktui-server config set --addr 0.0.0.0:9000

# Linux（以 root 安装）
sudo /usr/local/bin/quicktui-server config set --addr 0.0.0.0:9000

# Windows（PowerShell）
quicktui-server config set --addr 0.0.0.0:9000

地址格式为 host:port，IPv6 需加方括号，如 [::1]:9000。修改后，手机需要用新地址连接；可以运行 pairing qrcode 显示包含新地址的二维码。

安装时也可以直接指定：install --port 9000 或 --addr 127.0.0.1:9000。

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

macOS 与 Linux：

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

# Linux（普通用户）
journalctl --user -u quicktui -f

# Linux（以 root 安装）
journalctl -u quicktui -f

Windows 上服务端不写日志文件。需要查看输出时，先停止服务，再在前台运行服务端：

quicktui-server service uninstall
quicktui-server serve --log-level debug

service uninstall 会同时移除 Agent hook，服务端启动时会自动恢复。排查完成后按 Ctrl+C，再运行 quicktui-server service install 让服务端回到后台运行。

需要更详细的日志时，在配置文件中设置 log_level = "debug" 后重启服务。只看部分日志时，再设置 debug_categories，例如 debug_categories = ["WS"]。

Q.12 — 如何卸载 QuickTUI？

在 macOS 和 Linux 上，在安装命令后加 uninstall：

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

卸载会移除后台服务与 Agent hook，服务端程序和配置（含配对记录）会保留。在 Windows 上，先在 PowerShell 中运行 quicktui-server service uninstall，再到「设置 > 应用 > 已安装的应用」中卸载 QuickTUI Server，配置与配对记录会保留。需要完全移除时，参见安装指南的卸载。

Q.13 — Linux 上可以用 root 安装 QuickTUI 吗？

可以。在带 systemd 的 Linux 上以 root 运行安装命令，会安装为系统服务，开机自启，不依赖用户登录：

普通用户安装

程序：~/.local/bin/quicktui-server服务：systemd 用户服务，用 systemctl --user 管理配置：~/.config/quicktui-server-v2/

root 安装

程序：/usr/local/bin/quicktui-server服务：/etc/systemd/system/quicktui.service，用 systemctl 管理配置：/root/.config/quicktui-server-v2/

root 安装的服务以 root 身份运行。系统没有 systemd 时，只会安装程序，不注册服务。同一台机器上的 root 安装和普通用户安装是两个独立实例，请勿混用，见 Q.14。

Q.14 — root 和普通用户混用后，服务起不来。

QuickTUI 不会接管其他账号的文件，检测到混用时会报错：quicktui: unsupported mixed identity: <ID>，错误信息中附有期望的 euid、实际属主和路径。常见的 ID 有三种：

mixed-config

root 安装时，配置目录路径上有目录不属于 root、可被其他用户写入，或是符号链接。

mixed-binary

root 安装时，服务端程序路径不满足同样的要求。出现在安装或服务注册的输出中。

mixed-socket

tmux socket 目录属于其他用户，或 TMUX_TMPDIR 指向其他用户的目录。普通用户与 root 都可能遇到。

用以下命令确认身份与属主，并查看完整错误：

id -u
stat ~/.config/quicktui-server-v2

# 普通用户
journalctl --user -u quicktui -e

# root
journalctl -u quicktui -e

修复方法是让每个实例只使用自己账号下的配置、程序和 socket：用原账号卸载误装的实例，再以正确的身份重新安装。

Q.15 — Linux 上退出登录后，服务端就停止了？

Linux 普通用户安装的服务端以 systemd 用户服务运行，默认随登录会话启停。关闭 SSH 连接或退出登录后，服务端可能随之停止，手机将无法连接。开启 linger 即可常驻运行，根据情况选择对应的命令：

1. 直接开启（本机登录或当前用户有权限时）：

loginctl enable-linger

2. 提示权限不足（如 Access denied、Interactive authentication required，常见于 SSH 远程登录）。有 sudo 权限时：

sudo loginctl enable-linger "$USER"

没有 sudo 权限时，请管理员代为执行：

sudo loginctl enable-linger <你的用户名>

3. 提示 Failed to connect to bus。如果是用 su 或 sudo -u 切换到该用户后运行的，当前会话缺少用户总线，请改为直接以该用户 SSH 登录后再运行；或先补上运行时目录再开启：

export XDG_RUNTIME_DIR=/run/user/$(id -u)
loginctl enable-linger
systemctl --user restart quicktui

如果系统本身没有以 systemd 启动（部分容器、未启用 systemd 的 WSL），用户服务和 linger 都无法使用，请改用 root 安装，或先为系统启用 systemd。

确认已开启：输出 Linger=yes 即可。

loginctl show-user "$USER" --property=Linger

开启后服务端会开机自启并常驻运行，与是否登录无关。以 root 安装的系统服务不受此影响。

Q.16 — 配对时提示另一个 QuickTUI 服务端正在监听该端口。

旧版 QuickTUI 服务端仍在运行，占用了监听端口（默认 8022），新版无法使用。停止旧服务后重启服务端：

~/.local/bin/quicktui-server service restart

分不清哪个是旧服务时，参见 Q.14（root 安装与普通用户安装混用）。

连接与配对

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

在电脑上运行配对引导：

# macOS / Linux
~/.local/bin/quicktui-server pairing welcome

# Linux（以 root 安装）
sudo /usr/local/bin/quicktui-server pairing welcome

# Windows（PowerShell）
quicktui-server pairing welcome

按引导选择显示二维码的方式：推荐在桌面浏览器中显示；也可以直接在终端中显示，但部分终端字体可能导致二维码无法识别。手机扫不了码时，改选 Pairing text（中文界面为配对文本，见 Q.18）。

二维码出现后，在 App 中：

1. 在服务器列表点 +。
2. 选择 其他连接方式。
3. 选择 扫描二维码连接已启用增强功能的电脑，点 下一步。
4. 将摄像头对准二维码，完成配对。

Q.18 — 手机扫不了配对二维码怎么办？

改用配对文本。它和二维码携带同一个一次性配对码，只是变成了一行可以复制粘贴的文本。在电脑上运行配对向导并选择 Pairing text（中文界面为配对文本），或直接输出：

# macOS / Linux
~/.local/bin/quicktui-server pairing qrcode --text

# Windows (PowerShell)
quicktui-server pairing qrcode --text

复制以 qtpair: 开头的整行文本并传到手机上，例如在手机的 SSH 会话里复制，或使用共享剪贴板。然后在 App 中：

1. 在服务器列表中点 +。
2. 选择其他连接方式。
3. 选择粘贴配对文本，点下一步。
4. 粘贴文本后点下一步，确认后完成配对。终端复制带来的换行和多余空格会被自动移除。

和二维码一样，配对文本只能使用一次，15 分钟后过期。请勿分享。

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

先确认服务端正在运行：

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

# Linux
systemctl --user status quicktui

# Linux（以 root 安装）
systemctl status quicktui

# Windows（PowerShell）
Get-Process quicktui-server

没有运行就重启服务：

# macOS / Linux
~/.local/bin/quicktui-server service restart

# Linux（以 root 安装）
sudo systemctl restart quicktui

# Windows（PowerShell）
quicktui-server service restart

服务在运行但仍然被拒绝时，请确认防火墙、VPN 或隧道放行了服务端端口（默认 8022）。

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

可以。任选一种方式，让手机能访问到你的电脑：

QuickTUI Cloud 中转

无需任何网络配置。每个账号每月有免费中转流量，经常使用可订阅 QuickTUI Cloud。

VPN

例如 Tailscale，手机和电脑处在同一个虚拟网络里即可直连。

隧道或反向代理

例如 Cloudflare Tunnel 或带 TLS 的反向代理，指向 http://127.0.0.1:8022，然后在 App 里填写公网 HTTPS 域名（不带 :8022）。

配对码、设备登录和你的所有操作都在端到端加密隧道里传输，即使直接开放 8022 端口，别人也无法窃听内容或冒充你的电脑。不过直接开放时，外界能看到这里运行着 QuickTUI 及其版本号等少量信息，大量恶意连接也可能让你自己的设备暂时连不上，所以更推荐上面几种方式。

通过隧道或反向代理配对时，先把 QuickTUI 服务端更新到最新版，再生成带公网地址的配对二维码：

# macOS / Linux
~/.local/bin/quicktui-server pairing qrcode --public-url https://your.domain

# Windows（PowerShell）
quicktui-server pairing qrcode --public-url https://your.domain

隧道或反向代理需要保留原始 Host 请求头，并发送 X-Forwarded-Proto；Cloudflare Tunnel 默认两者都满足。如果你的代理不发送该请求头，还需要把 QuickTUI App 更新到最新版。

Cloudflare Tunnel、HTTPS 反向代理（nginx、Caddy）和路由器端口转发的详细设置步骤，见远程访问指南。

配对二维码短期有效，请勿泄露。

Q.21 — App 提示「需要本地网络访问权限」。

iPhone 和 iPad 默认不允许 App 访问局域网内的设备。打开 设置 → 隐私与安全性 → 本地网络，打开 QuickTUI，然后回到 App 重试。服务器同时绑定了 QuickTUI Cloud 中转并使用自动模式时，App 会先通过中转连接。

Q.22 — 在家能连上，出门就连不上。

App 使用的是局域网地址（例如 192.168.1.10 这样的 IP 或 .local 主机名），只在和电脑同一个网络时有效。先设置在任何地方都能访问的方式（见 Q.20），再在这台电脑的编辑服务器页面修改地址，不需要重新配对。

Q.23 — 用了 Tailscale 还是连不上。

1. 确认 iPhone 上的 Tailscale 已连接，并且没有同时开启其他 VPN；iOS 同一时间只能开一个 VPN。
2. 确认电脑上的 Tailscale 已登录同一个账号。
3. 地址使用 http://，端口 8022。
4. 如果用的是电脑的 Tailscale 名字（例如 my-mac），改用 100.x.y.z 地址试试。如果能连上，说明 Tailscale 管理后台没有开启 MagicDNS。
5. 如果 tailnet 设置了访问控制，需要允许手机访问电脑的 TCP 8022 端口。

在中国大陆，Tailscale 不自建 DERP 中转服务器时可能非常慢，通常改用 QuickTUI Cloud 中转更合适。

Q.24 — 用主机名连不上，用 IP 地址能连上。

手机没能解析这个主机名。请检查：

1. 使用以 .local 结尾的名字，例如 my-mac.local。Mac 上可以在 系统设置 → 通用 → 共享 底部的本地主机名中查看。
2. 确认手机和电脑在同一个网络，并且 QuickTUI 有本地网络权限（见 Q.21）。
3. Linux 电脑需要运行 Avahi（mDNS）。Ubuntu 桌面版默认自带；服务器版需安装 avahi-daemon。
4. 手机通常无法解析 Windows 主机名，请改用 IP 地址或 Tailscale 地址。

Q.25 — App 提示此设备与服务器的配对已失效。

这台设备在电脑上被撤销了配对，或者服务端身份已通过 pairing identity rotate 更换。打开这台电脑的编辑服务器页面，点重新配对并扫描新的二维码（见 Q.17），或粘贴新的配对文本（见 Q.18）。

Q.26 — 通过隧道或反向代理连接时，App 显示 HTTP 状态码。

App 无法通过隧道或反向代理读取服务端能力信息。404 通常表示代理没有把根路径下的所有请求转发给服务端；502 或 503 通常表示代理连不上服务端，或服务端没有运行。隧道和代理需要满足的条件见远程访问指南。

Q.27 — QuickTUI 如何认证设备？

QuickTUI 通过设备配对来认证，全程端到端加密：

配对时

配对二维码里包含一次性配对码和电脑的身份指纹。配对码 15 分钟内有效、只能用一次，而且只在加密通道里传输。App 会记住电脑的身份，之后只连接身份一致的电脑，别人无法冒充。

设备密钥

每台手机在配对时生成自己的密钥，私钥保存在系统安全存储里（iPhone 的安全隔区或钥匙串，Android 的 Keystore），不会离开手机。

每次连接

App 先核对电脑身份，再用设备私钥证明自己是已配对的设备，双方为这次连接协商出全新的加密密钥。终端、文件、端口转发等所有数据都经过加密，并有防重放保护。

经 QuickTUI Cloud 中转时

中转服务只转发加密后的数据，看不到内容，也无法冒充任何一方。唯一的例外是推送通知：开启后，中转服务在投递时会短暂看到通知文字。

撤销设备

手机丢失或不再使用时，在电脑上撤销它：

# 列出已配对设备
~/.local/bin/quicktui-server pairing devices list

# 撤销指定设备
~/.local/bin/quicktui-server pairing devices revoke <设备 ID>

撤销后，该设备最迟 5 分钟内被断开，之后无法再连接。Windows 请在 PowerShell 中运行同样的命令，以 quicktui-server 开头。

会话

Q.28 — 工作区列表是空的。

列表显示电脑上所有已启用后端（Herdr、tmux 或两者）中的工作区。列表为空时，点右上角 [+] 新建一个工作区；有多个后端可用时，会先让你选择后端。

服务端会在需要时自动启动 Herdr 或 tmux。App 提示「服务器已连接，但没有可用的会话后端」时，说明电脑上还没有 Herdr 或 tmux，请先安装其中一个（见 Q.04 与 Q.05），再重启服务。

推荐使用 Herdr。它与 Agent 的集成更好、性能更出色，也是安装器在两者都没有时默认安装的后端。Herdr 与 tmux 同时可用时，服务端默认使用 Herdr（见 Q.31）。

在电脑上已有的工作区会自动出现在列表中：在本机 Herdr 中新建的工作区，刷新列表后即可看到；tmux 会话也一样，例如：

tmux new-session -s mysession

Q.29 — App 提示没有可用的会话后端，或显示后端错误。

说明服务端找不到可用的 tmux 或 Herdr，或者无法启动它们。按以下顺序排查：

1. 确认电脑上已安装 Herdr 或 tmux，安装方法见 Q.04 与 Q.05。 App 提示「服务器已连接，但没有可用的会话后端」时，也可以直接点安装 Herdr或安装 tmux（Windows 上只能安装 Herdr），由服务端自动安装，完成后 App 会自动重新连接。
2. 在电脑上运行 doctor，查看 tmux、Herdr 与各 Agent 的查找结果：

   ~/.local/bin/quicktui-server doctor

3. 如果在配置文件中设置了 tmux_bin 或 herdr_bin，确认它们是指向真实程序的绝对路径；tmux 需要 3.2 及以上版本。修改后重启服务。
4. 仍未解决时，查看服务端日志，见 Q.11。

Q.30 — App 提示「工作区已经关闭」。

正在打开的工作区已不存在。常见原因是工作区在电脑上被关闭，或 tmux / Herdr 重启过，原来的工作区标识随之失效。返回列表，重新选择或点 [+] 新建工作区即可。

服务端正在升级或重启时也可能短暂出现，稍等片刻重新连接即可。

Q.31 — QuickTUI 支持 Herdr 吗？

支持。tmux 与 Herdr 都是会话后端，可以同时启用。服务端每次启动时会自动检测电脑上的 tmux 与 Herdr 并启用它们；Herdr 可用时默认使用 Herdr。安装 Herdr 后重启服务，它就会出现在 App 中：

# macOS / Linux
~/.local/bin/quicktui-server service restart

# Linux（以 root 安装）
sudo /usr/local/bin/quicktui-server service restart

# Windows（PowerShell）
quicktui-server service restart

除 tmux 与 Herdr 外，QuickTUI 也支持 Luvus 后端，它不会被自动检测，需要在配置文件的 session_backends 中手动加入 luvus 并设置 luvus_bin。需要更改默认后端时，编辑配置文件中的 session_backend，详见安装指南的配置文件。Windows 始终使用 Herdr；原生 Windows 与 ARM64 电脑上的 Herdr 尚未完成全面验证。

Q.32 — 在 tmux 中运行 Agent 后，回滚历史出现重复或错位的文字。

Claude Code、Codex 等 Agent 使用全屏界面。如果它在终端的主屏幕而不是备用屏幕（alternate screen）上绘制，每次重绘都会写进 tmux 的回滚历史，表现为重复或错位的文字。解决方法是让 Agent 改用备用屏幕：

• Claude Code：运行 /tui fullscreen（v2.1.89 及以上）。要对所有会话默认生效，在 ~/.claude/settings.json 的 env 小节中加入 CLAUDE_CODE_NO_FLICKER，文件已有其他内容时合并进去即可：

  {
    "env": {
      "CLAUDE_CODE_NO_FLICKER": "1"
    }
  }

• Codex：由配置项 tui.alternate_screen 控制（默认 auto）。如果设成了 never，在 ~/.codex/config.toml 中改为 always：

  [tui]
  alternate_screen = "always"

• Grok Build：在 ~/.grok/pager.toml 中设置 alt_screen = "always"。
• Pi：在 /settings 中从普通模式切换到全屏模式。
• aider：默认使用备用屏幕，检查启动参数（如 --no-fancy-input）是否关闭了它。

已经写进回滚历史的内容可以清除：

tmux clear-history

如果 Claude Code 或 Codex 的配置文件没有开启全屏模式，App 会在打开终端时显示提示横幅，见 Q.33 和 Q.34。

Q.33 — App 提示 Claude Code 未开启全屏模式。

服务端每小时读取一次电脑上的 ~/.claude/settings.json（确认设置正确后改为每天一次）。如果 Claude Code 没有设置为全屏模式（使用备用屏幕），App 会在打开终端时显示这条横幅，每天最多一次。不开启全屏模式时，Claude Code 的输出在远程终端里可能重复或错位（见 Q.32）。服务端只读取该文件，不会修改它。开启全屏模式有两种方法，任选其一：

• 在 Claude Code 中运行 /tui fullscreen（v2.1.89 及以上）。
• 在 ~/.claude/settings.json 中加入 "tui": "fullscreen"，文件已有其他内容时合并进去即可：

  {
    "tui": "fullscreen"
  }

在同一文件的 env 小节中把 CLAUDE_CODE_NO_FLICKER 设为 1 也算已开启。如果 env 小节中设置了 CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN，请删除它，它会关闭全屏模式。服务端只检查 ~/.claude/settings.json，看不到在 shell 中 export 的变量或其他配置目录；这种情况下即使全屏模式已生效，也可能出现横幅，关闭即可。

Q.34 — App 提示 Codex 未开启全屏模式。

服务端每小时读取一次电脑上的 ~/.codex/config.toml（确认设置正确后改为每天一次）。如果 [tui] 下的 alternate_screen 为 never，Codex 会在主屏幕上绘制，输出在远程终端里可能重复或错位（见 Q.32），App 会在打开终端时显示这条横幅，每天最多一次。服务端只读取该文件，不会修改它。请把该设置改为 always，或删除这一行以使用默认值 auto：

[tui]
alternate_screen = "always"

启动参数 --no-alt-screen 也会在本次运行中关闭全屏模式，启动 Codex 时不要传入它。

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

这是终端颜色查询的回包被当成了输入。某些终端应用启动时会查询终端背景色，如果回包没有被正确处理，就会显示在输入框里。App 检测到这种情况时，会显示「检测到终端颜色回包泄漏」提示。

解决方法是在该应用中设置固定主题，不再查询终端颜色，例如在 Claude Code 中运行 /theme 选择一个具体主题。

如果同一个 tmux 会话还被其他终端同时连接，这些终端也可能产生回包，可以先断开它们再观察。

Q.36 — 终端里的文字显示错乱。

服务端为会话设置的 TERM 默认为 xterm-256color，电脑缺少对应 terminfo 时会自动回退。如果你修改过 term 配置（例如改成 xterm-ghostty），而电脑上的 tmux 不支持它，就可能出现渲染错乱。改回默认值即可，服务会自动重启：

~/.local/bin/quicktui-server config set --term xterm-256color

Herdr 后端始终使用 xterm-256color，不受此配置影响。

Q.37 — Agent 向导中某个 Agent 名字显示为警告颜色。

服务端找不到这个 Agent 的可执行文件。服务端以后台服务运行，它的 PATH 可能与你的登录 shell 不同。先运行 doctor 查看它检查了哪些位置：

~/.local/bin/quicktui-server doctor

然后在配置文件的 [agent_bins] 中写上 Agent 的完整路径（例如用 which claude 查到的路径），再重启服务：

[agent_bins]
claude = "/opt/homebrew/bin/claude"

Q.38 — App 中看不到 Agent 的实时状态。

Agent 状态来自安装器为各 Agent 添加的 hooks。Codex 需要在 Codex CLI 中运行 /hooks 信任它们；OpenCode 需要重启一次。其他情况可以重新安装 hooks：

~/.local/bin/quicktui-server hooks install

文件浏览

Q.39 — App 的文件管理器无法打开 Mac 上的桌面、文稿、下载等目录。

在 App 的文件管理器中浏览 Mac 时，打开 ~/Desktop（桌面）、~/Documents（文稿）、~/Downloads（下载）等目录会失败，App 提示「macOS 隐私设置阻止访问」。iCloud 云盘、外接磁盘和网络宗卷也可能出现同样的情况。

原因是这些目录受 macOS 隐私保护，访问前需要用户授权。QuickTUI 服务端在后台运行，macOS 不会为它弹出授权对话框，因此需要你手动为服务端开启「完全磁盘访问权限」。

解决步骤：

1. 在 App 的服务器列表中，点该服务器卡片上的 文件 图标打开文件管理器。如果显示「文件浏览已关闭」，先点 启用文件浏览。
2. 在 Mac 上打开 系统设置 → 隐私与安全性 → 完全磁盘访问权限（macOS 12 及更早版本为 系统偏好设置 → 安全性与隐私 → 隐私 → 完全磁盘访问权限）。
3. 点列表下方的 +，按提示输入 Mac 登录密码或使用触控 ID。
4. 在文件选择窗口中按 ⌘⇧G，输入 ~/.local/bin/quicktui-server 并回车，选中 quicktui-server 后点 打开。.local 是隐藏目录，直接在访达中浏览看不到，请用路径输入的方式。
5. 确认列表中出现 quicktui-server，并且右侧开关已打开。
6. 回到 App，点提示中的 已授权, 重测，重新检查访问权限。
7. 仍然无法访问时，在 Mac 上重启服务后再试：

   ~/.local/bin/quicktui-server service restart

升级或重新安装服务端后，程序文件会被替换。如果再次出现无法访问的情况，在「完全磁盘访问权限」中先移除 quicktui-server，再按上面的步骤重新添加。

Q.40 — Linux 上文件浏览提示 permission denied 或 403。

按以下几种原因排查：

文件浏览未开启

先在 App 中开启文件浏览。

在主目录以外修改文件

出于安全考虑，编辑、上传、新建、重命名和删除只允许在服务端运行用户的主目录内进行；主目录以外只能读取。root 安装的主目录为 /root。

系统权限不足

服务端以安装时的用户身份运行（root 安装为 root），只能访问该用户有权限的文件。

检查路径上每一级目录的权限与 ACL：

namei -l /path/to/file
getfacl /path/to/file

把服务端运行用户加入新的用户组后，需要重启服务才能生效：

~/.local/bin/quicktui-server service restart

启用了 SELinux 时，可用 getenforce 和 sudo ausearch -m AVC -ts recent 查看是否有拦截记录。

通知

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

Agent 通知需要服务端已绑定 QuickTUI Cloud 中转，并且 Agent hook 已安装。通知由服务端经 QuickTUI Cloud 转交 Apple 或 Google 的推送服务投递到手机。

默认情况下，通知只包含事件类别，例如「Agent 需要审批」「任务已完成」「Agent 出错」「会话已结束」，不含项目名、会话名或任务内容。可选开启的附加内容包括 Agent 类型、项目名、会话标识和任务或错误摘要。通知不会包含完整的终端输出、源代码或凭据。

要停止接收通知，在 iPhone 或 Android 的系统设置中关闭 QuickTUI 的通知权限即可。

App

Q.42 — 有 Android 版吗？

有，目前处于预览阶段。从 GitHub 下载 APK 安装，支持 Android 8.0 及以上，和 iPhone、iPad 版使用同一个服务端。预览期间全部功能免费。下载、安装与更新见 QuickTUI Android 应用（Preview）。