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

用户指南

QuickTUI 用户指南

适用于 iPhone 和 iPad 的 QuickTUI App.

关于本指南

本指南写给谁

本指南写给想用 iPhone 或 iPad 操作电脑端 AI 编程助手 (例如 Claude Code、Codex) 的用户. 你只需要:

  • 会在电脑上打开「终端」并粘贴、运行命令.
  • 知道自己电脑的用户名和登录密码.

本指南的约定

  • 粗体文字 表示 App 或电脑上的按钮、菜单、选项, 例如 下一步.
  • 代码块中多为可在电脑终端执行的命令: 复制整行粘贴至终端并回车运行. 配置文件内容或示意图会在正文中说明.
  • # 后面的文字是说明, 不用输入.
  • 「→」表示依次点按, 例如 设置 → 快捷栏.
  • 本指南用三种提示框:

提示: 能让操作更顺利的小技巧.

注意: 不注意可能导致操作失败.

警告: 不注意可能导致数据丢失或安全问题.

如何打开电脑上的「终端」

  • macOS: 打开 访达 → 应用程序 → 实用工具 → 终端. 也可以按 Command + 空格, 输入「终端」后按回车.
  • Linux: 大多数桌面系统可以按 Ctrl + Alt + T 打开.
  • Windows: 在开始菜单中搜索「PowerShell」并打开.

第 1 章 认识 QuickTUI

1.1 QuickTUI 能做什么

AI 编程助手 (本指南统称 Agent) 通常运行在电脑的终端里. 它们经常需要很长时间才能完成任务, 中途还会停下来问你问题或请你批准操作. 有了 QuickTUI, 你可以:

  • 离开电脑后, 用手机继续查看 Agent 的进度.
  • 在手机上回答 Agent 的提问、批准其操作.
  • 在手机上启动新的 Agent, 同时管理多个任务.
  • 接收 Agent 待审批与运行状态通知.

手机锁屏或断网时, Agent 会在电脑上继续工作, 不会中断.

1.2 QuickTUI 由哪几部分组成

QuickTUI 由以下几部分配合工作:

  • QuickTUI App
    装在你的 iPhone 或 iPad 上. 你在这里查看和操作.

  • QuickTUI 服务端 (QuickTUI Server)
    装在你的电脑上, 是一个在后台运行的服务程序. 它负责在电脑终端与移动设备间安全传输终端会话画面与输入数据.

  • 终端会话工具: tmux 或 Herdr
    装在你的电脑上, 是保存终端窗口的工具. 有了它, 手机断开后, 电脑上的终端和 Agent 仍会继续运行. QuickTUI 把这类工具称为「后端」.

    • Herdr: 推荐. 安装 QuickTUI 服务端时, 如果电脑上既没有 Herdr 也没有 tmux, 会自动安装 Herdr. Windows 上只支持 Herdr.
    • tmux: 老牌终端工具. 电脑上已经装了 tmux 时, QuickTUI 会自动使用它.

    一台电脑可以同时使用多个后端.

  • QuickTUI Cloud 中转 (可选)
    QuickTUI 提供的云端服务. 手机无法直连电脑时由其转发加密数据, 并负责中转 Agent 推送通知.

iPhone ─────────────────────> 你的电脑 (QuickTUI 服务端) ──> tmux / Herdr ──> Agent
   │                                  ▲
   └──> (可选) QuickTUI Cloud 中转 ───┘

1.3 你的数据是否安全

  • 手机和电脑之间的所有内容都经过端到端加密. 除通信两端设备外, 包括 QuickTUI Cloud 中转在内的任何第三方均无法查看内容.
  • 只有经过「配对」的手机才能连接你的电脑. 配对后, 手机会校验电脑身份防范仿冒; 电脑亦只允许受信任的已配对设备接入.
  • 端到端加密的唯一例外: 如果你开启了 Agent 通知, 通知摘要文本会经由 QuickTUI Cloud 中转推送至手机.

1.4 常用名词

  • 服务器: App 里的一条连接记录, 代表一台电脑. App 界面上的 服务器列表、编辑服务器 都指它. 本指南只在指 App 界面时使用这个词, 并一律加粗.

  • QuickTUI 服务端: 装在电脑上、在后台运行的程序, 英文名 QuickTUI Server, 命令是 quicktui-server. 一台电脑装一个服务端, 在 App 中对应一个 服务器.

  • 配对: 让手机成为某台电脑信任的设备. 每台想要连接这台电脑的设备都要配对一次.

  • 后端: 电脑上保存终端会话的工具, 即 tmux 或 Herdr.

  • 工作区: 一组终端窗口. 通常一个项目对应一个工作区.

  • 窗口: 工作区里的一个终端. 通常一个 Agent 占用一个窗口. 在 App 的切换器中也叫「会话」.

  • Pane (窗格): 一个窗口被分成几块时, 每一块叫一个 Pane.

  • 不同后端的叫法: 两种后端对「工作区」和「窗口」的叫法不同, 本指南统一使用「工作区」和「窗口」:

    • tmux: 工作区叫 session, 窗口叫 window. 切换器中显示为「N 个窗口」.
    • Herdr: 工作区叫 workspace (也称 space), 窗口叫 tab (标签页). 切换器中显示为「N 个标签页」.

    两种后端里, 窗口都可以再分成多个 Pane.

  • 切换器: App 中查看和切换所有工作区、窗口的面板.

  • 快捷栏: 终端界面底部放按钮和常用按键的横条. 可以叠放多条, 最下面一条叫「第一快捷栏」.

  • 输入栏: 先写好一段文字, 再一次性发给终端的输入条. 尤其适合语音输入和发送图片等附件给 Agent 的情况.

  • IP 地址: 设备在网络中的数字标识, 例如 192.168.1.10. 局域网动态分配的 IP 可能会变动.

  • 主机名: 电脑的名字, 例如 my-mac.local. 在同一个 Wi-Fi 下, 手机可以用主机名找到电脑, 不受 IP 地址变化影响.

  • Tailscale: 一个免费的组网工具. 在手机和电脑上都装好后, 手机在任何地方都能用固定的地址 (以 100. 开头) 或 Tailscale 电脑名找到电脑.

  • 端口: 区分同台电脑上不同网络服务的通道编号. QuickTUI 服务端默认使用 8022 端口.

  • SSH: 一种从别的设备登录电脑的方式. QuickTUI 可以用它在手机上帮你自动安装.

