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'authentificationComment utiliserScénario applicable
Connexion par abonnement (OAuth)Exécuter /login après avoir démarré piVous avez déjà des abonnements Claude Pro/Max, ChatGPT Plus/Pro, GitHub Copilot, etc.
Variable d'environnement de clé APIDéfinissez la variable d'environnement puis démarrez piVous avez une clé API et souhaitez la conserver dans la configuration du shell
Fichier d'identifiants de clé APISélectionnez le fournisseur de clé API pour le stockage via /loginVous 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 :

ProviderExigenceDescription
Claude Pro/MaxCompte d'abonnement AnthropicFacturé pour une utilisation supplémentaire, ne compte pas dans le quota du forfait
ChatGPT Plus/Pro (Codex)Abonnement OpenAI Plus ou ProCodex officiellement reconnu par OpenAI pour l'OSS
GitHub CopilotAbonnement GitHub CopilotPrend en charge github.com et les serveurs d'entreprise
xAI (Grok)Abonnement X PremiumUtilise le modèle Grok
OpenRouterCompte OpenRouterOAuth 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 :

ProviderVariable d'environnementNom de clé auth.json
AnthropicANTHROPIC_API_KEYanthropic
OpenAIOPENAI_API_KEYopenai
Google GeminiGEMINI_API_KEYgoogle
DeepSeekDEEPSEEK_API_KEYdeepseek
GroqGROQ_API_KEYgroq
MistralMISTRAL_API_KEYmistral
xAIXAI_API_KEYxai
OpenRouterOPENROUTER_API_KEYopenrouter

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 :

  1. Paramètre CLI --api-key (priorité la plus élevée)
  2. Informations d'identification dans le fichier auth.json
  3. Variables d'environnement
  4. Clé provenant d'un fournisseur personnalisé dans models.json

Pi Agent 凭证解析优先级链

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éflexionDescriptionScénario applicable
offN'affiche pas le processus de raisonnementQuestions-réponses simples, formatage de code
minimalRaisonnement minimalTâches de codage de base
lowRaisonnement faibleProblèmes de programmation généraux
moyenRaisonnement moyen (recommandé par défaut)Tâches de développement quotidiennes
élevéRaisonnement élevéConception d'architecture complexe, débogage
xhighRaisonnement très élevéProblèmes algorithmiques difficiles
maxRaisonnement maximalAnalyse 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