Authentification et configuration du modèle de Pi Agent
Pi Agent prend en charge deux méthodes d'authentification : la connexion par abonnement et la clé API. Ce chapitre explique en détail comment configurer Pi Agent pour se connecter aux modèles d'IA.
Aperçu des méthodes d'authentification
| Méthode d'authentification | Comment utiliser | Scénario applicable |
|---|---|---|
| Connexion par abonnement (OAuth) | Exécuter /login après avoir démarré pi | Vous avez déjà des abonnements Claude Pro/Max, ChatGPT Plus/Pro, GitHub Copilot, etc. |
| Variable d'environnement de clé API | Définissez la variable d'environnement puis démarrez pi | Vous avez une clé API et souhaitez la conserver dans la configuration du shell |
| Fichier d'identifiants de clé API | Sélectionnez le fournisseur de clé API pour le stockage via /login | Vous avez une clé API et souhaitez que Pi Agent la gère de manière centralisée |
Méthode 1 : Connexion par abonnement (recommandée)
Si vous êtes déjà abonné à Claude Pro/Max, ChatGPT Plus/Pro ou GitHub Copilot, c'est la méthode la plus pratique.
Après avoir démarré Pi Agent, saisissez la commande suivante :
/login
Sélectionnez ensuite votre fournisseur d'abonnement dans le menu qui apparaît :
| Provider | Exigence | Description |
|---|---|---|
| Claude Pro/Max | Compte d'abonnement Anthropic | Facturé pour une utilisation supplémentaire, ne compte pas dans le quota du forfait |
| ChatGPT Plus/Pro (Codex) | Abonnement OpenAI Plus ou Pro | Codex officiellement reconnu par OpenAI pour l'OSS |
| GitHub Copilot | Abonnement GitHub Copilot | Prend en charge github.com et les serveurs d'entreprise |
| xAI (Grok) | Abonnement X Premium | Utilise le modèle Grok |
| OpenRouter | Compte OpenRouter | OAuth crée une clé API, déduite du solde |
En mode d'authentification par abonnement Claude Pro/Max, Pi Agent utilise une utilisation supplémentaire, facturée par token, et ne compte pas dans le quota de votre forfait Claude. Vous pouvez le vérifier dansles paramètres d'utilisation de Claude.
Après connexion, les identifiants sont stockés dans~/.pi/agent/auth.json, et Pi Agent les utilisera automatiquement lors des prochains démarrages.
Pour vous déconnecter, utilisez :
/logout
Méthode 2 : Variable d'environnement de clé API
Si vous avez une clé API, vous pouvez définir la variable d'environnement avant de démarrer Pi Agent :
# 设置 Anthropic API Key export ANTHROPIC_API_KEY=sk-ant-api03-your-key-here # 启动 Pi Agent pi
Pi Agent prend en charge les variables d'environnement de clé API pour les principaux fournisseurs suivants :
| Provider | Variable d'environnement | Nom de clé auth.json |
|---|---|---|
| Anthropic | ANTHROPIC_API_KEY | anthropic |
| OpenAI | OPENAI_API_KEY | openai |
| Google Gemini | GEMINI_API_KEY | |
| 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 |
Configurer le fournisseur DeepSeek
Pi prend en charge les fournisseurs personnalisés via models.json. Emplacement du fichier de configuration :
- Linux / macOS:~/.pi/agent/models.json
- Windows:%USERPROFILE%\.pi\agent\models.json
Tout d'abord, obtenez une clé API depuis la plateforme ouverte DeepSeek :https://platform.deepseek.com/api_keys。
{
"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"
}
}
}
]
}
}
}
Définissez la variable d'environnement :
Utilisateurs de Linux / Mac :
export DEEPSEEK_API_KEY="<你的 DeepSeek API Key>"
Utilisateurs de Windows :
$env:DEEPSEEK_API_KEY="<你的 DeepSeek API Key>"
Entrez dans le répertoire du projet et exécutez la commande pi :
cd /path/to/my-project pi
Si vous ne voulez pas définir manuellement la variable d'environnement à chaque fois, vous pouvez écrire la commande export dans votre fichier de configuration de shell (comme ~/.zshrc ou ~/.bashrc) pour la rendre permanente.
Méthode 3 : Fichier d'identifiants de clé API
Vous pouvez également utiliser la commande /login pour sélectionner un fournisseur de clé API afin de stocker les identifiants.
L'emplacement de stockage est~/.pi/agent/auth.json, avec le format suivant :
{
"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" }
}
Le fichier d'identifiants est automatiquement défini sur0600permissions (lisible et modifiable uniquement par l'utilisateur), offrant un niveau de sécurité de base.
Ordre de résolution des identifiants
Lorsque Pi Agent doit obtenir une clé API, il effectue une recherche dans l'ordre de priorité suivant :
- Paramètre CLI --api-key (priorité la plus élevée)
- Informations d'identification dans le fichier auth.json
- Variables d'environnement
- Clé provenant d'un fournisseur personnalisé dans models.json
En d'autres termes, si vous définissez à la fois une variable d'environnement et auth.json, la valeur dans auth.json est prioritaire.
Fonctionnalités avancées d'auth.json
auth.json prend non seulement en charge le stockage de clés en texte clair, mais prend également en charge l'usage avancé suivant :
Obtenir la clé à partir de la ligne de commande
Utilisez le!préfixe pour exécuter une commande afin d'obtenir la clé, ce qui convient pour la lire depuis un gestionnaire de mots de passe :
{
"anthropic": {
"type": "api_key",
"key": "!security find-generic-password -ws 'anthropic-api-key'"
},
"openai": {
"type": "api_key",
"key": "!op read 'op://vault/item/credential'"
}
}
L'exemple ci-dessus montre comment obtenir la clé depuis le trousseau macOS et 1Password CLI.
Interpolation des variables d'environnement
Utilisez le$préfixe pour référencer les variables d'environnement :
{
"anthropic": {
"type": "api_key",
"key": "$MY_ANTHROPIC_KEY"
}
}
Changement de modèles
Après avoir configuré l'authentification, vous pouvez changer le modèle d'IA utilisé à tout moment :
En mode interactif, utilisez la commande/modelou appuyez surCtrl+Lpour ouvrir le sélecteur de modèle.
UtilisezCtrl+P / Shift+Ctrl+Ppour parcourir les modèles configurés.
Spécifiez le modèle depuis la ligne de commande :
# 指定提供商和模型 $ pi --provider anthropic --model claude-sonnet-4-20250514 # 使用 provider/model 格式 $ pi --model openai/gpt-4o "帮我重构这段代码" # 指定推理等级(thinking level) $ pi --model sonnet:high "解决这个复杂问题"
Le niveau de réflexion contrôle la profondeur de réflexion du modèle avant de répondre. Les niveaux vont de désactivé à max. Une réflexion plus profonde peut produire des réponses de meilleure qualité, mais consomme plus de tokens.
| Niveau de réflexion | Description | Scénario applicable |
|---|---|---|
| off | N'affiche pas le processus de raisonnement | Questions-réponses simples, formatage de code |
| minimal | Raisonnement minimal | Tâches de codage de base |
| low | Raisonnement faible | Problèmes de programmation généraux |
| moyen | Raisonnement moyen (recommandé par défaut) | Tâches de développement quotidiennes |
| élevé | Raisonnement élevé | Conception d'architecture complexe, débogage |
| xhigh | Raisonnement très élevé | Problèmes algorithmiques difficiles |
| max | Raisonnement maximal | Analyse logique extrêmement complexe |
La couleur de la bordure de l'éditeur change avec le niveau de réflexion, ce qui vous permet de voir intuitivement la profondeur de raisonnement actuelle.
Autres extensions