Vai al contenuto principale
Un agent compromesso non si ferma da solo. Una prompt injection che lo inganna in un loop di retry, o una chiave trapelata in un log di CI, continuerà a chiamare modelli finché qualcosa non dice basta. Su OrcaRouter quel “qualcosa” sono due campi sulla chiave stessa: un cap di spesa e una scadenza. Impostali una volta nell’editor delle chiavi e il gateway applica entrambi a ogni richiesta — nessuna modifica al codice dell’agent, nessun redeploy. Questa pagina è il riferimento focalizzato su quei due limiti. Per l’elenco completo dei campi di una chiave, vedi il token object; per il modello di identità attorno ad essi, vedi panoramica delle chiavi con scope.

​
1. Il limite di spesa per chiave API: credit_limit_usd

credit_limit_usd è il tetto di spesa complessiva per una chiave, espresso in USD semplici. Digiti una cifra in dollari nell’editor delle chiavi; OrcaRouter la converte nella quota iniziale della chiave e mette a metro ogni chiamata rispetto ad essa.

Bounded

credit_limit_usd: 25 conia una chiave con $25 di spesa. Ogni chiamata addebita il suo costo; una volta che il saldo rimanente tocca zero la chiave smette di autorizzare e ogni richiesta ulteriore viene rifiutata.

Unlimited

credit_limit_usd: 0 è il sentinella per nessun cap — la chiave attinge al saldo del tuo workspace senza alcun tetto per chiave. Comodo, ma il peggior raggio d’esplosione se trapela.
0 non significa “zero dollari” — significa illimitata. Una chiave che intendevi bloccare a un budget minuscolo deve portare un numero positivo. Per esprimere “questa chiave non può spendere nulla”, disabilitala o eliminala, non impostare il cap a 0.

​
2. Come viene messo a metro il cap: remain_quota e used_quota

Il cap in dollari che inserisci è la superficie rivolta all’umano. Sotto di esso, il gateway tiene traccia di due contatori sulla chiave:
CampoSignificato
remain_quotaSpesa rimasta prima che la chiave smetta di autorizzare.
used_quotaSpesa consumata finora nel corso della vita della chiave.
Impostare un credit_limit_usd positivo semina remain_quota da quella cifra in dollari; ogni chiamata fatturata sposta il costo da remain_quota a used_quota. Una chiave con cap illimitato porta invece unlimited_quota, e il controllo del saldo viene saltato del tutto.
Un block di guardrail o firewall non costa nulla rispetto al cap quando scatta prima che il modello giri — un guardrail_blocked in fase di input e un firewall_blocked inbound avvengono entrambi pre-metering, quindi remain_quota resta intatto. Un block di guardrail in fase di output rimborsa la richiesta. Vedi guardrails e firewall.

​
3. Auto-scadenza: expired_time

expired_time è un taglio assoluto — un timestamp Unix epoch (secondi) dopo il quale la chiave smette di autorizzare, indipendentemente da quanto budget rimanga.
  • Un timestamp futuro fa scadere la chiave in quell’istante. Il gateway lo confronta con l’ora corrente a ogni richiesta e rifiuta la chiamata una volta passato.
  • -1 è il sentinella per non scade mai.
I due limiti sono indipendenti ed entrambi devono passare. Una chiave con budget residuo ma con un expired_time passato è morta; una chiave dentro la sua finestra di validità con remain_quota a zero è morta. Vince qualunque dei due limiti scatti per primo. L’editor rifiuta una scadenza impostata nel passato, così non puoi coniare per sbaglio una chiave già scaduta alla nascita.
Per chiavi a vita breve coniate per esecuzione di CI o per agent effimero, vedi chiavi a scadenza.

​
4. Una chiave concreta con cap e scadenza

Un job notturno che riconcilia fatture con un unico modello economico, gira per un pilota di due settimane e non dovrebbe mai costare più di qualche dollaro a notte non ha quasi bisogno di agenzia. Configura la sua chiave nell’editor delle chiavi della console (/console/token — Developer+):
1

Imposta il cap di spesa

credit_limit_usd: 40 — l’intero budget del pilota. Un loop di retry incontrollato esaurisce la chiave, non il saldo del tuo workspace.
2

Imposta la scadenza

expired_time: il timestamp Unix per la fine della finestra del pilota. La chiave si auto-scade e non può essere riutilizzata dopo che il pilota è stato rilasciato.
3

Abbina agli altri scope

Aggiungi model_limits così che non possa escalare a un modello di frontiera, e allow_ips così che una chiave trapelata sia inutile fuori dall’host dello scheduler.
Se questo agent viene dirottato al terzo giorno, il danno è limitato a quel che resta dei suoi $40, e l’intera chiave sparisce in undici giorni a prescindere. Il resto del workspace resta intatto.
Entrambi i campi sono USD-e-tempo sulla chiave, non policy a livello di workspace. Per limitare la spesa di una singola esecuzione di agent (anziché la vita di una chiave), il verdetto cap_cost del Firewall è l’interruttore di sicurezza per esecuzione — vedi regole del firewall. I due si compongono: il cap della chiave vincola la vita, cap_cost vincola una singola esecuzione.

​
5. Chi può impostarli

Impostare credit_limit_usd ed expired_time fa parte del creare o modificare una chiave, il che richiede il ruolo Developer o superiore. Qualsiasi membro del workspace può leggere il record mascherato di una chiave; solo Developer+ può cambiarne i limiti. Le chiavi sono mascherate quando vengono mostrate — il plaintext è mostrato una volta alla creazione (vedi mascheramento delle chiavi).

​
6. Limitate per default

Una chiave con credit_limit_usd: 0 e expired_time: -1 non ha cap di spesa e non scade mai — agenzia massima, peggior raggio d’esplosione. Rendilo l’eccezione deliberata, non il default.

Illimitate vs limitate

Quando una chiave senza cap e senza scadenza è davvero la scelta giusta — e quando non lo è.

Checklist di minima agenzia

Fai passare ogni chiave di produzione attraverso lo stesso giro di hardening prima che venga rilasciata.

​
7. Correlati

Il token object

Ogni campo su una chiave, inclusi i contatori di quota.

Collegare le policy

Collega un guardrail e una policy del firewall alla stessa chiave.

Agenzia eccessiva

La minaccia che i cap di spesa e la scadenza sono costruiti per contenere.
Un cap di spesa e una scadenza sono l’assicurazione più economica su una chiave: due numeri che trasformano una credenziale a tempo indeterminato in una che fallisce in sicurezza — vuota o scaduta — invece di girare finché il tuo conto non se ne accorge.