第 2 章 开始之前

请先完成下面的检查.

2.1 电脑

  • 系统是 macOS、Linux 或 Windows.
  • 你要用的 Agent 已经装好, 并且能在终端里正常运行. 例如在终端输入 claude 能启动 Claude Code. QuickTUI 不负责安装 Agent.
  • 电脑保持开机, 并且不会自动睡眠. 电脑睡眠后手机无法连接.

提示: macOS 可以在 系统设置 → 电池 (或 节能) 中, 设置接通电源时防止自动睡眠.

2.2 手机

  • 从 App Store 安装 QuickTUI.
  • 手机和电脑连在同一个 Wi-Fi 上. 第一次安装配对时这样最简单; 以后在外面使用的方法见第 4 章.

第 3 章 安装与配对

3.1 选择安装方式

按顺序选择第一个适合你的方式:

  1. 方法 A: 在手机上自动安装 (推荐)
    适用于 macOS 和 Linux 电脑. 只需在手机上填写电脑的地址、用户名和密码, App 会自动完成安装和配对.
  2. 方法 B: 在电脑上安装, 然后扫码配对
    适用于 Windows 电脑, 或者不想开启 SSH 的电脑. 手机扫不了二维码时, 也可以从电脑复制配对文本, 粘贴到 App 中完成配对.
  3. 方法 C: 经 QuickTUI Cloud 配对
    适用于手机无法直连的电脑, 例如处于公司内网或无公网 IP 环境的电脑. 需要用 Apple 账号登录 QuickTUI.

3.2 选择电脑的地址

安装和连接时, 你需要告诉手机去哪里找电脑. 可以使用三种地址: 主机名、Tailscale 地址或 IP 地址.

使用 QuickTUI Cloud 中转时 (推荐, 见 4.3), 优先选择主机名. 这样在同一个 Wi-Fi 下, 手机会直接连接电脑, 速度最快; 离开该网络后, 手机检测到无法直连主机名时会自动切换至云端中转.

提示: 用 3.5 方法 C 经 QuickTUI Cloud 配对时, 不需要填写地址, 可以跳过本节.

不使用 QuickTUI Cloud 中转时, 推荐顺序如下:

  1. Tailscale 地址 (电脑名或 IP): 在家和在外面都能用. 需要先在手机和电脑上装好 Tailscale (见 4.4). 在中国大陆, Tailscale 可能很慢, 建议改用 QuickTUI Cloud 中转.
  2. 主机名: 只在同一个 Wi-Fi 下能用, 但电脑的 IP 地址变了也不受影响.
  3. IP 地址: 只在同一个 Wi-Fi 下能用, 路由器为电脑重新分配地址后需要修改.

选哪一种都可以, 以后随时能在 App 中改成另一种, 不需要重新配对 (见 4.1).

查看主机名

  • macOS: 打开 系统设置 → 通用 → 共享, 页面底部的 本地主机名 即是 (例如 my-mac.local).

  • Linux: 在终端运行:

    hostname

    在输出的主机名后追加 .local (例如 my-linux.local).

  • Windows: 手机通常无法用主机名找到 Windows 电脑, 请使用 Tailscale 地址或 IP 地址.

注意: Linux 电脑需要运行 Avahi (mDNS) 服务, 手机才能用 .local 主机名找到它. Ubuntu 桌面版默认已开启; Ubuntu Server 版可以运行 sudo apt install -y avahi-daemon 安装. 用主机名连不上时, 改用 IP 地址.

查看 Tailscale 地址

如果你已经在手机和电脑上装好并登录了 Tailscale, 打开 iPhone 上的 Tailscale App, 在设备列表中找到你的电脑, 可以看到:

  • Tailscale 电脑名, 例如 my-mac. 这是 Tailscale 提供的名字 (MagicDNS), 只要手机上的 Tailscale 处于连接状态就能使用.
  • 以 100. 开头的地址, 例如 100.101.102.103.

两者任选其一. 还没有装 Tailscale 时, 可以先用主机名或 IP 地址完成安装, 以后再按 4.4 改过来.

查看 IP 地址

  • macOS: 打开 系统设置 → Wi-Fi, 点已连接网络旁的 详细信息, 查看「IP 地址」. 或在终端运行: 
    ipconfig getifaddr en0
  • Linux: 在终端运行: 
    hostname -I

    输出的第一个地址通常即为本机局域网 IP.

  • Windows: 在 PowerShell 中运行 ipconfig, 查看当前网络下的「IPv4 地址」.

家庭网络中的地址一般形如 192.168.x.x 或 10.x.x.x.

提示: 想避免 IP 地址变化, 可以在路由器的 DHCP 设置中为电脑保留一个固定地址.

3.3 方法 A: 在手机上自动安装

第 1 步: 在电脑上开启 SSH

  • macOS:
    1. 打开 系统设置 → 通用 → 共享.
    2. 打开 远程登录.
  • Linux (Ubuntu / Debian): 在终端运行: 
    sudo apt install -y openssh-server
sudo systemctl enable --now ssh

