如何用 QuickTUI 从手机监督和引导电脑上的 AI Agent？

QuickTUI 可以让用户从 iPhone、iPad 或浏览器连接自己电脑上的真实终端，用手机启动、监督和引导 Claude Code、Codex 或其他命令行 AI Agent。macOS 与 Linux 端以 tmux 保存会话，Windows 使用 qscn 会话后端；手机断网、切换蜂窝网络或应用进入后台时，Agent 仍在电脑上继续运行，重新连接后可以回到同一现场。

它与专门适配某一种 Agent 的控制面不同：QuickTUI 主要提供通用终端、会话保活和移动工具栏，因此几乎任何能在终端运行的 Agent 都能使用。用户看到的不是经过摘要的任务卡片，而是实时终端输出，也可以直接回答问题和处理 Agent 自己显示的批准提示。

推荐部署顺序是：先在电脑安装并验证 tmux 或 Windows 会话后端，再安装 QuickTUI 服务；用原生移动 App 扫描二维码配对；在无敏感数据的测试仓库中启动 Agent；验证断线恢复、审批、通知和撤销；最后才用于真实项目。不要把一键安装与默认网络配置视为完整安全方案。

QuickTUI 适合什么场景

编程 Agent 往往要运行几分钟到几十分钟。用户离开电脑后，任务可能停在一个工具确认、澄清问题或测试错误上。QuickTUI 让用户从手机查看原始终端，及时允许或拒绝操作，在 Agent 偏离范围时追加指令，而不必远程传输整个桌面。

它适合命令行为主的长任务、服务器上的自动化、家中工作站和多项目观察。手机最适合做状态确认、短指令、一次审批和错误中断；复杂 diff 审查、大段代码编辑和图形界面调试仍应回到电脑完成。

由于 QuickTUI 不绑定单一 Agent，同一台电脑可以为 Claude Code、Codex 和自研工具分别建立会话，再从应用中切换。并行能力不代表可以让多个 Agent 修改同一工作区，每个任务仍应使用独立分支或工作树。

运行架构怎样理解

电脑端运行 QuickTUI server，并连接本地会话后端。macOS 与 Linux 上，会话后端是用户自行安装的 tmux；Windows 安装程序会配置 qscn。Agent CLI 运行在这些持久会话里，代码、凭据、构建工具和进程始终位于电脑。

移动端通过已配对的 profile 找到 server，日常终端业务流量默认尽量直连并使用端到端加密。配对二维码会注册当前设备并固定 server identity，手机不需要输入一个可全局使用的 root token。

浏览器客户端也可使用，但当前 server CLI 不会为新的 Web 或 Desktop profile 导出完整配对载荷。也就是说，浏览器访问主要适用于已经持有设备凭据的既有 profile；新增设备应先使用原生 App 扫描二维码，不能根据旧教程手工拼接凭据。

macOS 与 Linux 的前置条件

macOS 和 Linux 需要用户自行安装 tmux 3.2 或更高版本，QuickTUI 安装器不会代装。先在终端检查版本：

tmux -V

如果版本过低，使用操作系统可信的软件源升级。升级后建立一个普通测试会话，分离再重新附着，确认本机 tmux 正常工作。QuickTUI 依赖的是这个真实会话，底层不稳定时移动端也无法提供可靠保活。

目标 Agent CLI 也要在电脑端提前安装并认证。分别运行其版本或帮助命令，确认当前用户可以访问测试仓库。后台 server 的 PATH 可能与交互式 Shell 不同，若应用中找不到命令，应检查服务启动环境。

Windows 的会话后端

Windows 不使用 tmux，安装时会配置 qscn。用户应在 QuickTUI App 中通过 New Session 创建会话，不要照搬 macOS 或 Linux 的 tmux 命令。跨平台教程若没有说明这一点，很容易让 Windows 用户误以为安装失败。

Windows 安装程序还会配置服务运行。安装前确认 PowerShell 执行策略、应用来源和组织安全规则；受管设备不要为了运行一键命令临时关闭全局防护。完成后验证新会话、断开与重连，再启动真正的 Agent。

安装电脑端服务

官方页面为 macOS、Linux 和 Windows 提供一键安装命令。执行远程脚本前应先在浏览器或终端查看脚本内容，确认域名、下载文件、安装目录和服务配置，再运行。不要从论坛回复或短链接复制修改过的命令。

安装完成后检查 quicktui-server 是否可用，并阅读当前版本帮助。服务应以普通用户权限运行，不要因为项目目录权限错误就改用管理员或 root。更安全的做法是调整仓库归属、使用独立开发账户和限制凭据。

