Codex CLI — Configuration with OmniRoute (Deutsch)

TOML ist das einzige wirksame Format. Moderne Codex-Versionen lesen ausschließlich ~/.codex/config.toml (verifiziert mit codex-cli 0.147.0: codex --help dokumentiert -c/--config-Überschreibungen, die „aus ~/.codex/config.toml geladen“ werden). Die alte Datei ~/.codex/config.yaml gehörte zur veralteten npm CLI und wird stillschweigend ignoriert. Der Dashboard-Generator (/api/cli-tools/apply, Tool codex) schreibt TOML mit einer konservativen Zusammenführung — vorhandene Schlüssel und andere Provider-Blöcke bleiben erhalten, der API-Schlüssel verbleibt in OMNIROUTE_API_KEY (niemals in der Datei), und eine übrig gebliebene veraltete config.yaml wird als Migrationshinweis gemeldet, ohne verändert zu werden.

Direkt einsetzbare config.toml

Ersetzen Sie <YOUR_HOST> und <YOUR_KEY> durch Ihre Werte:

~/.codex/config.toml

model                          = "cx/gpt-5.5"
model_provider                 = "omniroute"
model_reasoning_effort         = "xhigh"
model_context_window           = 400000
model_auto_compact_token_limit = 350000
tool_output_token_limit        = 32768    # Obergrenze für die Verlaufsspeicherung pro Tool-Aufruf

[model_providers.omniroute]
name                 = "OmniRoute"
base_url             = "http://<YOUR_HOST>:20128/v1"
env_key              = "OMNIROUTE_API_KEY"
requires_openai_auth = false
wire_api             = "responses"

# ~/.bashrc oder ~/.zshrc — tatsächlicher Schlüsselwert, niemals in config.toml
export OMNIROUTE_API_KEY="<YOUR_KEY>"

macOS: In die ChatGPT-App integriertes Codex

Wenn Sie Codex über die ChatGPT-Desktop-App installiert haben, ist die codex-Binärdatei möglicherweise nur innerhalb des App-Bundles vorhanden und noch nicht in Ihrem Shell-PATH enthalten. Fügen Sie das Ressourcenverzeichnis zur Startdatei Ihrer Shell hinzu:

export PATH="/Applications/ChatGPT.app/Contents/Resources:$PATH"

Öffnen Sie eine neue Shell und überprüfen Sie anschließend die Installation:

command -v codex
codex --version

Lokales OmniRoute ohne Authentifizierung: Ein Platzhalterschlüssel genügt

Codex überprüft, ob die durch env_key benannte Umgebungsvariable vorhanden ist, bevor die erste Anfrage die CLI verlässt. Wenn Ihre lokale OmniRoute-Instanz keine Authentifizierung erfordert, genügt ein beliebiger nicht leerer Platzhalter:

export OMNIROUTE_API_KEY="${OMNIROUTE_API_KEY:-local}"

Verwenden Sie stattdessen einen echten Schlüssel, wenn Ihr OmniRoute-Server geschützt ist oder sich auf einem entfernten System befindet.

Gängige Host-Optionen

Zugriff	URL
Lokales Netzwerk	http://192.168.0.1:20128/v1
Tailscale	http://100.x.x.x:20128/v1
Loopback	http://localhost:20128/v1

---

wire_api = "responses" — weshalb es für alle Modelle funktioniert

Codex CLI hat wire_api = "chat" (Chat Completions) im Februar 2026 als veraltet eingestuft und erfordert jetzt wire_api = "responses" (OpenAI Responses API). Die Einstellung wire_api = "chat" führt seit v0.138 unmittelbar beim Start zum Absturz.

Viele Provider, darunter GLM und Kimi, stellen weiterhin nur einen Chat-Completions-Endpunkt bereit. DeepSeek V4 bietet inzwischen sowohl eine native Responses API als auch einen Anthropic-kompatiblen Endpunkt; OmniRoute verwendet standardmäßig Responses und ermöglicht jeder DeepSeek-Verbindung, die Anthropic-Kompatibilität auszuwählen.

OmniRoute löst dies transparent:

Codex CLI
  → wire_api = "responses"
  → POST /v1/responses (OmniRoute)
    → OmniRoute wählt das native Protokoll des Providers aus und übersetzt bei Bedarf
    → POST /responses (DeepSeek V4) oder /chat/completions (Mistral / GLM / Kimi / andere)

