q quicktuiv1
iOS 应用iOS → Android 应用Android →

安装

在电脑上安装 QuickTUI 服务端

QuickTUI 服务端运行在你自己的电脑上，为手机端接入 tmux 或 Herdr 中的会话，双方通信全程端到端加密。本页介绍服务端的安装与升级、设备配对、配置、命令行与卸载。

安装与升级

方式一：App 设置向导（推荐）

适用于可以通过 SSH 登录的 Mac 或 Linux 电脑，全部操作在手机上完成。

  1. 在 iPhone 或 iPad 上从 App Store 安装 QuickTUI，或安装 Android 应用（Preview）。首次打开时会自动进入设置向导；之后添加电脑，在服务器列表点 +。
  2. 选择 通过 SSH 连接并启用增强功能（推荐），点 下一步。
  3. 填写电脑的地址、端口和用户名，选择密码或 SSH 密钥登录。点 测试连接，连接成功后点 下一步。
  4. 选择安装源（Global 或中国，默认与手机所在地区一致），点 安装。App 会通过 SSH 登录电脑安装服务端，并自动完成配对。

SSH 密码和密钥仅用于本次安装，App 不会保存。

方式二：手动安装

适用于无法通过 SSH 登录的 Mac / Linux 电脑，或希望自行安装的情况。Windows 电脑请改用 Microsoft Store。在电脑上运行对应的命令：

Global · macOS / Linux

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

中国镜像 · macOS / Linux

curl -fsSL https://dl.quicktui.cn/q.sh | sh

命令会根据系统和 CPU 架构通过 HTTPS 下载对应的安装器并运行。安装器会安装服务端、写入配置、为 Agent 添加 hook、注册并启动后台服务，最后引导你配对设备（见配对设备）。

如果电脑上已有 tmux 或 Herdr，安装器会直接使用；两者都没有时，会从 Herdr 官方源安装 Herdr。安装器不会安装 tmux。Herdr 下载失败时只给出警告，服务端安装照常完成；自行安装 Herdr 后重新运行安装命令即可。

安装源：Global 与中国镜像

两个安装源提供相同的安装器与服务端，中国用户使用镜像下载更快。镜像只分发 QuickTUI 自身的文件，Herdr 始终从其官方源下载。

服务端之后的自动更新会沿用安装时的安装源。如需切换，用另一个安装源的命令重新安装一次。在 App 中升级服务端时，也可以为单次升级选择下载源。

覆盖安装（升级）

重新运行安装命令，或在 App 中对同一台电脑再次运行设置向导，即可覆盖安装：

也可以由服务端自行升级：

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

安装位置

macOS
二进制：~/.local/bin/quicktui-server
配置目录：~/.config/quicktui-server-v2/
后台服务：LaunchAgent ai.quicktui
Linux（普通用户）
二进制：~/.local/bin/quicktui-server
配置目录：~/.config/quicktui-server-v2/
后台服务：systemd 用户服务 quicktui
Linux（root）
二进制：/usr/local/bin/quicktui-server
配置目录：/root/.config/quicktui-server-v2/
后台服务：systemd 系统服务 quicktui
Windows
应用：Microsoft Store 中的 QuickTUI Server，命令为 quicktui-server
配置目录：%USERPROFILE%\.config\quicktui-server-v2\
后台服务：启动应用 QuickTUI Server

在 macOS 和 Linux 上，安装器不会修改 PATH 或 shell 配置。~/.local/bin 不在 PATH 中时，需要用完整路径运行 quicktui-server，因此下文命令均使用完整路径。

在 Linux 上以 root 运行安装命令时，会安装为系统服务：开机自动启动，不依赖用户登录，并以 root 身份运行。同一台机器上 root 安装和普通用户安装的是两个独立实例，请勿混用各自的配置、服务或程序；已经混用时，参见 FAQ Q.14 修复。

Linux 普通用户安装：请开启 linger，否则退出登录后服务端会停止。

