Pi Coding Agent 是那种很适合在“真正的”电脑上运行的工具：

• 仓库在本地
• 工具在本地
• 长时间会话很常见

然后你会有那个常见的愿望：

你想用手机看一眼。

不是要做一整套重构。

只是想：

• 看它在做什么
• 看它是否需要输入
• 发一条纠正

这份指南是让这一切变得合理可控的 Pi 专项工作流。

常见做法及其权衡

• 用手机 SSH

• 远程桌面

• 等着

• Happier：提供一个手机界面，用于查看进度、处理审批和发送一条后续消息。 权衡：它仍然依赖运行会话的电脑保持在线。

如果你第一次接触 Happier（它是什么，在哪里获取）

如果你之前没见过 Happier：它是一款面向编码会话的开源配套应用（移动端/网页/桌面）。

开始设置：

• GitHub: https://github.com/happier-dev/happier
• 安装/下载: https://github.com/happier-dev/happier#how-it-works
• Discord: https://discord.gg/W6Pb8KuHfg

简要总结

1. 在要运行会话的电脑上安装 Pi（pi --version）。
2. Pi 的认证基于环境变量（没有交互式登录流程）。
3. 如果你使用的系统支持已连接的凭据，选择一个兼容的配置（OpenAI Codex 订阅 OAuth、OpenAI API 密钥等）。
4. 如果检测不到 Pi，把 HAPPIER_PI_PATH 设为 pi 可执行文件的绝对路径。
5. 用适合手机的会话界面监控、审批并发送后续消息。

问题所在

Pi 和很多提供商不同，应用内没有“登录”这一步。

这不是 bug。

而是一种凭据模型：

• Pi 从基于环境变量的来源读取支持的凭据

所以手机工作流不是“从手机登录”。

而是：

• 确保电脑上有正确的凭据
• 然后用手机跟进会话

第 1 步：安装 Pi Coding Agent

根据提供商文档：

npm install -g @mariozechner/pi-coding-agent
pi --version

或者通过 hstack：

hstack providers install pi
pi --version

（如果你没听说过 hstack：它是 Happier 生态中的可选辅助工具，可以帮你安装提供商的 CLI。它不是必需的，npm install -g ... 完全可以。）

第 2 步：认证模型（仅环境变量）

Pi 是“凭据在电脑上，而不在聊天界面里”的一个清晰例子。

在源码中，Pi 认证探测标记为 piEnvOnly。

你应该假定的行为是：

• 如果那台电脑上有基于环境变量的凭据，Pi 就能运行
• 如果没有，就不能

实用凭据检查清单

在要运行 Pi 的电脑上：

1. 确认 pi --version 能运行。
2. 决定你使用哪种凭据：
   • OpenAI Codex 订阅 OAuth（已连接）
   • OpenAI API 密钥
   • Anthropic API 密钥
   • Claude 订阅 setup-token 配置（不是 OAuth）
3. 启动一个小会话，确认可以发送后续消息。

只要成功一次，手机工作流就很简单：监控、审批、推一下。

第 3 步：已连接凭据配置（可用时）

Pi 在启动时可以复用已连接服务（Connected services）的配置：

• openai-codex（订阅 OAuth）
• openai（API 密钥）
• claude-subscription 仅限 setup-token（以环境变量形式提供令牌）
• anthropic（API 密钥）

提供商文档中的重要限制：

• Pi 不接受 Claude OAuth 配置，请改用 setup-token 配置。

第 4 步：用 HAPPIER_PI_PATH 修复“找不到 pi”

如果 pi --version 在终端里能用，但应用检测不到 Pi，设置：

• HAPPIER_PI_PATH

这个覆盖在 CLI 测试中有实际覆盖。

第 5 步：手机工作流

可行的手机工作流刻意保持精简。

1. 打开会话
2. 检查它是否在等待审批
3. 发送一条后续消息
4. 离开

手机上该做什么（以及不该做什么）

适合在手机上做的：

• 审批
• 简短的约束（“下一步后停下”“先总结”）
• 快速检查差异

不建议在手机上做的：

• 大型重构
• 需要大量复制粘贴的事
• 无法核实路径或命令的事

适合 Pi 的三条可复制后续消息

1. 检查点

完成下一步后停下来，并总结：

• 你改了什么
• 你没改什么
• 你接下来想做什么

2. 约束

不要碰迁移和认证代码。如果你觉得必须改，先停下来问我。

3. 验证

继续之前，把你接下来要运行的确切命令贴出来，并解释原因。

如果 Pi 需要真正的终端操作，就等回到键盘前再处理。

如果你第一次接触 Happier

如果你之前没见过 Happier：它是一款开源配套应用，用于在电脑上运行 Pi 这类会话，并用手机监控。

开始设置：

• GitHub: https://github.com/happier-dev/happier
• 安装/下载: https://github.com/happier-dev/happier#how-it-works
• Discord: https://discord.gg/W6Pb8KuHfg

故障排查

检测不到 Pi

• 验证 pi --version
• 重启应用
• 设置 HAPPIER_PI_PATH

Pi 提示缺少凭据

把它当作那台电脑上的凭据问题：

• 确认你选择了哪个配置（如果你在用已连接的配置）
• 确认那台机器上有哪些环境变量或令牌

我用了 Claude OAuth，Pi 还是无法运行

这是预期的。

Pi 可以接受 Claude setup-token 配置，但不接受 Claude OAuth。

常见问题

为什么不能直接“从手机登录”？

因为 Pi 使用基于环境变量的凭据模型。

凭据存放在电脑上，而不是手机界面里。

相关指南

• 如何在多台电脑上使用同一个 Codex 订阅（不用在每台电脑上重新登录）