Pi Agent 使用指南：从安装到配置本地模型的完整教程

Pi 是轻量级终端 Coding Agent，支持多种大模型 provider。本文详细介绍了两种安装方式（官方脚本和 npm），以及通过 models.json、settings.json、auth.json 配置本地模型的方法，重点解决常见的 401 鉴权问题，并提供了可一键完成安装与配置的 shell 脚本，适合快速接入 OpenAI 兼容服务。

AI随手发现
作者：zhuge··预计阅读 26 分钟·72 阅读·0 评论
Pi Agent 使用指南：从安装到配置本地模型的完整教程

Pi 是一个轻量级的终端 Coding Agent，由 earendil-works 团队开发。它支持多种大模型 provider，可以通过 models.json 灵活配置自定义 OpenAI 兼容端点。本教程将带你从零开始安装 Pi、配置本地模型，并提供一键配置脚本。

一、安装 Pi

方式 1：官方安装脚本（推荐）

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

适用于 Linux / macOS，脚本会自动检测系统环境并完成安装。

方式 2：npm 全局安装

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

--ignore-scripts 会在安装时禁用依赖的 lifecycle 脚本，Pi 本身在 npm 安装时不需要这些脚本。

验证安装

pi --version

如果看到版本号输出，说明安装成功。

卸载 Pi

# npm 安装方式
npm uninstall -g @earendil-works/pi-coding-agent

# pnpm / yarn / bun 安装方式
pnpm remove -g @earendil-works/pi-coding-agent
yarn global remove @earendil-works/pi-coding-agent
bun uninstall -g @earendil-works/pi-coding-agent

二、配置模型

Pi 通过 ~/.pi/agent/ 目录下的几个 JSON 文件来管理配置：

文件作用
models.json定义自定义 provider 和 model（覆盖或新增内置项）
settings.json全局设置，包括默认 provider/model、主题、压缩策略等
auth.json凭证缓存（API key、OAuth token）
models-store.json模型 catalog 缓存（自动生成）

2.1 编写 models.json

假设你有一个本地的 OpenAI 兼容服务，运行在 http://127.0.0.1，模型名为 gpt-5.5，API key 为 sk-123456。

创建文件 ~/.pi/agent/models.json：

{
  "providers": {
    "openai": {
      "baseUrl": "http://127.0.0.1/v1",
      "api": "openai-completions",
      "apiKey": "sk-123456",
      "authHeader": true,
      "models": [
        { "id": "gpt-5.5" }
      ]
    }
  }
}

字段说明：

  • providers.openai：这里直接覆盖内置的 openai provider。如果你想保留内置模型同时新增，可以换一个自定义 provider 名（例如 my-local），但要同步修改 settings.json 里的 defaultProvider。
  • baseUrl：OpenAI 兼容服务的根地址。Pi 会请求 ${baseUrl}/chat/completions，所以如果你的服务本身就有 /v1 前缀，这里填 http://127.0.0.1/v1；如果服务的根就是 /v1，直接填 http://127.0.0.1。
  • api：流式协议类型。大多数 OpenAI 兼容服务用 openai-completions 即可。其他可选值：openai-responses、anthropic-messages、google-generative-ai。
  • apiKey：明文写 API key。Pi 也支持 "!command" 执行命令取值、"$ENV_VAR" 读取环境变量。注意：明文 key 会让配置文件泄露 token，正式环境建议用环境变量引用。
  • authHeader: true：关键开关。如果你的服务期望标准的 Authorization: Bearer <key> 头，必须加上这个字段，否则 Pi 可能用其他鉴权方式导致 401。
  • models：模型列表。每个 model 至少需要 id 字段，其他字段（name、contextWindow、maxTokens、cost、reasoning、input）都是可选的，Pi 会用默认值。

2.2 编写 settings.json

创建文件 ~/.pi/agent/settings.json，设置默认 provider 和 model：

{
  "defaultProvider": "openai",
  "defaultModel": "gpt-5.5",
  "defaultThinkingLevel": "medium"
}

这样启动 pi 后会自动选中 gpt-5.5 模型，无需手动 /model 切换。

2.3 清空 auth.json（重要）

创建空文件 ~/.pi/agent/auth.json：

echo '{}' > ~/.pi/agent/auth.json
chmod 600 ~/.pi/agent/auth.json

为什么要清空 auth.json？

根据 Pi 的 Resolution Order，凭证查找优先级是：

CLI --api-key  >  auth.json  >  环境变量  >  models.json 的 apiKey

也就是说，auth.json 里缓存的凭证优先级高于 models.json 里写的 apiKey。如果你之前用 /login 存过一个占位 key（比如 111111111111），Pi 会优先用那个错误的 key 发请求，导致本地服务返回 401: 无效的令牌。

清空 auth.json 之后，Pi 才会回退到 models.json 里配置的正确 key。

2.4 启动并验证

# 交互模式
pi

# 非交互模式快速测试
pi -p "回复一个字:好"

如果一切正常，你会看到模型返回 好。

2.5 常见排查路径

现象可能原因解决方案
401: 无效的令牌auth.json 里有旧凭证覆盖 models.json清空 auth.json 为 {}
401: 无效的令牌Pi 没发 Authorization: Bearer 头models.json 加 "authHeader": true
/model 列表里没你的 modelauth 未配置（models load but unavailable）确认 apiKey 字段已写入，或用 --api-key 传入
请求 404 路径不对baseUrl 没带 /v1 或带了多余前缀检查 ${baseUrl}/chat/completions 完整路径
服务不支持 developer 角色Ollama / vLLM / SGLang 等常见问题provider 加 "compat": { "supportsDeveloperRole": false }