电脑端还要保持可达。长任务期间避免自动休眠、合盖断网和强制重启；笔记本接通电源。QuickTUI 能保持终端会话，但不能让已关机或断电的机器继续执行。

如何生成二维码并配对

macOS 与 Linux 可运行：

quicktui-server pairing qrcode

Windows 则从安装目录调用 quicktui-server 的可执行文件并请求配对二维码。二维码会注册当前设备并固定 server identity。使用原生 App 扫描，不要把二维码截图发送给他人，也不要在共享直播中展示。

配对完成后核对 server 名称、设备和 profile。若出现未知设备或连接地址不符合预期，撤销配对并重新生成，不要继续使用。手机是终端控制入口，应启用设备锁、生物识别、账号保护和远程擦除。

创建第一个持久会话

在 macOS 或 Linux 上，可以先在电脑创建命名会话：

tmux new-session -s agent-demo
cd /srv/projects/agent-demo
git status

随后启动 Claude Code、Codex 或其他 Agent。用户从 QuickTUI App 打开同一会话后，会看到真正的终端流。离开电脑时将终端分离，而不是结束 Agent；即使手机连接断开，tmux 会话仍继续运行。

Windows 用户在 App 中新建会话，再选择正确工作目录并启动 Agent。不同会话使用清晰名称，包含项目和任务目的。不要把所有 Agent 都放进一个无名窗口。

怎样启动和引导 Agent

开始任务前先检查 Git 状态，确认用户原有修改。提示应写明目标、允许修改的范围、禁止操作、验收命令和停止条件。例如只改一个模块、不安装系统软件、不推送远端、测试失败两次后暂停并总结。

QuickTUI 展示的是实时终端，所以用户可以直接回答 Agent 问题、批准工具调用或补充方向。批准前要看清命令、参数、工作目录和目标文件。终端提示的安全能力取决于 Agent 自身，QuickTUI 并不会把所有任意 CLI 自动变成结构化权限系统。

发现 Agent 反复读取同一文件、重复测试或扩大修改范围时，及时发送中断并要求总结证据。移动端监督的价值在于缩短等待时间，不是让无人值守循环无限运行。

会话保活怎样工作

Agent 进程属于电脑上的 tmux 或 qscn 会话，不属于手机网络连接。手机从无线网络切换到 LTE 或 5G、应用进入后台、系统回收连接时，终端进程仍存在。重新打开 App 后可以接回实时画面。

重连后先读取最新输出，确认 Agent 是仍在执行、等待输入还是已经结束。不要因为短暂无画面就再次启动同一任务。两个 Agent 同时写同一工作区会导致冲突和结果污染。

如果底层会话本身被删除、电脑重启且未恢复，QuickTUI 无法凭客户端历史重建进程。重要长任务应结合系统服务、检查点和版本控制，不要把保活误解为永久恢复。

如何同时运行多个 Agent

每个 Agent 放在独立 tmux 会话或 Windows 会话中。例如一个负责功能分支，一个运行测试，另一个跟踪日志。客户端可以在会话间切换，单台电脑的基础功能可完整使用，多电脑配置则属于 Pro 范围。

并行任务必须隔离写入目录。使用 Git 工作树为每个 Agent 分配独立路径，避免共享依赖缓存中的破坏性操作。会话名可采用项目、分支和任务编号组合，便于手机上快速识别。

资源也要隔离。多个 Agent 同时编译或启动服务可能争抢内存、端口和数据库。为每个会话设置不同端口和测试数据库，并限制并发数量。

Agent 通知如何开启

通知是可选能力，需要用户先在设备系统中授予通知权限，再为该设备启用通知注册。每台 server 可以单独控制哪些已注册设备接收待审批、任务完成、错误和会话结束等类别。

默认通知正文只说明事件类型。单独的字段开关可以加入 Agent 类型、项目名、会话名以及任务或错误摘要。敏感项目应保留最小正文，锁屏只显示“需要处理”或“任务完成”，解锁后进入应用查看详情。

日常终端连接即使是直连，通知投递仍会经过 QuickTUI Relay 和苹果或谷歌的系统推送服务。用于投递、去重和打开对应本机 profile、session、interaction 的路由标识不受正文开关影响。组织评估隐私时，不能只检查终端数据通道，还要考虑推送元数据。

通知怎样避免噪声

建议只启用待审批、错误和完成通知。普通输出和每次工具调用不应持续提醒，否则用户很快会忽略真正重要的通知。不同 server 分开配置：工作站可启用审批，日志服务器只提醒错误。

项目名和会话名也可能泄露业务信息。使用中性任务编号，避免在名称中写客户、漏洞或内部代号。错误摘要可能包含路径和数据片段，高敏感环境应关闭。

