手机远程 Vibe Coding 配置教程（Moshi + Herdr + Pi）

Oct 31, 2026 · @eastseven

架构总览

手机只负责连接、查看和审批，Pi 始终在一台常驻开机的主机（本文以 Mac 为例）的 herdr 会话中运行。所有连接都通过 Tailscale，不需要在公网开放任何端口。

架构图

手机有两条通道连到主机：一条是 SSH/Mosh，用来操作终端；另一条是推送通道，由 moshi-hook 读取 Pi 的 hook 事件，经 Moshi 云端推到手机，你在手机上点的审批结果再沿同一条路返回给 Pi。

一、电脑端基础配置

被控主机是一台常驻开机的 Mac，下文用 <用户名> 指代它的登录用户。下面每一步都在这台 Mac 上执行，可以在本机终端里做，也可以从另一台电脑 SSH 进来做。

1. 确认 Tailscale

tailscale status        # 手机和这台 Mac 都应显示在线
tailscale ip -4         # 记下本机的 100.x.x.x 地址

在 Tailscale 管理后台打开 MagicDNS 之后，可以用 <主机名>.<tailnet>.ts.net 代替 IP。

2. 开启 SSH（远程登录）

sudo systemsetup -setremotelogin on
# 或者打开「共享」设置页手动开启：
open "x-apple.systempreferences:com.apple.Sharing-Settings.extension"

在「远程登录 → 允许访问」里确认包含当前用户。系统设置链接前面必须加 open，直接把链接当命令执行会报 command not found。

3. 配置 SSH 密钥

在手机 Moshi 里生成密钥，把公钥追加到 Mac 上：

mkdir -p ~/.ssh && chmod 700 ~/.ssh
echo "<手机公钥>" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

全部跑通以后，可以在 /etc/ssh/sshd_config 里设置 PasswordAuthentication no，关闭密码登录。

4. 安装 Mosh

brew install mosh
which mosh-server       # 应输出 /opt/homebrew/bin/mosh-server

后面执行 moshi-hook host setup 时会检查 mosh-server，找不到会直接报错退出。

5. 防止睡眠

sudo pmset -a sleep 0 disksleep 0

也可以在「系统设置 → 能源」里打开「防止自动睡眠」。主机一旦睡眠，SSH 连接和正在运行的 agent 都会中断。

6. 检查 ~/.config 的权限

ls -ld ~/.config        # 所有者应为当前用户，而不是 root
sudo chown -R $(whoami):staff ~/.config   # 仅在所有者是 root 时执行

如果以前用 sudo 装过工具，这个目录可能变成 root 所有，之后 moshi-hook 会报 mkdir ... permission denied。

二、安装 Herdr 与 Pi

Herdr 让 Pi 常驻后台运行，断网或关掉 App 都不会中断它。Pi 就是实际干活的编码 agent。

# Herdr
brew install herdr
# 或：curl -fsSL https://herdr.dev/install.sh | sh
herdr --version

# Pi
curl -fsSL https://pi.dev/install.sh | sh
# 或：npm install -g @earendil-works/pi-coding-agent（需要 Node.js 22.19+）

pi                              # 首次运行，配置模型和 API Key
herdr integration install pi    # 让 herdr 能准确识别 Pi 的状态
herdr integration status

安装时注意三点：

  • Pi 的 npm 包名已经从 @mariozechner/pi-coding-agent 改为 @earendil-works/pi-coding-agent。
  • 必须先运行一次 pi，让 ~/.pi/agent 目录生成出来，herdr integration install pi 才会写入扩展。
  • 第一次请在 Mac 本机的图形终端里运行 herdr，而不是通过 SSH。这样后台服务从图形会话启动，以后可以避免 Keychain 访问出问题。

herdr 常用操作：

操作命令 / 按键
启动或连接会话cd ~/project && herdr
分离（agent 继续运行）ctrl+b q
重新连接herdr
彻底停止（会结束所有 agent）herdr server stop
查看所有生效的快捷键ctrl+b ?

三、安装并配对 moshi-hook

用 herdr 时 moshi-hook 是必装的。它把 agent 的审批请求和完成事件推送到手机，Moshi 在 herdr 下没有抓屏识别作为后备，不装就收不到任何通知。

1. 安装

brew tap rjyo/moshi
brew trust --formula rjyo/moshi/moshi-hook   # 新版 Homebrew 默认不信任第三方 tap
brew install moshi-hook

2. 写入各 agent 的 hook

moshi-hook install

输出里应能看到 pi -> installed。显示 not found, skipped 的是本机没装的 agent，可以忽略。

中途会询问是否关闭 Codex 的共享后台服务，选 Turn it off。它只在 ~/.codex/config.toml 里写一行 daemon_auto_start = false，可以随时删掉恢复。关掉后每个 Codex 会话独立运行在自己的窗格里，审批不会落到错误的窗格。

3. 配对（推荐用文件存储密钥）

先在手机 Moshi 的「设置 → Agent Hooks」里复制配对 token，然后执行：

moshi-hook pair --token <token> --store file

为什么不用默认的钥匙串：通过 SSH 操作时，macOS 登录钥匙串是锁着的，会报 macOS Keychain is locked。主机重启后如果没人在本机登录，钥匙串也会一直锁着，daemon 照样读不到密钥。存成文件就没有这些问题。

