Chapter 3 · Providers and Models Config

Chapter goals: Master pi's authentication system (subscription/API Key/auth.json) and key resolution order; learn to接入 OpenAI-compatible custom models using models.json; andswitch efficiently between multiple models.

3.1 Two Access Methods

pi divides model sources into两类:

• Subscription:复用 your existing official subscription accounts; complete OAuth登录 via /login. Built-in支持: ChatGPT Plus/Pro (Codex), Claude Pro/Max, GitHub Copilot, xAI (Grok subscription), OpenRouter, Radius. OAuth tokens stored in ~/.pi/agent/auth.json and auto-renew;
• API Key: pay-as-you-go; provide keys via env vars or auth.json.

# Minimal API Key usage
export OPENAI_API_KEY=sk-...
export DEEPSEEK_API_KEY=sk-...
pi

Common providers and env vars对照 (excerpt from the official table):

Provider	Env Var
Anthropic	ANTHROPIC_API_KEY
OpenAI	OPENAI_API_KEY
DeepSeek	DEEPSEEK_API_KEY
Google Gemini	GEMINI_API_KEY
Groq	GROQ_API_KEY
OpenRouter	OPENROUTER_API_KEY
Volcano Ark/Qwen Token Plan	QWEN_TOKEN_PLAN_API_KEY

3.2 auth.json and Key Resolution Order

When /login selects an API-key类 provider, the key is written to ~/.pi/agent/auth.json (0600 permissions); auth.json优先级高于环境变量:

{
  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
  "deepseek": { "type": "api_key", "key": "sk-..." }
}

The key field supports四种写法 (value parsing rules):

{
  "a": { "type": "api_key", "key": "!security find-generic-password -ws 'anthropic'" },
  "b": { "type": "api_key", "key": "$MY_ANTHROPIC_KEY" },
  "c": { "type": "api_key", "key": "${KEY_PREFIX}_${KEY_SUFFIX}" },
  "d": { "type": "api_key", "key": "$$literal-dollar-prefix" }
}

• "!command": execute a shell command and take stdout (suitable for接 macOS Keychain, 1Password CLI);
• "$VAR" / "${VAR}": env var interpolation; $$ and $! are literal escapes.

完整解析优先级 (high→low): CLI --api-key → auth.json → env vars → custom provider keys in models.json.

3.3接入 OpenAI-Compatible Models via models.json

凡是说 OpenAI / Anthropic / Google协议的服务都能接入 ~/.pi/agent/models.json. Local Ollama只需 id:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [
        { "id": "llama3.1:8b" },
        { "id": "qwen2.5-coder:7b" }
      ]
    }
  }
}

Key points:

• apiKey write a placeholder (Ollama does not校验);但必须存在否则模型不出现在 /model 列表;
• Many OpenAI-compatible servers不认识 reasoning models' developer role; use compat.supportsDeveloperRole: false to让系统提示降级为 system messages;同理关闭 supportsReasoningEffort;
• compat can be placed at the provider level (applies to all models) or overridden at the model level.

When precise能力声明 is needed, use完整 fields:

{
  "id": "llama3.1:8b",
  "name": "Llama 3.1 8B (Local)",
  "reasoning": false,
  "input": ["text"],
  "contextWindow": 128000,
  "maxTokens": 32000,
  "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
}

Hot Reload

models.json re-reads每次打开 /model — editing the file mid-session无需重启 pi.

3.4 Multi-Model Switching in Practice

pi update --models   # Force-refresh the model目录 cache for config-type providers
pi --list-models     # List all available models from the CLI

Switching手段 in interactive:

Action	Effect
/model or Ctrl+L	Open the model picker
Ctrl+P / Shift+Ctrl+P	Cycle forward/backward through scoped models
/scoped-models	Configure which models参与 Ctrl+P cycling

Typical workflow:加入 "cheap/fast model + strong reasoning model" to scoped models;日常问答用前者;遇到硬骨头一键切到后者; Shift+Tab调整思考等级控制推理深度与成本.

3.5 Model Capability Differences Impact on Coding Tasks

• contextWindow决定一次能塞多少代码上下文;小窗口 models要靠 /compact (Chapter 6)勤压缩;
• reasoning/thinkingLevelMap影响架构设计与疑难调试质量;但显著增加延迟与 token成本;
• input supports image才能粘贴截图做 UI还原任务;
• samplingParams only生效 on OpenAI-compatible APIs;可透传 vLLM的 top_k、llama.cpp的 min_p 等服务端特有参数.

Chapter Summary

• Authentication两条路: /login subscription OAuth or API Key; auth.json > env vars > models.json key;
• Key values支持 !command, $ENV, ${VAR} interpolation and $$/$! escape四种解析方式;
• ~/.pi/agent/models.json可接入任意 OpenAI/Anthropic/Google协议服务; compat handles兼容性;
• Ctrl+L pick model, Ctrl+P cycle scoped models, Shift+Tab调 thinking level are日常三板斧;
• The model's context window/reasoning能力/multimodal支持直接决定它适合的编码任务类型.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. What is the correct priority for pi to resolve provider credentials?

2. After接入 local Ollama, the model does not appear in the /model list. The most likely cause is?

3. An OpenAI-compatible server不认识 developer role messages. How to handle it?

4. After modifying ~/.pi/agent/models.json, which statement is correct?

🛠️ Hands-on Practice

1. Use models.json to接入 a local or third-party OpenAI-compatible endpoint to pi;验证 with --list-models. 2.改造 your DeepSeek/OpenAI key into the "!command" form in auth.json (e.g. read from a password manager);验证优先级高于 env vars.
2. Configure two models with明显价格/能力差异 into scoped models; execute the same refactoring task with each;对比成本与质量.

Proceed to Chapter 4: Interactive Mode to拉满 the terminal效率.