从零配置 Pi

准备（Preparation） ​

本页使用 Pi 的原生 models.json Provider 结构。预计 10 分钟；准备 CC Switch v3.20.0、Pi 和专用 Key。CC Switch 只管理显式 Provider；它不会读取或写入 Pi auth.json，也不会更改 defaultProvider 或 defaultModel。本地代理转换并非所有模型和协议的通用兼容保证。

下载（Download） ​

从 Pi 官方仓库 或其官方安装说明安装 Pi，并从 CC Switch v3.20.0 Release 安装 CC Switch。打开已安装的 CC Switch，进入 关于，确认显示 v3.20.0；若实际版本不一致，先停止，不要继续配置。已安装受支持 Node.js/npm 的 Windows、macOS 与 Linux 可执行官方 npm 命令：

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

--ignore-scripts 是 Pi 官方快速安装命令的一部分。只有 pi --version 成功并打印版本号才继续；找不到命令时先修复 npm 全局可执行目录或 PATH。不要安装名称相似的第三方包。

首次启动（First launch） ​

运行 pi 一次并完成其初始引导，然后退出所有 Pi 会话。默认配置路径是 ~/.pi/agent/models.json；若设置了 PI_CODING_AGENT_DIR 或 CC Switch 的 Pi 目录覆盖，必须确认实际 agent 目录后再保存。

API Key 与分组（API Key and group） ​

为 Pi 单独创建 Key，选择包含目标模型、端点和能力的分组。保存 Key 名称、创建时间和分组即可；完整 Key 不应出现在 auth.json、终端历史、代码仓库或同步目录中。

模型目录：GET /v1/models ​

先用同一 Key 调用 GET https://suoxie.codes/v1/models，将 data[].id 中返回的精确值复制成 <MODEL_FROM_V1_MODELS>。下文的 <API_KEY> 只是说明要输入哪一把 Key；真实值通过隐藏提示临时进入环境变量，不写入命令历史。

$secureKey = Read-Host "API key" -AsSecureString
$credential = [System.Net.NetworkCredential]::new("", $secureKey)
$env:SUOXIE_API_KEY = $credential.Password
try {
  curl.exe --fail-with-body https://suoxie.codes/v1/models `
    -H "Authorization: Bearer $env:SUOXIE_API_KEY"
}
finally {
  Remove-Item Env:SUOXIE_API_KEY
  Remove-Variable secureKey, credential
}

read -rsp "API key: " SUOXIE_API_KEY
printf '\n'
export SUOXIE_API_KEY
curl --fail-with-body https://suoxie.codes/v1/models \
  -H "Authorization: Bearer $SUOXIE_API_KEY"
unset SUOXIE_API_KEY

在 CC Switch 配置 Provider ​

先完全退出 Pi，并按 PI_CODING_AGENT_DIR 或 CC Switch Pi 目录覆盖确认实际 agent 目录。若其中的 models.json 已存在，手动复制为同目录的 models.json.before-cc-switch，确认副本可读后再操作；若原文件不存在，记录这一点，不要创建空的假备份。然后选择 Pi，新增显式 Provider suoxie-openai。选择与实际上游一致的 Pi 原生 API format，Base URL 填 https://suoxie.codes/v1，填入专用 Key 和 <MODEL_FROM_V1_MODELS>。保存时 CC Switch 只增量写入 models.json.providers.suoxie-openai，不会创建内建 Provider，也不会改 Pi 默认模型。

{
  "providers": {
    "suoxie-openai": {
      "baseUrl": "https://suoxie.codes/v1",
      "apiKey": "<API_KEY>",
      "api": "openai-completions",
      "models": [
        {
          "id": "<MODEL_FROM_V1_MODELS>",
          "name": "<MODEL_FROM_V1_MODELS>"
        }
      ]
    }
  }
}

此 JSON 仅示意 OpenAI-compatible 格式；不要把 api 值当作自动转换器。实际格式必须与 Pi 的原生 Provider 文档及上游请求协议一致。

模型映射与协议（Model mapping and protocol） ​

Pi 中选择 suoxie-openai/<MODEL_FROM_V1_MODELS>，上游模型为同一 <MODEL_FROM_V1_MODELS>。默认模型保持 Pi 原有设置不变；需要测试时仅在当前会话选择新增 Provider。快速、推理和备用模型必须逐一来自模型目录，并由 Pi 所选 API format 与上游共同支持。

保存、启用与重启（Save, enable, and reload） ​

保存后确认 CC Switch 中 Provider 已启用，关闭 Pi 并重新启动或重新加载模型目录。打开模型选择器，确认新增 suoxie-openai/<MODEL_FROM_V1_MODELS> 存在且原默认模型仍未改变。若保存被拒绝，先处理 models.json 已被外部修改的 revision 保护，不要强行覆盖。

第一个请求（First request） ​

在当前会话选择新增 Provider，发送 Reply with OK，不要更改全局默认模型。成功标准是短文本响应、会话明确显示新增 provider/model，且原默认值保持不变。协议错误说明格式或上游能力不匹配，不能由模型列表自动解决。

Key 用量（Key usage） ​

在 Key 用量 按时间、Key、分组、端点和真实模型核对请求数、Token 和费用。先刷新和扩大查询范围，再判断是否存在延迟；避免重复请求作为唯一诊断方式。

错误处理（Errors） ​

回滚与安全（Rollback and security） ​

先在 Pi 中选回原 Provider/模型并完成短请求，再只删除 models.json.providers.suoxie-openai。若需要完整恢复，退出 Pi 与 CC Switch，将手动创建的 models.json.before-cc-switch 复制回 models.json，重启后复测；本页不声称 CC Switch 会为 Pi 自动备份。不要删除整个 models.json、不要触碰 auth.json、不要将测试 Key 写入默认配置；若正式凭据已泄露，应另行轮换。确认旧 Provider 路径的短请求正常后，最后撤销本轮临时测试 Key。若这里配置的是仍在使用的正式专用 Key，应继续保留它，只撤销本轮临时测试 Key，不影响正在使用的正式 Key。