字节笔记本
2026年10月6日 · 约 23 分钟读完
Pi + Herdr：VPS 手机远程跑 AI Agent
最近社区里有开发者分享了一套远程操控方案：在 VPS 上跑 Pi coding agent，用 Herdr 监控每个 Agent 的 idle/working 状态，再配一个网页面板，人不在电脑前，手机上也能看清 Agent 是在干活还是在等着，该输入指令的时候输入，不该重复发送的时候就不发。
这套方案解决了一个很多人都在头疼的问题：AI coding agent 跑在服务器上，人不在电脑前，怎么远程管？
本文整理了 Pi、Herdr 和整个生态里的几种 Web Dashboard 方案，从零开始，手把手教你怎么搭。
相关项目：Pi Coding Agent | Herdr | pi-dashboard
先搞清楚三个组件各自干什么
在动手之前，先理解三个东西的角色：
| 组件 | 干什么的 | 类比 |
|---|---|---|
| Pi | 开源 coding agent CLI，跑在你的项目里，读代码、改文件、执行命令 | 一个很聪明的程序员，住在终端里 |
| Herdr | Agent 多路复用器，tmux for AI agents，监控每个 Agent 的状态 | 程序员的工位管理器，一眼看到谁在忙、谁在等 |
| Web Dashboard | 把 Pi 的会话状态推到浏览器，手机上可操作 | 给工位装了摄像头和对讲机，你在外面也能管 |
数据流是这样的：
Pi (coding agent)
→ Herdr (监控 idle/working/blocked/done)
→ Web Dashboard (推到浏览器/手机)
→ 你 (看到状态，决定操作)Pi 是什么：极简 Agent Harness
Pi 是一个开源的 coding agent CLI。它的设计哲学是 "primitives, not features"：不给你封死的黑盒产品，而是给你原语，你自己组装。
核心特点：
- 模型无关：支持 Anthropic、OpenAI、Google、Ollama 等 15+ 个 provider，几百个模型
- 四种模式：Interactive（交互）、Print/JSON（脚本）、RPC（进程间通信）、SDK（嵌入你的应用）
- 树形会话历史：每次对话是一棵树，可以回到任意分叉点继续
- 上下文工程：AGENTS.md、SYSTEM.md、Skills、Prompt Templates、动态上下文，全部可控
- 可自修改：让 Pi 自己改自己的配置，
/reload一下继续用
安装：
# npm
npm install -g @mariozechner/pi-coding-agent
# 或用 pi-dashboard 的桌面应用，会自动安装 pi
# 下载地址: https://pi-dashboard.dev启动：
cd your-project
pi进去后就是一个交互式 TUI。你可以开始跟 Pi 说话，它会读你的代码、改文件、跑命令。
Herdr 是什么：tmux for AI Agents
Herdr 解决的问题是：当你同时跑多个 Agent（或者一个 Agent 跑多个任务），怎么一眼看到它们的状态？
它是 Rust 写的单二进制文件，活在你的终端里，不是 GUI 应用，也不是 Electron。和 tmux 的核心区别是：Herdr 知道它管理的进程是 AI Agent，能识别 Agent 的状态。
安装：
# curl
curl -fsSL https://herdr.dev/install.sh | sh
# 或 homebrew
brew install herdr
# 或 mise
mise use -g herdrHerdr 的四种状态
Herdr 的侧边栏会实时显示每个 Agent 的状态：
- blocked：Agent 需要你的输入或审批，比如要确认一个危险操作
- working：Agent 正在干活，读代码、改文件、跑测试
- done：任务完成了，你还没看
- idle：你已经看过结果了，Agent 空着等你
社区方案里手机端显示 idle/working 状态，用的就是这个机制。
Herdr 的核心操作
# 启动（在项目目录里）
herdr
# 在根 pane 里启动 pi
pi
# 新建 workspace（ctrl+b, shift+n）
# 分屏（ctrl+b, v 或 -）
# 新建 tab（ctrl+b, c）
# 切换 workspace（ctrl+b, w）
# detach（ctrl+b, q）：Agent 继续跑，你可以关终端
# 重新连接
herdr
# 安装 Pi 集成（让 Herdr 原生识别 Pi 的语义状态）
herdr integration install piHerdr vs tmux：为什么不用 tmux 就行？
| 能力 | tmux | Herdr |
|---|---|---|
| 持久会话 | 有 | 有 |
| detach/reattach | 有 | 有 |
| panes、tabs、workspaces | 有 | 有 |
| Agent 状态感知 | 无 | 有 |
| 活在终端里 | 有 | 有 |
| 鼠标原生支持 | 无 | 有 |
| 轻量二进制 | 有 | 有 |
| Agent 可以控制 Herdr | 无 | 有 |
最后一条很关键：Herdr 暴露了一个 Unix socket API，Agent 本身可以创建 workspace、分屏、spawn 子进程、等待状态变化。Agent 可以管理自己的工作环境。
VPS 部署：从零到能手机操控
下面是完整步骤。假设你有一台 VPS（任何 Linux 服务器都行），有 SSH 访问权限。
Step 1：在 VPS 上安装 Pi
ssh your-server
sudo apt update && sudo apt install -y nodejs npm # Debian/Ubuntu
npm install -g @mariozechner/pi-coding-agent
# 配置 API key（以 Anthropic 为例）
export ANTHROPIC_API_KEY=sk-ant-xxxx
# 测试
cd /root/my-project
pi能进去 Pi 的交互界面就算成功。
Step 2：安装 Herdr
curl -fsSL https://herdr.dev/install.sh | sh
herdr integration install piStep 3：用 Herdr 启动 Pi
cd /root/my-project
herdr
# 进入 Herdr 后，在根 pane 里启动 pi
pi现在 Herdr 的侧边栏应该显示 Pi 的状态了。
Step 4：部署 Web Dashboard（三种方案选一种）
方案 A：pi-dashboard（推荐，功能最全）
pi-dashboard 是目前 Pi 生态里最成熟的 Web Dashboard。它是一个桥接扩展，装在每个 Pi 会话里，把事件转发到一个本地服务器，再推到浏览器。
# 方式 1：桌面应用（自带 Node.js 和 pi）
# 下载 https://pi-dashboard.dev 的 macOS/Linux/Windows 安装包
# 方式 2：npm 包安装
pi install npm:@blackbelt-technology/pi-agent-dashboard
# 方式 3：独立安装
git clone https://github.com/samfoy/pi-dashboard
cd pi-dashboard
npm install
npm start功能一览：
- 多会话视图：所有 Pi 会话并排显示
- 实时聊天镜像：prompt、response、tool call、streaming token 全部零延迟推到浏览器
- 交互式对话框：confirm/select/input 对话框可以在浏览器里回复
- 内置终端：每个 workspace 一个 xterm.js 终端
- Diff 查看器：split-pane diff，看 Agent 改了什么
- 手机优化：双面板布局、滑动返回、触控菜单
- mDNS 发现：局域网内自动发现 Dashboard
- QR 码远程：一键开 zrok 隧道，扫码就连
远程访问（手机从外面连 VPS）：
# 在 VPS 上开 tunnel
# pi-dashboard 内置 zrok 集成，点一下就开
# 或手动用 SSH tunnel
ssh -L 3000:localhost:3000 your-server
# 然后手机浏览器访问 localhost:3000
# 或用 Caddy/Nginx 反代 + HTTPS
caddy reverse-proxy --from pi.yourdomain.com --to localhost:3000方案 B：Paseo（开源手机/桌面 App）
# Paseo 是专门为 Pi 做的手机/桌面客户端
# 自托管，开源
# 地址：https://paseo.sh/pi方案 C：自建简易 Web 端
这位开发者的做法是自己写一个简单的网页端，利用 Herdr 的状态数据来显示 idle/working。好处是完全定制，坏处是要自己动手。
如果你要走这条路，核心思路：
// Herdr 暴露 Unix socket API
// 你可以写一个小服务读取 socket 数据，推到 WebSocket，前端监听
// 伪代码思路：
// 1. 用 Node.js 连接 Herdr 的 Unix socket
// 2. 解析 Agent 状态事件
// 3. 通过 WebSocket 推到前端
// 4. 前端显示 idle/working 状态
// 5. 用户在前端输入指令，通过 WebSocket 回传到 PiStep 5：手机上操控（完整链路）
部署完成后，你的操作链路是：
手机浏览器打开 pi-dashboard URL
→ 看到 Pi 会话状态（idle/working）
→ idle 时：输入指令，开始新任务
→ working 时：看实时输出，不重复发送
→ blocked 时：在手机上点击 approve/reject
→ done 时：review diff，决定是否 merge手机上的 UX 关键细节：
idle/working 状态指示器要放在输入框附近（底部），不要放在页面顶部。因为手机输入时键盘会弹起来，如果状态指示器在顶部，你根本看不到它。
+---------------------+
| |
| Agent 输出区域 |
| （可滚动） |
| |
+---------------------+
| idle / working | <- 状态指示器，放在输入框上方
| [输入框] [发送] |
+---------------------+全部代理方案对比：5 种远程操控 Pi 的方式
整理了目前社区里所有方案，你按需求选：
| 方案 | 适合场景 | 手机体验 | 部署复杂度 | 开源 |
|---|---|---|---|---|
| pi-dashboard | 最全面的 Web 方案 | 优秀：双面板、触控优化 | 中（npm 一行装） | 是 |
| Herdr + SSH | 纯终端玩家 | 一般：配 Moshi SSH 客户端 | 低 | 是 |
| Paseo | 想要原生 App | 良好：原生体验 | 中 | 是 |
| TelePi (Telegram Bot) | Telegram 重度用户 | 优秀：Bot 对话式操控 | 中 | 是 |
| Pi Pulse | 轻量远程控制 | 良好：状态加控制 | 低 | 未知 |
TelePi 方案（Telegram Bot）
如果你不想开浏览器，想在 Telegram 里直接操控 Pi：
# TelePi 是社区项目
# 项目地址搜索 "TelePi pi coding agent"
# 核心原理：跑一个 Telegram Bot，消息转发给 Pi，Pi 的输出推回 Telegram这个方案的体验很像和 Agent 聊天，因为 Telegram 本来就是聊天 App，交互方式非常自然。
SSH + Moshi 方案（最简单）
什么都不装，直接用 SSH：
# VPS 上
herdr
pi
# 手机上装 Moshi（iOS/Android SSH 客户端）
# SSH 连到 VPS，直接在手机终端里用 Herdr最简单，但没有图形界面，手机上操作体验一般。
成本估算：这个方案要花多少钱
VPS 选择
| 配置 | 用途 | 月费 |
|---|---|---|
| 1C1G（最入门） | 跑 Pi + Herdr 足够，模型推理在云端 | $3-5 |
| 2C2G（推荐） | 多个 Agent 并行 + Dashboard | $8-12 |
| 4C4G（重度用户） | 同时跑 3-5 个 Agent + 本地模型 | $20-30 |
注意：Pi 本身不吃多少资源，真正的计算量在 LLM API 那边。VPS 只是一个终端容器 + Dashboard 服务器。
API 费用（大头）
Pi 只是调 API，费用取决于你用的模型：
- Claude Sonnet: ~$3/百万 token（输入），$15/百万 token（输出）
- GPT-4o: ~$2.5/$10
- Gemini Flash: ~$0.075/$0.30（最便宜）
- 本地 Ollama: 免费（但需要本地 GPU）
一个月重度使用（每天 2-3 小时），API 费用大概 $20-80，取决于模型选择。
总成本
| 场景 | VPS | API | 合计/月 |
|---|---|---|---|
| 轻度（每天 1 小时） | $5 | $10-20 | $15-25 |
| 中度（每天 2-3 小时） | $10 | $30-60 | $40-70 |
| 重度（全天跑 Agent） | $20 | $80-200 | $100-220 |
进阶技巧
1. 多 Agent 并行
Herdr 的核心卖点就是多 Agent 管理：
herdr
# 在第一个 pane 里：pi
# ctrl+b, v 分屏
# 在第二个 pane 里：pi（另一个项目）
# ctrl+b, shift+n 新建 workspace
# 在第三个 workspace 里：pi（第三个项目）
# Herdr 侧边栏同时显示三个 Agent 的状态2. Agent 控制 Herdr
装了 Pi 集成后，Pi 可以通过 socket API 控制 Herdr：
# Pi 的 SKILL.md 里可以加这些能力：
- 创建新 workspace 来处理子任务
- 在新 pane 里启动辅助工具（linter、test runner）
- 等待某个 pane 的进程完成
- 根据其他 pane 的输出做决策这意味着 Agent 可以自己管理自己的工作空间，不需要你手动分屏。
3. 会话持久化
# Herdr detach 后 Agent 继续跑
# ctrl+b, q
# 关掉终端，关掉电脑
# 第二天回来
ssh your-server
herdr # 重新连接，所有 Agent 还在跑
# Pi 的会话也是树形持久化的
# /tree 可以回到任意历史节点4. 模型热切换
Pi 支持会话中切换模型：
# Pi TUI 里
/model claude-sonnet-4-20250514 # 切到 Claude Sonnet
/model gpt-4o # 切到 GPT-4o
/model gemini-2.5-flash # 切到便宜的快速模型
# Ctrl+L 快速切换，Ctrl+P 循环收藏的模型简单任务用便宜模型，复杂任务用贵模型，在同一个会话里灵活切换。
5. 自定义 Skills
Pi 的 Skills 和 Claude Code 的 Skills 类似，放在项目目录里自动加载：
cd your-project
mkdir -p .pi/skills
# 写一个 Skill
cat > .pi/skills/review.md << 'EOF'
---
name: review
description: Review-first: check code quality before committing.
---
# Steps
1. Read the changed files
2. Check for bugs, edge cases, naming issues
3. Verify tests cover critical paths
4. Write findings as a checklist
EOF
# Pi 会自动识别并加载
pi
# 然后在对话里输入 /review 触发我推荐的入门路径
如果你想现在就动手：
第一周：本地装 Pi，熟悉交互。跑几个小项目，体验一下。
第二周：装 Herdr，学会多 Agent 管理。体验 detach/reattach。
第三周：买一台 $5/月的 VPS，把 Pi + Herdr 部署上去。
第四周：装 pi-dashboard，配好 HTTPS，用手机连上去。开始真正的远程 Agent 工作流。
第二个月：开始用 TelePi 或 Paseo，找到最适合你的操控方式。
第三个月：探索 Agent 控制 Herdr 的能力，让 Agent 自己管理工作空间。
参考资源
- Pi Coding Agent 官网
- Herdr: agent multiplexer (GitHub)
- pi-dashboard: Your pi agents, in the browser
- Paseo: Pi Agent Mobile and Desktop App
- TelePi: Telegram Remote Control for Pi
- Pi Pulse: Remote Control for pi.dev Agents
- BlackBeltTechnology/pi-agent-dashboard (GitHub)
- samfoy/pi-dashboard (GitHub)
- Pi: The Minimal Agent Within OpenClaw（lucumr.pocoo.org）
- How I built a dev server that runs on half a lightbulb（bhave.sh）