Bei Verwendung von OmniRoute benötigen Sie niemals einen separaten Übersetzungs-Proxy. Alle Modelle verwenden wire_api = "responses" — OmniRoute übernimmt den Rest.

wire_api ist die Standardeinstellung — das Feld verwendet standardmäßig "responses" und kann vollständig aus config.toml weggelassen werden. Setzen Sie es nur dann ausdrücklich, wenn Sie die Absicht dokumentieren möchten.

---

Kontextfenster und Komprimierung

Felder der Token-Konfiguration

Feld	Beschreibung
model_context_window	Gesamtes Token-Budget für das aktive Modell. Auf das vom Modell angegebene Limit setzen.
model_auto_compact_token_limit	Schwellenwert, der die automatische Komprimierung des Verlaufs auslöst. Maximum: 90 % von model_context_window — Werte über 90 % werden stillschweigend ignoriert.
tool_output_token_limit	Obergrenze für die pro Tool-Aufruf im Verlauf gespeicherten Ausgabe-Token. Verhindert, dass eine einzelne große Tool-Antwort das Fenster füllt. Dies ist nicht die maximale Ausgabe — es handelt sich um eine Speichergrenze für den Verlauf.
compact_prompt	Inline-Überschreibung für den bei der Komprimierung verwendeten System-Prompt (v0.138+).

Hinweis zu model_max_output_tokens: Dieses Feld ist nicht Teil des Konfigurationsschemas der Codex CLI (es fehlt in der Codex-Codebasis in Rust). Wenn es gesetzt wird, wird es stillschweigend ignoriert. Verlassen Sie sich nicht darauf — verwenden Sie tool_output_token_limit, um zu steuern, wie viel Tool-Ausgabe im Verlauf gespeichert wird.

Kontextfenster nach Modell

Modell	OmniRoute-ID	Kontextfenster	auto_compact	tool_output_limit
GPT-5.5	cx/gpt-5.5	400k zuverlässig (max. 1M)	350,000	32,768
Kimi K2.7 (denkendes Modell)	kmc/kimi-k2.7	131,072	112,000	32,768
Kimi K2.6	kmc/kimi-k2.6	131,072	112,000	32,768
GLM-5.2 / 5.2-max (denkendes Modell)	glm/glm-5.2	131,072	112,000	32,768
MiMo V2.5 Pro (denkendes Modell)	opencode-go/mimo-v2.5-pro	131,072	112,000	32,768
Qwen 3.7 Plus (denkendes Modell)	opencode-go/qwen3.7-plus	32,768	28,000	16,384
DeepSeek V4 Pro (OllamaCloud)	ollamacloud/deepseek-v4-pro	131,072	112,000	32,768
DeepSeek V4 Pro	ds/deepseek-v4-pro	1,000,000	900,000	65,536
MiMo V2.5	opencode-go/mimo-v2.5	131,072	112,000	32,768
Gemma 4 31B (OllamaCloud)	ollamacloud/gemma4:31b	32,768	28,000	16,384
Nemotron 3 Super (OllamaCloud)	ollamacloud/nemotron-3-super	32,768	28,000	16,384
GPT-OSS 20B (OllamaCloud)	ollamacloud/gpt-oss:20b	32,768	28,000	16,384
DeepSeek V4 Flash (OllamaCloud)	ollamacloud/deepseek-v4-flash	65,536	56,000	16,384
Gemini 3 Flash Preview (OllamaCloud)	ollamacloud/gemini-3-flash-preview	1,000,000	850,000	32,768
GLM-5 Turbo	glm/glm-5-turbo	131,072	112,000	16,384
GLM-4.7 Flash	glm/glm-4.7-flash	131,072	112,000	16,384
Mistral Large Latest	mistral/mistral-large-latest	262,144	220,000	16,384

Komprimierungsformel: effective_window = model_context_window - min(tool_output_token_limit, 20000). Werte über 20k ändern den Auslösepunkt der Komprimierung nicht.

Faustregel: Setzen Sie model_auto_compact_token_limit auf 85–88 % von model_context_window. Gehen Sie niemals über 90 % — höhere Werte werden stillschweigend ignoriert.

---

