AI 编程 Agent
在 Mac 上跑，
你在手机上控。

QuickTUI 需要 tmux 3.2 或更高版本。安装脚本可自动为你安装 — 优先使用系统包管理器（brew、apt、yum、dnf），否则下载预编译包解压到 ~/.local/tmux。

当服务 PATH 找不到 tmux 时，安装脚本会保存 QUICKTUI_TMUX_BIN。

服务会读取 ~/.config/quicktui/config — 手动启动的 quicktui-server 进程不会自动读取。

键：QUICKTUI_TOKEN、QUICKTUI_ADDR（默认 0.0.0.0:8022）、QUICKTUI_TERM（默认 xterm-256color）、QUICKTUI_LANG（默认 en_US.UTF-8），可选 QUICKTUI_TMUX_BIN。

编辑后重启服务：

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

# Linux
systemctl --user restart quicktui

两条路径：

重新运行安装脚本 — 原子替换、失败回滚、配置保留。

服务端自更新 — 使用缓存发布检查、下载当前平台二进制、替换可执行文件。自更新不会自动重启；可在 App/浏览器重启、调用 POST /v2/api/restart，或重启系统服务。

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

查看状态：

quicktui-server --check-upgrade

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

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

服务方式：确保 ~/.config/quicktui/config 存在且包含：

QUICKTUI_TOKEN=…

手动启动：传入 --token 或在环境中设置 QUICKTUI_TOKEN — 普通启动不会自动读取配置文件。

先检查服务：

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

# Linux
systemctl --user status quicktui

若跳过了服务注册，用相同的 token 和地址手动启动服务端。若服务已在运行，请确认防火墙或隧道放通了 QUICKTUI_ADDR 对应的端口。

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

改用广泛支持的 TERM。在 ~/.config/quicktui/config 中配置：

QUICKTUI_TERM=xterm-256color

然后重启服务。手动启动命令则用：

--term xterm-256color

服务端无法启动或附加 tmux。查看日志：

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

# Linux
journalctl --user -u quicktui -f

若设置了 QUICKTUI_TMUX_BIN，必须是指向真实 tmux 二进制的绝对路径。也请确认 QUICKTUI_TERM 与 QUICKTUI_LANG 有效。

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

# Linux
journalctl --user -u quicktui -f

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

服务方式：编辑 ~/.config/quicktui/config 中的 QUICKTUI_ADDR，然后重启。

手动方式：

quicktui-server --addr 0.0.0.0:9000

安装时：

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

安装脚本接受 IPv4 地址或主机名，不接受 IPv6 字面量。

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

停止服务并卸载它所管理的服务端。

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，授权弹窗永远不会显示，系统会静默拒绝直到用户手动加白名单。

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 也可能拦截。用 ausearch -m AVC -ts recent 或 getenforce 检查。临时测试用 setenforce 0（生产环境不要长期 permissive）。
• 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。

QuickTUI 显示当前 tmux 会话。若尚无会话，从 App 或浏览器点 New Session 创建，或在服务器上运行：

tmux new-session -s mysession

现象。在 tmux pane 里使用 Claude Code（或同类 TUI 工具如 OpenAI Codex CLI、aider）一段时间后，向上滚动 tmux 历史会看到重复的帧、错位的列，或旧渲染的碎片。重启 QuickTUI 服务端 不能 让桌面 tmux 自愈，只有 tmux clear-history 才能清掉。

原因。Claude Code 的 TUI 基于 Ink 渲染库。当渲染区域超过 viewport（或满屏重绘时），Ink 的 render loop 会在 主屏 上发送 CSI 3 J（"擦除滚动条历史"）并重绘整屏 — 且没有 DECSET 2026（同步输出）包裹。tmux 把这些半截帧写进 pane scrollback。后续每次 SIGWINCH / 改尺寸会再叠加一份。上游 issue：

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

解决方法。用 fullscreen 模式跑 Claude Code — 切到 alternate screen buffer（和 vim / htop 一样），完全不动 scrollback。需要 Claude Code v2.1.89+：

/tui fullscreen

v2.1.89 — v2.1.109 版本用环境变量代替：

CLAUDE_CODE_NO_FLICKER=1 claude

清掉已经污染的 scrollback。烂字节已经在 tmux 内存里，只能整段清掉：

tmux clear-history

然后用 fullscreen 模式重启 Claude Code 防止再次发生。QuickTUI 客户端在你选择运行了 Claude Code（或其他已知 main-screen TUI 工具）的 pane 时也会弹一条提示条。

现象。多个客户端（比如本地终端加上 QuickTUI App 或浏览器）同时 attach 同一个 tmux session 时，终端应用的输入框会反复出现类似 11;rgb:2828/2c2c/3434 的乱码，有时连续好几条。

原因。部分终端应用会通过发送 OSC 10/11/12 转义查询（"当前前景色 / 背景色 / 光标色是什么"）来自动探测配色主题。tmux 把查询转发给最外层终端，再把对方的回包路由回 pane。当多个客户端同时 attach 时，回包可能在应用为这次查询打开的解析窗口关闭之后才到达，于是应用把这些原始转义字节当成了普通按键，直接塞进了自己的输入框。这是终端应用侧的 bug，与 QuickTUI 无关 — 例如 Claude Code 就有对应的 #12910 — OSC terminal color query responses leak into input buffer。

解决方法。

1. 把受影响的应用改成固定主题，不用自动探测。Claude Code 里运行 /theme，选一个固定的浅色或深色值。
2. 其他 TUI 工具同理，关闭自动终端配色 / 主题检测。
3. 可选：在 ~/.tmux.conf 里加一行，降低转义序列被拆片误判的概率：

   set -s escape-time 100

你在安装时设定的密钥 — 用于保护服务器不被未授权访问。在服务器上查看：

cat ~/.config/quicktui/config

首次在 App 或浏览器登录时按提示输入。

这是服务端返回的消息 — tmux 会话已关闭或被重命名，或 tmux 服务本身未运行。

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