手机通过 Tailscale 内网以 PWA 网页驱动终端多路复用器中的 AI 代理

方案简介

ColliePWA 是一个开源（MIT）的移动端 Web 应用（PWA），用于在手机上驱动运行于终端多路复用器（Herdr、tmux、zellij）中的 AI 代理，如 Claude Code、Codex 和 OpenCode。每个 Collie 实例连接到一个多路复用器，默认通过 Tailscale 对外服务。你在 iPhone 或 Android 手机上打开 URL，即可查看哪个代理需要输入，并直接用手机键盘回应。

它解决的问题是：通常做法是用 Termux SSH 进主机再 attach 到多路复用器会话，但在触屏上操作 TUI 很笨拙——特殊按键难按，Ctrl/Esc/方向键需要别扭的组合键，纯文本输入也和软键盘冲突。Collie 提供的是移动界面：点一下需要输入的代理，正常打字，一个拇指即可发送 Esc 或 Ctrl+C。

该方案适合在终端多路复用器中运行 AI 代理、并希望从手机恢复会话的开发者。方案假定有一个 Tailscale tailnet，手机与主机必须共享同一 tailnet，且 tailscale serve 配置为默认入口。Collie 是单用户设计：只支持一个 tailnet 上的一名操作者，不提供多租户认证。

亮点与能力

• React Router + Vite 技术栈，配合 TypeScript、Tailwind、shadcn 和 Bun bridge
• 状态仪表盘：以需要你输入的代理为先，其余窗格归入各自的工作区和标签行
• 推送通知：当代理阻塞等待用户输入时提醒
• 快捷操作与斜杠命令：可按代理逐一配置
• 终端控制键小键盘：Esc、Ctrl+C、方向键及修饰键组合
• 输出搜索与超出标准终端回滚范围的完整对话历史
• 文件附件：相册中的图片，以及 markdown、文本和代码文件
• 设备配对作为写凭据：设备配对后，每次写入都需要其令牌
• Crews：多台机器的 Collie 收拢在一个 URL 之后，支持操作者触发的故障转移
• 六种 UI 语言和按设备设置的字体
• Herdr 会话切换可直接在网页界面完成
• PWA 支持，本地 loopback 运行，无外部账号或云依赖

组成与分工

• ColliePWA：自托管的移动端 Web 客户端，把多路复用器中的窗格渲染为可点按的移动界面，转发按键与输入
• Herdr：1.0 的主要支持目标，会话切换可从网页界面管理
• tmux / zellij：实验性支持的终端多路复用器，承载 AI 代理的终端会话
• Tailscale：默认入口，通过 tailscale serve 把 Collie 暴露给你私有 tailnet 中的手机
• Claude Code / Codex / OpenCode：被驱动的终端 AI 代理
• React Router + Vite（TypeScript、Tailwind、shadcn、Bun bridge）：Web 客户端的前端技术栈

前置要求

• 一台运行多路复用器与 AI 代理的主机，以及与你共享 tailnet 的手机
• 主机需安装 Tailscale 并配置 tailscale serve 作为默认入口
• 安装脚本需要 curl、tar 和一个 sha256 工具，不需要编译工具链，也不需要 sudo
• Herdr 为 1.0 主要支持目标；tmux 与 zellij 为实验性支持

实施步骤

在主机上（不是手机上）运行官方安装脚本：

bash
curl -fsSL https://colliepwa.dev/install.sh | sh

该脚本会下载适用于你平台的最新发行版，校验 sha256 校验和，安装文件，并把 collie 放入 PATH。随后它会打印剩余的手动步骤：先生成一份配置，再运行 collie start。

你无需提前指定多路复用器。首次运行 collie start 时会检测 Herdr、tmux 和 zellij，然后提示你选择。

如果你偏好从源码构建，docs/install.md 涵盖了手动构建以及各系统的安装说明。

使用与配置要点

• 在手机浏览器打开 Collie URL，仪表盘会把需要输入的代理排在顶部；可以查看空间、标签和窗格
• 长按窗格胶囊或标签可以重命名或关闭；Claude 窗格会反映通过 /rename 设置的名字
• 按住仪表盘行或窗格胶囊（或用鼠标右键）可将该窗格固定到仪表盘和切换器顶部
• 点按即可回答 AskUserQuestion 提示；代理自身的提示会变成可点按的按钮
• 可在多路复用器/herd 之间切换，并在代理阻塞等待输入时收到推送通知
• 一键回复来自 quick-replies.toml 配置
• 外观、语言、字体可按设备在设置中调整

注意事项与常见问题

• Collie 天生提供对你机器的远程 shell 访问：单个 Collie API 调用会把任意按键直接发送进活动的终端窗格。任何能访问该 URL 的人都可以读取窗格输出（源码、机密、环境变量、代理输出），并以你的完整用户权限执行任意命令。没有沙箱，也没有命令白名单，因为这些会破坏核心工作流。
• 把 URL 当作 root 登录对待：严格绑定到 tailnet，设置 COLLIE_TRUSTED_USER，只配对你正在使用的实体手机。
• 绝不要 tailscale funnel：funnel 会把端口暴露到公网，而 serve 把访问限制在你的私有 tailnet。任何情况下都不要 funnel Collie。
• Collie 是单用户的：支持一个 tailnet 上的一名操作者，无多租户认证，不要用于共享或公开访问。
• tmux 和 zellij 支持为实验性：两者都能运行，但测试仅限于一名操作者在一台机器上；如使用遇到 bug 欢迎报告。
• 内置语音输入在显式配置之前保持禁用状态。

优缺点

• ✓ 手机上直接响应代理请求
• ✓ 无外部账号无云依赖
• ✕ tmux/zellij 支持为实验性
• ✕ 提供远程 shell，无沙箱

出处

本方案挖掘自开源项目 AltanS/collie，方案内容与实施命令均来自其 README 原文。