Risorse per sviluppatori

Gemini CLI

Configura Gemini CLI con l’API Gemini nativa di RunAPI, verifica le richieste e ripristina la configurazione precedente.

Visualizza Markdown

Panoramica

Gemini CLI è un agente nel terminale. Questa guida cambia il suo fornitore di modelli nell’API Gemini nativa di RunAPI; aggiungere gli strumenti RunAPI tramite MCP è un passaggio distinto.

Prima di iniziare

Segui la guida ufficiale all’installazione. Crea una chiave API standard dedicata con la guida all’autenticazione, poi copia un ID di modello Gemini nativo dal catalogo dei modelli. Non includere mai la chiave nei commit.

SHELL

npm install -g @google/gemini-cli

Configura RunAPI

Inizia con queste variabili nella shell corrente. L’URL di base è la radice HTTPS dell’API, senza /v1beta; l’SDK aggiunge POST /v1beta/models/{model}:streamGenerateContent?alt=sse. HTTP è consentito solo per localhost.

SHELL

export GOOGLE_GEMINI_BASE_URL=https://runapi.ai
export GEMINI_API_KEY=YOUR_RUNAPI_API_KEY
export GEMINI_MODEL=YOUR_RUNAPI_MODEL_ID

Per un uso persistente, salva le stesse tre variabili in ~/.gemini/.env, fuori dai repository. Limita l’accesso con chmod 600 ~/.gemini/.env. Gemini CLI cerca .env dalla directory corrente verso quelle superiori, poi controlla ~/.gemini/.env e ~/.env; verifica eventuali file in conflitto.

Unisci queste due impostazioni in ~/.gemini/settings.json preservando le altre. Usa gemini-api-key per l’autenticazione con chiave API; non riutilizzare un accesso Google memorizzato. La chiave viene inviata in x-goog-api-key per impostazione predefinita.

JSON

{
  "security": {
    "auth": {"selectedType": "gemini-api-key"}
  },
  "model": {"name": "YOUR_RUNAPI_MODEL_ID"}
}

Scegli un modello

Usa GEMINI_MODEL, --model YOUR_RUNAPI_MODEL_ID o /model in una sessione interattiva. Evita auto, pro e flash: questi alias possono risolversi in ID di modelli Google non disponibili in RunAPI. Selezione interna, classificazione e rilevamento dei cicli possono richiedere anche modelli ausiliari flash o flash-lite; verificane separatamente la disponibilità.

Verifica

Esegui questi comandi in un repository fidato. Controlla il modello con /about o /stats in una sessione interattiva, poi conferma una richiesta streamGenerateContent corrispondente nei registri d’uso RunAPI. Una risposta CLI riuscita non dimostra da sola quale endpoint l’abbia ricevuta.

SHELL

gemini --version
gemini -p "Describe this repository in one sentence."

Aggiungi strumenti RunAPI

MCP aggiunge strumenti, non un fornitore di modelli. Questo comando registra il server locale; segui Local MCP per l’autenticazione e la verifica separate.

SHELL

gemini mcp add runapi npx -y @runapi.ai/mcp

Risoluzione dei problemi

Se le richieste arrivano ancora a Google, controlla i file .env in conflitto, security.auth.selectedType, l’accesso memorizzato e le variabili di autenticazione Google/Vertex. Se compare Invalid auth method selected, scegli gemini-api-key anziché gateway nelle impostazioni e riavvia.

Con 401, controlla la chiave ed eventuali modifiche di GEMINI_API_KEY_AUTH_MECHANISM; per impostazione predefinita viene usato x-goog-api-key. Per 404, rimuovi /v1beta dall’URL di base e copia nuovamente un ID di modello Gemini nativo supportato. Se un modello ausiliario non è disponibile, verifica l’ID richiesto; scegliere il modello principale non garantisce tutte le funzioni CLI.

RunAPI non espone countTokens né embedContent. Gemini CLI può stimare localmente i token se countTokens fallisce; le stime possono differire dai registri d’uso. Usa HTTPS tranne per localhost e non disabilitare la verifica dei certificati.

Rimuovi RunAPI

Rimuovi le tre variabili dalla shell e dai file .env salvati, ripristina security.auth.selectedType e il modello precedenti e revoca la chiave dedicata in RunAPI. Rimuovi il server MCP aggiunto separatamente solo se non ti servono più i suoi strumenti.

SHELL

unset GOOGLE_GEMINI_BASE_URL GEMINI_API_KEY GEMINI_MODEL

Passaggi successivi

Prosegui con la guida rapida all’API LLM, Gemini generateContent, streamGenerateContent, il catalogo dei modelli o Local MCP.