AIProxyServer - Guida

Per iniziare

1. Avvia l'app

Apri AIProxyServer. Al primo avvio il proxy si attiva automaticamente e resta in ascolto sulla porta 8421 del tuo computer locale. La finestra principale mostra tre sezioni:

• Proxy Server — stato attuale, base URL e un pulsante per avviare o arrestare il listener
• Bearer Token — interruttore di autenticazione opzionale e visualizzazione del token
• Provider — tutti i provider AI cloud supportati, con un Imposta chiave API pulsante per ogni riga

2. Aggiungi la tua prima chiave API

1. Scegli un provider qualsiasi dall'elenco Provider (per esempio OpenAI (ChatGPT))
2. Fai clic su Ottieni chiave API per aprire la console del provider nel browser, quindi crea o copia una chiave
3. Fai clic su Imposta chiave API sulla stessa riga e incolla il valore nella finestra di dialogo
4. Fai clic su Salva. L'etichetta di stato passa a Configurato in verde

3. Collega un'app client

Punta un qualsiasi client compatibile con OpenAI al proxy. Il Base URL è http://localhost:8421/<provider>/v1. Il segmento del provider determina quale cloud riceve la richiesta.

# Esempio: SDK Python di OpenAI puntato al proxy
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8421/openai/v1",
    api_key="not-used-but-required-by-sdk",
)
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

Il client non vede mai la chiave reale. AIProxyServer allega le credenziali upstream quando inoltra la richiesta.

Panoramica dell'interfaccia

Pannello Proxy Server

Pannello Bearer Token

• Richiedi autenticazione con Bearer Token — casella di controllo che attiva o disattiva l'autenticazione. Disattivata per impostazione predefinita, per un uso locale senza complicazioni.
• Campo Token — visualizzazione in sola lettura del token attuale. Mostrato come puntini; usa Copia per copiarlo.
• Rigenera — genera un nuovo token casuale. I client esistenti devono essere aggiornati con il nuovo valore.

Pannello Provider

Una riga per ogni provider cloud supportato. Ogni riga mostra:

• Il nome visualizzato (per esempio Claude (Anthropic))
• Stato della configurazione — verde Configurato quando una chiave API è salvata, grigio Non configurato in caso contrario
• Il percorso URL usato dai tuoi client, ad es. /anthropic/v1/chat/completions
• Imposta chiave API — apre una finestra di dialogo per inserire le credenziali
• Ottieni chiave API — apre la console del provider nel browser

Provider supportati

Sono inclusi undici servizi AI cloud. La maggior parte usa nativamente il formato OpenAI Chat Completions e viene inoltrata così com'è. Tre (Anthropic, Gemini, ERNIE) parlano protocolli propri; AIProxyServer traduce richieste e risposte al volo, così il tuo client vede sempre e solo formati OpenAI.

Note specifiche per provider

• Azure OpenAI — incolla l'endpoint completo del deployment nel campo Endpoint Base URL , per esempio https://my-resource.openai.azure.com/openai/deployments/gpt-4o. Il proxy aggiunge /chat/completions?api-version=2024-02-01 automaticamente.
• ERNIE — Baidu Qianfan usa OAuth, quindi sono necessarie sia API Key sia Secret Key . AIProxyServer richiede e memorizza nella cache i token di accesso dietro le quinte.
• Gemini — l'autenticazione avviene tramite un parametro di query nell'URL; il proxy lo aggiunge per te. Restano validi i limiti al minuto del piano gratuito.

Riferimento API

Endpoint

Streaming

Quando il client invia "stream": true, il proxy risponde con Server-Sent Events nel formato OpenAI:

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"},...}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},...}]}

data: [DONE]

Gli stream nativi di Anthropic e Gemini vengono tradotti in questo formato, così tutti i client possono usare un unico parser.

Intestazione di autenticazione

Quando Richiedi autenticazione con Bearer Token è attivo, invia il token mostrato nella finestra principale con ogni richiesta:

