手动配置 Pi
Pi 是一款运行在终端中的编码代理。接入 Waihub 时，需要分别配置模型、认证信息和启动默认项。
已有可用的 AI 助手？让它直接帮你配置
如果设备上已经安装并配置好了 Codex、Claude Code 或其它具备本地文件操作能力的 AI 助手，可以直接把下面这段话发给它：
text
参考 https://docs.waihub.top/guide/cli/pi 为我配置 pi，API Key 可以参考 ~/.codex/auth.json 或 ~/.claude/settings.json。配置过程中不要在对话中回显完整 API Key。AI 助手完成操作后，建议仍按本页“第七步：验证配置”检查模型、认证状态和实际请求。
配置要点
Pi 的全局配置目录是 ~/.pi/agent。本教程会创建或修改三个文件：
models.json：声明 Waihub 接口与模型auth.json：保存 API Keysettings.json：设置默认模型与推理等级
请注意，应编辑的是 models.json，不是 Pi 自动维护的 models-store.json。
第一步：安装 Pi
根据使用习惯选择命令行版或桌面版。两种方式完成安装后，都可以继续使用本页后面的 Waihub 配置。
使用 CLI 前请先准备 Node.js 22.19.0 或更高版本，然后在终端运行：
bash
npm install -g --ignore-scripts @earendil-works/pi-coding-agent确认安装结果：
bash
pi --version如果终端提示找不到 npm，请先从 Node.js 官网 安装最新版 Node.js，再重新打开终端。
第二步：打开配置目录
在 CMD 中运行：
batch
mkdir "%USERPROFILE%\.pi\agent" 2>nul
start "" "%USERPROFILE%\.pi\agent"第三步：创建 models.json
在 ~/.pi/agent 目录下创建 models.json，写入：
json
{
"providers": {
"waihub": {
"name": "Waihub",
"baseUrl": "https://waihub.top/v1",
"api": "openai-responses",
"models": [
{
"id": "gpt-5.6-sol",
"name": "GPT-5.6 Sol (Waihub)",
"reasoning": true,
"input": ["text", "image"],
"contextWindow": 272000,
"maxTokens": 128000,
"compat": {
"supportsDeveloperRole": true,
"supportsStrictMode": true,
"supportsOpenAIGrammarTools": true,
"supportsLongCacheRetention": true
}
}
]
}
}
}这里使用 Pi 官方支持的 openai-responses API 类型，并将 Waihub 的 Codex 系列兼容地址设为 https://waihub.top/v1。
更换模型
上面的完整示例默认使用能力更强的 gpt-5.6-sol。日常开发希望兼顾速度与成本时，可以把模型对象中的 id 和 name 改为 gpt-5.6-terra，并同步修改后面 settings.json 中的 defaultModel。模型选择建议见渠道链接与模型列表。
第四步：创建 auth.json
前往 Waihub Token 控制台 创建 API Key，然后在 ~/.pi/agent 目录下创建 auth.json：
json
{
"waihub": {
"type": "api_key",
"key": "sk-xxxxxxxx"
}
}将 sk-xxxxxxxx 替换为你自己的完整 API Key。waihub 必须与 models.json 中 providers 下的提供商名称完全一致。
不要泄露 API Key
不要把包含真实密钥的 auth.json 提交到 Git、发送到群聊，或放进截图和录屏。怀疑密钥泄露时，请立即在 Waihub 控制台停用旧密钥并创建新密钥。
第五步：配置 settings.json
如果 ~/.pi/agent/settings.json 已存在，请保留其中原有设置，再加入下面三个字段；如果不存在，可以直接创建：
json
{
"theme": "dark",
"defaultProvider": "waihub",
"defaultModel": "gpt-5.6-sol",
"defaultThinkingLevel": "medium"
}字段含义：
| 字段 | 作用 |
|---|---|
defaultProvider | 启动时默认使用 waihub 提供商 |
defaultModel | 启动时默认选择 gpt-5.6-sol |
defaultThinkingLevel | 默认推理等级；medium 适合多数任务 |
如果原文件中包含 lastChangelogVersion 或其它字段，不需要删除。例如：
json
{
"lastChangelogVersion": "0.85.1",
"theme": "dark",
"defaultProvider": "waihub",
"defaultModel": "gpt-5.6-sol",
"defaultThinkingLevel": "medium"
}版本号只是示例，请保留本机已有的值。
第六步：保护配置文件
macOS 或 Linux 用户建议限制配置文件权限，避免其它本机用户直接读取密钥：
bash
chmod 600 ~/.pi/agent/auth.json \
~/.pi/agent/models.json \
~/.pi/agent/settings.jsonWindows 用户不需要运行 chmod，请使用系统账户权限保护自己的用户目录。
第七步：验证配置
1. 检查模型是否加载
bash
pi --list-models waihub正常情况下会看到类似结果：
text
provider model context max-out thinking images
waihub gpt-5.6-sol 272K 128K yes yes2. 检查认证状态
bash
pi auth check --provider waihub --model gpt-5.6-sol --json认证就绪时会返回：
json
{
"status": "ready",
"provider": "waihub",
"authType": "api_key"
}3. 发送最小测试请求
bash
pi --provider waihub \
--model gpt-5.6-sol \
--thinking medium \
--no-session \
--no-tools \
-p "Reply with exactly: PI_OK"如果终端返回 PI_OK，说明接口地址、模型和认证均已配置成功。
完成后，在任意项目目录直接启动：
bash
cd /path/to/project
pi在 Pi 中切换模型和推理等级
启动 Pi 后可以使用：
/model：选择模型；在选择器中按Ctrl+S保存为启动默认模型/thinking：选择推理等级；按Ctrl+S保存为默认等级Shift+Tab：快速循环切换推理等级
也可以只对当前启动命令临时指定：
bash
pi --model waihub/gpt-5.6-sol --thinking high常见问题
模型列表里没有 Waihub
依次检查：
- 文件名是否为
~/.pi/agent/models.json - 是否误写成了
models-store.json - JSON 是否缺少逗号、括号或双引号
api是否为openai-responsesbaseUrl是否为https://waihub.top/v1
可以用下面的命令检查 JSON 语法：
powershell
Get-Content "$HOME\.pi\agent\models.json" | ConvertFrom-Json | Out-Null
Get-Content "$HOME\.pi\agent\settings.json" | ConvertFrom-Json | Out-Null
Get-Content "$HOME\.pi\agent\auth.json" | ConvertFrom-Json | Out-Null没有输出且命令正常结束，表示 JSON 语法有效。
认证状态是 invalid 或 missing
- 确认
auth.json中的键名是waihub - 确认认证类型写作
"type": "api_key" - 确认
key中没有多余空格或换行 - 前往 Waihub 控制台确认密钥仍然有效且余额充足
修改配置后没有生效
退出当前 Pi 会话并重新运行 pi。models.json 在打开 /model 时会重新加载，也可以重新打开模型选择器检查。
模型能显示，但调用时报错
先运行认证检查，再运行本页的最小测试请求。如果模型列表和认证都正常，重点检查模型名是否仍在 Waihub 当前可用列表中。