Vai al contenuto principale
Una chiave senza tetto è una chiave che può prosciugare l’intero saldo del tuo workspace se un agent va in loop. Il modo singolarmente più efficace per vincolare il raggio d’esplosione di un agent compromesso o incontrollato è dare alla sua chiave un cap di spesa. Sul gateway hosted ogni chiave è o illimitata o limitata da una quota di chiave API misurata in dollari USA — e la scelta è un campo nell’editor delle chiavi. Questa pagina spiega le due modalità, come il cap è applicato sul percorso di relay, e quando scegliere quale. Per l’insieme completo dei vincoli che una chiave porta — allow-list di modelli, allow-list di IP, collegamenti a policy — vedi Il token object.

​
1. Le due modalità

Ogni chiave si risolve in esattamente uno di due stati:

Unlimited

unlimited_quota = true. La chiave attinge al saldo del workspace senza alcun tetto per chiave. Nessun controllo di spesa gira al momento della richiesta — l’unico limite è il saldo stesso del workspace.

Bounded

credit_limit_usd > 0. La chiave porta il proprio cap di spesa complessiva in USD. Una volta che la spesa cumulativa raggiunge il cap, la chiave smette di funzionare — il resto del workspace resta intatto.
Imposti questo nella schermata Chiavi della console (/console/token). Creare o modificare una chiave richiede il ruolo Developer o superiore.
credit_limit_usd = 0 significa illimitata — zero è il sentinella per “nessun cap”, non “un cap di zero dollari”. Per vincolare una chiave, dalle un importo positivo in dollari.

​
2. Come viene applicata una quota di chiave API

Quando imposti credit_limit_usd a un numero positivo, il gateway lo converte in un saldo interno remain_quota per quella chiave e porta unlimited_quota a false. Da quel momento:
  • remain_quota è il margine di spesa rimasto della chiave, ridotto man mano che la chiave fattura l’uso.
  • used_quota è la spesa cumulativa che la chiave ha già registrato.
  • A ogni chiamata di relay, il gateway controlla la chiave prima di inoltrare la richiesta. Una chiave limitata il cui remain_quota ha raggiunto zero viene rifiutata come esaurita — la chiamata non raggiunge mai il modello.
Una chiave illimitata (unlimited_quota = true) salta del tutto quel controllo del saldo; è vincolata solo dal saldo del workspace e da qualsiasi altro limite a livello di chiave che imposti (allow-list di modelli, allow-list di IP, scadenza).
Una chiave limitata è un cap complessivo, non un budget mensile a scorrimento — il cap conta la spesa totale nel corso della vita della chiave. Per un budget che si resetta, emetti una nuova chiave limitata alla tua cadenza (es. una nuova chiave per sprint) e revoca quella vecchia. Vedi Gestire le chiavi.

​
3. Un esempio concreto

Supponi di stare deployando un agent di summarization schedulato e di voler garantire che non possa mai spendere più di $25 indipendentemente da cosa faccia il modello. Imposta il cap quando crei la chiave: 
// POST alla schermata Chiavi della console (Developer+).
// Configura nella console — la chiave di relay (sk-orca-…) non è mai usata per
// amministrare le chiavi; è presentata solo sulle chiamate di inferenza /v1/*.
{
  "name": "nightly-summarizer",
  "credit_limit_usd": 25,        // limitata: cap complessivo di $25
  "model_limits_enabled": true,
  "model_limits": ["openai/gpt-4o-mini"],
  "expired_time": -1             // -1 = non scade mai
}
Il gateway la memorizza come chiave limitata: unlimited_quota = false e un remain_quota del valore di 25.L′agentchiamailmodelloconlachiavedirelay‘sk−orca−…‘comealsolito.Nell′istanteincuilaspesacumulativaraggiungei25. L'agent chiama il modello con la chiave di relay `sk-orca-…` come al solito. Nell'istante in cui la spesa cumulativa raggiunge i 25, la chiave è esaurita e ogni ulteriore chiamata /v1/* viene rifiutata — senza che tu guardi una dashboard, e senza toccare il resto del workspace. Per rendere la stessa chiave illimitata in seguito, modificala e attiva l’interruttore unlimited — la console imposta unlimited_quota = true e credit_limit_usd = 0 insieme, e la chiave può di nuovo attingere all’intero saldo del workspace.

​
4. Quale modalità scegliere

Qualsiasi chiave consegnata a un agent autonomo, a un job di CI o a un’integrazione di terze parti dovrebbe essere limitata. Un cap di spesa è la garanzia più economica che un loop da prompt injection o una tempesta di retry non possano far lievitare un conto senza limiti — il cap ferma la chiave prima che il danno si aggravi. Abbinalo a un limite sui modelli stretto e a un’ IP allow-list.
Per una chiave che esiste solo per una demo, un load test o un singolo deployment, combina un piccolo credit_limit_usd con un expired_time. La chiave si auto-ritira su qualunque limite scatti per primo. Vedi Quota, cap e scadenza e Chiavi a scadenza.
Una chiave usata da un servizio di produzione core che controlli pienamente, dove un cap per chiave causerebbe solo outage spurie, può restare illimitata — il saldo del workspace è la rete di sicurezza. Tieni queste chiavi poche, nominale chiaramente, e dai loro comunque uno scope con limiti sui modelli e sugli IP.
Una chiave limitata che si esaurisce a metà esecuzione inizia a rifiutare le chiamate immediatamente. È il punto — ma significa che un agent incustodito può fermarsi a metà di un job. Dimensiona il cap per il lavoro che ti aspetti, e tieni d’occhio la spesa nelle viste di utilizzo della console così da poter alzare il cap prima che morda un’esecuzione legittima.

​
5. Come si relazionano i campi del cap

I tre campi che governano questo sono un singolo interruttore con un saldo derivato — imposti il cap in dollari, il gateway deriva il resto:
CampoSignificato
credit_limit_usdIl tuo input. > 0 = cap limitato in USD; 0 = illimitata.
unlimited_quotatrue quando la chiave non ha cap; impostato a false automaticamente quando dai un credit_limit_usd positivo.
remain_quotaMargine di spesa derivato per una chiave limitata; raggiungere zero esaurisce la chiave.
Imposti sempre e solo credit_limit_usd (o unlimited_quota) nell’editor. remain_quota e used_quota sono mantenuti dal gateway man mano che la chiave fattura l’uso — sono telemetria di sola lettura, mostrata nelle viste di utilizzo della console.

​
6. Dove si colloca nel control stack

Un cap di spesa vincola quanto una chiave può fare; il resto dello scope della chiave vincola cosa può fare. I due si compongono:

Quota, cap e scadenza

Combina un cap in dollari con una scadenza assoluta così che una chiave si auto-ritiri su qualunque limite scatti per primo.

Il token object

Ogni campo che una chiave porta — limiti sui modelli, allow-list di IP, collegamenti a policy, etichetta environment — in un unico riferimento.

Checklist di minima agenzia

La ricetta completa per la chiave più ristretta possibile, un vincolo alla volta.

Scope, chiavi e policy

Come il cap si inserisce nella gerarchia workspace → policy → chiave, e come vincolare una chiave riduce il raggio d’esplosione.
Più ristretto è il cap di spesa di ciascuna chiave, più piccolo è il conto che un singolo agent compromesso può far lievitare — e più chiara è la tua traccia di audit di quanto ciascuna chiave era autorizzata a spendere.