Authorization: Bearer <token-shown-in-app>

Impostazioni

Apri la finestra Impostazioni dall'icona a forma di ingranaggio nella barra degli strumenti in basso.

Esempi di client

cURL

# OpenAI (passthrough)
curl http://localhost:8421/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# Claude tramite lo stesso formato OpenAI
curl http://localhost:8421/anthropic/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 1024
  }'

SDK Python di OpenAI

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8421/gemini/v1",
    api_key="placeholder",  # ignorato quando Bearer Token è disattivato
)
stream = client.chat.completions.create(
    model="gemini-2.0-flash",
    messages=[{"role": "user", "content": "Tell me a joke"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

Flutter / Dart

// Con un qualsiasi client Dart compatibile con OpenAI
final client = OpenAIClient(
  baseUrl: 'http://localhost:8421/anthropic/v1',
  apiKey: '', // non usato quando Bearer Token è disattivato
);

Suggerimenti

• Lascia il Bearer Token disattivato mentre sviluppi in locale; attivalo nel momento in cui abiliti l'accesso LAN.
• Usa Base URL distinti per ogni provider nel codice del client, così puoi cambiare provider modificando una sola costante.
• Il proxy si avvia automaticamente, ma puoi arrestarlo temporaneamente dalla finestra principale in caso di conflitto di porte.
• Se il piano gratuito di un provider ti limita, il messaggio di errore upstream viene inoltrato testualmente. Nessuna logica di ritentativo viene nascosta al client.
• L'endpoint /v1/providers è utile per scoprire quali provider sono configurati in fase di esecuzione.

Risoluzione dei problemi

Il proxy non si avvia

• Un altro processo potrebbe già usare la porta 8421. Cambia la porta nelle Impostazioni e riavvia il proxy.
• Controlla il log di sistema per il messaggio di errore mostrato all'avvio.

Una richiesta restituisce 401 Unauthorized

• Il requisito del Bearer Token è attivo, ma il client non ha inviato l'intestazione Authorization: Bearer ... corrispondente.
• La chiave API del provider potrebbe non essere valida — l'errore upstream viene inoltrato, quindi controlla il corpo del messaggio.

Una richiesta restituisce "API key is not configured"

• Apri l'elenco Provider e fai clic su Imposta chiave API per il provider in questione.
• Per ERNIE devono essere compilate sia API Key sia Secret Key. Per Azure OpenAI è richiesto anche l'Endpoint Base URL.

Il dispositivo mobile non riesce a raggiungere il proxy

• Attiva Consenti accesso LAN nelle Impostazioni.
• Usa l'IP LAN mostrato nel campo Base URL, non localhost.
• Assicurati che entrambi i dispositivi siano sulla stessa rete Wi-Fi e che il firewall consenta le connessioni in ingresso sulla porta del proxy.

Le risposte in streaming arrivano tutte insieme

• Assicurati che il client invii "stream": true nel corpo JSON.
• Alcune librerie HTTP mettono gli SSE in buffer per impostazione predefinita — disattiva il buffering delle risposte lato client.

Privacy

• Le chiavi API sono memorizzate cifrate con Fernet in ~/Library/Application Support/AIProxyServer/credentials.enc. La chiave di cifratura in master.key ha permessi 0600.
• Anche il Bearer Token, quando è attivo, viene memorizzato solo nel vault cifrato e non viene mai scritto nel normale file delle impostazioni.
• Il proxy inoltra le richieste solo ai provider che hai configurato esplicitamente. Non effettua nessun'altra chiamata in uscita.
• Nessuna telemetria, nessuna analisi, nessun report di crash.
• L'associazione di rete predefinita è 127.0.0.1 soltanto. L'esposizione sulla LAN è facoltativa.
• I contenuti delle conversazioni non vengono memorizzati. AIProxyServer inoltra i byte e li dimentica immediatamente.