Pi Agent安装教程：macOS/Windows/Linux三步装好AI编程助手（含Gatekeeper拦截破解）-平芜编程栈

【免费下载链接】pi-agent-desktop

Pi — A cross-platform AI coding agent, bringing the Claude Code experience to your desktop. No environment setup, no terminal commands. Download and start coding right away.

项目地址：https://gitcode.com/gh_mirrors/pi/pi-agent-desktop

点击查看免费下载

Pi Agent 是一款跨平台的AI 编程助手桌面应用，它把 Pi Agent 的智能体能力封装成开箱即用的独立安装包——无需配置环境、无需敲终端命令，下载后即可让 AI 帮你读代码、改文件、执行工具调用。本文是一份面向新手的 Pi Agent 安装教程：在 macOS、Windows、Linux 上只需三步就能装好，并重点解决 macOS 首开时被 Gatekeeper 拦截、Windows 缺 WebView2 等常见拦路虎。

装好之后你会看到这样的界面：左侧按项目管理历史会话，中间实时展示 Agent 的思考、bash/文件读取等工具调用、上下文用量与成本，右侧可预览源码、Diff 与文档。

一、系统要求：你的电脑能装 Pi Agent 吗？

先对号入座，Pi Agent 官方构建支持以下平台（详见 README.zh-CN.md）：

平台	最低要求	安装产物
macOS	macOS 11+，仅限Apple Silicon（M 系列芯片，无 Intel 版）	`aarch64.dmg`
Windows	Windows 10/11 x64	以`x64-setup.exe`结尾的安装程序
Linux	x64 发行版，需WebKitGTK 4.1 + GTK 3	`.deb`包（另有社区 Flatpak）

✅ 好消息：安装包已内置 Next.js 服务、Node.js 运行时与 Pi SDK，打开 App 即自动启动本地服务，你完全不需要单独安装 Node.js。

二、第 1 步：macOS 安装 Pi Agent

2.1 下载 aarch64.dmg 并拖入 Applications

从官方 Release 页面下载Apple Silicon对应的aarch64.dmg（官方不为 Intel Mac 构建）；
双击打开磁盘映像，把Pi Agent图标拖进Applications（应用程序）文件夹即可。

2.2 Homebrew 一键安装

如果你用 Homebrew 管理 Mac 软件，也可以从本仓库的 tap 安装，之后直接执行：

brew install --cask pi-agent

首次使用需先添加本仓库的 tap（完整命令见 README.zh-CN.md，只需执行一次）。Cask 定义见 Casks/pi-agent.rb。App 会在「设置」里自行升级，brew upgrade默认不会动它；brew uninstall --cask --zap pi-agent可彻底移除（不会删除与 pi CLI 共用的~/.pi数据）。

2.3 Gatekeeper 拦截破解：首开"已损坏/无法验证开发者"怎么办？

⚠️ 这是 macOS 新手最常踩的坑：Pi Agent 目前尚未使用 Apple Developer ID 签名和公证，所以首次打开可能被系统拦下，提示"无法验证开发者"或"已损坏，无法打开"（Homebrew 安装也一样）。两种解法任选其一：

方法 A（图形界面）：进入「系统设置 › 隐私与安全性」，向下滚动找到拦截提示，点击「仍要打开」。

方法 B（一条命令，推荐）：在终端执行，移除隔离属性：

xattr -dr com.apple.quarantine "/Applications/Pi Agent.app"

执行完再双击启动即可，这是目前最稳妥的 Pi Agent macOS 放行方案。

三、第 2 步：Windows 安装 Pi Agent

从 Release 页面下载文件名以x64-setup.exe结尾的 Windows 安装程序；
双击运行，按向导完成安装——安装器检测到系统缺少Microsoft WebView2时会自动补装；
安装完成后即可启动。若 SmartScreen 对未签名.exe弹出警告，选择"仍要运行"即可。

四、第 3 步：Linux 安装 Pi Agent

4.1 官方 .deb 包安装（Ubuntu/Debian 系）

下载.deb包后，用发行版自带的包管理器安装：

sudo apt install ./pi-agent-desktop_*.deb

如果你的发行版没有预装 WebKitGTK 4.1 和 GTK 3，先通过包管理器安装对应开发/运行库再启动 App。

4.2 社区 Flatpak 版本

不想折腾系统依赖的话，可考虑社区维护的 Flatpak 版本（非官方发布，但兼容大多数发行版并自动处理更新）。

装好启动后，Pi Agent 会出现在系统托盘里，右键即可显示或退出主窗口：

在 Linux 上同样可以按提供商切换模型（DeepSeek、Lingma、Kimi 等）：

五、首次使用：配置模型并接续历史会话

首次打开 Pi Agent 后，在输入框右下角的模型选择器里挑选模型并配置凭证（支持 OAuth / API Key、自定义模型配置、Skills 和 Plugins 管理）。

📂 如果你在这台机器上用过 Pi CLI，App 会自动读取本地数据目录~/.pi/agent/，历史会话（.jsonl文件）、模型与认证配置直接可用，无需迁移；如需指向其他目录，可设置环境变量PI_CODING_AGENT_DIR。

深色模式下，Agent 的工具调用、Token 用量与成本一目了然：

一次真实会话中，你可以直观看到 Agent 思考、执行gh issue view、rg等命令并汇总结果的全过程：

六、版本检查与一键升级

Pi Agent 最多每 7 天检查一次最新稳定 Release，只有当本地版本落后时，「设置」页的Upgrade按钮才会点亮。点击后下载的是包含pi → pi-web → pi-agent-desktop三个组件完整签名的整包，安装后自动重启，避免组件版本不一致（机制详见 docs/desktop-updates.md）。

七、常见问题速查（Troubleshooting）

现象	平台	解决办法
"已损坏，无法打开 / 无法验证开发者"	macOS	`xattr -dr com.apple.quarantine "/Applications/Pi Agent.app"`或系统设置点「仍要打开」
启动后白屏/闪退	Windows	确认已安装 WebView2 运行时（安装器通常会自动补装）
提示缺少 WebKitGTK/GTK	Linux	通过发行版包管理器安装 WebKitGTK 4.1 与 GTK 3
服务异常需要排查	macOS	查看日志`~/Library/Logs/com.abcwyc.pi-agent/server.log`（见 docs/desktop.zh-CN.md）
装完 App 却找不到全局`pi`命令	全平台	属正常现象，Pi CLI 需按上游说明单独安装

八、进阶：从源码构建 Pi Agent（开发者可选）

如果你是开发者，想直接跑源码，准备Node.js 22、npm、Rust 1.85+（macOS 另需 Xcode Command Line Tools，Windows 需要 C++ Build Tools），然后：

git clone https://gitcode.com/gh_mirrors/pi/pi-agent-desktop cd pi-agent-desktop npm install npm run desktop:dev

该命令会启动 Next.js 开发服务器并用原生 Tauri 窗口打开，不生成安装包；完整的桌面打包与 Release 流程见 scripts/ 与 src-tauri/ 目录说明。

🎉 至此，你已经在 macOS / Windows / Linux 上装好了 Pi Agent 这款 AI 编程助手：下载对应平台的安装包 → 处理平台安全拦截（重点是 macOS Gatekeeper）→ 启动后配置模型即可开写。祝编码愉快！

【免费下载链接】pi-agent-desktop

Pi — A cross-platform AI coding agent, bringing the Claude Code experience to your desktop. No environment setup, no terminal commands. Download and start coding right away.

项目地址：https://gitcode.com/gh_mirrors/pi/pi-agent-desktop

点击查看免费下载