Configuration and provider settings
Strix turns environment values and a small JSON file into one validated settings object. These settings select the model route, provide access data, shape model requests, and set limits for each model turn.
Configuration sources and validation
The configuration system resolves process environment values, the active JSON file, and field defaults into one settings object. The normal file is ~/…/cli-config.json. A command-line config path replaces it for the current process. The file stores values inside an env object so the same names work in both places. load_settings() caches the resolved object, while a new config override clears that cache. Settings groups values for the main model, finding deduplication, runtime, context, telemetry, integrations, and viewer behavior. Model requests can also receive user-defined extra headers and body fields through the model settings.
model, api_key, and api_base form one provider connection. If the shell changes one of these values, Strix drops the stored values for the linked connection instead of combining old and new connection data. This prevents a model from silently using a key or endpoint that belongs to another provider.
References: strix/…/loader.py• L26-60 strix/…/loader.py• L140-168 strix/…/settings.py• L229-238
Configuration precedence
Environment values win even when the file uses another accepted alias for the same field. A missing, malformed, or wrongly shaped file does not replace the environment or defaults. When Strix persists settings, it writes only environment values that are currently set and uses a restricted file mode. It does not serialize every default or resolved value.
Stored provider connection values are treated as a unit. A changed environment value causes the stored model, key, and base URL to be removed before the file is read or written. An unset environment value leaves the existing file value in place, while an empty environment value clears that field during persistence.
References: strix/…/loader.py• L63-90 strix/…/loader.py• L106-154 strix/…/settings.py• L29-56
Validation boundaries
Pydantic validates types and allowed ranges before consumers use the settings. Reasoning effort accepts a fixed set of names and normalizes those names to lower case. API type accepts responses or chat_completions. Preflight and stream limits reject invalid values. Context limits and the per-turn tool-call limit also reject invalid values. The model preflight timeout must be at least one second. The first-event, stream-idle, whole-stream, cache-block, and tool-call limits cannot be negative or zero where a positive value is required. A missing model is a startup error for a normal API-key route. A chatgpt/<model> route instead requires a valid ChatGPT subscription sign-in.
References: strix/…/settings.py• L11-14 strix/…/settings.py• L29-114 strix/…/settings.py• L143-160 strix/…/codex.py• L394-405
Model and provider selection
The selected model name controls both the provider path and the request shape. A scan may pass a model directly, which takes priority over STRIX_LLM; otherwise Strix uses the configured model. The provider keeps known prefixes for native OpenAI routes and sends other provider names through the compatible provider layer. The SDK-native API path is selected by an explicit API type when one is set. Otherwise Strix uses the model catalog to choose Responses when the model lists that endpoint and uses Chat Completions for other models. A secondary model such as the report-deduplication judge can bind its own API key and base URL, so it does not reuse the main model's process-wide provider credentials.
The following flow shows how configuration becomes a provider request.
flowchart LR
A[Environment or config file] --> B[Validated settings]
B --> C[Resolved model name and API type]
C --> D{Model route}
D -->|OpenAI or compatible API| E[SDK or LiteLLM provider]
D -->|chatgpt prefix| F[Codex subscription client]
E --> G[Guarded model turn]
F --> G
G --> H[Provider request]
Request controls
The main LLM settings become per-request model settings at scan start. They affect the model turn without changing the scan’s tool set or task.
| Setting | Provider-facing effect |
|---|---|
STRIX_API_TYPE or STRIX_FORCE_API | Forces the Responses or Chat Completions request path when the selected route supports both. |
STRIX_REASONING_EFFORT | Requests the chosen reasoning level when the model route supports reasoning. none leaves reasoning unset. |
LLM_TIMEOUT | Sets the request timeout. |
LLM_PREFLIGHT_TIMEOUT | Bounds the startup model check separately from normal model turns. |
LLM_STREAM_FIRST_EVENT_TIMEOUT | Fails a stream when its first event does not arrive within the configured time. A value of 0 disables this bound. |
LLM_STREAM_IDLE_TIMEOUT | Fails a streamed turn when no event arrives within the configured gap. A value of 0 disables this idle check. |
LLM_STREAM_TOTAL_TIMEOUT | Fails a streamed turn when it exceeds the configured whole-stream time. A value of 0 disables this bound. |
LLM_DISABLE_STREAMING | Uses one completed request for normal compatible routes that do not support reliable streams. It does not change the always-streamed Codex route. |
STRIX_PROMPT_CACHE and STRIX_CACHE_BLOCK_TOKENS | Enable prompt-cache request fields when supported and set the token block size used to shape cacheable prompt content. |
STRIX_FORCE_REQUIRED_TOOL_CHOICE | Requests a required tool choice only when the selected route accepts that mode. |
STRIX_PARALLEL_TOOL_CALLS | Allows the provider request to opt in to parallel tool calls when the selected route supports that mode. |
LLM_EXTRA_HEADERS | Adds user headers to requests on the LiteLLM and native OpenAI paths. |
LLM_EXTRA_BODY | Adds user request fields to model calls that support extra body data. |
STRIX_OPENROUTER_STICKY_SESSIONS | Adds a stable per-agent OpenRouter session ID when enabled, so related calls can remain on one upstream provider and retain its prompt cache. The default is disabled. |
The scan passes these controls to the model provider after it resolves the final model. Provider-specific checks can change tool schema strictness and the tool protocol, so one request shape is not forced onto every provider.
References: strix/…/settings.py• L29-114 strix/…/models.py• L249-268 strix/…/models.py• L370-375 strix/…/models.py• L602-656 strix/…/models.py• L713-740
Provider defaults and attribution
Strix applies the configured key and base URL to the SDK and compatible provider layer. It disables model tracing, sends extra headers on both routing paths, and adds app attribution headers for Vercel AI Gateway models. OpenRouter models receive the same app headers plus OpenRouter category attribution. Provider cost callbacks remain active so usage can be accounted for. OpenRouter calls can optionally use a stable session per agent when STRIX_OPENROUTER_STICKY_SESSIONS is enabled; otherwise Strix does not add a session ID. These defaults prepare the client before the scan or model preflight sends a request.
A provider created for a dedicated secondary model keeps that model's key and base URL on its own route rather than changing the main model's defaults. This lets a secondary request use a different account or endpoint without changing the active scan.
References: strix/…/models.py• L530-600 strix/…/models.py• L693-717 strix/…/models.py• L777-876
Codex subscription settings
The chatgpt/<model> model prefix selects the ChatGPT subscription route instead of an API-key route. The access record is kept apart from the normal config file in ~/…/subscription-auth.json. It contains OAuth data and the account identity needed by the backend. The client refreshes near-expiry access tokens under a process and cross-process guard. It stamps a fresh bearer token and account header onto each request, which lets a long scan continue across token expiry.
The subscription client checks for a usable sign-in before it starts. A missing or invalid record therefore fails during model setup rather than after the scan has begun.
References: strix/…/codex.py• L54-85 strix/…/codex.py• L106-127 strix/…/codex.py• L318-405
Codex request behavior
The ChatGPT backend requires streamed Responses requests. Strix enforces streaming even when the caller asks for a complete response, then collects the stream into the result expected by the scan loop. It also sends store=false and encrypted reasoning content. Configured reasoning levels are mapped to levels accepted by this backend, so minimal maps to low and xhigh or max map to high. A content-guardrail rejection is terminal for that model and is not treated as a transient retry.
References: strix/…/models.py• L85-160 strix/…/models.py• L602-623 strix/…/codex.py• L130-160
Tool-call identity and turn limits
The model layer protects the conversation before it gives model output to the run loop. Some providers restart tool-call numbering on every turn, which can create duplicate IDs in one conversation. Other providers omit IDs or return empty IDs. Strix repairs duplicate and blank IDs, keeps each new turn’s replacements stable across streamed events, repairs malformed tool arguments before the history is reused, and preserves the pairing between a tool call and its result.
The turn limit protects the scan from one response that queues an unsafe number of tool calls. Stream bounds protect it from a provider that never sends its first event, goes silent between events, or does not finish within the whole-stream limit.
sequenceDiagram
participant M as Model provider
participant G as Turn guard
participant R as Scan run loop
M->>G: Stream response with tool calls
G->>G: Enforce first-event, idle, and total bounds
G->>G: Repair blank and duplicate IDs
G->>G: Repair malformed arguments
G->>G: Keep up to configured calls
G-->>R: Valid events and completed response
R->>M: Tool results on the next turn
Tool-call limit semantics
LLM_MAX_TOOL_CALLS_PER_TURN counts tool calls in one assistant response. The default keeps at most 32 calls. A value above zero keeps the first calls up to that value and drops later calls from both streamed events and the completed response. A value of zero disables this limit. Dropped calls are logged so an operator can see that the model response was shortened.
References: strix/…/settings.py• L93-108 strix/…/models.py• L249-389
Provider failure handling
Provider choice also affects how Strix interprets failures. Normal model calls use a retry policy for provider-suggested failures, network errors, and selected server or rate-limit responses. A stream that misses its first event, exceeds its idle gap, or exceeds its total time fails through the timeout path so the existing retry path can replay the turn. Codex content-guardrail errors are excluded because repeating the same request does not clear the block.
References: strix/…/models.py• L75-83 strix/…/models.py• L420-479 strix/…/models.py• L687-700
Change checklist
When these files or sections are changed, remember to consider these:
- Keep every accepted environment alias aligned between
Settingsfields, JSON-file mapping, and persistence. A mismatch can make a saved value appear to load while an environment value silently wins. - Keep the linked LLM connection rule aligned between loading and persistence. Otherwise an updated model can retain an old key or endpoint.
- Keep
chatgpt/model detection aligned across environment validation, provider construction, and auth-mode reporting. A mismatch can send a subscription model down the API-key path. - When changing model request controls, update both the normal request builder and the Codex-specific request rules. The Codex backend has stricter stream and reasoning requirements.
- When changing API route selection, keep the explicit API type, model catalog lookup, and provider capabilities aligned. Otherwise a model can receive a request protocol that its endpoint does not support.
- When changing stream limits, keep first-event, idle, and total timeout values aligned between settings validation, the turn guard, and the non-streaming wrapper. Otherwise a disabled or bounded setting can be applied to the wrong request mode.
- When changing tool-call identity or argument handling, preserve the same decision across history, streamed item events, and the terminal response. Blank or placeholder IDs need a stable per-output replacement, malformed arguments need a valid replay form, and tool results must remain paired with their calls.
- When adding a provider route, review its tool schema, reasoning, prompt-cache, header, and authentication support instead of assuming the OpenAI route applies.
- When changing secondary-model credentials, keep the dedicated provider route separate from the main model's process-wide defaults. Otherwise a dedupe request can use the wrong endpoint or credentials.
- When changing
STRIX_API_TYPEorLLM_EXTRA_HEADERS, keep the SDK-native and LiteLLM paths aligned. Otherwise the selected route can ignore the requested API mode or required header. - When changing provider attribution or
STRIX_OPENROUTER_STICKY_SESSIONS, keep model detection, header cleanup, and request transformation aligned. Otherwise a route can receive stale attribution or unexpected upstream pinning. - When changing
LLM_EXTRA_BODYorDEDUPE_LLM_EXTRA_BODY, keep the accepted field shape aligned with the request builders for the main and secondary model paths. Otherwise a valid setting can be loaded but never reach the intended provider. - When changing
STRIX_PARALLEL_TOOL_CALLS, keep the setting aligned with provider capability checks and tool-call result handling. Otherwise a provider can receive an unsupported mode or the run loop can process calls with the wrong assumptions.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| No model is set for a normal route | The scan stops before the first model request | Environment validation and runner startup require a resolved model |
chatgpt/<model> is used without a valid OAuth record | Model setup fails because no subscription token is available | Sign in with the ChatGPT auth flow before the scan |
| The model catalog does not list the selected API endpoint and no explicit API type is set | The SDK can send the model through an incompatible request path | Route selection uses the catalog and allows an explicit API type override |
| A provider omits or reuses tool-call IDs | Strict providers reject the replayed conversation | The turn guard assigns stable replacements for blank IDs and rewrites collisions while preserving call-result pairing |
| A tool call has malformed arguments and the history replays the raw value | The next provider request can fail schema or JSON validation | The turn guard repairs arguments into a valid JSON object before replay |
| One response emits more calls than the configured limit | The run loop would process an excessive queue | The turn limiter keeps only the allowed prefix |
| A streamed provider misses its first event, goes silent, or runs past the whole-stream bound | The turn can hang or consume the scan's time budget | The first-event, idle, and total stream timeouts abort the turn so retry can run |
| Codex blocks content through its cyber-risk guardrail | Repeating the same request continues to fail | Strix reports a terminal guardrail error and requires a different model or prompt |
| A dedicated secondary model inherits the main model's endpoint settings | A dedupe request can fail or use the wrong provider account | The secondary provider binds its own key and base URL when configured |
| The shell changes one linked provider value while old values remain in the file | The model can run against a mixed provider connection | The loader drops the linked stored connection before it resolves or persists settings |
| A forced API path or required header is applied to only one provider route | Requests can fail or reach the endpoint without the needed protocol or header | The model setup applies API type and extra headers to the matching SDK and LiteLLM paths |
| Sticky OpenRouter sessions are enabled without a stable request context | Calls do not receive a session ID and cannot gain session-based upstream pinning | Strix adds IDs only when the model call has an agent identity and the setting is enabled |
| Attribution state from a prior model remains when the model changes | A provider can receive headers intended for another route | Strix removes prior app attribution headers before applying the headers for the resolved model |
| Parallel tool calls are enabled for a route that does not support them | The provider can reject the request or return a tool format the run loop cannot use | Provider capability checks must gate the request option |
Key files
| File | Why to read it |
|---|---|
| strix/…/settings.py | Defines the validated settings groups, aliases, model request limits, stream bounds, API path choice, preflight bound, extra request fields, parallel tool-call option, and defaults. |
| strix/…/loader.py | Explains source precedence, linked connection handling, config overrides, caching, and persistence. |
| strix/…/models.py | Shows model routing, provider defaults, Codex behavior, secondary-provider isolation, request controls, stream bounds, turn guards, attribution, and optional OpenRouter sessions. |
| strix/…/codex.py | Defines subscription model selection, OAuth storage, token refresh, and request auth. |
| strix/…/tool_call_ids.py | Explains conversation-wide tool-call ID repair, including missing and duplicate IDs. |
| strix/…/tool_call_arguments.py | Explains repair of malformed tool-call arguments before conversation replay. |
| strix/…/tool_call_limits.py | Defines the per-turn tool-call safety boundary. |
| strix/…/inputs.py | Connects settings to request-level reasoning, timeout, header, cache, and tool-choice controls. |
| strix/…/runner.py | Shows when configuration is loaded and how the resolved model starts a scan. |
| strix/…/environment.py | Shows the user-facing checks for model and authentication readiness. |
| strix/…/dedupe.py | Shows how a dedicated dedupe model receives its own provider credentials. |
| docs/configuration-and-integrations.md | Provides the parent overview of configuration and external integration concerns. |
| docs/mcp-integration.md | Covers the related model-tool integration settings. |
| docs/proxy-and-caido-integration.md | Covers the related proxy and Caido settings and resource flow. |