第 2 步: 在手机上安装

  1. 打开 QuickTUI App. 第一次打开会自动进入设置向导.

    提示: 以后要添加电脑时, 在 服务器列表 中点右上角的 +.

  2. 选择 通过 SSH 连接并启用增强功能 (推荐), 点 下一步.

  3. 填写电脑信息:

    • 主机: 电脑的地址 (见 3.2). 可以填 Tailscale 电脑名或地址 (例如 my-mac 或 100.101.102.103)、主机名 (例如 my-mac.local) 或 IP 地址 (例如 192.168.1.10).
    • 端口: 保持 22 不变.
    • 用户: 电脑的登录用户名.
    • 认证: 选 密码, 输入电脑的登录密码.

  4. 点 测试连接.

  5. 第一次连接时会弹出 信任 SSH 主机密钥?, 点确认.

  6. 看到连接成功后, 点 下一步.

  7. 选择 安装源:

    • 在中国大陆, 选 中国.
    • 在其他地区, 选 海外.

  8. 点 安装, 等待安装完成. 页面会实时显示安装过程, 通常需要一两分钟.

  9. 安装完成后, App 会自动完成配对, 并在 服务器列表 中添加这台电脑.

注意: 你在 主机 中填写的地址, 也是之后手机连接这台电脑时优先使用的地址.

提示: 如果用你填写的地址连不上 QuickTUI 服务端, App 会依次尝试电脑的主机名、Tailscale 地址和局域网 IP 地址, 以首个连通成功的地址保存该服务器配置. 你可以在 编辑服务器 页面查看最终使用的地址.

提示: 电脑密码只用于这次安装, App 不会保存.

注意: Linux 用户安装完成后, 请务必完成 3.7 节设置, 避免用户登出后服务终止.

如果自动配对失败

安装已经成功, 只是配对没完成. 常见原因有:

  • 手机能连上电脑的 SSH, 却连不上 8022 端口 (例如被电脑防火墙拦截).
  • 用的是主机名或 Tailscale 电脑名, 但手机暂时解析不了这个名字 (例如手机上的 Tailscale 没有连接).

请检查以上两点, 然后按 3.4 的「第 2 步」和「第 3 步」扫码配对.

提示: 也可以换一个地址, 重新运行一次自动安装, 不会有副作用.

3.4 方法 B: 在电脑上安装, 然后扫码配对

第 1 步: 在电脑上安装

macOS 或 Linux: 在终端运行下面一行 (二选一):

# 在中国大陆
curl -fsSL https://dl.quicktui.cn/q.sh | sh

# 在其他地区
curl -fsSL https://quicktui.ai/q.sh | sh

安装程序会自动完成所有设置. 结束时终端会显示 QuickTUI is installed — pair a device, 并列出显示二维码的方式:

  • 电脑有桌面时, 输入 1 (Browser QR) 按回车, 二维码会在浏览器中打开.
  • 通过 SSH 等没有桌面的方式安装时, 输入 1 (Terminal QR) 按回车, 二维码直接显示在终端中.
  • 手机扫不了二维码时, 输入 Pairing text (中文界面为 配对文本) 前面的数字按回车, 终端会显示一行配对文本, 然后按第 3 步的「改用粘贴配对文本」操作.

如果接着让你选择地址, 参考下方第 2 步第 3 项完成选择, 随后直接进行第 3 步扫码.

Windows:

  1. 打开 Microsoft Store, 搜索并安装 QuickTUI Server. 这就是 Windows 版的 QuickTUI 服务端.
  2. 从开始菜单打开 QuickTUI Server.
  3. 如果 Windows 询问是否允许通过防火墙, 选择 允许.
  4. QuickTUI 服务端会自动打开配对向导. 按第 2 步的第 2、3 点操作, 然后进行第 3 步.

注意: Windows 上第一次请务必从开始菜单打开 QuickTUI Server, 这样它才会在开机登录后自动启动.

第 2 步: 在电脑上显示配对二维码

  1. 在终端运行:

    quicktui-server pairing welcome

    注意: 这是本指南第一次在终端运行 quicktui-server. 不同电脑的运行方法如下, 本指南之后的命令都简写为 quicktui-server:

    • macOS 和 Linux: 程序安装在 ~/.local/bin/ 文件夹中, 安装程序不会把这个文件夹加入命令搜索路径. 如果终端提示 command not found, 可以二选一:
      • 每次都写完整路径, 例如 ~/.local/bin/quicktui-server pairing welcome.
      • 运行下面对应的一行命令, 然后关闭并重新打开终端. 之后就可以直接输入 quicktui-server. 
        # macOS
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
# Linux
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
    • Linux (以 root 安装): 程序安装在 /usr/local/bin/, 以 root 身份直接运行 quicktui-server, 或在命令前加 sudo, 例如 sudo quicktui-server pairing welcome.
    • Windows: 在 PowerShell 中直接运行 quicktui-server.

  2. 向导询问配对方式时, 如果可以, 优先选择浏览器二维码. 终端可能因为字体等问题, 导致显示的二维码无法扫描. 手机完全扫不了码时, 选择 Pairing text (中文界面为 配对文本), 然后按第 3 步的「改用粘贴配对文本」操作.

  3. 如果向导让你选择地址, 按 3.2 选择. 列表中每个地址后面标有类型:

    • hostname: 电脑的主机名.
    • tailscale: Tailscale 地址 (以 100. 开头).
    • lan: 局域网 IP 地址.
    • 其他类型 (wireguard、tunnel、wan): 其他网络的地址, 一般不选.

提示: 列表中的主机名在 Linux 上通常不带 .local, 手机可能找不到. 想用主机名或 Tailscale 电脑名配对时, 可以直接指定地址生成二维码, 例如:

