Pi 使用指南
Pi 是一款可扩展的终端编程 Agent。它支持通过覆盖内置 provider 的方式接入 TokenFlux 的 OpenAI 兼容接口。
本次实测覆盖上述 macOS CLI 配置与模型调用。交互式 /login 保存凭据、模型选择界面及 Windows / Linux 安装流程未在本次实测。
安装
根据使用习惯选择官方安装方式。
需要 Node.js 22.19.0 或更高版本。确认 node --version 满足要求后，全局安装 Pi：
npm install -g --ignore-scripts @earendil-works/pi-coding-agent安装完成后，在终端运行以下命令验证安装：
pi --version输出版本号即表示安装成功。
接入 TokenFlux
1. 创建 API Key
按 创建 API Key 教程 创建一张 API Key，选择 ChatGPT 分组。
模型可用性
本教程以 gpt-6-astra 为例。完整可用模型列表请以 模型广场 和所选 Key 分组实际支持的模型为准。
2. 配置 models.json
Pi 支持通过全局模型配置文件覆盖内置 provider。
全局配置路径：
- macOS / Linux：
~/.pi/agent/models.json - Windows：
%USERPROFILE%\.pi\agent\models.json
创建并编辑该文件，写入以下配置：
{
"providers": {
"openai": {
"baseUrl": "https://tokenflux.dev/v1"
}
}
}若 models.json 已存在，将 openai 配置合并到现有 providers 下即可，不要覆盖其他 provider。
3. 登录并保存 API Key
启动 Pi 并使用内置 /login 命令保存凭据：
- 在终端运行
pi进入交互模式。 - 输入
/login并按回车。 - 在 provider 列表中选择 OpenAI。
- 粘贴复制的 TokenFlux API Key。
Pi 会把凭据保存至 ~/.pi/agent/auth.json（Windows 为 %USERPROFILE%\.pi\agent\auth.json），无需将 API Key 写入 models.json，也不需要手动编辑 auth.json。此处保存的凭据会对应 models.json 中覆盖的 openai Base URL。
启动与选择模型
检查模型目录
运行以下命令检查 Pi 中匹配的模型：
pi --list-models gpt-6-astra交互启动
指定 provider 和模型启动交互会话：
pi --provider openai --model gpt-6-astra启动 Pi 之后，也可以在交互界面中通过 /model 命令或快捷键 Ctrl+L 切换模型。
最小验证
使用以下最小命令验证调用：
pi --provider openai --model gpt-6-astra --no-session --no-tools -p "只回复 OK"真实调用与扣费说明
该验证命令会向 TokenFlux 发起真实模型调用并产生计费。收到模型的 OK 回复即表示接入成功。
常见问题与注意事项
看到模型列表不代表分组一定支持
Pi 内置模型目录可能显示当前 TokenFlux 分组不支持的模型。模型出现在列表中只说明客户端可以列出它；实际接入情况仍需通过最小调用确认。
费用与扣费核算
Pi 底部 footer 显示的内置 OpenAI 成本元数据基于官方预设费率，不代表 TokenFlux 最终价格。实际扣费和用量请以 TokenFlux 模型广场 和控制台使用记录为准。
更新模型目录
如需同步 Pi 内置的模型定义，可运行：
pi update --models相关入口
- 创建 API Key — 选择分组并生成密钥
- API 端点 — 地址与协议格式
- 排障 — 按症状定位问题
- Pi 官方项目 (GitHub) — 源码与官方文档
- Pi 官网 — 官方主页