5 分钟从零到手机：Collie + Tailscale + Herdr 安装与设备配对的保姆级教程

Collie 是一款自托管的 PWA 手机客户端，让你用手机直接查看并操作运行在 Herdr 终端里的 Claude Code、Codex、OpenCode 等 AI 编程助手。本文带你用 5 分钟完成 Collie 安装、Tailscale 私有组网和手机设备配对，从零把 AI Agent 管理装进口袋。

一、Collie 是什么？为什么值得装？

想象一下：你在家里的电脑上让 Claude Code 跑着重构任务，出门路上它弹出一个权限确认框——没有手机客户端的话，你只能干等。

Collie 解决的就是这个问题。它在你的电脑和手机之间架起一座桥：

• 状态看板（Dashboard）：哪些 agent 在等你输入，永远排在最上面，其他面板按工作区分组
• 直接回复：用系统键盘正常打字回答 agent 的提问，权限提示会变成可点击的按钮
• 特殊按键面板：Esc、Ctrl+C、方向键一拇指搞定
• 推送通知：agent 被阻塞时手机响铃提醒你
• 设备配对（Pairing）：只有配过对的手机才能访问，安全性由你掌控

它的形态是 PWA：不需要 App Store 或 Google Play，浏览器打开、加到主屏幕即可全屏使用，全程无账号云依赖、无遥测。

二、安装前检查清单：3 样东西缺一不可

⚠️先读这条：Collie 的设计就是提供远程 Shell 能力——任何已配对的设备都能以你的用户权限读取面板、发送按键。请把它的 URL 当作 root 登录入口来对待，详见官方安全说明。

三、第一步：安装 Tailscale，搭好私有 tailnet

Tailscale 会把你的主机和手机连进同一个私有网络（tailnet）。Collie 只在这个网络上可达，这是它默认且推荐的“前门”。

Linux 主机上执行：

curl -fsSL https://tailscale.com/install.sh | sh sudo tailscale up --operator=$USER

其中--operator=$USER允许当前用户运行tailscale serve（第四步 Collie 会用到）。Mac 用户安装 Tailscale 应用并登录后，在应用设置中安装tailscale命令行即可。

接下来做两件事：

1. 登录 Tailscale 管理控制台，开启Enable HTTPS——Collie 强制要求 HTTPS
2. 在手机上安装 Tailscale App，用同一个账号登录

至此，电脑和手机已在同一条私有网络里。

四、第二步：安装 Herdr，让终端面板“不死”

Herdr 是终端复用器：它让终端面板和 coding agent 在你断开连接后继续运行，Collie 再把它们镜像到手机上。

curl -fsSL https://herdr.dev/install.sh | sh # macOS 也可以：brew install herdr herdr

Herdr 打开一个面板后，在里面启动你的 agent，例如输入claude。然后让 Herdr 保持运行，不要退出。

五、第三步：一行脚本安装 Collie

在主机上打开第二个终端，执行官方安装脚本：

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

脚本会自动下载当前平台的预编译二进制、校验 sha256 并把collie放到~/.local/bin，全程不需要sudo，也不依赖编译工具链（脚本源码可参考 scripts/install.sh）。如果 shell 提示找不到collie，把~/.local/bin加入 PATH 即可。

六、第四步：collie start 一键启动并暴露到 tailnet

COLLIE_MUX=herdr collie start

这一条命令完成了三件事：

• 在后台启动 Collie bridge（只绑定 loopback，不直接暴露）
• 通过tailscale serve把它发布到你的 tailnet 上
• 记住herdr作为复用器，以后只需运行collie start

就绪后终端会打印Collie is running，tailnet一行给出你的 URL，形如https://myhost.tail1234.ts.net——把它记下来，手机就要访问它。

如果你是通过 SSH 连到远程 Linux 主机，执行下面这条让 Collie 在退出登录后继续运行：

loginctl enable-linger $USER

七、第五步：扫码上手机，完成设备配对

配对是 Collie 的最后一道门，也是最重要的一道：未配对的设备什么都看不到，只会看到“Pair this device”界面。

1）获取二维码：在主机上运行

collie qr

2）手机扫码，在浏览器中打开 Collie。

3）添加到主屏幕，让它像原生 App 一样全屏运行：

• iPhone：Safari 中点「分享」→「添加到主屏幕」→「添加」
• Android：Chrome 中打开 Collie 设置页，点击顶部卡片的Install

4）生成配对码：回到主机执行

collie pair

会打印一个8 位字符的配对码（有效期 10 分钟），同时也会打印一个可直接扫的二维码。

5）在 Collie 里完成配对：打开主屏幕图标 →Settings → System → Paired devices→ 输入配对码和设备名（如my phone）→ 点击Pair this device。

📌易错点：请在主屏幕 App 内完成配对，而不是浏览器标签页里。iPhone 上主屏幕 App 的存储与 Safari 相互独立，在 Safari 里配对了不会带过去。另外，配对码输错 5 次会失效，需要重新运行collie pair。

配对成功后，仪表盘会列出你的 Herdr 面板，等待输入的面板永远置顶。点进面板即可查看输出、用键盘回复、点按钮确认权限。

八、安全三原则，装完务必记住

1. 永远不要tailscale funnel——funnel会把端口暴露到公网，而serve只对你的私有 tailnet 开放。只允许用serve
2. 共享 tailnet 时设置身份白名单：在.env中配置COLLIE_TRUSTED_USER=you@example.com，把访问严格限制到你的 tailnet 账号
3. 设备即凭证，可随时吊销：换手机或设备丢失时，在主机上执行collie devices revoke <label>立即生效；collie devices list可查看哪些设备持有凭证

更多细节见官方安全文档。

九、常见问题与下一步

遇到问题先查故障排查指南，它按你实际会搜索的症状来组织；完整命令参考见命令手册，其他安装方式（Nix、Arch、Windows、源码构建）见安装文档。装好之后的进阶玩法：

• 📱 Claude Code 在 tmux 或 Herdr 中、手机上的完整用法
• 🔔 配置 Web Push 推送通知：agent 一等你输入，手机立刻响铃（语音输入与推送）
• ⚙️ 自定义按键布局、快捷回复、启动器：配置指南

技术内幕：Herdr 适配器的实现位于 bridge/mux/herdr/，它对复用器的轮询与事件流处理遵循 MUX_CONTRACT.md 定义的契约。

5 分钟，3 个工具，1 次扫码——现在，你的 AI agent 牧群已经住进了手机。🐕