地址：https://github.com/earendil-works/pi
官网地址：https://pi.dev/

1. 安装方法

npm install -g @earendil-works/pi-coding-agent

2. 鉴权关键配置文件：

3. ~/.pi/agent/models.json <-- 鉴权配置

4. ~/.pi/agent/auth.json <-- 鉴权配置

5. ~/.pi/agent/settings.json <-- 可以参考下面的配置

{
  "lastChangelogVersion": "0.74.0",
  "defaultProvider": "yeshen_gateway",
  "defaultModel": "deepseek-v4-pro",
  "defaultThinkingLevel": "high"
}

Authentication

pi 支持四种鉴权方式，按优先级从高到低排列：

1. --api-key 命令行参数
2. ~/.pi/agent/auth.json 配置文件
3. 环境变量
4. ~/.pi/agent/models.json 自定义 provider 的 apiKey

---

1. --api-key 命令行参数

最高优先级，运行时传入，仅存在于内存中，不落盘。

用法

pi --model anthropic/claude-sonnet-4-20250514 --api-key sk-ant-api03-xxxx

• --api-key 必须配合 --model 或 --provider 使用
• 密钥与指定 model 所属的 provider 关联（如 anthropic）
• 每次启动都需要重新传入

相关参数

参数	类型	说明
--api-key <key>	string	API 密钥，纯文本
--model <provider/model>	string	必需，指定使用该 key 的 model
--provider <id>	string	指定 provider（可选，否则从 model 推断）

---

2. ~/.pi/agent/auth.json

持久化鉴权文件，文件权限 0600，目录权限 0700。

文件结构

{
  "<provider-id>": {
    "type": "<credential-type>",
    ...
  }
}

顶层 key 为 provider ID，value 为凭证对象，支持两种 type：

2.1 API Key 类型

{
  "openai": {
    "type": "api_key",
    "key": "sk-..."
  }
}

key 字段支持的三种格式

格式	示例	说明
字面值	"key": "sk-ant-api03-xxxx"	直接使用
环境变量名	"key": "OPENAI_API_KEY"	从 process.env 读取
Shell 命令	"key": "!op read 'op://vault/api-key'"	以 ! 开头，执行命令取 stdout 作为 key

Shell 命令的结果会按进程生命周期缓存。

2.2 OAuth 类型

通过 /login 命令自动写入，存储 OAuth 鉴权后的 token：

{
  "anthropic": {
    "type": "oauth",
    "access": "sk-ant-api03-...",
    "refresh": "sk-ant-api03-...",
    "expires": 1718208000000
  }
}

字段	类型	说明
access	string	Access token，作为 API key 使用
refresh	string	Refresh token，用于刷新过期的 access token
expires	number	过期时间戳（ms，已扣除 5 分钟缓冲）
*	any	额外 provider 特定字段（如 enterpriseUrl、accountId）

内置 OAuth Provider

Provider ID	名称	鉴权方式
anthropic	Anthropic (Claude Pro/Max)	Authorization Code + PKCE
github-copilot	GitHub Copilot	Device Code Flow
openai-codex	ChatGPT Plus/Pro (Codex)	Authorization Code + PKCE

OAuth token 到期后会自动刷新（带文件锁防并发）。

管理方式

• /login：交互式选择 provider 并完成鉴权
• /logout：删除指定 provider 的鉴权信息
• 直接编辑文件：手动写入 JSON

---

3. 环境变量

当 auth.json 没有对应 provider 的凭证时，自动从环境变量读取。

完整映射表

