Pi

在 Pi 终端编程代理中添加 Token Factory 提供方，通过 models.json 配置国产模型，并用 /model 选择后开始使用。

开始前准备

按Pi 官方安装说明安装工具，确认终端可以运行 pi。
在控制台创建工具专用 API Key，确认通用余额充足。
从模型文档复制已开放 OpenAI Chat Completions 的模型 ID；编程任务需要模型支持工具调用与流式输出。

配置连接

OpenAI 兼容 Base URL

Base URL 填写 https://api.tokenfactory.cn/v1，接口类型使用 openai-completions。这里的名称对应 Chat Completions，最终请求为 https://api.tokenfactory.cn/v1/chat/completions。

1. 提供 API Key

在准备启动 Pi 的终端内输入 API Key。执行下面的命令后会等待输入，粘贴后按回车；Key 不会显示在终端或写入命令历史。

macOS / Linux · Bash 或 ZshWindows · PowerShell

bash

export TOKENFACTORY_API_KEY
read -r -s TOKENFACTORY_API_KEY

powershell

$tokenFactorySecret = Read-Host "Token Factory API Key" -AsSecureString
$env:TOKENFACTORY_API_KEY = [System.Net.NetworkCredential]::new("", $tokenFactorySecret).Password

2. 添加自定义模型

创建或编辑 ~/.pi/agent/models.json，在 providers 中添加 tokenfactory。已有文件时合并此条目，保留其他提供方。

json

{
  "providers": {
    "tokenfactory": {
      "baseUrl": "https://api.tokenfactory.cn/v1",
      "api": "openai-completions",
      "apiKey": "$TOKENFACTORY_API_KEY",
      "models": [
        {
          "id": "<model-id>",
          "name": "Token Factory"
        }
      ]
    }
  }
}

将 <model-id> 替换为平台模型 ID。apiKey 中的 $TOKENFACTORY_API_KEY 表示读取环境变量，保留开头的 $；单独写 TOKENFACTORY_API_KEY 会被当前 Pi 视为字面量。

此示例先使用基础文本配置。模型的上下文长度、最大输出及推理能力应按实际模型填写，不能用客户端默认值推断平台上限。字段说明见Pi 官方自定义模型文档。

选择模型并验证

在同一终端进入测试目录，运行 pi。
输入 /model，选择 tokenfactory 下的目标模型。每次打开选择器，Pi 都会重新读取 models.json。
发送：“只回复‘连接成功’，不读取文件、不执行命令。”收到正常回复后，再对一个测试文件验证读取与解释任务。

在 CC Switch 中新增 Pi 提供方后，也要回到 Pi 用 /model 选择。新增配置与改变当前会话模型是两个步骤。

Pi 的本地价格估算不代表 Token Factory 账单。模型调用使用通用余额按实际用量计费，账户用量与余额以控制台为准。

常见问题

现象	检查方法
`/model` 中没有目标模型	检查 JSON 格式、`providers` 层级、模型 `id` 和鉴权配置；缺少可用凭据时模型可能不可选。
`401` 认证失败	确认 `apiKey` 使用带 `$` 的环境变量引用，并从设置了变量的终端启动 Pi。
`404`	Base URL 保留 `/v1`，不包含完整 `/chat/completions` 路径。
报接口或模型不可用	确认 `api` 为 `openai-completions`，模型 ID 与平台 Chat Completions 能力一致。
修改配置后仍调用旧模型	再次打开 `/model` 并显式选择新模型。
推理参数、上下文或工具调用报错	根据模型真实能力设置参数；工具调用需要模型支持，不能仅靠新增模型条目开启。
限流或中途断开	参考错误处理；先检查已经发生的文件修改与命令执行。

Pi ​

开始前准备 ​

配置连接 ​

1. 提供 API Key ​

2. 添加自定义模型 ​

选择模型并验证 ​

常见问题 ​

相关文档 ​

Pi