quicktui-server pairing qrcode --browser --public-url http://my-linux.local:8022
quicktui-server pairing qrcode --browser --public-url http://my-mac:8022

第 3 步: 在手机上扫码

  1. 在 App 的 服务器列表 中点 +.
  2. 点 其他连接方式.
  3. 选择 扫描二维码连接已启用增强功能的电脑, 点 下一步.
  4. 对准电脑屏幕上的二维码扫描.
  5. 在 配对服务器 页面点 配对服务器.

提示: 每个二维码只能配对一台设备. 要配对多台设备, 为每台设备重新生成二维码.

警告: 二维码 15 分钟内有效. 失效前任何人扫到它都能连接你的电脑. 不要截图分享或发到网上.

改用粘贴配对文本

配对文本和二维码携带同一个一次性配对码, 只是变成了一行可以复制粘贴的文本. 摄像头扫不了二维码, 或者你在手机上通过 SSH 操作电脑时, 可以改用它.

  1. 在电脑上运行 quicktui-server pairing welcome 并选择 Pairing text (中文界面为 配对文本), 或者运行:

    quicktui-server pairing qrcode --text

    终端会显示一行以 qtpair: 开头的文本.

  2. 复制这一整行并传到手机上, 例如在手机的 SSH 会话里直接复制, 或使用设备间的共享剪贴板.

  3. 在 App 的 服务器列表 中点 +, 点 其他连接方式, 选择 粘贴配对文本, 点 下一步.

  4. 粘贴文本后点 下一步. 终端复制带来的换行和多余空格会被自动移除.

  5. 在 配对服务器 页面点 配对服务器.

警告: 配对文本只能使用一次, 15 分钟内有效. 失效前任何拿到它的人都能连接你的电脑. 不要通过公开渠道发送或发到网上.

3.5 方法 C: 经 QuickTUI Cloud 配对

适用于手机无法直接连到的电脑. 电脑和手机都连接到 QuickTUI Cloud, 由它转发加密数据.

注意: 每个账号每月有少量免费中转流量, 每月初重置. 免费账号可以这样连接的电脑数量有限. 流量用完或电脑数量超出后, 需要订阅 QuickTUI Cloud. 免费流量适合偶尔查看; 经常使用建议订阅, 或改用第 4 章的其他方式.

第 1 步: 在电脑上安装并获取配对码

  1. 按 3.4 的第 1 步在电脑上安装.
  2. 安装结束时, 终端会显示 QuickTUI is installed — pair a device, 并列出几个选项. 输入 Pair through QuickTUI Cloud 前面的数字, 按回车.
  3. 选择区域: 在中国大陆选 China mainland, 其他地区选 Global. 要与手机上选择的区域一致.
  4. 终端会显示一个形如 ABCD-1234 的配对码. 配对码 15 分钟内有效, 最多可以输错 5 次. 保持终端窗口打开, 进行第 2 步.

提示: 如果安装时跳过了配对, 或者配对码已经过期, 在终端运行下面的命令重新打开配对向导, 然后选择 Pair through QuickTUI Cloud:

quicktui-server pairing welcome

第 2 步: 在手机上输入配对码

  1. 在 App 的 服务器列表 中点 + → 其他连接方式 → 经 QuickTUI Cloud 配对.
  2. 选择与电脑相同的区域 (手机上的 中国 对应电脑上的 China mainland, 海外 对应 Global), 用 Apple 账号登录.
  3. 输入电脑上显示的配对码, 点 配对服务器.

配对成功后, 电脑的终端会显示 Paired: 和你的设备名.

3.6 给另一台 iPhone 或 iPad 配对

每台设备都要单独配对, 不需要重新安装:

  • 直接连接的电脑: 在电脑上按 3.4 的第 2 步显示二维码, 在新设备上按第 3 步扫码.
  • 经 QuickTUI Cloud 配对的电脑: 在电脑上运行 quicktui-server pairing welcome 获取新的配对码, 在新设备上按 3.5 的第 2 步输入.

3.7 Linux 必做: 让服务在退出登录后继续运行

在 Linux 上以普通用户安装后, 默认情况下用户会话注销 (含断开 SSH) 会导致服务被系统终止. 运行下面的命令启用会话驻留 (linger) 解决:

loginctl enable-linger

如果提示 Access denied 或需要认证, 改为运行:

sudo loginctl enable-linger "$USER"

检查是否成功:

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

看到 Linger=yes 就表示设置成功.

3.8 检查安装是否成功

在 App 的 服务器列表 中, 点你的电脑. 能看到终端画面, 就说明安装和配对都成功了. 下一步请看第 5 章启动 Agent.

连不上时, 请看第 9 章故障排除.

第 4 章 离开电脑时也能连接

如果安装时用的是主机名或局域网 IP 地址, 手机只在和电脑连同一个 Wi-Fi 时能连上. 本章介绍离开家或办公室后如何连接. 用 3.5 方法 C 经 QuickTUI Cloud 配对, 或安装时已经使用 Tailscale 地址的, 不需要再做任何设置.

4.1 先了解两件事

1. 换地址不需要重新配对

手机连接电脑用的是一个「地址」, 例如 http://192.168.1.10:8022. 你可以随时在 App 中修改这个地址, 不需要重新配对:

  1. 在 服务器列表 中, 打开这台电脑的 编辑服务器 页面.
  2. 修改 协议、主机 和 端口.
  3. 点 测试连接, 成功后保存.

最佳实践: 先在同一 Wi-Fi 下完成配对, 再按本章指引配置远程访问地址.

2. 为什么不需要证书也安全

QuickTUI 的加密不依赖 HTTPS 证书. 即使地址是 http:// 开头, 内容也经过端到端加密, 第三方无法窃听通信内容, 亦无法伪造服务端身份.