systemd 用户服务默认随用户登录会话启停。关闭 SSH 连接或退出桌面登录后，服务端可能随之停止，手机将无法连接。根据情况选择对应的命令：

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 安装的系统服务不受此影响。

Windows：Microsoft Store

在 Windows 上，从 Microsoft Store 安装 QuickTUI Server：

  1. 安装 Herdr。Windows 上的会话运行在 Herdr 中，Store 应用不会自动安装它： 
    powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"
  2. 从 Microsoft Store 获取 QuickTUI Server 并安装。
  3. 从开始菜单打开 QuickTUI Server。首次打开会在后台启动服务端、开启登录时自动启动，并打开配对引导（见配对设备）。

首次请从开始菜单打开：在终端里直接运行 quicktui-server 不会开启登录时自动启动。不想让它登录时启动，可在任务管理器的「启动应用」中关闭 QuickTUI Server。

Microsoft Store 会自动更新服务端，因此 Windows 上不能使用 upgrade install。在 PowerShell 中以 quicktui-server <命令> 运行命令，例如 quicktui-server pairing welcome。服务端首次监听端口时，Windows 可能询问是否允许其通过防火墙。

之前用 PowerShell 安装脚本安装过？首次打开 Store 应用时会移除旧的计划任务或启动项，并停止旧的服务端。已配对的设备和配置都会保留，无需重新配对。如果旧计划任务由管理员创建，应用会提示你在管理员 PowerShell 中运行 schtasks /Delete /TN QuickTUI /F 删除它。之后可以删除旧的 %LOCALAPPDATA%\QuickTUI\quicktui-server.exe。

Windows 与 Herdr

服务端按以下顺序查找 Herdr：配置文件中的 herdr_bin、环境变量 QUICKTUI_HERDR_BIN、PATH、Herdr 官方安装位置。如需使用自己安装的 Herdr，将 herdr_bin 设为其完整路径，再运行 quicktui-server service restart。

原生 Windows 运行与 ARM64 电脑上的 Herdr 尚未完成全面验证，如遇问题欢迎反馈。

安装命令的用法

在 macOS 和 Linux 上，安装脚本的完整写法是「命令 + 参数」：

curl -fsSL https://quicktui.ai/q.sh | sh -s -- <命令> [参数]

不写命令时默认执行 install，安装当前正式版服务端，无需指定通道。

命令

install
安装服务端，已安装时覆盖安装
check
检查运行时依赖，不安装任何内容
prepare
只安装缺失的依赖，不安装服务端
uninstall
移除后台服务与 Agent hook（见卸载），不接受参数
help
显示帮助

install 的参数

--channel preview
安装预览版服务端
--tag <tag>
安装指定的发布版本
--server <绝对路径>
安装本地的服务端二进制文件
-y, --yes
以非交互方式安装，不打开配对引导
--addr <地址>
监听地址：主机、host:port 或 http(s)://host:port；只写主机时端口为 8022。默认 0.0.0.0:8022。IPv6 需加方括号并带端口，如 [::1]:9000
--port <端口>
只修改监听端口（默认 8022）；不能与已带端口的 --addr 同时使用
--term <值>
会话的 TERM（默认 xterm-256color），仅对 tmux 后端生效
--lang <值>
会话的 LANG（默认 en_US.UTF-8），仅对 tmux 后端生效
--no-service
不注册后台服务，也不打开配对引导；仍会安装服务端、写入配置并更新 hook

--channel、--tag、--server 只能指定其一。例如，以非交互方式安装并监听 9000 端口：

curl -fsSL https://quicktui.ai/q.sh | sh -s -- install -y --port 9000

check 与 prepare 的参数

--server <绝对路径>
检查或准备指定的本地服务端二进制。省略时使用已安装的服务端；尚未安装时，临时下载并校验当前正式版服务端，用完即删除

配对设备

每台手机或平板需要分别配对。通过设置向导安装时会自动完成配对；手动安装或添加新设备时，按以下步骤操作。

