Providers

Pi oferece suporte a provedores baseados em assinatura por meio de provedores OAuth e API key por meio de variáveis de ambiente ou arquivo de autenticação. Catálogos integrados são fornecidos com pi; provedores configurados podem atualizar catálogos mais recentes e armazená-los em cache em ~/.pi/agent/models-store.json para uso offline.

• Subscriptions
• API Keys
• Auth File
• Cloud Providers
• llama.cpp
• Custom Providers
• Resolution Order

Use /login no modo interativo e selecione um provedor:

• ChatGPT Plus/Pro (Codex)
• Claude Pro/Max
• GitHub Copilot
• xAI (Grok/X subscription)
• OpenRouter (OAuth-minted API key billed from OpenRouter credits)
• Radius

Use /logout para limpar credenciais. Os tokens são armazenados em ~/.pi/agent/auth.json e atualizados automaticamente quando expiram. Em vez disso, o OpenRouter cria um API key controlado pelo usuário que não expira automaticamente.

• Requer assinatura ChatGPT Plus ou Pro
• Aprovado oficialmente pela OpenAI: Codex for OSS

A autenticação de assinatura Anthropic está ativa para contas Claude Pro/Max. O uso por ferramentas de terceiros é debitado de extra usage e cobrado por token, não contra os limites do plano Claude.

• Pressione Enter para github.com ou insira seu domínio GitHub Enterprise Server
• Se você obtiver "modelo não suportado", habilite-o no VS Code: Copilot Chat → seletor de modelo → selecione modelo → "Ativar"

• Execute /login xai e selecione Usar uma assinatura
• XAI_API_KEY permanece disponível através de Use um API key

• Execute /login openrouter e selecione Entrar com OpenRouter para abrir o fluxo de autorização OpenRouter PKCE
• A autorização cria um OpenRouter API key controlado pelo usuário, cobrado de seus créditos OpenRouter
• Em máquinas remotas/sem cabeça (por exemplo, acima de SSH) o navegador não pode alcançar o retorno de chamada de loopback; cole o URL de redirecionamento final (ou o código de autorização) no prompt de login
• OPENROUTER_API_KEY permanece disponível através de Use um API key

Radius é um gateway pi-messages dinâmico. /login radius armazena OAuth tokens em auth.json; o catálogo do gateway é atualizado de forma independente e armazenado em cache em models-store.json. Gateways Radius personalizados podem ser declarados em models.json com "oauth": "radius" e um gateway baseUrl.

Use /login no modo interativo e selecione um provedor para armazenar um API key em auth.json ou defina credenciais por meio de variável de ambiente:

export ANTHROPIC_API_KEY=sk-ant-...
pi

Referência para variáveis de ambiente e chaves auth.json: const envMap em packages/ai/src/env-api-keys.ts.

Armazene credenciais em ~/.pi/agent/auth.json:

{
  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
  "ant-ling": { "type": "api_key", "key": "..." },
  "openai": { "type": "api_key", "key": "sk-..." },
  "deepseek": { "type": "api_key", "key": "sk-..." },
  "nvidia": { "type": "api_key", "key": "nvapi-..." },
  "google": { "type": "api_key", "key": "..." },
  "opencode": { "type": "api_key", "key": "..." },
  "opencode-go": { "type": "api_key", "key": "..." },
  "together": { "type": "api_key", "key": "..." },
  "qwen-token-plan":  { "type": "api_key", "key": "sk-sp-..." },
  "qwen-token-plan-individual": { "type": "api_key", "key": "sk-sp-..." },
  "qwen-token-plan-cn": { "type": "api_key", "key": "sk-sp-..." },
  "xiaomi": { "type": "api_key", "key": "..." },
  "xiaomi-token-plan-cn":  { "type": "api_key", "key": "..." },
  "xiaomi-token-plan-ams": { "type": "api_key", "key": "..." },
  "xiaomi-token-plan-sgp": { "type": "api_key", "key": "..." }
}