4.2 选择适合你的方式

各连接方式按配置复杂度由低到高排列如下:

  1. QuickTUI Cloud 中转 (推荐, 见 4.3)
    不需要任何网络设置, 在中国大陆也能稳定使用. 每月有少量免费流量, 经常使用需要订阅.
  2. Tailscale (见 4.4)
    在手机和电脑上各装一个免费 App. 不用改路由器, 不用买域名. 在中国大陆可能很慢.
  3. 你已经在用的 VPN (见 4.5)
    例如 WireGuard、ZeroTier 或公司 VPN.
  4. Cloudflare Tunnel (进阶, 见 4.6)
    适合有自己的域名、并托管在 Cloudflare 的用户.
  5. 自建 HTTPS 反向代理 (进阶, 见 4.6)
    适合已经在用 nginx 或 Caddy 的用户.
  6. 路由器端口转发 (进阶, 见 4.6)
    适合家里宽带有公网 IP 的用户. 安全性略差, 不推荐新手使用.

4.3 QuickTUI Cloud 中转 (推荐)

QuickTUI Cloud 中转不需要任何网络设置: 电脑和手机都主动连接 QuickTUI Cloud, 由它转发加密数据. 无论手机在哪里, 都能连上电脑.

  • 还没有配对: 按 3.5 方法 C 经 QuickTUI Cloud 配对. 配对后这台电脑固定走中转.
  • 已经直接配对过: 按下面的步骤为这台电脑绑定中转. 绑定后, 手机能直接连上电脑时直接连接, 连不上时自动改走中转.

接收 Agent 通知也需要绑定中转 (见 7.4).

注意: 每个账号每月有少量免费中转流量, 适合偶尔查看. 经常使用请订阅 QuickTUI Cloud.

为已配对的电脑绑定中转

  1. 在 服务器列表 中, 点顶部的 Cloud 按钮.
  2. 选择正确的区域 (中国或海外) 并以 Apple 账号登录.
  3. 在 管理中转配额 qtrid (中转实例编号) 页面, 选择一个 qtrid, 点 绑定, 然后选择你的电脑.
  4. 打开这台电脑的 编辑服务器 页面, 把 模式 设为 自动.

模式 有三个选项:

  • 自动: 优先直接连接, 连不上时自动改走中转. 推荐.
  • 直连: 只直接连接.
  • 中转: 只走中转.

中转流量的用量显示在 服务器列表 顶部的 Cloud 横幅中. 流量用完时 App 会提示.

4.4 Tailscale

Tailscale 会把你的手机和电脑连成一个私人网络. 不管手机用的是 Wi-Fi 还是蜂窝数据, 都能用同一个地址找到你的电脑.

注意: 在中国大陆, Tailscale 的连接可能非常缓慢. 要获得稳定的速度, 需要自己额外部署私有的 DERP 中转服务器, 难度较大. 在中国大陆使用时, 建议优先选择 QuickTUI Cloud 中转 (见 4.3).

第 1 步: 在电脑上安装 Tailscale

  1. 打开 https://tailscale.com/download, 下载并安装电脑版.
  2. 启动 Tailscale, 登录账号 (可以用 Google、Apple、Microsoft 等账号).

第 2 步: 在 iPhone 上安装 Tailscale

  1. 在 App Store 安装 Tailscale.
  2. 用和电脑上 同一个账号 登录.
  3. 打开 Tailscale App 中的连接开关. 系统会提示添加 VPN 配置, 选择允许.

第 3 步: 查看电脑的 Tailscale 地址

打开 iPhone 上的 Tailscale App, 在设备列表中找到你的电脑. 下面两种写法任选一种:

  • Tailscale 电脑名, 例如 my-mac. 这是 Tailscale 的 MagicDNS 功能提供的名字, 好记, 而且不会变. 也可以使用完整写法, 例如 my-mac.tail1234.ts.net.
  • 以 100. 开头的地址, 例如 100.101.102.103.

也可以在电脑终端运行下面的命令查看:

tailscale ip -4      # 显示 100. 开头的地址
tailscale status     # 显示所有设备的名字和地址

注意: Tailscale 电脑名只有在 Tailscale 管理后台开启了 MagicDNS 时才能使用. 新建的 Tailscale 账号默认已开启. 用电脑名连不上时, 改用 100. 开头的地址.

第 4 步: 让 QuickTUI 使用这个地址

  • 还没安装 QuickTUI 服务端: 按 3.3 方法 A 安装, 在 主机 一栏直接填 Tailscale 电脑名或 100. 开头的地址.

  • 用方法 B 扫码配对: 在电脑上运行下面的命令生成二维码 (把 my-mac 换成你的 Tailscale 电脑名), 然后按 3.4 第 3 步扫码:

    quicktui-server pairing qrcode --browser --public-url http://my-mac:8022

    也可以运行 quicktui-server pairing welcome, 在地址列表中选择类型为 tailscale 的地址.

  • 已经配对过: 打开这台电脑的 编辑服务器 页面, 设置:

    • 协议: HTTP
    • 主机: Tailscale 电脑名或地址, 例如 my-mac 或 100.101.102.103
    • 端口: 8022

    点 测试连接, 成功后保存.

现在, 只要 iPhone 上的 Tailscale 保持连接, 你在任何地方都能连上电脑. 在家时也可以直接使用这个地址, 不需要来回切换.

注意: iPhone 同一时间只能开一个 VPN. 打开其他 VPN 时, Tailscale 会断开, QuickTUI 也会连不上.

注意: 如果你的 Tailscale 设置了访问控制规则 (ACL), 需要允许手机访问电脑的 8022 端口. 未配置过 ACL 则无需处理.

4.5 你已经在用的 VPN