网络和端到端加密

配对后业务连接默认尝试直连，并使用端到端加密。用户仍应让电脑服务只暴露在可信局域网或加密私有网络，不把端口直接开放到公网。系统防火墙限制来源范围，服务以普通用户运行。

端到端加密保护传输内容，不限制终端能执行的命令。已配对手机获得的是实际终端入口，Agent 又继承电脑用户权限。因此最小权限账户、沙盒、容器、受限工作区和开发凭据仍然必要。

公共无线网络可能阻止设备直连或进行客户端隔离。遇到连接失败，不要通过关闭认证解决，应检查路由、私有网络和 server 状态。需要中继时也要保留设备身份校验。

浏览器客户端有哪些限制

浏览器访问只适用于已经持有设备凭据的 profile。当前 server CLI 不会输出新 Web 或 Desktop profile 配对所需的完整载荷，因此新设备应使用原生 App 扫描二维码。不要从开发者工具复制半套凭据尝试手工注册。

浏览器环境还涉及扩展、同步和本地存储风险。共享电脑上使用后应退出并清除 profile，不能让浏览器自动填充终端凭据。组织终端可通过独立浏览器配置和设备管理降低泄露风险。

怎样控制操作权限

QuickTUI 让用户看到真实终端，但工具审批由具体 Agent 提供。Claude Code、Codex 和其他 CLI 的权限选项不同。首次运行应选择保守模式，并在测试仓库验证危险操作确实会停下来等待。

不要允许 Agent 自动推送 Git、发布生产、删除广泛目录或读取用户主目录。把生产凭据从运行账户移除，比在提示中写“不要使用”更可靠。涉及高风险命令时回到电脑复核。

终端中出现来自网页、Issue、日志或仓库文档的命令，不能自动视为用户授权。外部文本可能包含提示注入，Agent 应把它作为数据处理。任何要求上传密钥、关闭安全策略或扩大目录访问的内容都应拒绝。

如何从手机审查结果

QuickTUI 提供真正的终端，而不是所有 Agent 通用的结构化 diff。可以让 Agent 在结束时运行 Git 状态和差异统计，并输出按文件的摘要。小修改可在终端查看，复杂改动应回到代码审查工具。

完成通知只表示进程报告完成，不证明测试通过或实现正确。用户需要检查退出码、失败测试、未跟踪文件和实际差异。不要从手机看到一句“完成”就直接合并或发布。

常见故障排查

安装后找不到 tmux

macOS 与 Linux 安装器不会代装 tmux。运行版本检查，确保至少为 3.2，并确认 quicktui-server 的服务环境能找到可执行文件。Windows 不适用这个检查，它使用 qscn。

二维码可以扫描但无法连接

检查电脑是否在线、server 是否运行、防火墙和网络路由是否允许手机访问。确认手机保存的是当前 server identity；重装或重置服务后可能需要重新配对。

切换网络后画面没有更新

先等待重连并检查会话状态，不要重复启动 Agent。若电脑端 tmux 会话仍有输出，问题位于传输或 profile；若会话已退出，则查看 Agent 退出原因。

收不到完成通知

依次检查系统通知权限、设备通知注册、该 server 的类别开关和系统推送连接。终端直连正常并不证明通知链路正常，因为推送使用独立服务。

浏览器不能添加新设备

这是当前配对限制。先用原生 App 扫描二维码建立完整 profile，再按文档使用既有凭据。不要要求 server CLI 输出它目前没有提供的完整 Web 配对载荷。

怎样撤销访问

手机遗失、转赠或怀疑泄露时，在电脑端撤销对应设备 profile，并停止 server 检查近期会话。只卸载手机 App 不足以证明凭据已失效。检查 Git 日志、工作区修改和终端历史，轮换可能暴露的开发凭据。

不再使用时停止后台服务，移除自动启动并清理只属于 QuickTUI 的配对状态。tmux 中可能仍有 Agent 运行，卸载前先列出会话并逐个正常结束，避免留下无人监督进程。

推荐的实际使用流程

部署阶段使用测试仓库，完成二维码配对、网络切换、会话恢复和通知验证。任务阶段在电脑建立独立工作树与命名会话，给 Agent 明确范围和停止条件。移动阶段只处理必要审批、短澄清和异常中断。验收阶段回电脑审查 diff、运行测试并提交。

QuickTUI 的优势是兼容任意终端 Agent，并直接复用成熟会话后端；代价是权限和结果呈现更多依赖底层 CLI。把真实终端、保活和通知当作远程监督工具，而不是无限制自动执行入口，才能兼顾便利与安全。