pi Coding Agent API 设置

pi 的官方 Custom Models 机制从 ~/.pi/agent/models.json 加载网关与自定义模型。TokenHub 使用 openai-completions API 类型；这里没有“添加 Provider”图形表单，配置文件就是正式入口。

第一步：为 models.json 准备凭证

在启动 pi 的同一个终端设置：

export TOKENHUB_API_KEY="sk-..."

models.json 中必须写成 "$TOKENHUB_API_KEY" 才表示读取环境变量。官方特别说明，缺少 $ 的大写字符串会被当成字面 Key，而不是环境变量名。

第二步：编辑 ~/.pi/agent/models.json

{
  "providers": {
    "tokenhub": {
      "baseUrl": "__API_BASE_URL__/v1",
      "api": "openai-completions",
      "apiKey": "$TOKENHUB_API_KEY",
      "models": [
        {
          "id": "YOUR_TOKENHUB_MODEL_ID",
          "name": "TokenHub / YOUR_TOKENHUB_MODEL_ID",
          "reasoning": false,
          "input": ["text"],
          "contextWindow": 128000,
          "maxTokens": 8192
        }
      ]
    }
  }
}

逐项按 TokenHub 模型详情修正：

• id 是实际传给 API 的 Model ID，必填。
• reasoning 只有模型支持扩展思考时才改为 true。
• input 默认只有 text；支持图片时才写 ['text', 'image']。
• contextWindow 默认值虽然是 128000，但仍应填写模型真实上下文。
• maxTokens 是最大输出，默认值是 16384；不能用上下文窗口替代。

TokenHub 使用 Bearer Token；若当前 pi 版本没有自动添加 Authorization header，可在 Provider 层加入 "authHeader": true。

第三步：打开 /model 触发重新加载

在 pi 会话中运行 /model。官方说明每次打开 /model 都会重新读取 models.json，所以编辑后无需重启。选择 tokenhub/YOUR_TOKENHUB_MODEL_ID，先要求解释一个文件，再测试工具调用。

如果 Provider 或模型显示但不可选，说明配置已加载、凭证却没有解析成功。检查环境变量，或使用 /login / auth.json 保存该 Provider 的 Key。

pi 特有的兼容项

部分 OpenAI-compatible 服务不接受 developer role 或 reasoning_effort。只有实际出现对应 400 错误时，才添加：

"compat": {
  "supportsDeveloperRole": false,
  "supportsReasoningEffort": false
}

不要预先关闭能力。TokenHub 请求成功后，再根据具体模型决定是否配置 thinkingLevelMap、图片输入、采样参数或价格。

按 pi 的加载机制排错

• /model 中完全没有 Provider：检查文件路径、JSON 语法、baseUrl 和 api。
• Provider 存在但模型不可选：$TOKENHUB_API_KEY 未解析，或尚未通过 /login 配置凭证。
• 401：确认 pi 进程继承了环境变量，并按需设置 authHeader: true。
• 400 或提前截断：修正 contextWindow、maxTokens 或 compat，不要盲目放大数值。
• 修改未生效：重新打开 /model，而不是只看当前会话底部的旧选择。

官方资料

• pi：Custom Models
• pi：Custom Providers Extension API