qwen-token-plan-individual usa o mesmo endpoint internacional e QWEN_TOKEN_PLAN_API_KEY que qwen-token-plan, mas limita o seletor aos modelos documentados para assinaturas individuais. O existente provedor mantém seu catálogo mais amplo para compatibilidade com versões anteriores. Ao usar auth.json, armazene o credencial no provedor que você selecionar; uma variável de ambiente é compartilhada por ambos os provedores internacionais.

O arquivo é criado com permissões 0600 (somente leitura/gravação do usuário). As credenciais do arquivo de autenticação têm prioridade sobre as variáveis de ambiente.

As credenciais de chave de API também podem incluir valores de ambiente no escopo do provedor. Esses valores são usados antes das variáveis de ambiente do processo ao resolver a chave de credencial, os cabeçalhos de provedor/modelo e a configuração do provedor, como IDs de conta Cloudflare, configurações do Azure OpenAI, projeto/localização do Vertex, configurações do Bedrock, PI_CACHE_RETENTION e HTTP_PROXY/HTTPS_PROXY.

{
  "cloudflare-ai-gateway": {
    "type": "api_key",
    "key": "$CLOUDFLARE_API_KEY",
    "env": {
      "CLOUDFLARE_API_KEY": "...",
      "CLOUDFLARE_ACCOUNT_ID": "account-id",
      "CLOUDFLARE_GATEWAY_ID": "gateway-id"
    }
  }
}

Use isto quando pi precisar usar configurações de provedor diferentes das do ambiente shell do projeto.

O campo key suporta execução de comandos, interpolação de ambiente e literais:

• Comando Shell: "!command" no início executa todo o valor como um comando e usa stdout (armazenado em cache durante a vida útil do processo)

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

• Interpolação de ambiente: "$ENV_VAR" ou "${ENV_VAR}" usa o valor da variável nomeada. A interpolação funciona dentro de literais maiores.

  { "type": "api_key", "key": "$MY_ANTHROPIC_KEY" }
  { "type": "api_key", "key": "${KEY_PREFIX}_${KEY_SUFFIX}" }

  $FOO_BAR é a variável FOO_BAR; use ${FOO}_BAR quando BAR for texto literal. Variáveis de ambiente ausentes tornam o valor não resolvido.
• Escapes: "$" emite um "
  quot; literal; "$!" emite um "!" literal sem acionar a execução de comandos.

  { "type": "api_key", "key": "$literal-dollar-prefix" }
  { "type": "api_key", "key": "$!literal-bang-prefix" }

• Valor literal: Usado diretamente. Strings simples em maiúsculas como MY_API_KEY são literais; use $MY_API_KEY para variáveis de ambiente.

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

As credenciais OAuth também são armazenadas aqui após /login e gerenciadas automaticamente.

export AZURE_OPENAI_API_KEY=...
export AZURE_OPENAI_BASE_URL=https://your-resource.ai.azure.com
# also supported: https://your-resource.cognitiveservices.azure.com
# also supported: https://your-resource.openai.azure.com
# root endpoints are auto-normalized to /openai/v1
# or use resource name instead of base URL
export AZURE_OPENAI_RESOURCE_NAME=your-resource

# Optional
export AZURE_OPENAI_API_VERSION=2024-02-01
export AZURE_OPENAI_DEPLOYMENT_NAME_MAP=gpt-4=my-gpt4,gpt-4o=my-gpt4o

Use /login amazon-bedrock para armazenar uma chave de API do Bedrock ou configure uma das fontes de credenciais da AWS disponíveis no ambiente abaixo:

# Option 1: AWS Profile
export AWS_PROFILE=your-profile

# Option 2: IAM Keys
export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...

# Option 3: Bearer Token
export AWS_BEARER_TOKEN_BEDROCK=...

# Optional region (defaults to us-east-1)
export AWS_REGION=us-west-2

Também suporta funções de tarefa ECS (AWS_CONTAINER_CREDENTIALS_*) e IRSA (AWS_WEB_IDENTITY_TOKEN_FILE).

pi --provider amazon-bedrock --model us.anthropic.claude-sonnet-4-20250514-v1:0