如果要走扫码流程，执行 moshi-hook host setup，并且要先装好 mosh。这个流程会同时配置手机的 SSH 接入。

4. 启动服务并检查

brew services restart moshi-hook
moshi-hook status       # 应显示 paired
moshi-hook doctor       # 所有检查项应为 ✓

doctor 里要确认三项：daemon 在运行、pairing 已完成、tmux/herdr 能找到。只要这三项是 ✓，下面的 Agent inbox、Chat View、Diff viewer 等功能就会一起恢复。

macOS 右上角弹出「App 后台活动」通知是正常现象，说明 moshi-hook 注册成了登录项。不要在「登录项与扩展」里关掉它，否则重启后服务不会自动启动。

四、手机端配置

手机端只需要两个 App：Tailscale 负责组网，Moshi 负责终端、收件箱和审批。

  1. 安装 Tailscale，登录和 Mac 同一个账号，确认显示 Connected。
    • Android 同一时间只能运行一个 VPN。如果状态栏的钥匙图标属于别的代理工具，Tailscale 就会被挤掉，连接一定失败。
    • 如果用主机名连不上、用 IP 能连上，就把「设置 → 网络 → 私人 DNS」关掉或改成自动。私人 DNS 会干扰 MagicDNS。
  2. 从 Google Play 或 App Store 安装 Moshi。
  3. 新建连接：
字段填写
主机主机的 Tailscale IP（100.x.x.x），或 <主机名>.<tailnet>.ts.net
端口22
用户名<用户名>
认证SSH 密钥（公钥已写入主机的 authorized_keys）
Mosh server 路径（如需要）/opt/homebrew/bin/mosh-server
  1. 允许 Moshi 发送通知（Android 在「设置 → 应用 → Moshi → 通知」）。没有通知权限，审批和完成提醒会静默丢失。
  2. iPhone 用户可以在「Moshi → 设置 → Hooks」里打开 Live Activity，在锁屏上直接看到 agent 状态。

关于付费：免费版就有完整的 SSH 终端、无限会话、agent 推送（有频率限制）和语音输入，日常够用。Pro 版每月 7.99 美元或每年 69.99 美元，可用于三台设备，额外提供 Mosh 传输、herdr 多路复用界面、图片粘贴和 diff 查看。

五、验证与日常使用

收件箱里能出现 Pi 任务的卡片，就说明整条链路通了。按下面五步验证一次：

  1. 手机用 Moshi 连接主机。
  2. 执行 cd ~/某个项目 && herdr。
  3. 在窗格里运行 pi，给一个小任务，比如「给 README 加一段说明」。
  4. 锁屏等它完成，看 Moshi 是否收到推送。
  5. 打开 Moshi 收件箱，任务应该出现在「Needs you / Working / Done」其中一栏。

日常使用的几个习惯：

  • 一个项目一个 workspace：手机屏幕小，侧边栏状态清楚才能一眼看出哪个 agent 在等你。
  • 离开时只分离，不停止：按 ctrl+b q 或直接关掉 App，Pi 会在主机上继续跑。herdr server stop 会结束所有 agent。
  • agent 必须在 herdr 里启动：在裸 shell 里运行的 agent，Moshi 无法跟踪。也不要在 herdr 里再套一层 tmux。
  • hook 改动后重启 agent：agent 只在启动时读取 hook 配置。重装或更新 moshi-hook 之后，正在运行的 Pi 要重启一次。
  • 用语音写需求：长任务交给 Pi 自己跑，你只在审批推送或它卡住的时候介入。

六、常见问题与排查

下表是配置过程中常见的报错，按通常出现的顺序排列。

现象原因解决
Refusing to load formula ... from untrusted tap新版 Homebrew 默认不信任第三方 tapbrew trust --formula rjyo/moshi/moshi-hook
zsh: command not found: x-apple.systempreferences...把系统设置链接当成了命令前面加 open
mkdir ~/.config/moshi: permission denied~/.config 的所有者变成了 rootsudo chown -R $(whoami):staff ~/.config，不要用 su 或 root 运行 moshi-hook
mosh-server was not found on PATH没装 moshbrew install mosh
macOS Keychain is locked or unavailable通过 SSH 操作时钥匙串是锁着的moshi-hook pair --token <token> --store file
status: unpaired / doctor 显示 daemon not running还没配对，daemon 启动后马上退出完成配对后执行 brew services restart moshi-hook
doctor 显示 no tmux, herdr ...这台机器上没装 herdrbrew install herdr，然后重启 moshi-hook
手机报 Connection failed: Disconnected远程登录没开、VPN 不是 Tailscale、MagicDNS 被私人 DNS 干扰，或主机在睡眠按第一节第 2 步和第四节第 1 步逐项检查，先改用 IP 连接试试
收件箱一直没反应daemon 没运行，或配对的不是同一个 Moshi 账号moshi-hook doctor，再看 moshi-hook logs -f

还查不出原因时，可以同时打开两组日志对照：

log stream --predicate 'process == "sshd"' --info              # SSH 层：请求有没有到达 Mac
tail -50 ~/Library/Application\ Support/Moshi/hook.log       # moshi-hook 层

最后提醒一点：moshi-hook host setup 生成的 moshi://host/setup?... 链接里带有一次性配对密钥，过期之前不要发到别处。