Pi Agent 支持两种认证方式：订阅登录和 API Key。本章详细介绍如何配置，让 Pi Agent 连接到 AI 模型。

---

认证方式概览

认证方式	操作方法	适用场景
订阅登录（OAuth）	启动 pi 后执行 /login	已有 Claude Pro/Max、ChatGPT Plus/Pro、GitHub Copilot 等订阅
API Key 环境变量	设置环境变量后启动 pi	有 API Key，希望持久化到 shell 配置
API Key 凭证文件	通过 /login 选择 API Key 提供商存储	有 API Key，希望 Pi Agent 统一管理

---

方式一：订阅登录（推荐）

如果你已经订阅了 Claude Pro/Max、ChatGPT Plus/Pro 或 GitHub Copilot，这是最便捷的方式。

启动 Pi Agent 后，输入以下命令：

/login

然后在出现的菜单中选择你的订阅提供商：

提供商	要求	说明
Claude Pro/Max	Anthropic 订阅账号	使用额外用量计费，不占用计划额度
ChatGPT Plus/Pro (Codex)	OpenAI Plus 或 Pro 订阅	OpenAI 官方认可的 Codex for OSS
GitHub Copilot	GitHub Copilot 订阅	支持 github.com 和企业服务器
xAI (Grok)	X Premium 订阅	使用 Grok 模型
OpenRouter	OpenRouter 账户	OAuth 创建 API Key，从余额扣费

Claude Pro/Max 订阅认证模式下，Pi Agent 使用的是额外用量（extra usage），按 token 计费，不占用你的 Claude 计划额度。你可以在 Claude 用量设置 中查看。

完成登录后，凭证会存储在 ~/.pi/agent/auth.json 中，之后启动 Pi Agent 会自动使用。

如需退出登录，使用：

/logout

---

方式二：API Key 环境变量

如果你有 API Key，可以在启动 Pi Agent 前设置环境变量：

# 设置 Anthropic API Key
export ANTHROPIC_API_KEY=sk-ant-api03-your-key-here

# 启动 Pi Agent
pi

Pi Agent 支持以下主要提供商的 API Key 环境变量：

提供商	环境变量	auth.json 键名
Anthropic	ANTHROPIC_API_KEY	anthropic
OpenAI	OPENAI_API_KEY	openai
Google Gemini	GEMINI_API_KEY	google
DeepSeek	DEEPSEEK_API_KEY	deepseek
Groq	GROQ_API_KEY	groq
Mistral	MISTRAL_API_KEY	mistral
xAI	XAI_API_KEY	xai
OpenRouter	OPENROUTER_API_KEY	openrouter

配置 DeepSeek 供应商

Pi 通过 models.json 支持自定义供应商，配置文件地址：

• Linux / macOS：~/.pi/agent/models.json
• Windows：%USERPROFILE%\.pi\agent\models.json

先在 DeepSeek 开放平台获取 API Key：DeepSeek。

{
  "providers": {
    "deepseek": {
      "baseUrl": "https://api.deepseek.com",
      "api": "openai-completions",
      "apiKey": "$DEEPSEEK_API_KEY",
      "models": [
        {
          "id": "deepseek-v4-pro",
          "name": "DeepSeek V4 Pro",
          "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",
            "reasoningEffortMap": {
              "minimal": "high",
              "low": "high",
              "medium": "high",
              "high": "high",
              "xhigh": "max"
            }
          }
        },
        {
          "id": "deepseek-v4-flash",
          "name": "DeepSeek V4 Flash",
          "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",
            "reasoningEffortMap": {
              "minimal": "high",
              "low": "high",
              "medium": "high",
              "high": "high",
              "xhigh": "max"
            }
          }
        }
      ]
    }
  }
}

设置环境变量：

Linux / Mac 用户：

export DEEPSEEK_API_KEY="<你的 DeepSeek API Key>"

Windows 用户：

$env:DEEPSEEK_API_KEY="<你的 DeepSeek API Key>"

进入项目目录并执行 pi 命令：

cd /path/to/my-project
pi

如果你不想每次手动设置环境变量，可以将 export 命令写入 shell 配置文件（如 ~/.zshrc 或 ~/.bashrc），使其永久生效。

---

方式三：API Key 凭证文件

你也可以通过 /login 命令，选择 API Key 提供商来存储凭证。

存储位置为 ~/.pi/agent/auth.json，格式如下：

{
  "anthropic": { "type": "api_key", "key": "sk-ant-api03-your-key" },
  "openai": { "type": "api_key", "key": "sk-your-openai-key" },
  "deepseek": { "type": "api_key", "key": "sk-your-deepseek-key" }
}

凭证文件会自动设置为 0600 权限（仅用户可读写），安全性有基本保障。

---

凭证解析顺序

当 Pi Agent 需要获取 API Key 时，按以下优先级查找：

1. CLI 参数 --api-key（最高优先级）
2. auth.json 文件中的凭证
3. 环境变量
4. models.json 中自定义提供商的 Key

也就是说，如果你同时设置了环境变量和 auth.json，auth.json 中的值会优先生效。

---

auth.json 高级功能

auth.json 不仅支持存储明文 Key，还支持以下高级用法：

从命令行获取 Key

使用 ! 前缀执行命令来获取 Key，适合从密码管理器读取：

{
  "anthropic": {
    "type": "api_key",
    "key": "!security find-generic-password -ws 'anthropic-api-key'"
  },
  "openai": {
    "type": "api_key",
    "key": "!op read 'op://vault/item/credential'"
  }
}

上例展示了从 macOS Keychain 和 1Password CLI 获取 Key 的方式。

环境变量插值

使用 $ 前缀引用环境变量：

{
  "anthropic": {
    "type": "api_key",
    "key": "$MY_ANTHROPIC_KEY"
  }
}

切换模型

配置好认证后，你可以随时切换使用的 AI 模型：

交互模式中使用 /model 命令或按 Ctrl+L 打开模型选择器。

使用 Ctrl+P / Shift+Ctrl+P 在已配置的模型间循环切换。

命令行方式指定模型：

# 指定提供商和模型
$ pi --provider anthropic --model claude-sonnet-4-20250514

# 使用 provider/model 格式
$ pi --model openai/gpt-4o "帮我重构这段代码"

# 指定推理等级（thinking level）
$ pi --model sonnet:high "解决这个复杂问题"

推理等级（Thinking Level）控制模型在回答前进行多深度的思考。等级从 off（关闭）到 max（最大），推理越深回答质量可能越高，但消耗的 token 也越多。

推理等级	说明	适用场景
off	不显示推理过程	简单问答、代码格式化
minimal	最少推理	基础编码任务
low	低度推理	一般编程问题
medium	中度推理（默认推荐）	日常开发任务
high	高度推理	复杂架构设计、调试
xhigh	超高度推理	困难算法问题
max	最大推理	极复杂逻辑分析

编辑器的边框颜色会随推理等级变化，让你直观地看到当前推理深度。