手动安装完成后，安装器通常会直接打开配对引导。使用了 -y 或 --no-service、未在交互终端中运行，或电脑已有配对设备时，不会自动打开。在 Windows 上，每次从开始菜单打开 QuickTUI Server 都会打开配对引导。其他情况请手动执行以下步骤。

第一步：在电脑上显示配对二维码

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

# Windows（PowerShell）
quicktui-server pairing welcome

按引导选择显示方式。推荐在浏览器中显示；也可以直接在终端中显示，但部分终端字体可能导致二维码无法识别。手机扫不了二维码时，选择 Pairing text（中文界面为配对文本）：引导会输出一行文本，复制后粘贴到 App 中即可。

第二步：在 App 中扫码

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

使用配对文本时，第 3 步改选 粘贴配对文本，粘贴整行文本后点 下一步。从终端复制带来的换行和多余空格会被自动移除。

二维码包含一次性配对码，有效期 15 分钟，使用后立即失效。有效期内任何人扫描都可以完成配对，请勿分享或公开。配对文本携带同一个配对码，规则相同。

也可以跳过引导，用 pairing qrcode 直接生成二维码，可选参数如下：

运行 pairing addresses 可查看可用的网络地址。

已配对的设备可以随时查看和撤销：

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

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

设备撤销后立即无法建立新连接，已有连接会在 5 分钟内断开，需重新配对才能继续使用。如需一次性移除所有设备，使用 pairing identity rotate：它会更换服务端身份并清空全部配对，运行前需先停止服务。

配置文件

配置保存在配置目录下的 config.toml 中，采用 TOML 格式，目录位置见安装位置。macOS 同样位于 ~/.config，而非 ~/Library。大多数命令支持用 --config <路径> 指定其他配置文件，服务端的其他数据会存放在该文件所在目录。

服务端仅在启动时读取配置，手动修改后需重启服务使其生效：

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

常用配置项也可以通过 config set 修改，该命令会自动重启服务：

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

服务端运行时只读取配置文件，不读取 QUICKTUI_* 环境变量。这类环境变量仅在安装时生效，由安装器写入配置文件。

配置项

addr
监听地址 host:port。写成 http(s):// 形式时会去掉前缀，服务端始终监听明文 HTTP，所有配对后的流量在端到端加密隧道内默认值：0.0.0.0:8022
session_backend
默认会话后端：tmux、herdr、luvus、shell，必须包含在 session_backends 中默认值：启用列表中有 Herdr 时为 herdr，否则为第一个启用的后端
session_backends
启用的后端，逗号分隔。自动检测只添加不删除；手动修改后不再自动检测，清空 session_backend、session_backends、session_backends_auto 可恢复自动检测默认值：每次启动时按检测到的 tmux / Herdr 自动补充
term
会话的 TERM；对应 terminfo 不存在时回退到 xterm-256color默认值：xterm-256color
lang
会话的 LANG；该 locale 不存在时回退到 C.UTF-8默认值：en_US.UTF-8
tmux_socket
tmux 服务器 socket 的绝对路径；默认与你自己的 tmux 共用同一个服务器默认值：$TMUX_TMPDIR 或 /tmp 下的 tmux-<uid>/default
tmux_bin
tmux 可执行文件的绝对路径；无效时给出警告并重新查找默认值：自动查找
herdr_bin
Herdr 可执行文件路径默认值：自动查找
herdr_client_retention
终端释放后保留 Herdr 客户端的时长（Go 时长格式），0 表示不保留默认值：5m
luvus_client_retention
终端释放后保留 Luvus 客户端的时长（Go 时长格式），0 表示不保留默认值：5m
luvus_bin
Luvus 后端的可执行文件路径默认值：无
tmux_env_<名称>
在会话中设置环境变量 <名称>（自动转为大写），如 tmux_env_editor = "vim"默认值：无
tmux_env_unset
在会话中移除的环境变量，逗号分隔默认值：无
[agent_bins]
按 Agent 指定可执行文件路径的表，如 claude = "/abs/path/claude"默认值：无
trusted_proxies
受信任的反向代理 IP / CIDR，逗号分隔；只信任这些地址转发的来源头默认值：空
files_enabled
是否开启文件浏览，通常在 App 里切换默认值：false
update_channel
自动更新通道：server2 或 preview默认值：安装时写入
update_region
更新下载区域：global 或 cn默认值：按更新清单地址判断
update_manifest_url
更新清单地址，由安装源决定默认值：内置地址
releases
发布文件下载地址，由安装源决定默认值：内置地址
log_level
日志级别：info、debug（增加调试日志）或 verbose（增加更详细的日志）默认值：info
debug_categories
输出调试日志的类别，例如 ["WS", "TMUX"]；留空或 * 表示全部类别默认值：全部类别

