跳转至正文
ColliePWA

02/Documentation

在 tmux 或 Herdr 中运行 Claude Code，并从手机进行控制

SSH 断开时让 Claude Code 在 tmux 或 Herdr 中保持运行。通过手机管理会话、确认提示，并发送 Esc 或 Ctrl，支持推送提醒。

SSH 连接断开，Claude Code 随之终止。手机终端键盘缺少 Esc 和 Ctrl 键。一小时后返回，Claude Code 一直停在等待确认的提示上闲置。

本指南解决这三个问题。在 tmux 或 Herdr 中运行 Claude Code，使其在连接断开后继续运行。然后添加 Collie，在手机上优先显示等待处理的会话并提供缺失的按键。

在 tmux 中保持 Claude Code 运行

在 tmux 会话中启动 Claude Code。连接断开时，它会在宿主机上继续运行。

tmux new -s claude       # start a session named claude
claude                   # run Claude Code inside it

使用 Ctrl+b 然后按 d 分离。稍后从任意机器登录并重新连接：

tmux attach -t claude

会话由 tmux 服务端持有，而不是由 SSH 登录持有，因此连接断开不会终止 Claude Code。运行 tmux ls 列出宿主机上的会话。

Herdr

Herdr 是专为编码 agent 构建的终端工作区管理器。其运作方式相同。

curl -fsSL https://herdr.dev/install.sh | sh    # or: brew install herdr
herdr                                           # start Herdr, or reattach to it
claude                                          # in the pane Herdr opens

使用 Ctrl+b 然后按 q 分离，或者直接关闭终端。Herdr 服务端会保持面板和 Claude Code 运行。再次运行 herdr 即可重新连接。

zellij

运行 zellij -s claude，启动 claude，使用 Ctrl o 然后按 d 分离，再通过 zellij attach claude 重新连接。Collie 仅镜像一个 zellij 会话。参见 zellij 说明。

同时运行多个 Claude Code 会话

为每个会话分配独立的窗口和检出目录，避免两个 agent 编辑相同的文件。

# a second checkout, on its own branch
git worktree add ~/src/app-review -b review
tmux new-window -t claude -n review -c ~/src/app-review
claude                                     # in the new window

在 tmux 中，按 Ctrl+b 然后按 c 打开窗口，按 Ctrl+b 然后按 w 列出窗口。按 Ctrl+b 然后按 % 左右拆分面板，按 Ctrl+b 然后按 " 上下拆分面板。

在 Herdr 中，在 Herdr 运行期间为每个 agent 分配独立的工作区：

herdr workspace create --label review --cwd ~/src/app-review

运行多个会话会产生多个等待中的提示。Collie 会将需要输入的面板置于仪表盘顶部，其余面板按工作区归类。长按某一行可将该面板固定在顶部。在 tmux 和 zellij 上，此排序需要来自 步骤 3 的 beacon 钩子。

使用 Collie 在手机上进行控制

Collie 运行在宿主机上，将 Herdr、tmux 或 zellij 面板镜像到手机浏览器。相同步骤适用于 Codex、OpenCode 及任何其他终端 agent。只有面板中的命令发生变化。

注意。 Collie 的设计机制提供对本机的远程 shell 访问。安装前请阅读 安全性。
  • Claude Code 运行在宿主机的 Herdr、tmux 或 zellij 面板中。手机上不运行任何 agent 代码。
  • 手机通过 tailnet 在浏览器中打开 Collie。仪表盘列出各个面板，并优先显示等待中的会话。
  • 你可以查看输出、提交回复，并从按键托盘发送 Esc、Tab、方向键或修饰键。不需要 SSH 客户端。
  • 可选的推送通知会在 agent 需要输入时提醒你。

准备工作

  • 安装了 Claude Code 的 Linux 或 macOS 宿主机。
  • 终端复用器：Herdr、tmux 或 zellij。Herdr 可以直接检测 agent。在 tmux 和 zellij 上，Collie 使用 beacon 钩子，这需要 Linux。
  • 在宿主机和手机上安装 Tailscale，并在 tailnet 上启用 HTTPS。其他配置方式请参见 部署。
  • 一部 iPhone 或 Android 手机。

1. 安装 Collie

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

在 Herdr 上，你可以直接安装插件：herdr plugin install AltanS/collie。安装 介绍了这两种方法。

2. 启动服务

collie start

首次运行会检查 Herdr、tmux 和 zellij，然后将你的选择写入 .env。它会启动 tailscale serve 并输出一个 tailnet URL。参见 启动它。

3. 在窗格中运行 Claude Code

在 Herdr 上，打开一个窗格并运行 claude。Herdr 会将该窗格标记为 Collie 的 agent。

在 tmux 或 zellij 上，每台主机只需安装一次 beacon hook。这让 Collie 能够区分 agent 和普通 shell。接下来，在 Collie 镜像的会话中打开一个窗口或标签页，然后启动 Claude Code：

collie hooks install claude    # once per host, Linux only
tmux new-window -n claude      # or: zellij action new-tab --name claude
claude

除非设置了 COLLIE_MUX_ENDPOINT_TMUX，否则 Collie 会镜像默认的 tmux 服务器。上面提到的 claude 会话会自动出现。

正在运行的 Claude Code 实例不会自动重新加载设置。安装 hook 后请重启 Claude Code。参见 Collie 将 hook 写入 Claude 自身的设置中。

4. 在手机上打开

在主机上运行 collie qr 扫描二维码，或者打开 collie url 中的链接。确保手机处于同一个 tailnet 中。

  1. 配对手机。 在主机上运行 collie pair 并扫描二维码。配对后，手机将获得对窗格的写入权限（配对设备）。
  2. 添加到主屏幕。 在 Android 上，点击“设置”顶部的 安装。在 iPhone 上，点击 Safari 的分享面板。

5. 回复 Claude Code

  • 控制台会将需要输入的窗格排在最上方。点击窗格即可打开。
  • 输入框使用标准文本字段，支持手机语音输入。
  • 点击键盘上方操作栏中的 按键。按键面板包含 Esc、方向键、Enter、Tab、Space、修饰键、数字键以及 F1 至 F12。Esc 和 Ctrl 组合键不依赖手机键盘。
  • Claude Code 按钮位于同一行：Model、Effort、Compact 和 Resume。参见 配置。

6. 接收通知（可选）

collie push-keys     # writes the VAPID keys to your .env
collie restart

在手机上的 Collie 设置中开启通知。需要输入 默认启用。在 iPhone 上，需要先将 Collie 添加到主屏幕。Safari 仅支持向主屏幕 Web 应用发送 Web Push。参见 Web Push。

通过手机访问 Claude Code 的其他方式

  • Claude Code Remote Control 将 Claude 应用或 claude.ai/code 连接到机器上的 Claude Code 会话，其流量经过 Anthropic API（Anthropic 文档）。Collie 则是镜像终端窗格，因此它适用于复用器中的任何 agent，且流量保留在你的 tailnet 内。
  • Termius、Moshi 或 Termux 等 SSH 应用 会显示完整终端。这种方式可行，但移动端键盘上的终端控制键很难用。Esc、Ctrl 和方向键都需要变通解决。

在 GitHub 上编辑本页

The rest of the documentation