认证与模型配置

为什么 pi 不内置模型

打开 pi 的那一刻你会发现：它没有自带 AI 模型。你得自己去申请一个 API Key 交给它。

这不是功能缺失，是设计选择。pi 的核心原则是 BYOK——自带密钥。它不做模型代理、不赚 API 差价、不绑定任何一家提供商。

这样做有三个好处：

1. 你选模型，不用被工具限制。觉得 DeepSeek 便宜性价比高就用 DeepSeek，复杂任务想切 Claude Sonnet 就切 Sonnet。
2. 账单归你自己。API 费用走你自己的账号，花多少看多少，没有隐藏成本。
3. 数据不出你控制的边界。你可以接本地模型（通过 llama.cpp 或 Ollama），代码完全不离开你的机器。

三种配 Key 的方式，从快到稳

pi 支持三种方式提供 API Key，各有适用场景：

方式	怎么做	适合谁
环境变量	启动 pi 前 export 设置	习惯命令行、喜欢显式控制的开发者
auth.json 文件	通过 /login 命令存储	不想每次手动设环境变量的用户
models.json 自定义	在配置文件中声明提供商	接入 DeepSeek 等自定义提供商

三种方式可以混用。pi 查找 Key 的优先级是：

1. CLI 参数 --api-key（最高）
2. auth.json 中的凭证
3. 环境变量
4. models.json 中声明的 apiKey

知道这个顺序很重要——如果你同时用环境变量和 /login 存了 Key，pi 会用 /login 存的，而不是环境变量里的。

方式一：环境变量，最简单直接

如果你手里已经有某个平台的 API Key，在启动 pi 前设个环境变量就行：

export ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxx
pi

pi 启动后会自动识别环境变量中的 Key，连接对应提供商。支持的主要环境变量：

提供商	环境变量名
Anthropic	ANTHROPIC_API_KEY
OpenAI	OPENAI_API_KEY
Google Gemini	GEMINI_API_KEY
DeepSeek	DEEPSEEK_API_KEY
Groq	GROQ_API_KEY
Mistral	MISTRAL_API_KEY
xAI	XAI_API_KEY
OpenRouter	OPENROUTER_API_KEY

方式二：订阅登录，有 Claude Pro 就更省事

如果你已经订阅了 Claude Pro/Max、ChatGPT Plus/Pro 或 GitHub Copilot，可以直接用它们登录 pi：

在 pi 交互界面里输入：

/login

然后从菜单里选择你的订阅提供商。pi 会打开浏览器完成 OAuth 认证，之后凭证保存到 ~/.pi/agent/auth.json。

存好之后每次启动 pi 自动生效。想退出登录的话：

/logout

方式三：models.json，给 pi 接上自定义提供商

DeepSeek 本身是内置提供商（用 DEEPSEEK_API_KEY 环境变量就能直接激活），这里故意再用 models.json 演示一遍自定义配置的方式——本地 Ollama、代理网关这类非内置提供商正是靠这个方式接入的。

这是最灵活但也最需要仔细配置的方式。下面以 DeepSeek 为例，一步一步走通。

实战：给 pi 接上 DeepSeek

DeepSeek 提供 OpenAI 兼容接口，pi 可以复用现成的 OpenAI 适配层来对接。整个流程分四步。

第一步：申请 DeepSeek API Key

打开 platform.deepseek.com/api_keys，登录后创建一个新的 API Key，复制下来。Key 的格式类似 sk-xxxxxxxxxxxxxxxx。

第二步：创建 models.json

找到 pi 的配置目录，新建 models.json：

操作系统	文件路径
macOS / Linux	~/.pi/agent/models.json
Windows	%USERPROFILE%\.pi\agent\models.json

写入以下内容：

{
  "providers": {
    "deepseek": {
      "baseUrl": "https://api.deepseek.com",
      "api": "openai-completions",
      "apiKey": "${DEEPSEEK_API_KEY}",
      "models": [
        {
          "id": "deepseek-chat",
          "name": "DeepSeek Chat",
          "contextWindow": 1000000,
          "maxTokens": 384000,
          "input": ["text"],
          "reasoning": true,
          "cost": {
            "input": 0.14,
            "output": 0.28,
            "cacheRead": 0.028,
            "cacheWrite": 0
          },
          "compat": {
            "requiresReasoningContentOnAssistantMessages": true,
            "thinkingFormat": "deepseek",
            "thinkingLevelMap": {
              "minimal": null,
              "low": null,
              "medium": null,
              "high": "high",
              "xhigh": null,
              "max": "max"
            }
          }
        },
        {
          "id": "deepseek-reasoner",
          "name": "DeepSeek Reasoner",
          "contextWindow": 1000000,
          "maxTokens": 384000,
          "input": ["text"],
          "reasoning": true,
          "cost": {
            "input": 1.74,
            "output": 3.48,
            "cacheRead": 0.145,
            "cacheWrite": 0
          },
          "compat": {
            "requiresReasoningContentOnAssistantMessages": true,
            "thinkingFormat": "deepseek",
            "thinkingLevelMap": {
              "minimal": null,
              "low": null,
              "medium": null,
              "high": "high",
              "xhigh": null,
              "max": "max"
            }
          }
        }
      ]
    }
  }
}

几点说明：

• apiKey 用了 ${DEEPSEEK_API_KEY} 形式，表示从环境变量读取。你的 Key 不用明文写进文件。
• baseUrl 是 DeepSeek 的 OpenAI 兼容接口地址，这个不变。
• api 设为 openai-completions，告诉 pi 用 OpenAI 的协议格式跟 DeepSeek 通信。
• 两个模型 deepseek-chat 和 deepseek-reasoner：前者是通用对话模型，便宜、响应快，日常写代码够用；后者是深度推理模型，单价更高，适合复杂分析和重构。
• thinkingLevelMap 把 pi 的推理等级映射到 DeepSeek 的实现。DeepSeek 目前主要支持 high 和 max 两档——xhigh 被映射到 max，其余中低档位设为 null（不支持）。

第三步：设置环境变量

macOS / Linux：

export DEEPSEEK_API_KEY="sk-你的真实Key"

Windows PowerShell：

$env:DEEPSEEK_API_KEY="sk-你的真实Key"

把这一行写入你的 shell 配置文件（~/.zshrc、~/.bashrc 或 PowerShell Profile），以后每次开终端自动生效。

第四步：启动并切换模型

进项目目录启动 pi：

cd ~/my-project
pi

进了交互界面后输入 /model 打开模型选择器，找到 deepseek 提供商，选 DeepSeek Chat 或 DeepSeek Reasoner。切换完成后发一条消息试试：“你好，介绍一下你自己”——能正常回复就说明接入成功了。

多提供商并存，自由切换

pi 允许你同时配多个提供商。比如你可以把 Anthropic、DeepSeek 和本地 Ollama 的配置都写在 models.json 里：

{
  "providers": {
    "deepseek": {
      "baseUrl": "https://api.deepseek.com",
      "api": "openai-completions",
      "apiKey": "${DEEPSEEK_API_KEY}",
      "models": []
    },
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "***",
      "models": [
        { "id": "qwen2.5-coder:7b" }
      ]
    }
  }
}

加上 Anthropic、OpenAI 这种内置提供商通过环境变量就能激活，最终 pi 里可能出现四五个可切换的模型。日常用便宜的，关键时刻切强的，主动权在你手里。