Autenticación y configuración de modelos de Pi Agent

Pi Agent admite dos métodos de autenticación: inicio de sesión por suscripción y API Key. Este capítulo detalla cómo configurar Pi Agent para conectarse a modelos de IA.

Resumen de métodos de autenticación

Método de autenticación	Método de operación	Escenarios aplicables
Inicio de sesión por suscripción (OAuth)	Después de iniciar pi, ejecutar /login	Ya tener suscripciones a Claude Pro/Max, ChatGPT Plus/Pro, GitHub Copilot, etc.
Variable de entorno de API Key	Iniciar pi después de configurar las variables de entorno	Tener API Key y desear persistirla en la configuración del shell
Archivo de credenciales de API Key	Almacenar seleccionando el proveedor de API Key mediante /login	Tener API Key y desear que Pi Agent la gestione de forma unificada

Método 1: Inicio de sesión por suscripción (recomendado)

Si ya tienes suscripciones a Claude Pro/Max, ChatGPT Plus/Pro o GitHub Copilot, esta es la forma más conveniente.

Después de iniciar Pi Agent, introduce el siguiente comando:

/login

Luego selecciona tu proveedor de suscripción en el menú que aparece:

Proveedor	Requisito	Descripción
Claude Pro/Max	Cuenta de suscripción de Anthropic	Se factura por uso adicional, no consume el cupo del plan
ChatGPT Plus/Pro (Codex)	Suscripción a OpenAI Plus o Pro	Codex for OSS reconocido oficialmente por OpenAI
GitHub Copilot	Suscripción a GitHub Copilot	Compatible con github.com y servidores empresariales
xAI (Grok)	Suscripción a X Premium	Usar el modelo Grok
OpenRouter	Cuenta de OpenRouter	OAuth crea una API Key y descuenta del saldo

En el modo de autenticación por suscripción Claude Pro/Max, Pi Agent utiliza el uso adicional (extra usage), se factura por token y no consume tu cupo del plan de Claude. Puedes verlo enConfiguración de uso de Claudeverlo.

Después de iniciar sesión, las credenciales se almacenan en~/.pi/agent/auth.jsony se usarán automáticamente al iniciar Pi Agent posteriormente.

Para cerrar sesión, utiliza:

/logout

Método 2: Variable de entorno de API Key

Si tienes una API Key, puedes configurar una variable de entorno antes de iniciar Pi Agent:

# 设置 Anthropic API Key
export ANTHROPIC_API_KEY=sk-ant-api03-your-key-here

# 启动 Pi Agent
pi

Pi Agent admite las variables de entorno de API Key de los siguientes proveedores principales:

Proveedor	Variable de entorno	Nombre de clave en auth.json
Anthropic	ANTHROPIC_API_KEY	anthropic
OpenAI	OPENAI_API_KEY	openai
Google Gemini	GEMINI_API_KEY	google
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

Configurar el proveedor DeepSeek

Pi admite proveedores personalizados mediante models.json. Dirección del archivo de configuración:

Linux / macOS：~/.pi/agent/models.json
Windows：%USERPROFILE%\.pi\agent\models.json

Primero obtén una API Key en la plataforma abierta de 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"
            }
          }
        }
      ]
    }
  }
}

Configura la variable de entorno:

Usuarios de Linux / Mac:

export DEEPSEEK_API_KEY="<你的 DeepSeek API Key>"

Usuarios de Windows:

$env:DEEPSEEK_API_KEY="<你的 DeepSeek API Key>"

Entra en el directorio del proyecto y ejecuta el comando pi:

cd /path/to/my-project
pi

Si no quieres configurar manualmente la variable de entorno cada vez, puedes añadir el comando export al archivo de configuración del shell (como ~/.zshrc o ~/.bashrc) para que sea permanente.

Método 3: Archivo de credenciales de API Key

También puedes almacenar credenciales seleccionando un proveedor de API Key mediante el comando /login.

La ubicación de almacenamiento es~/.pi/agent/auth.json, con el siguiente formato:

{
  "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" }
}

El archivo de credenciales se configurará automáticamente con permisos0600(solo lectura y escritura para el usuario), lo que ofrece una seguridad básica.

Orden de resolución de credenciales

Cuando Pi Agent necesita obtener una API Key, la busca con la siguiente prioridad:

Argumento de CLI --api-key (prioridad más alta)
Credenciales en el archivo auth.json
Variable de entorno
Key del proveedor personalizado en models.json

Pi Agent 凭证解析优先级链

Es decir, si configuras tanto la variable de entorno como auth.json, el valor en auth.json tendrá prioridad.

Funciones avanzadas de auth.json

auth.json no solo admite el almacenamiento de Keys en texto plano, sino también los siguientes usos avanzados:

Obtener la Key desde la línea de comandos

Usar!prefijo para ejecutar un comando y obtener la Key, ideal para leer desde gestores de contraseñas:

{
  "anthropic": {
    "type": "api_key",
    "key": "!security find-generic-password -ws 'anthropic-api-key'"
  },
  "openai": {
    "type": "api_key",
    "key": "!op read 'op://vault/item/credential'"
  }
}

El ejemplo anterior muestra cómo obtener Keys desde macOS Keychain y 1Password CLI.

Interpolación de variables de entorno

Usar$prefijo para hacer referencia a variables de entorno:

{
  "anthropic": {
    "type": "api_key",
    "key": "$MY_ANTHROPIC_KEY"
  }
}

Cambiar de modelo

Después de configurar la autenticación, puedes cambiar en cualquier momento el modelo de IA utilizado:

En el modo interactivo, usa/modelcomando o pulsaCtrl+Lpara abrir el selector de modelos.

UsarCtrl+P / Shift+Ctrl+Ppara alternar cíclicamente entre los modelos configurados.

Especificar el modelo desde la línea de comandos:

# 指定提供商和模型
$ pi --provider anthropic --model claude-sonnet-4-20250514

# 使用 provider/model 格式
$ pi --model openai/gpt-4o "帮我重构这段代码"

# 指定推理等级（thinking level）
$ pi --model sonnet:high "解决这个复杂问题"

El nivel de razonamiento (Thinking Level) controla cuán profundamente piensa el modelo antes de responder. Los niveles van de off (desactivado) a max (máximo). Cuanto más profundo sea el razonamiento, mayor puede ser la calidad de las respuestas, pero también consume más tokens.

Nivel de razonamiento	Descripción	Escenarios aplicables
off	No muestra el proceso de razonamiento	Preguntas y respuestas simples, formateo de código
minimal	Razonamiento mínimo	Tareas básicas de codificación
low	Razonamiento bajo	Problemas de programación generales
medium	Razonamiento medio (recomendado por defecto)	Tareas de desarrollo diarias
high	Razonamiento alto	Diseño de arquitectura compleja, depuración
xhigh	Razonamiento muy alto	Problemas algorítmicos difíciles
max	Razonamiento máximo	Análisis lógico extremadamente complejo

El color del borde del editor cambia según el nivel de razonamiento, lo que te permite ver de forma visual la profundidad de razonamiento actual.

Otras extensiones

Favoritos de referencia