三、一键配置脚本

把下面这段保存为 setup-pi.sh，加可执行权限后运行即可完成 Pi 的安装 + 配置。

#!/bin/sh
# 兼容处理：bash 启用 pipefail，普通sh不启用
if [ -n "${BASH_VERSION:-}" ]; then
    set -euo pipefail
else
    set -euf
fi

# ============================================
# 配置区：按需修改
# ============================================
PI_BASE_URL="http://192.168.200.23:3030/v1"
PI_API_KEY="sk-0cd1562bcfba417d96e8b2bbb96ca9b8"
PI_MODEL_ID="gpt-5.5"
PI_API_TYPE="openai-completions"   # openai-completions | openai-responses | anthropic-messages
PI_PROVIDER_NAME="openai"          # 覆盖内置 openai；自定义可改为 my-local
PI_THINKING_LEVEL="medium"         # off | minimal | low | medium | high | xhigh | max
# ============================================

echo "==> [1/4] 安装 Pi..."
curl -fsSL https://pi.dev/install.sh | sh

echo "==> [2/4] 创建配置目录..."
mkdir -p "$HOME/.pi/agent"

echo "==> [3/4] 写入配置文件..."

# models.json：定义 provider + model
cat > "$HOME/.pi/agent/models.json" << EOF
{
  "providers": {
    "${PI_PROVIDER_NAME}": {
      "baseUrl": "${PI_BASE_URL}",
      "api": "${PI_API_TYPE}",
      "apiKey": "${PI_API_KEY}",
      "authHeader": true,
      "models": [
        { "id": "${PI_MODEL_ID}" }
      ]
    }
  }
}
EOF

# settings.json：默认 provider / model / thinking level
cat > "$HOME/.pi/agent/settings.json" << EOF
{
  "defaultProvider": "${PI_PROVIDER_NAME}",
  "defaultModel": "${PI_MODEL_ID}",
  "defaultThinkingLevel": "${PI_THINKING_LEVEL}"
}
EOF

# auth.json：清空缓存凭证，避免覆盖 models.json 的 apiKey
echo '{}' > "$HOME/.pi/agent/auth.json"
chmod 600 "$HOME/.pi/agent/auth.json"

echo "==> [4/4] 验证..."
if command -v pi >/dev/null 2>&1; then
    echo "Pi 路径: $(command -v pi)"
    echo "配置目录: $HOME/.pi/agent"
    echo ""
    echo "运行下面命令测试连通性（需要本地服务已启动）："
    echo "  pi -p '回复一个字:好'"
else
    echo "警告: pi 不在 PATH 中。请重启 shell 或手动 source 配置。"
fi

echo ""
echo "==> 安装与配置完成！"

使用方式

# 1. 保存脚本
# 2. 赋予可执行权限
chmod +x setup-pi.sh

# 3. 执行
./setup-pi.sh

脚本说明

  1. 配置区集中：所有可变参数（baseURL、apikey、model id 等）都放在脚本顶部的 配置区，按需修改即可，不需要翻到脚本中段改。
  2. authHeader: true 默认开启：覆盖绝大多数 OpenAI 兼容服务的鉴权方式。
  3. auth.json 清空：避免之前 /login 留下的占位 key 覆盖 models.json 里的真实 key，这是最常见的"配置看起来对但 401"的根因。
  4. provider 名可自定义：默认覆盖内置 openai；如果想保留内置模型同时新增自定义端点，把 PI_PROVIDER_NAME 改成 my-local 之类即可。
  5. 幂等：重复运行脚本不会出错，配置文件会被覆盖为最新值。

四、进阶用法

4.1 多 provider 共存

{
  "providers": {
    "openai": {
      "baseUrl": "http://127.0.0.1/v1",
      "api": "openai-completions",
      "apiKey": "sk-xxx",
      "authHeader": true,
      "models": [{ "id": "gpt-5.5" }]
    },
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        { "id": "llama3.1:8b" },
        { "id": "qwen2.5-coder:7b" }
      ]
    }
  }
}

启动后用 /model 在不同 provider 的模型间切换。

4.2 用环境变量代替明文 key

把 apiKey 字段写成环境变量引用形式：

"apiKey": "$MY_OPENAI_KEY"

然后在 shell 里 export MY_OPENAI_KEY=sk-xxx，Pi 会在请求时解析变量值。这样配置文件可以安全提交到 Git 仓库。

4.3 临时切换模型（不改配置）

pi --provider my-local --model gpt-5.5

适合在不修改 settings.json 的情况下临时跑一次其他模型。

4.4 处理本地服务不支持 developer 角色

很多 OpenAI 兼容服务（Ollama、vLLM、SGLang 等）不识别 developer 角色。在 provider 配置里加 compat：

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [{ "id": "gpt-oss:20b", "reasoning": true }]
    }
  }
}

compat 可以在 provider 级别（对所有 model 生效），也可以在 model 级别覆盖。

五、参考资料

结语

Pi 的配置虽然看似复杂，但核心就三件事：

  1. models.json 定义 provider + model
  2. settings.json 设置 默认 provider/model
  3. auth.json 清空 避免缓存覆盖

掌握这三点，再配合上面的一键脚本，你可以在 1 分钟内把 Pi 接入任何 OpenAI 兼容的本地或云端服务。Happy coding!

相关文章

随手发现

Git多远程仓库同步实战指南

36 阅读
AI

Claude Code权限配置全攻略

106 阅读
AI

Claude Code与Codex安装配置指南

97 阅读

评论

加载中...