O cache de prompt é habilitado automaticamente para modelos Claude cujo ID contém um nome de modelo reconhecível (modelos básicos e perfis de inferência definidos pelo sistema). Para perfis de inferência de aplicativos (cujos ARNs não contêm o nome do modelo), defina AWS_BEDROCK_FORCE_CACHE=1 para ativar pontos de cache:

export AWS_BEDROCK_FORCE_CACHE=1
pi --provider amazon-bedrock --model arn:aws:bedrock:us-east-1:123456789012:application-inference-profile/abc123

Se você estiver se conectando a um proxy Bedrock API, as seguintes variáveis de ambiente poderão ser usadas:

# Set the URL for the Bedrock proxy (standard AWS SDK env var)
export AWS_ENDPOINT_URL_BEDROCK_RUNTIME=https://my.corp.proxy/bedrock

# Set if your proxy does not require authentication
export AWS_BEDROCK_SKIP_AUTH=1

# Set if your proxy only supports HTTP/1.1
export AWS_BEDROCK_FORCE_HTTP1=1

CLOUDFLARE_API_KEY pode ser definido via /login. O ID da conta e o slug do gateway podem ser definidos como variáveis de ambiente ou no objeto env da credencial API key em auth.json.

export CLOUDFLARE_API_KEY=...           # or use /login
export CLOUDFLARE_ACCOUNT_ID=...
export CLOUDFLARE_GATEWAY_ID=...        # create at dash.cloudflare.com → AI → AI Gateway
pi --provider cloudflare-ai-gateway --model "claude-sonnet-4-5"

Rotas para OpenAI, Anthropic e Workers AI por meio do Cloudflare AI Gateway. Workers AI usa o Unified API (/compat) e IDs de modelo prefixados (workers-ai/@cf/...). OpenAI usa a rota de passagem OpenAI (/openai) com IDs de modelo OpenAI nativos, como gpt-5.1. Anthropic usa a rota de passagem Anthropic (/anthropic) com IDs de modelo antrópicos nativos, como claude-sonnet-4-5.

A autenticação do AI Gateway usa CLOUDFLARE_API_KEY como cf-aig-authorization. A autenticação upstream pode ser uma das seguintes:

Para uso normal do pi, prefira faturamento unificado ou BYOK armazenado. O BYOK inline requer a configuração de um cabeçalho upstream Authorization adicional para o provedor Cloudflare AI Gateway, por exemplo, por meio de uma substituição de provedor/modelo models.json.

CLOUDFLARE_API_KEY pode ser definido via /login. CLOUDFLARE_ACCOUNT_ID pode ser definido como uma variável de ambiente ou no objeto env da credencial API key em auth.json.

export CLOUDFLARE_API_KEY=...           # or use /login
export CLOUDFLARE_ACCOUNT_ID=...
pi --provider cloudflare-workers-ai --model "@cf/moonshotai/kimi-k2.6"

Pi define automaticamente x-session-affinity para descontos de prefix caching.

Usa credenciais padrão do aplicativo:

gcloud auth application-default login
export GOOGLE_CLOUD_PROJECT=your-project
export GOOGLE_CLOUD_LOCATION=us-central1

Ou defina GOOGLE_APPLICATION_CREDENTIALS para um arquivo de chave de conta de serviço.

Pi suporta o servidor roteador llama.cpp. Configure-o com /login llama.cpp, gerencie modelos carregados com /llama e selecione um modelo carregado com /model.

Consulte llama.cpp para configuração do servidor, layout do diretório do modelo, variáveis de ambiente e uso de comandos.

Por meio de models.json: Adicione Ollama, LM Studio, vLLM ou qualquer provedor compatível com uma API compatível (OpenAI Completions, OpenAI Responses, Anthropic Messages, Google Generative AI). Consulte models.md.

Através de extensões: Para provedores que precisam de implementações API personalizadas ou fluxos OAuth, crie uma extensão. Consulte custom-provider.md e examples/extensions/custom-provider-gitlab-duo.

Ao resolver credenciais para um provedor:

1. CLI --api-key bandeira
2. Entrada auth.json (token API key ou OAuth)
3. Variável de ambiente
4. Chaves de provedor personalizadas de models.json