Modellpräfix: cx/

Alle Codex-Modelle in OmniRoute verwenden das Präfix cx/:

Codex-CLI-Name	OmniRoute-Modell
cx/gpt-5.5	GPT-5.5 Standard
cx/gpt-5.4	GPT-5.4 Standard
cx/gpt-5.4-mini	GPT-5.4 Mini
cx/gpt-5.1-codex-mini	GPT-5.1 Codex Mini

Andere Anbieter verwenden ihr eigenes Präfix (kmc/, glm/, ds/, ollamacloud/, opencode-go/, mistral/) — das Präfix entspricht dem OmniRoute-Anbieter-Alias.

---

Reasoning-Aufwand

Steuert, wie viel das Modell vor der Antwort „nachdenkt“.

Wert	Verwendungszweck
none	Kein Reasoning — direkte Antwort
low	Triviale Aufgaben (Umbenennen, Formatieren)
medium	Serverstandard, wenn nicht angegeben
high	Aufgaben mittlerer Komplexität (Refactoring, Debugging)
xhigh	Architektur, tiefgehende Analyse, komplexe Probleme

# Überschreibung pro Aufruf
codex -c model_reasoning_effort=low "Variable x in count umbenennen"
codex -c model_reasoning_effort=xhigh "das Authentifizierungsmodul entwerfen"

Legen Sie außerdem eine Reasoning-Zusammenfassung fest, damit Desktop den Gedankengang als Text darstellen kann (und nicht nur verschlüsselte Blobs):

~/.codex/config.toml

model_reasoning_effort = "xhigh"   # oder ultra, sofern unterstützt
model_reasoning_summary = "detailed"  # auto | concise | detailed | none

OmniRoute-Denkbudget (Servereinstellung)

Auf dem OmniRoute-Host muss Settings → AI → Thinking Budget auf passthrough gesetzt sein, damit Codex-Aufwand und -Zusammenfassung an den Upstream-Anbieter weitergeleitet werden. Der Modus auto entfernt alle clientseitigen Felder reasoning / reasoning_effort und führt zu leeren Thinking-Panels, selbst wenn Codex korrekt konfiguriert ist.

Vollständige Anleitung: THINKING_BUDGET.md.

Komprimierung und Prompt-Cache sind davon unabhängig und funktionieren unter passthrough weiterhin.

---

Profile — benannte Konfigurationen pro Modell/Workflow

Mit Profilen können Sie Modell und Kontextfenster über ein einziges Flag wechseln. Jedes Profil ist eine einfache Datei ~/.codex/<name>.config.toml, die die Basisdatei config.toml überlagert.

Benennungsregel (Codex CLI v0.137+): Die Datei muss ~/.codex/<name>.config.toml heißen — ohne das Präfix profile-. Die CLI löst -p kimi-k27 zu ~/.codex/kimi-k27.config.toml auf. Wird die Datei nicht gefunden, greift stillschweigend die Standardkonfiguration.

codex --profile kimi-k27 "10.000 Zeilen dieser Codebasis analysieren"
codex -p glm52 "Architekturprüfung"
codex --profile deepseek-flash "Variable umbenennen"   # schnell, kostengünstig

Aufwandsprofile (gleiches Modell, unterschiedlicher Aufwand)

codex -p low      # cx/gpt-5.5, Aufwand=low
codex -p medium   # cx/gpt-5.5, Aufwand=medium
codex -p high     # cx/gpt-5.5, Aufwand=high
codex -p xhigh    # cx/gpt-5.5, Aufwand=xhigh (Standard)
codex -p chat     # cx/gpt-5.5, kein Aufwand festgelegt (Serverstandard)

Thinking-Modelle (hoher Denkaufwand) — xhigh + detaillierte Zusammenfassung

Profil	Modell	Kontext	Verwendungszweck
kimi-k27	kmc/kimi-k2.7	128k	Beste Thinking-Qualität (Kimi)
glm52	glm/glm-5.2	128k	GLM-Thinking
glm52max	glm/glm-5.2-max	128k	Maximales GLM-Thinking
mimo-pro	opencode-go/mimo-v2.5-pro	128k	MiMo-Thinking
qwen37plus	opencode-go/qwen3.7-plus	32k	Qwen-Thinking

Gute Modelle — hoher Aufwand