如果你已经在用 WireGuard、ZeroTier 或公司 VPN, 并且手机连上 VPN 后能访问电脑, 就可以直接用电脑在 VPN 中的地址.

  1. 在电脑终端运行, 列出电脑的所有地址: 
    quicktui-server pairing addresses

    类型为 wireguard 或 tunnel 的通常就是 VPN 地址.

  2. 已经配对过时, 打开这台电脑的 编辑服务器 页面, 协议 选 HTTP, 主机 填这个地址, 端口 填 8022, 点 测试连接, 成功后保存.
  3. 还没配对时, 用这个地址生成二维码 (把 10.8.0.2 换成实际地址), 然后按 3.4 第 3 步扫码: 
    quicktui-server pairing qrcode --browser --public-url http://10.8.0.2:8022

注意: 公司 VPN 可能不允许访问员工的电脑, 或者拦截 8022 端口. 连不上时请咨询公司网络管理员, 或改用 QuickTUI Cloud 中转 / Tailscale.

4.6 Cloudflare Tunnel、自建反向代理与路由器端口转发 (进阶)

下面三种方式适合已经有自己的域名、反向代理或公网 IP 的用户. 详细的设置和配对步骤见官网的 远程访问指南:

  • Cloudflare Tunnel: 电脑主动连接 Cloudflare, 通过你自己域名下的 HTTPS 网址访问. 不需要公网 IP, 也不需要改路由器. 前提是域名托管在 Cloudflare.
  • 自建 HTTPS 反向代理: 已经在用 nginx 或 Caddy 时, 把一个单独的域名转发给 QuickTUI 服务端.
  • 路由器端口转发: 家里宽带有公网 IP 时, 在路由器上把一个外部端口转发到电脑的 8022 端口. 这种方式把服务端直接暴露在互联网上, 不推荐新手使用.

第 5 章 启动 Agent

5.1 创建工作区

第一次连接电脑时, 如果还没有工作区:

  1. 点快捷栏上的 切换器 按钮.
  2. 在 工作区 标题旁点 +.
  3. 在 新建工作区 对话框中填写:
    • 后端: 只有电脑上同时启用了 tmux 和 Herdr 时才需要选择. 若无特殊需求, 保持默认即可.
    • CWD: 工作区的默认文件夹, 一般选你的项目文件夹.
    • 工作区名称: 可以不填, 会自动命名.
  4. 点 创建.

提示: 建议每个项目独立建立一个工作区, 名称与项目名保持一致.

提示: 你在电脑上用 tmux 或 Herdr 自己创建的工作区, 也会出现在切换器中, 可以直接打开.

电脑上没有可用的后端时

如果 App 提示 服务器已连接, 但没有可用的会话后端, 说明电脑上没有可用的 tmux 或 Herdr (例如安装时自动下载 Herdr 失败了). 可以直接在 App 中安装:

  1. 在提示面板中点 安装 Herdr (推荐). macOS 和 Linux 上也可以选择 安装 tmux; Windows 上只能安装 Herdr.
  2. 等待安装完成. 安装过程中可以离开这个页面, 安装会在电脑上继续进行.
  3. 安装成功后, App 会自动重新连接.

安装失败时, 面板会显示原因和可以在电脑上手动运行的命令. 在电脑上手动装好后, 回到 App 点重试即可, 不需要重启 QuickTUI 服务端.

5.2 用 Agent 向导启动 Agent

Agent 向导会在当前工作区中新开一个窗口, 并在里面启动 Agent.

  1. 点快捷栏上的 Agent 向导 按钮.
  2. 选择 Agent: 左右滑动, 点选你要用的 Agent. 名字显示为警告颜色时, 表示电脑上没有找到这个 Agent (见 5.4).
  3. 设置 配置 (可以保持默认):
    • 预设: 保存好的模型和推理档位组合.
    • 模型 / 推理档位: 只有部分 Agent 显示.
    • 模式: 通常保持 Default; 若需长时间无人值守运行, 可考虑 YOLO 模式 (注意下方警告).
  4. 选择工作目录: 点路径可以从最近用过的文件夹中选; 点旁边的文件夹按钮可以浏览选择.
  5. 会话标题: 给这个任务起个名字, 方便以后找到. 可以不填.
  6. 点 启动.

App 会自动切换到新窗口, Agent 开始运行. 向导会自动记忆本次配置, 方便下次快速启动.

警告: 部分 Agent 提供 YOLO 模式. 这个模式下 Agent 执行任何操作都不再请求你的批准, 可能修改或删除文件. 只在你完全信任的项目中使用.

提示: 也可以在切换器中点某个工作区右侧的 …, 选择 Agent 向导, 直接在那个工作区中启动 Agent.

提示: 在 设置 → 管理 Agent 模型 中可以添加自定义模型和预设.

5.3 在终端里直接启动

除使用向导外, 亦可在终端内直接输入命令启动 Agent, 例如:

claude

5.4 Agent 向导找不到 Agent 时

QuickTUI 服务端作为后台服务运行, 默认环境变量可能无法自动解析安装在非标准路径下的 Agent 可执行文件.

  1. 在电脑终端运行下面的命令, 查看 QuickTUI 服务端找到了哪些程序: 
    quicktui-server doctor
  2. 在电脑终端运行 which claude (Windows 上在 PowerShell 中运行 Get-Command claude; 把 claude 换成你的 Agent 命令), 记下输出的完整路径.
  3. 用任意文本编辑器打开配置文件 (macOS 和 Linux 可以运行 nano ~/.config/quicktui-server-v2/config.toml; 其他系统的位置见附录 B), 在末尾加入: 
    [agent_bins]
claude = "/opt/homebrew/bin/claude"

    把路径换成第 2 步得到的路径.

  4. 保存后重启: quicktui-server service restart.

