Zum Hauptinhalt springen
OrcaRouter wendet vier Ebenen auf jeden Request in einer festen Reihenfolge an. Jede Ebene ist unabhängig, workspace-bezogen und hängt sich ohne Code-Änderung an einen API-Key. Diese Seite führt einen Request durch alle vier Ebenen der Reihe nach und behandelt dann Auflösungsreihenfolge sowie Fail-open/Fail-closed-Verhalten. Eine breitere Einführung finden Sie unter KI-Agenten mit OrcaRouter absichern.

​
1. Ebene 1 — Scoped API-Key

Der Schlüssel ist das erste Tor. Bevor Inhalte inspiziert oder ein Modell aufgerufen wird, löst das Gateway den aufrufenden Schlüssel auf und entscheidet, ob der Request überhaupt erlaubt ist. Was der Schlüssel enthält:
  • model_limits — der Satz von Modellen, die der Schlüssel aufrufen darf. Ein Request für ein Modell außerhalb der Liste wird sofort abgelehnt.
  • allow_ips — optionale IP-Allowlist. Ein Request von einer nicht gelisteten Quelle wird abgelehnt.
  • credit_limit_usd — ein hartes Ausgabenlimit. Ein Request, der den Schlüssel über das Limit bringen würde, wird abgelehnt.
  • expiry — ein hartes Ablaufdatum. Abgelaufene Schlüssel werden abgelehnt.
  • environment — ein Tag (production, staging, dev, …) zum Organisieren und Identifizieren des Schlüssels nach Deployment-Umgebung.
  • guardrail_id — die Guardrail-Policy, die an diesen Schlüssel bindet (siehe Ebene 2 und Ebene 4).
  • firewall_policy_id — die Firewall-Policy, die an diesen Schlüssel bindet (siehe Ebene 3).
  • is_firewall_gateway — kennzeichnet den Schlüssel als Firewall-Gateway-scoped Token; erforderlich für die Evaluate- und MCP-Gateway-Routen.
Ein Request, der die Schlüsselvalidierung nicht besteht, erreicht nie ein Modell — und wird nie gemessen. Wo konfigurieren: Konsole → API-Keys, oder die Token-API. Erfordert Developer+ zum Erstellen oder Bearbeiten; is_firewall_gateway und Klartext-Schlüssel-Lesezugriff erfordern Admin. Das vollständige Schlüsselmodell beschreibt Scope, Keys, Policies und Workspaces.

​
2. Ebene 2 — Input-Guardrails

Sobald der Schlüssel validiert ist, führt das Gateway die Input-Stage-Regeln des gebundenen Guardrails gegen den Request-Text aus — bevor ein Upstream-Modell aufgerufen wird. Was es sieht: Die Nachrichten des Aufrufers, wie eingereicht. (Ein Prompt, der aus einer Prompt-Registry injiziert wird, wird später in der Routing-Phase angehängt; Input-Regeln sehen ihn nicht.) Verfügbare Regeltypen: keyword, regex, pii, max_chars, external, llm_judge, grounding. Aktionen, die eine Regel erzeugen kann:
AktionWas passiert
blockRequest wird abgelehnt — HTTP 400 guardrail_blocked. Kein Kontingent wird belastet. Als skip-retry markiert.
maskTreffer wird redigiert (z. B. jane@acme.com → [EMAIL]). Der bereinigte Text wird an das Modell weitergegeben.
flagTreffer wird aufgezeichnet; Traffic bleibt unverändert.
Ein block in dieser Stage bedeutet, dass das Modell nie aufgerufen wird. Kosten: null. Der Aufrufer sieht einen strukturierten Fehler, der das Guardrail und die ausgelöste Regel benennt. Wo konfigurieren: Konsole → Guardrails, oder die Guardrail-API. Erfordert Developer+ zum Erstellen oder Ändern. Das vollständige Regelreferenz finden Sie unter Guardrails.

​
3. Ebene 3 — Modell läuft

Wenn der Schlüssel gültig ist und Input-Guardrails bestanden wurden, leitet das Gateway den Request an das Upstream-Modell weiter. Dies ist die einzige Ebene ohne konfigurierbare Durchsetzung — das Modell tut einfach seine Arbeit. Die Firewall operiert auf den Aktionen, die das Modell produziert (Ebene 3 → Ebene 4 unten), nicht auf dem Modell selbst. Routing, Fallbacks und Load-Balancing passieren hier transparent.

​
4. Ebene 4 — Agent-Firewall (Tool-Calls und Egress)

