第 10 篇 · 常见问题解答（FAQ）
遇到问题时来这一篇找答案。按类别分类，方便查找。
10.1 安装问题
Q1：pi 不是内部或外部命令 / pi: command not found
原因：npm 的全局安装目录没加入系统路径（PATH）。
解决：
终端运行：
npm config get prefix，记下显示的路径（比如C:\Users\你的用户名\AppData\Roaming\npm）把该路径加入系统环境变量 PATH（方法见 第 2 篇 的排错小节）
重新打开终端再试
pi --version
Q2：安装 Pi 时卡住 / 很慢
原因：npm 从国外服务器下载，国内可能慢。
解决：把 npm 换成国内镜像源（淘宝镜像），终端运行一次：
BASH
npm config set registry https://registry.npmmirror.com
然后重新安装 Pi。
Q3：node --version 没反应 / 报错
解决：Node.js 没装好。重新下载 LTS 版安装（https://nodejs.org），装完**重启终端**。
10.2 登录问题
Q4：/login 后浏览器打不开
解决：
手动复制终端提示的网址，粘贴到浏览器打开
如果授权页面显示"无法访问"，可能是网络问题，检查代理/网络
Q5：提示密钥无效 / API key invalid
解决：
检查密钥是否复制完整（前后没有空格）
确认密钥是对应公司的（比如 Anthropic 的密钥不能用在 OpenAI 上）
密钥可能有有效期，去官网重新生成一个
Q6：提示"model not supported"（模型不支持）
解决：
可能是你的订阅级别不包含该模型，换一个型号试试（
/model）GitHub Copilot 的话：去 VS Code 里 Copilot Chat → 模型选择器 → 启用该模型
10.3 使用问题
Q7：Pi 卡住不动了 / 没反应
解决：
按
Esc取消当前操作还不行就
Ctrl + C两次退出，重新启动（会话会自动保存，用pi -c继续）
Q8：对话太长，Pi 好像"失忆"了
原因：AI 的"短期记忆"满了。
解决：
输入
/compact手动压缩（把旧内容总结掉）或
/new开新会话，把关键背景重新说一遍
Q9：Pi 乱改我的文件 / 干了我没让干的事
解决：
在重要文件夹使用前，先告诉 Pi："只读，不要修改任何文件"
或启动时限制工具：
pi --tools read,grep,find,ls（只读模式）重要文件建议用 Git 管理版本，出问题能回退
Q10：怎么让 Pi 只说中文？
解决：在对话里明确说"请用中文回复"，或写进项目说明文件 AGENTS.md：
MARKDOWN
- 所有回复请使用中文
Q11：!命令 提示命令不存在
解决：Pi 运行在 bash 环境（Git 自带的），Windows 的 dir、copy 等命令 在 bash 里对应的名字不同（如 dir → ls，copy → cp）。 小白不用纠结，直接用中文让 Pi 干活，它会自己选对命令。
10.4 会话与数据
Q12：聊天记录存在哪？能备份吗？
位置：C:\Users\你的用户名\.pi\agent\sessions\
备份：直接复制这个文件夹即可。
Q13：卸载 Pi 会删掉聊天记录吗？
不会。卸载只删程序，~/.pi/agent/ 文件夹（设置、记录、密钥）都会保留。
Q14：怎么彻底删除 Pi 的所有数据？
npm uninstall -g @earendil-works/pi-coding-agent卸载程序手动删除文件夹
C:\Users\你的用户名\.pi\agent\（里面包括登录密钥，删除前想清楚）
10.5 模型与费用
Q15：用 Pi 要花钱吗？
Pi 软件本身免费。花钱的是 AI 服务：
订阅方式：每月固定费用（如 Claude Pro）
API 密钥方式：按使用量扣费
在 Pi 里输入
/session可以看到当前会话的用量和费用。
Q16：哪种模型适合小白？
建议：直接用默认模型。不同模型的差别主要在速度、深度、价格， 默认的就是"综合最优"。
Q17：怎么限制花费？
用小一点的模型（价格低）
思考级别调到
off或minimal（省 token）注意别让 Pi 做超大任务（比如"分析整个硬盘"）
10.6 环境与网络
Q18：需要"梯子"吗？
取决于你用的 AI 服务：
国外服务（Claude、OpenAI、GitHub Copilot）：可能需要代理
国内服务（Kimi、MiniMax、通义等）：不需要
有代理的话，可以在设置里配置（见 第 9 篇 的网络代理小节）。
Q19：Pi 每次启动都联网检查更新，能关吗？
关更新检查：设置环境变量
PI_SKIP_VERSION_CHECK=1完全离线：
PI_OFFLINE=1关遥测：设置文件里
"enableInstallTelemetry": false
10.7 其他
Q20：可以和朋友分享我的对话吗？
可以！
/export 名字.html→ 导出成网页文件发给朋友/share→ 生成一个分享链接
Q21：Pi 和 Claude Code / Cursor 有什么区别？
Pi 是一个极简、可深度定制的终端助手：
核心功能精简，不内置一堆花哨功能
一切都可以通过"技能/扩展/包"按需添加
适合喜欢自己掌控一切的用户
Q22：哪里能找到更多帮助？
Pi 的完整官方文档（英文）在你电脑里就有：
PLAINTEXT
C:\Users\Administrator\AppData\Roaming\npm\node_modules\@earendil-works\pi-coding-agent\docs\
README.md—— 总览docs\quickstart.md—— 快速开始docs\usage.md—— 使用手册docs\settings.md—— 设置说明docs\keybindings.md—— 快捷键docs\sessions.md—— 会话docs\providers.md—— 登录和提供商docs\models.md—— 自定义模型
🎉 结语
恭喜你读完了整套教程！
记住核心三句话：
在项目文件夹里输入
pi启动直接用中文说出你想让 Pi 做的事
会话自动保存，
pi -c随时继续
剩下的，就是在使用中慢慢探索了。祝你玩得开心！🚀