5.5 Agent 状态检测 (hooks)

QuickTUI 能显示 Agent 是「工作中」还是「等待输入」, 并在需要时通知你. 这依赖安装时自动加入各 Agent 配置的 hooks. 大多数情况下你不需要做任何事, 只有两个例外:

  • Codex: 需要在 Codex 中输入 /hooks, 信任 QuickTUI 添加的 hooks 后才生效.
  • OpenCode: 安装后需要重启 OpenCode 一次.

第 6 章 与 Agent 交流

Agent 运行在电脑的终端里. App 中显示的就是这个终端, 你的输入会直接发给 Agent.

6.1 认识终端界面

  • 顶部栏:
    • 左侧: 返回 服务器列表、切换全屏.
    • 中间: 当前工作区的名字.
    • 右侧: 文件 和 端口转发 两个按钮. 文件 打开文件管理器, 浏览和传输电脑上的文件; 端口转发 把电脑上的端口 (例如开发中的网页服务) 转发到手机上访问. 这两个功能不在本指南范围内.
  • 终端画面: 中间的大块区域, 就是电脑上的终端.
  • 快捷栏: 底部的按钮条. 默认的按钮从左到右是:
    • 设置、切换器、文件、Agent 向导
    • 自定义键盘、剪贴板历史
    • 命令面板、输入栏、显示 / 收起键盘

快捷栏放不下时可以左右滑动. 你还可以在 设置 → 快捷栏 中, 再添加最多 3 条快捷栏, 放 Esc、Tab、方向键、Ctrl 组合键等常用按键. 按住按键会连续发送.

6.2 给 Agent 发送指令

推荐用 输入栏 发送较长的指令:

  1. 点快捷栏上的 输入栏 按钮.
  2. 在输入栏中输入指令或 Prompt 内容. 可以编辑多行.
  3. 点发送. 整段文字会一次性发给 Agent.
  4. 点输入栏内的回形针图标, 可以添加要发送给 Agent 的附件.

提示: 在 设置 → 点击终端时 中, 可以设置点一下终端就打开输入栏.

其他输入方式:

  • 系统键盘: 字符按键即时输入发送, 适合简短命令.
  • 自定义键盘: 为终端设计的键盘, 带有 Esc、Ctrl、方向键等按键.
  • 命令面板: 预存常用指令片段, 点击即可直接发送. 在 设置 → 管理命令面板 中添加.
  • 剪贴板历史: 重新粘贴之前复制过的内容.

6.3 回应 Agent

  • Agent 给出几个编号选项时: 输入对应的数字再按回车, 或者用方向键选择后按回车.
  • 中断或停止 Agent: 按 Esc (Claude Code) 或 Ctrl + C. 这两个键可以放在快捷栏上.
  • 斜杠命令: 和在电脑上一样输入, 例如 /clear.
  • 在通知中批准: 开启 Agent 通知后 (见 7.4), Agent 请求权限时手机会收到通知. 长按通知, 可以直接选择 批准 或 拒绝, 不用打开 App.

6.4 查看和复制输出

  • 查看之前的内容: 在终端画面上上下滑动.
  • 复制文字:
    1. 长按要复制的文字, 出现放大镜后拖动调整范围.
    2. 点浮动的 复制 按钮.
    3. 若文本因终端自动折行截断, 点 智能复制 可合并为连续单行后复制.

6.5 离开与回来

使用期间可随时锁屏、切出 App 或断开网络, 电脑端 Agent 持续运行不受影响. 回到 QuickTUI 后, App 会自动重新连接并同步最新画面.

第 7 章 用切换器管理多个任务

同时运行多个 Agent 任务时, 用 切换器 来查看它们的状态、在它们之间切换.

7.1 打开和关闭切换器

  • 打开: 点快捷栏上的 切换器 按钮.
  • 关闭: 点右上角的关闭按钮, 或在空白处向下滑.

7.2 看懂切换器

切换器从上到下分为两部分:

服务器
 [我的 Mac ✓] [办公室 Linux]          ← 点按切换到另一台电脑

工作区  ⊕                              ← 新建工作区
  api-refactor   tmux · 3 个窗口   …   ← 点按展开或收起; … 打开菜单
    ✓ 1 claude    (Claude 图标) (工作中)
      2 codex     (Codex 图标)  (等待输入)
      3 shell
  docs           herdr · 2 个标签页 …
  • 服务器: 你添加过的所有电脑. 带勾标记当前电脑, 轻点其他电脑即可切换.
  • 工作区: 名字后面标有它的后端 (tmux 或 herdr) 和窗口数量. tmux 显示「N 个窗口」, Herdr 显示「N 个标签页」. 轻点展开显示里面的窗口, 再次轻点收起. 工作区只有一个窗口时, 轻点即可直接进入.
  • 窗口: 带勾标记当前活动窗口, 轻点其他窗口即可切换. 运行着 Agent 的窗口会显示 Agent 的图标和状态.
  • Pane: 一个窗口被分成几块时, 窗口下方会列出每一块, 可以直接切换到某一块.

7.3 Agent 状态

窗口旁的状态图标告诉你每个 Agent 在做什么:

  • 工作中: Agent 正在执行任务. 不需要你操作.
  • 等待输入: Agent 暂停等待你批准或回答提问. 请尽快进入这个窗口处理.
  • 已完成: Agent 完成了这一轮任务. 可以去查看结果, 指派下一步任务.
  • 空闲: Agent 没有在工作.

提示: 打开切换器, 先找「等待输入」的窗口处理, 是最高效的使用方式.

7.4 接收 Agent 通知

开启通知后, 不打开 App 也能知道哪个 Agent 需要你.

