Pi 安装与 OmniProxy 配置

Pi 是一个很小的终端助手，也就是直接在命令行里和你对话、读取文件并完成任务的程序。它的系统提示较短，默认工具也不多；需要其他命令、流程或界面时，可以再通过扩展补上。扩展可以理解为给 Pi 增加能力的组件，做好后也能分享给别人。

子代理是把一部分任务交给另一个助手处理，计划模式则是先整理步骤、再开始执行。这两项不在默认功能里，可以让 Pi 自己做出来，或安装别人分享的包。

安装前准备

macOS 和 Linux 使用安装脚本，也就是一条会自动完成下载和安装的命令。Windows 使用 Pi 首页提供的 PowerShell 命令；PowerShell 是 Windows 自带的命令行环境。也可以把 Pi 放进 WSL，也就是 Windows 中的 Linux 环境。

如果选择 npm 安装，需要先准备 Node.js 22.19 或更新版本。npm 是随 Node.js 使用的软件包管理工具，可以从命令行安装 Pi。

macOS Linux

install.sh

curl 官方脚本
依赖由安装器固定
更新用 pi update

Windows

install.ps1

官网 PowerShell 命令
Git for Windows 提供 Bash
也可以进 WSL

已有 Node

npm

需要 Node 22.19+
包名是 pi-coding-agent
加 --ignore-scripts

安装脚本会固定依赖。npm 安装不会固定间接依赖，并要加上 --ignore-scripts。

安装并首次启动

macOS 或 Linux 打开终端后，运行：

curl -fsSL https://pi.dev/install.sh | sh

Windows 打开 PowerShell，然后运行：

powershell -c "irm https://pi.dev/install.ps1 | iex"

已经安装 Node.js 22.19 或更新版本时，也可以使用 Quickstart 中的替代命令：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

安装脚本在交互终端里可能会停下来提问，需要根据画面继续操作。已经有符合要求的 Node 时，这条 npm 命令不会进入提问。想装到别的目录时，加上 --prefix /你的目录。2026-10-09 这样装到了 Pi 1.1.0。

正常的 npm 安装不需要依赖的生命周期脚本，也就是软件包在安装过程中自动执行的脚本。安装脚本会固定依赖，之后用 pi update 更新。npm 安装的更新方式以你使用的包管理器为准。Nix 用户从 Pi 的 flake 安装；flake 是 Nix 用来描述软件和依赖的配置，pi update 不能更新 Nix 安装。

安装结束后，先确认 Pi 能被终端找到：

pi --version

Windows 上如果要让模型执行 Bash 命令，建议大多数本机用户安装 Git for Windows。Bash 是 Pi 用来运行部分命令的命令环境。Pi 会依次查找 ~/.pi/agent/settings.json 里的 shellPath、Program Files 里的 Git Bash，以及 PATH 上的 bash.exe。shellPath 用来指定 Bash 的位置，PATH 则是系统查找命令时使用的目录列表。

启动后可以输入 !printf 'Bash is working\n' 检查。文件和工具已经在 WSL 里时，就在那个 Linux 环境里按 Quickstart 安装。

接下来进入你准备让 Pi 查看或处理的文件夹，再启动：

cd /path/to/folder
pi

这个文件夹会作为 Pi 当前工作的范围，用来发现文件和配置，也会用来归组会话。

从 OmniProxy 取得连接参数

先从 OmniProxy 准备以下三项：

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: 从 OmniProxy 当前模型列表复制

baseUrl 是 Pi 发送请求的接口地址，要写到 /v1。apiKey 是访问接口时使用的密钥。Model ID 是要调用的模型名称，需要从 OmniProxy 当前模型列表完整复制。

api 填写兼容接口示例里的 openai-completions。这个字段告诉 Pi 按哪一种接口格式发送请求。

模型 ID 要整段复制，名称中的斜杠也要保留。2026-10-09 供应商文档里的两个对照 ID 是 gemini-3.8-flash 和 grok-4.7。列表里没有的名字不要照抄。

填写工具配置

