Pi Agent Desktop 图标 Pi Agent Desktop
EN

Pi Agent Desktop 使用指南

按下面的顺序操作，就可以完成安装、模型配置并开始第一次对话。

1安装应用选择适合系统的安装包 2配置模型登录账号或填写 API Key 3选择项目创建第一条会话 4按需扩展添加技能、插件或消息渠道

下载安装

打开下载页面，网站会优先推荐当前系统对应的安装包。桌面安装包已经内置 Pi Coding Agent 运行时，日常使用不需要另外安装 Pi CLI。

macOS

Apple Silicon（M 系列）选择 arm64，Intel Mac 选择 x64。下载 DMG 后拖入“应用程序”。

Windows

支持 Windows 10 / 11 x64。运行 EXE 安装程序，按安装向导完成安装。

Linux

支持 Linux x64 AppImage。下载后添加可执行权限，再双击或从应用菜单启动。

macOS 安装

  1. 根据芯片类型下载 Apple Silicon 或 Intel 版本的 DMG。
  2. 打开 DMG，把 Pi Agent Desktop 拖到“应用程序”文件夹。
  3. 从“应用程序”打开。正式发布包已经签名并通过 Apple 公证。

Windows 安装

  1. 下载 Windows x64 安装程序并运行。
  2. 按安装向导完成安装。
  3. 当前安装包尚未配置代码签名；如果 SmartScreen 显示“未知发布者”，确认文件来自项目的 GitHub Releases 后，选择“更多信息 → 仍要运行”。

Linux 安装

  1. 下载 Linux x64 AppImage。
  2. 在文件属性中允许“作为程序执行”，或运行 chmod +x Pi-Agent-Desktop-*.AppImage。
  3. 打开 AppImage。Linux 版本当前使用手动更新。
第一次启动：先选择一个项目目录，再进入“设置 → 模型”完成模型配置。没有用过 Pi CLI 也可以直接开始。

认识主界面

主界面由左侧会话区、中间对话区和右侧文件区组成。

左侧：项目与会话

  • 选择或切换项目目录
  • 点击“新建会话”开始新任务
  • 搜索、切换、重命名或删除会话
  • 从底部打开设置

中间：对话工作区

  • 输入问题并查看流式回复
  • 查看思考、工具调用与执行结果
  • 切换模型、推理等级和工具预设
  • 添加图片或使用 @ 引用文件

右侧：文件与预览

  • 浏览当前项目文件
  • 用标签页打开多个文件
  • 预览代码、Markdown、图表和文档
  • 拖动分隔线调整面板宽度

开始第一条会话

  1. 在左侧选择项目目录。
  2. 点击“新建会话”。
  3. 确认输入框下方已经选择可用模型。
  4. 描述你的目标，例如“介绍这个项目”或“帮我查找登录页面”。

如果只是聊天或处理临时任务，也可以选择一个空目录。只有在你明确授权工具后，Agent 才能读取或修改相应项目文件。

配置模型

入口设置→模型

Pi Agent Desktop 本身不提供模型额度。你需要连接已有的模型服务账号，或填写模型服务商提供的 API Key。

使用 API Key

  1. 打开“设置 → 模型”，点击“添加服务商”。
  2. 选择你的模型服务商。
  3. 粘贴 API Key，点击“保存”。
  4. 选择要使用的模型；如果界面提供“测试”，可以先测试连接。
  5. 关闭设置，在会话输入框下方选择刚配置的模型。

使用 OAuth 登录

  1. 在“添加服务商”中选择支持 OAuth 的服务商。
  2. 点击“登录”，按提示在浏览器中完成授权。
  3. 回到应用，确认服务商显示为已连接。

自定义兼容服务

如果你使用的是兼容 OpenAI、Anthropic 或 Google API 的自建服务，可以添加自定义服务商，并填写 Base URL、API 类型、API Key 和模型信息。这部分只在普通服务商列表无法满足需求时使用。

配置失败？先检查 API Key 是否完整、账号是否有可用额度、网络是否能访问服务商，再使用模型卡片中的“测试”查看错误信息。

Skills 设置

入口选择项目→设置→技能

这里只介绍设置方法。Skill 的具体能力和使用方式由它自己的说明决定。

  1. 先在左侧选择项目，再打开“设置 → 技能”。
  2. 选择已有 Skill，使用右上角开关设置它是否对模型可见。
  3. 需要添加时点击“添加技能”，搜索名称，选择“全局”或“当前项目”，再点击“安装”。
  4. 只有确实需要自定义说明时才修改内容，并点击“保存更改”。