需要满足的条件:

  • 这台电脑已经绑定 QuickTUI Cloud 中转 (见 4.3, 或用 3.5 方法 C 配对).
  • Agent hooks 已生效 (见 5.5).
  • iPhone 的 设置 → 通知 → QuickTUI 中允许通知.

设置方法:

  1. 在 服务器列表 中, 打开这台电脑的 Agent 通知 页面.
  2. 打开 通知此设备.
  3. 选择要接收哪些通知: 需要审批、任务完成、Agent 错误、会话结束.
  4. (可选) 选择通知中要显示的内容: 包含 Agent、包含项目、包含摘要、包含会话名称.

注意: 默认情况下通知只说明「发生了什么」, 不包含项目名称和任务内容. 打开第 4 步的选项后, 这些内容会经过 QuickTUI Cloud 发送. 通知永远不会包含完整的终端输出、源代码或密码.

7.5 推荐的任务工作流

一个项目一个工作区, 一个任务一个窗口.

  1. 为每个项目创建一个工作区, CWD 选项目文件夹 (见 5.1).
  2. 每个任务用 Agent 向导 启动一个 Agent, 在 会话标题 中写上任务名, 例如 修复登录.
  3. 提交任务后即可离开. 收到通知或打开切换器时, 优先处理 等待输入 的窗口.
  4. 任务完成并确认结果后, 关闭这个窗口 (见 7.7).

提示: 在工作区的 … 菜单中选择 默认工作目录, 之后在这个工作区里新开的窗口和 Agent 都会自动使用这个文件夹.

7.6 快速切换

在终端画面上 左右滑动, 可以直接切换到上一个或下一个窗口, 不用打开切换器.

可以在 设置 → 水平滑动目标 中修改左右滑动切换的对象:

  • 工作区: 在工作区之间切换.
  • 会话: 在窗口之间切换.
  • Pane: 在窗格之间切换.
  • 会话+Pane: 在窗口和窗格之间切换 (默认).

7.7 新建、重命名和关闭

  • 新建工作区: 点 工作区 标题旁的 +.
  • 在工作区中新开一个窗口: 点工作区右侧的 … → 新建会话. 创建后会自动切换过去.
  • 在工作区中启动 Agent: 点工作区右侧的 … → Agent 向导.
  • 重命名或关闭工作区: 点工作区右侧的 …, 或长按工作区.
  • 重命名或关闭窗口: 长按窗口. 只有当前工作区中的窗口可以这样操作.

警告: 关闭工作区或窗口会结束里面正在运行的所有程序, 包括 Agent, 而且无法撤销. 关闭前请确认任务已经完成.

提示: 如果当前工作区被关闭了 (例如在电脑上关闭), App 会自动切换到另一个工作区; 一个工作区都没有时, 会自动新建一个.

第 8 章 维护

8.1 升级 QuickTUI 服务端

推荐 (macOS 和 Linux): 重新运行安装命令. 在电脑终端运行和安装时相同的命令即可升级到最新版本 (二选一):

# 在中国大陆
curl -fsSL https://dl.quicktui.cn/q.sh | sh

# 在其他地区
curl -fsSL https://quicktui.ai/q.sh | sh

重新安装会保留已配对的设备、服务端身份、QuickTUI Cloud 中转绑定和现有设置, 无需重新配对.

其他升级方式:

  • 在手机上升级: QuickTUI 服务端有新版本时, 服务器列表 中这台电脑旁会出现 升级 按钮. 点它并按提示操作.
  • 在电脑上用命令升级 (macOS 和 Linux): quicktui-server upgrade install.
  • Windows: 由 Microsoft Store 自动更新.

注意: 升级时 QuickTUI 服务端会重启, App 与电脑的连接会短暂中断, 随后自动重新连接. 活跃终端会话与正在运行的 Agent 均不受影响.

8.2 管理已配对的设备

手机丢失或不再使用时, 应该取消它的配对:

  1. 在电脑终端列出所有已配对设备: 
    quicktui-server pairing devices list
  2. 找到要取消的设备, 记下它的 device_id, 然后运行: 
    quicktui-server pairing devices revoke <device_id>

    把 <device_id> 换成实际的 ID.

被取消的设备会在 5 分钟内断开, 重新配对前无法再次连接.

警告: 若怀疑配对凭据泄露, 可以一次清除所有设备. 之后所有设备均需要重新配对.

  1. 停止服务: 
    # macOS
launchctl bootout gui/$(id -u)/ai.quicktui
# Linux
systemctl --user stop quicktui
# Linux (以 root 安装)
sudo systemctl stop quicktui
# Windows (PowerShell; Microsoft Store 版本中这条命令只停止服务进程)
quicktui-server service uninstall
  2. 更换服务端身份并清空全部配对: 
    quicktui-server pairing identity rotate
  3. 重新启动服务: 
    quicktui-server service restart

8.3 卸载

卸载的命令和步骤 (含 Windows 与彻底删除) 见官网安装页的 卸载 一节.

卸载会停止 QuickTUI 服务端, 但保留配对信息, 以后重新安装时不需要重新配对. tmux、Herdr 和你的 Agent 不会被卸载.

第 9 章 故障排除

常见问题的原因和解决方法都整理在官网的 常见问题 中. 按你遇到的现象打开对应条目:

附录 A: 常用命令

quicktui-server 的全部命令和参数见官网安装页的 命令行参数. 找不到 quicktui-server 时, 见 3.4 第 2 步中的说明.

附录 B: 文件位置与配置

  • 程序、配置目录和后台服务在各系统上的位置, 见官网安装页的 安装位置.
  • 配置文件 config.toml 的全部设置项 (包括 addr、trusted_proxies、session_backends、[agent_bins] 等), 见官网安装页的 配置文件.

修改配置文件后, 需要运行 quicktui-server service restart 才会生效.

相关链接