Profil	Modell	Kontext	Verwendungszweck
kimi-k26	kmc/kimi-k2.6	128k	Allgemeine Verwendung (Kimi)
deepseek-pro	ollamacloud/deepseek-v4-pro	128k	DeepSeek Pro über OllamaCloud
deepseek	ds/deepseek-v4-pro	1M	DeepSeek Pro direkt, sehr großer Kontext
mimo	opencode-go/mimo-v2.5	128k	MiMo für allgemeine Verwendung

Einfache Modelle — kein Reasoning-Aufwand

Profil	Modell	Kontext	Verwendungszweck
gemma4	ollamacloud/gemma4:31b	32k	Kostengünstig und leistungsfähig
nemotron	ollamacloud/nemotron-3-super	32k	NVIDIA Nemotron
gptoss	ollamacloud/gpt-oss:20b	32k	Open-Source-GPT

Schnelle Modelle — geringer Aufwand

Profil	Modell	Kontext	Verwendungszweck
deepseek-flash	ollamacloud/deepseek-v4-flash	64k	Schnelle Aufgaben
gemini-flash	ollamacloud/gemini-3-flash-preview	1M	Sehr schnell, sehr großer Kontext
glm5turbo	glm/glm-5-turbo	128k	GLM Turbo
glm47flash	glm/glm-4.7-flash	128k	GLM Flash
mistral	mistral/mistral-large-latest	256k	Mistral Large

Schnelle Entscheidungstabelle

Aufgabe	Empfohlenes Profil
Umbenennen, formatieren, Boilerplate	--profile deepseek-flash oder -p low
Erklären, kurze Überprüfung	-p chat oder -p gemini-flash
Debugging, moderates Refactoring	-p medium oder -p kimi-k26
Neue Funktion, komplexe Tests	-p high oder -p mimo
Architektur, tiefgehende Analyse	-p kimi-k27 oder -p glm52 oder -p xhigh
Codebasisanalyse (benötigt 1M Kontext)	--profile deepseek oder --profile gemini-flash
Maximale Denkqualität	-p glm52max oder -p mimo-pro
Kostenbewusst	-p gemma4 oder -p gptoss

---

Profile automatisch mit omniroute setup-codex generieren

Wenn Sie OmniRoute auf einem VPS ausführen, können Sie Profildateien automatisch aus dem Live-Modellkatalog generieren:

# Von einem VPS aus (verwendet das lokale OmniRoute auf Port 20128)
omniroute setup-codex

# Von einem beliebigen Rechner aus — auf Ihren VPS verweisen
omniroute setup-codex --remote http://100.x.x.x:20128 --api-key sk-xxx

# Vorschau anzeigen, ohne Dateien zu schreiben
omniroute setup-codex --remote http://100.x.x.x:20128 --dry-run

# Nur GLM- und Kimi-Profile generieren
omniroute setup-codex --only glm,kimi

# In ein benutzerdefiniertes Verzeichnis schreiben
omniroute setup-codex --codex-home /path/to/.codex

Der Befehl ruft /v1/models ab, verwendet optimierte Profile für bekannte Modelle, greift bei anderen kompatiblen Textmodellen auf die Katalogmetadaten zurück und schreibt für jedes Modell ~/.codex/<name>.config.toml. Der Vorgang ist idempotent und kann daher sicher erneut ausgeführt werden.