键名须为小写。文件中的 session_backends_auto、tmux_bin_auto、herdr_bin_auto 由服务端自动维护，请勿手动修改。旧版的 token 已废弃，服务端会自动移除。

配置目录中的其他文件

pairing_auth.json
已配对设备与配对凭据
e2e_identity.json
服务端的端到端加密身份，pairing identity rotate 会替换它
relay.json
relay_registration_identity.json
QuickTUI Cloud 中转绑定与注册身份
herdr-sids.json
session-sids.json
session-default-cwd.json
会话 ID 与新会话默认工作目录
agent-wizard*.json
从 quicktui.ai 下载的 Agent 启动配置及其签名缓存
agentbridge2/
Agent 状态数据与各 Agent 的 hook 启用设置
*.lock
写入配置、配对与身份时使用的锁文件

日志位置：macOS 位于 ~/Library/Logs/QuickTUI/；Linux 用以下命令查看：

# 普通用户安装
journalctl --user -u quicktui

# root 安装
journalctl -u quicktui

安装后添加的 hook 与服务

Agent hook

各 Agent 配置中的 hook 会把 Agent 事件（例如等待审批、任务完成或出错）报告给服务端，服务端据此发送 Agent 通知（见 FAQ Q.41）。安装器会为以下 Agent 添加 hook：

Claude Code
添加会话开始 / 结束、提交提示词、通知、停止、工具调用前后、权限请求等事件的 hook修改的文件：~/.claude/settings.json（设置了 CLAUDE_CONFIG_DIR 时在该目录下）
Codex
添加 hook，并清理旁边 config.toml 中 QuickTUI 的旧条目。需要在 Codex CLI 里用 /hooks 信任后才会生效修改的文件：~/.codex/hooks.json（或 CODEX_HOME 下）
Grok
QuickTUI 独占的 hook 文件修改的文件：~/.grok/hooks/ab2.json（或 GROK_HOME 下）
OpenCode
插件文件，不修改 opencode.json；可能需要重启 OpenCode 才会加载修改的文件：~/.config/opencode/plugins/agentbridge2.js（或 OPENCODE_CONFIG_DIR 下）

每个 hook 都运行 quicktui-server ab2hook --agent <名称>，将 Agent 事件记录并转交给服务端。hook 出错时会静默退出，不影响 Agent 运行。QuickTUI 只修改自己添加的条目，不会改动你已有的 hook。

每次运行安装器或启动服务端时，都会更新 hook 使其指向当前服务端，并清理旧版 hook。可用以下命令关闭或重新开启：

# 关闭并移除所有 Agent 的 hook，之后不再自动添加
~/.local/bin/quicktui-server hooks uninstall

# 重新开启，并为所有 Agent 安装 hook
~/.local/bin/quicktui-server hooks install

service uninstall 同样会移除 hook，但保持开启状态，下次安装或启动服务端时会重新添加。

后台服务

macOS
~/Library/LaunchAgents/ai.quicktui.plist 与启动脚本 ai.quicktui.sh，登录后自动启动并保持运行
Linux（普通用户）
systemd 用户服务 ~/.config/systemd/user/quicktui.service，已启用
Linux（root）
systemd 系统服务 /etc/systemd/system/quicktui.service，开机自启
Windows
Microsoft Store 应用自带的启动应用 QuickTUI Server，首次从开始菜单打开应用时启用；可在任务管理器的「启动应用」中管理