Nachdem das Modell geantwortet hat — oder inline, wenn Tool-Calls emittiert werden — beurteilt die Agent-Firewall jede Aktion, die das Modell anfordert. Vier Durchsetzungs-Surfaces:
SurfaceWas die Firewall sieht
inboundTool-Definitionen, die der Agent dem Modell anbietet. Ein gefährliches Tool blockieren, bevor das Modell es wählen kann.
responsetool_calls, die das Modell in seiner Antwort ausgibt.
mcpEin tools/call, der durch das Firewall-MCP-Gateway dispatcht oder über den Evaluate-Hook ausgewertet wird.
egressEin ausgehendes Netzwerkziel (Host / IP / CIDR), das von einem Tool gemeldet wird — die SSRF- und Datenexfiltrations-Surface.
Verdikte, die eine Regel (oder der Default) erzeugen kann:
VerdiktWas es tut
allowAufruf geht durch. Geloggt.
auditAufruf geht durch; zur Überprüfung aufgezeichnet. Das Standard-default_verdict.
denyAufruf blockiert — HTTP 400 firewall_blocked auf der inbound-Surface; ein Tool-Fehler auf mcp.
sanitizeGematchte Teilstrings werden aus Tool-Argumenten redigiert; der bereinigte Aufruf geht durch. Auf inbound (noch keine Argumente), eskaliert zu deny.
pending_approvalAufruf wird zurückgehalten; ein externer Prüfer genehmigt oder lehnt ab; der Agent reicht mit einem einmal nutzbaren Approval-Token erneut ein.
cap_costVerweigern, sobald die akkumulierten Ausgaben des Agentenlaufs ein Cent-Limit pro Regel überschreiten.
Ein deny auf der inbound-Surface kostet keine Modell-Tokens — der Block feuert vor dem Upstream-Aufruf. Ein pending_approval-Hold gibt HTTP 400 firewall_approval_pending mit einer Approval-ID zurück, die der Client pollt. Wo konfigurieren: Konsole → Firewall, oder die Firewall-API. Erfordert Developer+ zum Erstellen oder Ändern von Policies und Regeln. Das vollständige Regelreferenz finden Sie unter Firewall und Firewall-Regeln.

​
5. Ebene 5 — Output-Guardrails

Nachdem das Modell geantwortet hat (und nachdem ein etwaiger Tool-Call-Zyklus abgeschlossen ist), führt das Gateway die Output-Stage-Regeln des gebundenen Guardrails gegen den Antworttext aus, bevor er den Aufrufer erreicht. Dieselben Regeltypen und Aktionen wie in Ebene 2 gelten. Ein Output-block gibt HTTP 400 guardrail_blocked zurück und erstattet das vorab verbrauchte Kontingent — der Aufrufer zahlt nichts.
Streaming und Output-Masking. Eine block-Aktion wird sowohl bei Streaming- als auch bei Nicht-Streaming-Antworten durchgesetzt — bei einem Stream schneidet der Scanner mitten im Flug und sendet eine Ersatznachricht. Eine mask-Aktion auf dem Output gilt derzeit nur für Nicht-Streaming-Antworten; bei einer Streaming-Antwort wird der ursprüngliche Chunk unmaskiert durchgereicht. Überprüfen Sie Ihre Stage/Stream-Kombination in der Guardrail-Sandbox, bevor Sie sich darauf verlassen.

​
6. Ebene 6 — Audit

Jeder Match, jedes Verdikt und jede Freigabe wird in den Audit-Trail geschrieben, korreliert mit dem Agentenlauf und der Session, die ihn verursacht haben. Dies ist kein separater Durchsetzungsschritt — er läuft parallel zu den Ebenen 2–5 — aber er ist die Ebene, die die anderen zur Rechenschaft zieht. Was geloggt wird:
  • Guardrail-Matches: Regeltyp, Aktion, Stage, Detail-String und (wenn Log raw content aktiviert ist) der gematchte Teilstring.
  • Firewall-Events: Surface, Tool-Name, Verdikt, gematchte Regel, Reason-Code, Risikofaktoren und der Lauf/die Session, zu der der Aufruf gehört.
  • Freigabe-Entscheidungen: wer genehmigt oder abgelehnt hat, wann und ob sich die zugrunde liegende Regel zwischen Hold und Entscheidung geändert hat.
  • Policy-Änderungen: jedes Erstellen, Aktualisieren, Löschen und jede Autonomie-Level-Änderung schreibt eine versionierte Audit-Zeile.
Wo überprüfen: Konsole → Guardrails → Matches; Konsole → Firewall → Events, Runs & Sessions, Audit. Der Guardrail-Matches-Feed ist für jedes Workspace-Mitglied offen; die Firewall-Events- und Runs & Sessions-Feeds erfordern Developer+.

​
7. Zusammenfassungstabelle