OmniRoute kann dieselben Profildateien außerdem automatisch synchronisieren, nachdem eine erfolgreiche Erkennung bzw. ein erfolgreicher Import von Anbietermodellen den Live-Katalog geändert hat. Diese Funktion ist optional und standardmäßig deaktiviert: Aktivieren Sie sie im CLI Code dashboard („CLI profile auto-sync“ → Codex) oder setzen Sie OMNIROUTE_AUTO_SYNC_CODEX_PROFILES=true (dabei wird auch CLI_ALLOW_CONFIG_WRITES berücksichtigt, das standardmäßig aktiviert ist). Wenn diese Funktion aktiviert ist, schreibt sie ausschließlich separate Profildateien unter ~/.codex/*.config.toml; die aktive bzw. standardmäßige Datei ~/.codex/config.toml, Codex-lb-Einstellungen, Authentifizierung oder Anbieterauswahl werden niemals geändert.

---

Codex mit omniroute launch-codex starten

Prüft den Zustand Ihrer OmniRoute-Instanz, bevor Codex gestartet wird:

# Mit dem lokalen OmniRoute starten (Standardport 20128)
omniroute launch-codex

# Mit einem bestimmten Profil starten
omniroute launch-codex --profile kimi-k27

# Mit einem entfernten VPS starten
omniroute launch-codex --remote http://100.x.x.x:20128/v1 --api-key sk-xxx

# Zusätzliche Argumente an codex übergeben
omniroute launch-codex --profile glm52 -- --yolo "fix this bug"

Codex ist außerdem ein Ziel der beiden generischen, manifestgesteuerten Einstiegspunkte (bin/cli/cli-manifest.mjs):

# Interaktive Modellauswahl → schreibt ~/.codex/<name>.config.toml (TOML, env_key)
omniroute configure codex

# codex mit dem über -c-Flags injizierten omniroute-Anbieter starten (es wird keine Konfiguration geschrieben)
omniroute run codex

---

Neue Funktionen der Codex CLI (v0.138–v0.141)

Version	Funktion
v0.138	Übergabe an die Desktop-App (/app), persönliche Zugriffstoken v2, --profile als ausschließliche Profilauswahl (veraltete [profiles]-Tabellen innerhalb der Datei führen beim Start zum Absturz)
v0.139	web_search = "live" — native Websuche aus dem Code-Modus; oneOf/allOf in MCP-Werkzeugschemas; Umgebungsdiagnose mit codex doctor
v0.140	Token-Ansicht mit /usage innerhalb der Sitzung; /import aus Claude-Code-Sitzungen; Unterbefehl codex delete <SESSION_ID>; Amazon-Bedrock-Authentifizierung über das aws-Objekt in der Anbieterkonfiguration
v0.141	Ende-zu-Ende-verschlüsseltes Noise-Relay für entfernte Ausführungsumgebungen; SQLite-WAL-Korrektur; P-521-TLS-Unterstützung

Neue config.toml-Felder (ab v0.138)

# Native Websuche (v0.139)
web_search = "live"   # "disabled" | "cached" | "live"

# Separate Systemanweisung für Entwickler (v0.138)
developer_instructions = "Always prefer functional style."

# Benutzerdefinierte Anweisung zur Komprimierung
compact_prompt = "Summarise the above as bullet points."

# /review an ein kostengünstigeres Modell weiterleiten
review_model = "glm/glm-5-turbo"

# OpenAI-Dienststufe
service_tier = "fast"   # "fast" | "flex"

Neue [model_providers.<id>]-Felder

[model_providers.omniroute]
base_url             = "http://100.x.x.x:20128/v1"
env_key              = "OMNIROUTE_API_KEY"
requires_openai_auth = false

# Statische zusätzliche Header bei jeder Anfrage
[model_providers.omniroute.http_headers]
"X-Custom-Header" = "value"

# Aus Umgebungsvariablen gelesene Header
[model_providers.omniroute.env_http_headers]
"X-Trace-Id" = "TRACE_ID"

# Zusätzliche URL-Abfrageparameter (nützlich für die Azure-api-version)
[model_providers.omniroute.query_params]
"api-version" = "2024-12-01-preview"

Amazon-Bedrock-Authentifizierung (v0.140)

[model_providers.bedrock]
base_url = "https://bedrock-runtime.us-east-1.amazonaws.com"

[model_providers.bedrock.aws]
profile = "default"   # ~/.aws/credentials-Profil
region  = "us-east-1"

---

Mehrere Server

[model_providers.omniroute-main]
base_url = "http://192.168.0.1:20128/v1"
env_key  = "OMNIROUTE_API_KEY"

[model_providers.omniroute-tailscale]
base_url = "http://100.x.x.x:20128/v1"
env_key  = "OMNIROUTE_API_KEY"

---

Claude Code — entsprechende Konfiguration

Codex CLI (config.toml)	Claude Code (Umgebungsvariable)	Auswirkung
tool_output_token_limit = 32768	(nicht direkt verfügbar)	Verlaufslimit pro Tool
model_context_window = 400000	(vom Modell bestimmt)	Kontextfenster
—	CLAUDE_CODE_MAX_OUTPUT_TOKENS=65536	Maximale Tokenanzahl pro Antwort

# ~/.bashrc — Token-Limit für Claude Code
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=65536

---

Kurzreferenz — CLI-Flags

Flag	Kurzform	Auswirkung
--model <id>	-m	Überschreibt model für diesen Aufruf
--profile <name>	-p	Lädt ~/.codex/<name>.config.toml
--config key=value	-c	Überschreibt ein beliebiges config.toml-Feld (wiederholbar)
--enable <feature>	—	Aktiviert ein Feature-Flag explizit
--disable <feature>	—	Deaktiviert ein Feature-Flag explizit
--search	—	Aktiviert die Live-Websuche für diesen Aufruf

Neu in v0.140:

codex delete <SESSION_ID>          # eine Sitzung löschen
codex delete <SESSION_ID> --force  # Bestätigung überspringen
codex debug models --bundled       # gebündelten Modellkatalog als JSON auflisten

Innerhalb einer interaktiven Sitzung:

Befehl	Auswirkung
/model	Öffnet die Modellauswahl
/usage	Zeigt die Token-Nutzung dieser Sitzung an (v0.140)
/app	Übergibt an die Desktop-App (v0.138)
/import	Importiert eine Claude-Code-Sitzung (v0.140)
/help	Listet alle Slash-Befehle auf

---

Lang laufende Aufgaben

Zwei OmniRoute-Standardeinstellungen können mehrstündige Codex-CLI-Sitzungen unbemerkt sabotieren. Keine davon ist eine Codex-CLI-Einstellung — beide befinden sich auf der OmniRoute-Seite. Benutzer, die eine Konfiguration von vorgeschalteten Proxys migrieren, welche Konten fest zuordnen und Leerlaufbegrenzungen deaktivieren, stoßen häufig auf beide Probleme und kommen zu dem Schluss, OmniRoute könne „keine lange Sitzung aufrechterhalten“.

Symptom	Wahrscheinliche Ursache	Einstellung
Sitzung wechselt ständig die Konten / Prompt-Cache-Kontinuität geht zwischen Zügen verloren	TTL der Sitzungsaffinität ist 0 (deaktiviert)	sessionAffinityTtlMs
Verbindung bricht mitten im Schlussfolgern ohne clientseitige Meldung ab	Stream-Leerlaufüberwachung wurde nach 10 Minuten ohne Upstream-Chunk ausgelöst	STREAM_IDLE_TIMEOUT_MS

Zugehörige Diskussionen: #7126 (Abbrüche bei langen Aufgaben), #5718 (warum Affinität standardmäßig deaktiviert ist). Nachverfolgung: #7287.

1. Sitzungsaffinität — eine Konversation einem Konto fest zuordnen

Standardwert: sessionAffinityTtlMs = 0 (deaktiviert).

Wo sie festgelegt wird

• Dashboard → Einstellungen → Routing → Sitzungsaffinität → Affinitäts-TTL (Sekunden) (ComboDefaultsTab)
• Oder die Einstellungen per PATCH mit sessionAffinityTtlMs in Millisekunden aktualisieren (Zod-Bereich 0–86_400_000, d. h. bis zu 24 Stunden)

In #7274 vom ausschließlich für Codex vorgesehenen codexSessionAffinityTtlMs umbenannt. Der veraltete Schlüssel wird weiterhin als schreibgeschützter Alias akzeptiert; neue Konfigurationen sollten sessionAffinityTtlMs verwenden. Die Affinität gilt jetzt für jeden Anbieter, sobald die TTL größer als 0 ist, nicht nur für Codex — siehe docs/architecture/RESILIENCE_GUIDE.md → Sitzungsaffinität.

Was nicht funktioniert, wenn der Wert bei 0 bleibt

Jeder Zug einer Codex-Konversation mit mehreren Zügen wird von der aktiven Kombinationsstrategie unabhängig geroutet und kann bei jedem Zug auf einem anderen Konto landen. Dadurch wird die Kontinuität der Upstream-Sitzung bzw. des Prompt-Caches unterbrochen. OmniRoute berücksichtigt Codex-Sitzungsheader (x-codex-session-id / x-session-id / x-omniroute-session) und Textkörperfelder wie prompt_cache_key / session_id nur dann, wenn die TTL größer als 0 ist (extractSessionAffinityKey in src/sse/services/auth.ts).

Empfehlung für eine einzelne mehrstündige Aufgabe

Setzen Sie die TTL höher als die erwartete tatsächliche Laufzeit der Aufgabe (das UI-Maximum beträgt 86400 Sekunden = 24 Stunden):

Erwartete Aufgabendauer	Affinitäts-TTL (UI, Sekunden)	sessionAffinityTtlMs
Einige Stunden	14400 (4 Std.)	14400000
Über Nacht / ~12 Std.	43200 (12 Std.)	43200000
Ganzer Tag	86400 (24 Std., Maximum)	86400000

Die explizite Aktivierung ist beabsichtigt: Das Deaktivieren der Affinität begünstigt den Lastenausgleich zwischen Konten; das Aktivieren begünstigt die Kontinuität einer einzelnen langen Agentensitzung. Dieser Leitfaden ändert den Standardwert nicht — Betreiber, die lange Codex-Aufgaben ausführen, müssen die Funktion explizit aktivieren.

2. Stream-Leerlaufzeitlimit — stille Schlussfolgerungszüge nicht abbrechen

Standardwert: STREAM_IDLE_TIMEOUT_MS = 600000 (10 Minuten). Ist die Variable nicht gesetzt, übernimmt sie den Wert von REQUEST_TIMEOUT_MS; der gemeinsame Basiswert beträgt ebenfalls 600000. Siehe docs/guides/SETUP_GUIDE.md → Zeitlimits.

Was beim Standardwert nicht funktioniert

Ein Codex-Reasoning-/Tool-Turn, der länger als 10 Minuten ohne echten Upstream-Chunk still bleibt, wird vom SSE-Inaktivitäts-Watchdog (open-sse/utils/stream.ts) zwangsweise beendet. Der Client stellt häufig nur einen abrupten Verbindungsabbruch fest — passend zu „automatisch und ohne Benachrichtigung gestoppt“.

Entscheidendes Detail: Der synthetische SSE-Heartbeat von OmniRoute setzt den Inaktivitäts-Timer nicht zurück. Nur ein echter Upstream-Body-Chunk aktualisiert lastChunkTime. Ein stilles Modell, das noch „nachdenkt“, ist aus Sicht des Watchdogs nicht von einem blockierten Upstream zu unterscheiden.

Verwandte Undici-Body-Inaktivität: FETCH_BODY_TIMEOUT_MS (standardmäßig ebenfalls dieselbe 10-Minuten-Basislinie; 0 deaktiviert sie). Beim Streaming deckt FETCH_TIMEOUT_MS nur den Verbindungsaufbau / die ersten Header ab — sobald der Stream aktiv ist, werden Unterbrechungen durch STREAM_IDLE_TIMEOUT_MS und FETCH_BODY_TIMEOUT_MS geregelt.

Empfehlung für eine einzelne, mehrere Stunden dauernde Aufgabe

In der Prozessumgebung von OmniRoute (.env / compose / systemd):

# Inaktivitätslimits für Stream und Body bei langen Reasoning-Turns deaktivieren
STREAM_IDLE_TIMEOUT_MS=0
FETCH_BODY_TIMEOUT_MS=0

Alternativ können Sie die Werte höher als die längste erwartete stille Phase setzen (Werte in Millisekunden):

# Beispiel: Bis zu 2 Stunden Stille zwischen Upstream-Chunks zulassen
STREAM_IDLE_TIMEOUT_MS=7200000
FETCH_BODY_TIMEOUT_MS=7200000

Starten Sie OmniRoute neu, nachdem Sie diese Umgebungsvariablen geändert haben.

Konkrete Anleitung — mehrstündige Codex-Aufgabe

1. Konto fest zuordnen: Dashboard → Settings → Routing → Session affinity → Affinity TTL = 43200 (12 Std.) oder 86400 (max. 24 Std.).
2. Inaktivitätslimits erhöhen / deaktivieren in der Umgebung von OmniRoute:

STREAM_IDLE_TIMEOUT_MS=0
FETCH_BODY_TIMEOUT_MS=0

3. Behalten Sie die übliche Codex-config.toml bei (wire_api = "responses", korrekte base_url, OMNIROUTE_API_KEY) — für diese beiden Verhaltensweisen gibt es auf Codex-Seite keine Optionen für Affinität/Inaktivität.
4. Starten Sie OmniRoute neu und anschließend die lange Codex-Aufgabe.

Entscheidung zu Standardwerten (#7287)

Option	Ausgelieferter Standardwert	In diesem Leitfaden ändern?
sessionAffinityTtlMs	0 (aus)	Nein — bleibt Opt-in (Lastverteilung vs. Kontinuität; siehe Diskussion #5718)
STREAM_IDLE_TIMEOUT_MS	600000 (10 Min.)	Nein — bleibt für allgemeinen Datenverkehr bei 10 Minuten; Betreiber langer Codex-Aufgaben erhöhen oder deaktivieren den Wert

Eine globale Änderung eines dieser Standardwerte würde das Verhalten für jeden Client einer Instanz ändern, nicht nur für Codex. Dokumentieren Sie die Optionen; lassen Sie die Standardwerte unverändert, bis eine ausdrückliche Betreiberentscheidung etwas anderes vorgibt.

Diagnose von Inaktivitätsabbrüchen

Wenn der Inaktivitäts-Watchdog ausgelöst wird, protokolliert OmniRoute eine Zeile in folgender Form:

[STREAM] Idle timeout: no data from codex for 600000ms (model: cx/gpt-5.5)

Suchen Sie mit Grep nach Idle timeout: no data from (oder nach dem Code stream_idle_timeout / Fehlernamen StreamIdleTimeoutError). Das Provider-Segment entspricht dem Provider, den OmniRoute für diese Anfrage verwendet hat (codex, eine andere Provider-ID oder provider, falls unbekannt) — es ist nicht immer die wörtliche Zeichenfolge codex.

---

Fehlerbehebung

Error: wire_api = "chat" is no longer supported Entfernen Sie wire_api = "chat" aus Ihrer Konfiguration. Setzen Sie wire_api = "responses" oder lassen Sie das Feld weg (seit v0.138 ist "responses" der Standardwert).

Error: model not found Überprüfen Sie, ob das Modell in OmniRoute mit dem richtigen Präfix vorhanden ist. Verwenden Sie omniroute models list oder öffnen Sie /dashboard/providers/<provider>.

Authentication error Stellen Sie sicher, dass OMNIROUTE_API_KEY exportiert ist: echo $OMNIROUTE_API_KEY.

ERROR: Missing environment variable: OMNIROUTE_API_KEY Codex überprüft vor der ersten Anfrage, ob die Umgebungsvariable vorhanden ist. Exportieren Sie für geschützte Server einen echten Schlüssel oder einen nicht leeren Platzhalter wie OMNIROUTE_API_KEY=local, wenn Ihre lokale OmniRoute-Instanz keine Authentifizierung erfordert. Starten Sie die Shell neu, wenn Sie die Variable zu ~/.bashrc oder ~/.zshrc hinzugefügt haben.

Connection refused Überprüfen Sie, ob OmniRoute ausgeführt wird und ob Host und Port von base_url für Ihr Netzwerk korrekt sind (lokal, Tailscale oder VPS).

Sitzung stürzt nahe dem Kontextlimit ab Setzen Sie model_context_window und model_auto_compact_token_limit explizit. Siehe die Tabelle zum Kontextfenster oben.

Kompaktierung wird zu spät ausgelöst Senken Sie model_auto_compact_token_limit auf 80–85 % des Fensters. Setzen Sie den Wert niemals über 90 %.

Profil wird nicht geladen (-p <name> wird stillschweigend ignoriert) Stellen Sie sicher, dass die Datei unter ~/.codex/<name>.config.toml vorhanden ist (ohne das Präfix profile-). Führen Sie ls ~/.codex/*.config.toml aus.

Lange Codex-Aufgabe bricht während der Ausführung ab / wechselt zwischen Anfragen das Konto Siehe Lang laufende Aufgaben. Aktivieren Sie Sitzungsaffinität (TTL länger als die Aufgabendauer) und erhöhen oder deaktivieren Sie STREAM_IDLE_TIMEOUT_MS / FETCH_BODY_TIMEOUT_MS. Durchsuchen Sie die OmniRoute-Protokolle mit grep nach Idle timeout: no data from.

---

OmniRoute-Quellcode (a58000c7685f)