重启服务不会结束 tmux 会话。除上述内容外，安装器不修改其他系统配置，包括 .bashrc、.zshrc 与 PATH。Linux 普通用户安装的服务需要开启 linger 才能在退出登录后继续运行，见上文。

命令行参数

quicktui-server 没有全局参数，参数均属于各个子命令。任意命令加 -h 或 --help 可查看帮助；标有 [--config] 的命令可指定配置文件。

serve
前台运行服务端（后台服务运行的就是它）。参数：--config、--debug-addr <地址>（临时覆盖监听地址）、--term、--lang、--tmux-socket、--log-level、--debug-categories
pairing welcome [--config]
配对引导
pairing qrcode [--config]
显示配对二维码，参数见配对设备
pairing addresses [--config]
列出可写入二维码的网络地址
pairing relay --site global|cn [--config] [--replace-relay]
经 QuickTUI Cloud 中转配对设备：在主机上运行，在 App 中输入主机显示的配对码，再在主机上批准
pairing devices list [--config]
列出已配对设备
pairing devices revoke <设备 ID> [--config]
撤销设备
pairing identity rotate [--config]
更换服务端身份并清空全部配对，需先停止服务
upgrade check [--config]
检查是否有新版本
upgrade install [--config] [--channel server2|preview]
升级服务端并重启服务；带 --channel 时切换通道。Windows 不支持，由 Microsoft Store 负责更新
service install
注册后台服务，参数同 serve，传入的参数会写入配置文件
service uninstall [--config]
移除后台服务与 Agent hook
service restart
刷新服务定义并重启服务
hooks install [--config]
为所有 Agent 开启并安装 hook
hooks uninstall [--config]
为所有 Agent 关闭并移除 hook
config show [--config]
显示配置文件内容
config set [--config] [--addr] [--term] [--lang] [--tmux-socket]
修改配置并重启服务
config relay delete [--config]
删除 QuickTUI Cloud 中转绑定
doctor [--config]
检查 tmux、Herdr 与各 Agent 可执行文件的查找结果
version
显示版本号

installer、ab2hook、ab2ctl 与 service win-autostart 供安装器、hook 和 Windows 启动应用内部调用，无需手动运行。

卸载

在 macOS 和 Linux 上，在安装命令后加 uninstall，或直接让服务端卸载服务：

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

# 或直接运行
~/.local/bin/quicktui-server service uninstall

卸载会停止并移除后台服务，同时移除 Agent hook。服务端程序和配置目录会保留，其中包括配对记录，因此重新安装后无需重新配对。卸载仅作用于当前用户的安装，root 与普通用户的安装需分别卸载。tmux、Herdr 及其中的会话，以及你的 Agent 都不受影响。

在 Windows 上，先在 PowerShell 中停止服务端并移除 Agent hook，再到「设置 > 应用 > 已安装的应用」中卸载 QuickTUI Server。配置目录会保留，其中包括配对记录：

quicktui-server service uninstall

完全移除

  1. 关闭 Agent hook：
    # macOS / Linux
~/.local/bin/quicktui-server hooks uninstall

# Windows（PowerShell）
quicktui-server hooks uninstall
  2. 按上文卸载。
  3. 删除程序和配置目录：
    • macOS：~/.local/bin/quicktui-server、~/.config/quicktui-server-v2/、~/Library/Logs/QuickTUI/
    • Linux 普通用户：~/.local/bin/quicktui-server、~/.config/quicktui-server-v2/
    • Linux root：/usr/local/bin/quicktui-server、/root/.config/quicktui-server-v2/
    • Windows：%USERPROFILE%\.config\quicktui-server-v2\；如果之前用 PowerShell 安装脚本安装过，还有 %LOCALAPPDATA%\QuickTUI\
  4. tmux 与 Herdr 为独立安装，如不再需要，请自行卸载。

删除配置目录会同时清除配对记录，重新安装后需要重新配对所有设备。

相关链接