HoRain云--Pi Agent 认证与模型配置

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/MaxAnthropic 订阅账号使用额外用量计费不占用计划额度ChatGPT Plus/Pro (Codex)OpenAI Plus 或 Pro 订阅OpenAI 官方认可的 Codex for OSSGitHub CopilotGitHub Copilot 订阅支持 github.com 和企业服务器xAI (Grok)X Premium 订阅使用 Grok 模型OpenRouterOpenRouter 账户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_KEYsk-ant-api03-your-key-here # 启动 Pi Agent piPi Agent 支持以下主要提供商的 API Key 环境变量提供商环境变量auth.json 键名AnthropicANTHROPIC_API_KEYanthropicOpenAIOPENAI_API_KEYopenaiGoogle GeminiGEMINI_API_KEYgoogleDeepSeekDEEPSEEK_API_KEYdeepseekGroqGROQ_API_KEYgroqMistralMISTRAL_API_KEYmistralxAIXAI_API_KEYxaiOpenRouterOPENROUTER_API_KEYopenrouter配置 DeepSeek 供应商Pi 通过 models.json 支持自定义供应商配置文件地址Linux / macOS~/.pi/agent/models.jsonWindows%USERPROFILE%\.pi\agent\models.json先在 DeepSeek 开放平台获取 API KeyDeepSeek。{ 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 KeyWindows 用户$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 时按以下优先级查找CLI 参数 --api-key最高优先级auth.json 文件中的凭证环境变量models.json 中自定义提供商的 Key也就是说如果你同时设置了环境变量和 auth.jsonauth.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 命令或按 CtrlL 打开模型选择器。使用 CtrlP / ShiftCtrlP 在已配置的模型间循环切换。命令行方式指定模型# 指定提供商和模型 $ 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最大推理极复杂逻辑分析编辑器的边框颜色会随推理等级变化让你直观地看到当前推理深度。