Pi 的用户级自定义模型配置写在 models.json。这个文件位于 agent 目录，默认目录是 ~/.pi/agent，因此完整位置是 ~/.pi/agent/models.json。如果设置了环境变量 PI_CODING_AGENT_DIR，Pi 会改用该变量指定的目录；环境变量可以理解为系统提供给程序读取的一项配置值。

按照兼容接口示例填写：

{
  "providers": {
    "omniproxy": {
      "baseUrl": "https://your-omniproxy-origin.example/v1",
      "api": "openai-completions",
      "apiKey": "<YOUR_OMNIPROXY_API_KEY>",
      "models": [
        { "id": "gemini-3.8-flash", "input": ["text"] },
        { "id": "grok-4.7", "input": ["text"] }
      ]
    }
  }
}

providers 用来列出接入的服务，models 用来列出可以选择的模型。每个模型的 id 必须对应 OmniProxy 当前模型列表中的完整 Model ID，input 则表示这里配置的是文字输入。

apiKey 可以直接写成字面值，也可以写成 $NAME 或 ${NAME}，让 Pi 从环境变量读取。以 ! 开头的值会被当成命令，在每次请求时执行。不要把真实密钥提交进仓库。网关不校验密钥时，可以填一串只在本机使用的占位字符。2026-10-09 这样读到了文件。

打开 /model 会重新加载这个文件。/model 是 Pi 中用于查看和选择模型的入口。自定义模型在 Pi 能解析到凭证之前，不会出现在 /model 里。选中模型后按 Ctrl+S，可以把它存成新会话的默认模型。

文件

models.json

默认目录 ~/.pi/agent
providers 里加一项
api 用 completions

地址

baseUrl

写到 /v1
apiKey 可写变量
模型 id 要精确

选用

/model

打开后会重载文件
选中刚才的模型
Ctrl+S 可存默认

文件改完后，在 Pi 里打开 /model，确认模型已经出现。

验证一个真实任务

配置完成后，可以在有文件的目录里做一次非交互检查。非交互是指不进入持续对话，Pi 完成这一个任务后就结束。把 --model 后面的内容换成 OmniProxy 当前列表里的完整 ID：

pi -p --provider omniproxy --model gemini-3.8-flash --tools read "读出你指定的文件的第一行，不要改文件。"

这里的 --tools read 只开放读取工具，任务内容也明确要求不要修改文件。2026-10-09 用 Pi 1.1.0 读出了文件内容。第一次回复大约两分钟。

也可以使用交互方式：进入目录运行 pi，再用 /model 选中模型。Quickstart 里的一个示例任务是让 Pi 说明这个仓库如何组织、怎样运行检查。观察它是否读取了文件并给出说明，然后在 OmniProxy 的调用记录里确认来源和模型 ID。

启动

pi 能打开

先 cd 到文件夹
pi --version 有输出
界面底部有模型名

任务

它读了目录

问仓库怎么组织
看它列出的文件
不要只看配置保存

记录

网关看得到

来源是 Pi
模型 ID 一致
密钥留在本机

界面底部能看到模型名之后，还要完成一次真实任务。

常见错误

找不到 pi：重开终端后再试 pi --version。npm 安装时确认全局 bin 在 PATH 里。
/model 里没有自定义模型：确认 models.json 在 ~/.pi/agent/，apiKey 能被解析，然后重新打开 /model。
Windows 提示找不到 Bash：安装 Git for Windows，或在 ~/.pi/agent/settings.json 里设置 shellPath。JSON 里的反斜杠要写成两个。
请求被拒绝：核对 api 是否为 openai-completions，baseUrl 是否以 /v1 结束。不要只因为对方自称兼容就打开额外的兼容开关。
模型 ID 无效：从 OmniProxy 当前列表重新复制。

官方参考

安装命令见 Pi 官网和 Quickstart。模型文件见 Choose a Model 和 Configuration。Windows 的命令环境见 Run Pi on Windows。举例用的模型 ID 见 Gemini 模型列表和 xAI 模型页。

用你自己的 OmniProxy 配置替换每个占位符。不要发布真实密钥。

保存成功或 HTTP 200 不单独等同完整 Agent 兼容。请在 OmniProxy 调用记录中确认来源和模型。

官方来源 · Pi ↗