EbeneWas sie kontrolliertWas sie siehtErgebnis bei einem TrefferWo konfigurieren
1. Scoped KeyIdentität, Modellzugang, Ausgaben, IP, AblaufAuth-Token des RequestsHTTP 4xx, bevor irgendetwas läuft; keine MessungKonsole → API-Keys (Developer+)
2. Input-GuardrailsRequest-TextinhaltNachrichten des AufrufersBlock (HTTP 400 guardrail_blocked, keine Gebühr), mask oder flagKonsole → Guardrails (Developer+)
3. Modell———Routing- / Channel-Konfiguration
4. Agent-FirewallTool-Calls, MCP-Dispatch, EgressTool-Name, Argumente, Zielallow / audit / deny / sanitize / pending_approval / cap_costKonsole → Firewall (Developer+)
5. Output-GuardrailsAntwort-TextinhaltAntwort des ModellsBlock (HTTP 400, Kontingent erstattet), mask oder flagKonsole → Guardrails (Developer+)
6. AuditZurechenbarkeit und TrailAll das ObigeUnveränderlicher Log-EintragKonsole → Matches (Member) / Events & Runs (Developer+)

​
8. Policy-Auflösungsreihenfolge

Für jeden Request werden das aktive Guardrail und die Firewall-Policy unabhängig voneinander aufgelöst:
  1. Schlüssel-Bindung — wenn der Schlüssel eine explizite guardrail_id oder firewall_policy_id trägt, bindet diese Policy (wenn sie existiert und aktiviert ist).
  2. Workspace-Default — wenn der Schlüssel keine Bindung hat, gilt das aktivierte is_default-Guardrail oder die -Policy des Workspaces.
  3. Keines von beiden — keine Durchsetzung. Der Request ist byte-identisch zu einem Workspace, der das Feature nie aktiviert hat.
Die zwei Ebenen unterscheiden sich, wenn eine angehängte Policy deaktiviert ist: Eine deaktivierte Guardrail-Bindung schaltet Guardrails für diesen Schlüssel aus (kein Fallback), während eine deaktivierte Firewall-Bindung auf die Workspace-Standard-Firewall-Policy zurückfällt. Höchstens ein Guardrail und eine Firewall-Policy pro Workspace können der Default sein. Das Promoten eines neuen Defaults degradiert das alte in derselben Transaktion.

​
9. Fail-open und Fail-closed

Zwei Verhaltensweisen — auf verschiedene Fälle angewendet.Fail-open (transiente Fehler): Wenn die Policy-Auflösung auf einen transienten Fehler stößt — einen Datenbank-Schluckauf, einen Netzwerk-Aussetzer auf dem Weg zu einem externen Anbieter — degradiert das Gateway zu keiner Durchsetzung, anstatt den Traffic lahmzulegen. Die Sicherheit degradiert; die Verfügbarkeit bleibt erhalten. Konfigurieren Sie fail_open: false bei external- oder llm_judge-Regeln, wenn eine verpasste Prüfung für Ihre Policy inakzeptabel ist.Fail-closed (mehrdeutige Fälle): Dort, wo Nicht-Durchsetzung die Regel aushebeln würde, schlägt die Engine closed fehl: ein Egress-Bericht mit einem nicht auflösbaren Ziel wird verweigert; ein unerreichbarer Approval-Store hält den Aufruf zurück, anstatt ihn durchzulassen; ein Skill, dessen Ownership nicht aufgelöst werden kann, wird blockiert. Die Verfügbarkeit bleibt auf dem Happy-Path erhalten; die Sicherheit wird bei den Edge-Cases, die zählen, nicht stillschweigend übersprungen.
Siehe Enforcement-Modi für den vollständigen Entscheidungsbaum und Wie OrcaRouter Requests inspiziert für die Relay-Pfad-Mechanik.

​
10. Vertiefungen

Guardrails

Vollständige Regelreferenz — Typen, Aktionen, PII-Entities, LLM-Judge, Grounding und die Test-Sandbox.

Firewall

Policy-Modell, Verdikte, Surfaces, Shadow-Mode, HITL-Freigabe und Anomalieerkennung.

Firewall-Regeln

Die Regel-Matching-Sprache — Tool-Globs, Argument-Klauseln, Egress-Listen und Sanitizer.

Guardrails vs. Firewall

Welche Ebene welche Bedrohung abfängt — und wann Sie beide brauchen.

Scope, Keys und Policies

Das vollständige Schlüsselmodell: was ein Schlüssel enthält und wie Policies aufgelöst werden.

Enforcement-Modi

Fail-open vs. Fail-closed — der vollständige Entscheidungsbaum.
Jeder Aufruf durch OrcaRouter durchläuft alle vier Durchsetzungsebenen in Reihenfolge — Schlüsselvalidierung, Input-Prüfung, Firewall-Urteil, Output-Prüfung — mit einem vollständigen Audit-Trail, der über alle geschrieben wird.