Provider ID	环境变量
anthropic	ANTHROPIC_OAUTH_TOKEN / ANTHROPIC_API_KEY
openai	OPENAI_API_KEY
azure-openai-responses	AZURE_OPENAI_API_KEY
deepseek	DEEPSEEK_API_KEY
google	GEMINI_API_KEY
google-vertex	GOOGLE_CLOUD_API_KEY
groq	GROQ_API_KEY
cerebras	CEREBRAS_API_KEY
xai	XAI_API_KEY
openrouter	OPENROUTER_API_KEY
vercel-ai-gateway	AI_GATEWAY_API_KEY
zai	ZAI_API_KEY
mistral	MISTRAL_API_KEY
minimax	MINIMAX_API_KEY
minimax-cn	MINIMAX_CN_API_KEY
moonshotai	MOONSHOT_API_KEY
moonshotai-cn	MOONSHOT_API_KEY
huggingface	HF_TOKEN
fireworks	FIREWORKS_API_KEY
together	TOGETHER_API_KEY
opencode / opencode-go	OPENCODE_API_KEY
kimi-coding	KIMI_API_KEY
cloudflare-workers-ai	CLOUDFLARE_API_KEY
cloudflare-ai-gateway	CLOUDFLARE_API_KEY
xiaomi	XIAOMI_API_KEY
xiaomi-token-plan-cn	XIAOMI_TOKEN_PLAN_CN_API_KEY
xiaomi-token-plan-ams	XIAOMI_TOKEN_PLAN_AMS_API_KEY
xiaomi-token-plan-sgp	XIAOMI_TOKEN_PLAN_SGP_API_KEY
github-copilot	COPILOT_GITHUB_TOKEN / GH_TOKEN / GITHUB_TOKEN

云端环境鉴权（无需显式 API Key）

Provider ID	鉴权方式
google-vertex	Google ADC（gcloud auth application-default login），需配合 GOOGLE_CLOUD_PROJECT + GOOGLE_CLOUD_LOCATION
amazon-bedrock	AWS 凭证链：AWS_PROFILE / AWS_ACCESS_KEY_ID+AWS_SECRET_ACCESS_KEY / AWS_BEARER_TOKEN_BEDROCK / ECS/EC2 容器凭证 / Web Identity Token

---

4. ~/.pi/agent/models.json 自定义 Provider

适用于自定义 provider（如 ollama、vLLM、LM Studio 等）。仅对在 models.json 中显式定义的 provider 生效，内置 provider 不从此文件回退。

文件结构

{
  "providers": {
    "<provider-id>": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        { "id": "llama3.2" }
      ]
    }
  }
}

Provider 配置字段

字段	类型	必需	说明
name	string	否	显示名称
baseUrl	string	是（自定义 provider）	API 基础 URL
apiKey	string	是（自定义 provider）	API 密钥，支持字面值、环境变量名、!command 三种格式（同 auth.json）
api	string	否	API 协议（如 "openai-completions"、"anthropic-messages"、"openai-responses"）
headers	Record<string, string>	否	自定义 HTTP 请求头
authHeader	boolean	否	是否自动添加 Authorization: Bearer <apiKey> 头
models	ModelDefinition[]	否	自定义 model 列表
modelOverrides	Record<string, ModelOverride>	否	覆盖内置 model 的参数
compat	ProviderCompat	否	兼容性选项

models.json 中 apiKey 的分辨优先级

1. 字面值（如 "ollama"）
2. 环境变量名（如 "MY_LOCAL_KEY"，先查 process.env，找不到当作字面值）
3. Shell 命令（如 "!gcloud auth print-access-token"，以 ! 开头）

Shell 命令结果不缓存（与 auth.json 不同，每次解析都会执行）。

---

完整鉴权解析链

用户请求 API Key (providerId)
  │
  ├─ 1. --api-key 运行时参数（内存，不落盘）
  │    └─ 命中 → 返回
  │
  ├─ 2. auth.json
  │    ├─ type: "api_key" → resolveConfigValue(key)
  │    │    ├─ 字面值
  │    │    ├─ 环境变量名
  │    │    └─ !shell 命令（缓存）
  │    └─ type: "oauth" → getApiKey(cred)
  │         ├─ 未过期 → 返回 access token
  │         └─ 已过期 → 自动 refresh → 返回新 access token
  │
  ├─ 3. 环境变量（如 OPENAI_API_KEY）
  │    └─ 命中 → 返回
  │
  └─ 4. models.json 自定义 provider apiKey
       └─ 命中 → resolveConfigValue(apiKey)（不缓存）
            └─ 仅在 models.json 中显式定义的 provider 有效