建议：通用 Skill 选择“全局”，只服务当前仓库的 Skill 选择“当前项目”。

Plugins 设置

入口选择项目→设置→插件

插件页只需要配置插件来源、安装范围和启用状态。

  1. 先选择项目，再打开“设置 → 插件”。
  2. 点击“添加插件”，填写 npm 包、Git 仓库或本地绝对路径。
  3. 选择“全局”或“当前项目”，然后点击“安装”。
  4. 在已安装列表中启用、禁用、更新或移除插件。
  5. 设置发生变化后，点击“重新加载会话”使配置生效。
注意：Plugin 可以执行代码，只添加可信来源。

消息渠道设置

入口设置→消息渠道

先选择要连接的渠道，只填写该渠道要求的账号信息：

渠道设置内容
个人微信点击“连接微信”，使用手机扫码并确认登录。
Telegram填写从 BotFather 获取的 Bot Token。
飞书 / Lark选择平台，填写企业自建应用的 App ID 与 App Secret。
  1. 保存账号信息，并按需设置默认工作目录和访问策略。
  2. 启动账号，确认状态显示为“运行中”。
  3. 使用“测试连接”检查配置；需要与当前会话共享上下文时，再绑定对应消息对话。

开发工具设置

入口设置→开发工具

应用会自动扫描所需工具。普通使用只需要处理显示为“缺少”或“不可用”的项目。

  1. 点击“重新扫描”，查看工具状态、来源和版本。
  2. 已经安装的工具保持“自动”，检测不正确时点击“选择”指定路径。
  3. 缺少工具且应用提供托管版本时，点击“安装”；文件损坏时点击“修复”。
无需全部安装：状态正常的工具不用处理；应用托管的工具保存在私有目录，不会修改系统 PATH。

更新、后台运行与本地数据

检查更新

打开“设置 → 关于”，可以检查稳定版更新。macOS 与 Windows 支持在应用内下载并安装；Linux AppImage 当前需要从下载页面手动获取新版本。

保持消息渠道在线

在“设置 → 通用”开启“关闭窗口时最小化到托盘”。关闭主窗口后消息渠道会继续运行；从托盘菜单选择“退出”才会真正停止应用。

本地数据

  • 会话和 Pi 配置默认保存在本机 ~/.pi/agent/。
  • 已经使用 Pi CLI 的用户可以直接复用原有会话和配置。
  • 模型请求仍会发送给你所选择的模型服务商，请同时了解该服务商的隐私政策。
  • 消息渠道凭证使用操作系统安全存储加密保存，不会在设置页中重新显示。

常见问题

普通使用需要安装 Node.js 或 Pi CLI 吗？

不需要。桌面安装包已经内置 Pi Coding Agent 运行时。只有某些 Skills、Plugins 或 Agent 命令依赖额外工具时，才需要在“设置 → 开发工具”中检查或安装。

为什么“技能”和“插件”页面提示先选择项目？

Skills 和 Plugins 可以按项目安装，因此应用需要先知道当前项目目录。回到主界面左侧选择一个项目，再重新打开设置即可。

配置模型后仍然无法发送消息？

确认输入框下方已经选择模型，然后检查 API Key、账号额度和网络连接。回到“设置 → 模型”，使用“测试”查看服务商返回的具体错误。

消息渠道批准配对后为什么没有回复？

触发配对的第一条消息不会进入 Agent。批准后，请让同一个用户再发送一条新消息。

关闭窗口后消息渠道为什么离线？

打开“设置 → 通用”，启用“关闭窗口时最小化到托盘”。如果从托盘或应用菜单选择了“退出”，所有消息渠道都会停止。

Windows 安装时出现 SmartScreen 提示怎么办？

当前 Windows 安装包尚未配置代码签名。请确认安装包来自项目的 GitHub Releases，再选择“更多信息 → 仍要运行”。

支持 Linux 吗？

支持 Linux x64 AppImage。当前暂不提供 Linux ARM64 构建，更新时需要手动下载新的 AppImage。

遇到问题如何反馈？

先记录应用版本、操作系统和错误提示，然后前往 GitHub Issues。请勿上传 API Key、Token、App Secret 或其他敏感信息。