Engine configuration

config/engine.toml configures inference providers. It is required and must define exactly one global default provider.

The file maps provider names to provider tables.

[default]
apiBase = "https://api.openai.com/v1"
apiKey = "not-needed"
defaultModel = "gpt-5.6"
isGlobalDefault = true
kind = "openai"

Provider fields

Field	Required	Default	Description
apiBase	Yes	—	Absolute provider API base URL.
apiKey	No	["not-needed"]	One API key, or an array of keys for rotation.
defaultModel	Yes	—	Default model name.
isGlobalDefault	No	false	Marks exactly one provider as the global default.
kind	No	"openai"	Provider kind: openai, anthropic, or openai-codex.
authId	No	"default"	OAuth credential id used by openai-codex.
availableModels	No	"analyze"	Explicit model list, or "analyze" to resolve the provider's models on demand; a list replaces analysis for that provider.
customHeaders	No	{}	Extra request headers sent with provider requests.
maxGenerationRetries	No	2	Generation retry count.
maxTurns	No	30	Maximum engine turns per request.
useFilesApi	No	false	Files API mode; false or "kimi".
useJpegForImages	No	false	Send images as JPEG.
useToolChoiceAuto	No	false	Prefer automatic tool choice.

When availableModels = "analyze", the /model override subcommand analyzes the provider's model list on demand, so models published after the runtime started are selectable without a restart. Autocomplete reuses a successful analysis for 30 seconds and renews that window on every keystroke, so one lookup covers an operator typing a model name.

When a header value contains $session, the runtime replaces it on generation requests with the lower-case hexadecimal SHA-256 hash of the current session ID. The same hash is sent as the provider prompt cache key, so configured headers and provider-side cache partitioning share one opaque session identifier instead of the internal ID. The placeholder is also resolved for OpenAI-compatible file uploads and Codex requests.

Per-model overrides

A [<provider>.models.<model>] table overrides context and reasoning settings for one model.

[default.models.gpt-5.6]
contextWindow = 128000
contextBudget = 0.8
contextHardBudget = 0.95
reasoning = "medium"
reasoningBudget = 8192
supportsVision = true
supportsVideo = false
maxImagesPerRequest = 10
toolFailThreshold = 3

Field	Default	Description
contextWindow	—	Context window size in tokens; resolved from provider metadata when absent.
contextBudget	—	Soft context budget as a fraction of the window.
contextHardBudget	—	Hard context budget as a fraction of the window.
reasoning	true	Reasoning toggle or mode: true, false, or xhigh, high, medium, low, minimal, none.
reasoningBudget	16384	Reasoning token budget.
supportsVision	true	Whether the model accepts images.
supportsVideo	false	Whether the model accepts video.
maxImagesPerRequest	—	Maximum images per request.
toolFailThreshold	3	Tool failures allowed before recovery.

Provider kinds

• openai — OpenAI-compatible chat completions API.
• anthropic — Anthropic messages API.
• openai-codex — OpenAI Codex via ChatGPT OAuth credentials managed by the codex command.

Codex models

An openai-codex provider talks to the ChatGPT Codex backend, so apiBase must be https://chatgpt.com/backend-api; the runtime appends codex/responses for generation and codex/models for the model list.

[codex]
kind = "openai-codex"
apiBase = "https://chatgpt.com/backend-api"
authId = "default"
defaultModel = "gpt-5.6-terra"
isGlobalDefault = true

The runtime asks that backend for the account's model list, so models it publishes after the runtime started are selectable without a restart. The query reuses its result for five minutes, sends the provider's customHeaders, and falls back to a catalog snapshot bundled with the build when it fails, logging a warning instead of failing the command. Only models the backend publishes as visible appear in the list and in autocomplete; a hidden model stays selectable by naming it in availableModels or in a [codex.models.<model>] table.

A configured model name reaches the backend unchanged apart from a stripped vendor/ prefix and normalized case and separators, so the runtime never substitutes a different model for the one you chose. Reasoning follows the levels the backend advertises for that model: an explicit reasoning mode is used when the model advertises it, false and minimal use the model's least advertised level, and an unset mode uses the model's advertised default. The reasoning picklist stops at xhigh, so max, which the backend accepts for some models, is not selectable in configuration. Context windows resolve from the same catalog, so contextWindow is optional when the backend reports one.

Codex image input is automatically downscaled when its 32-pixel patch count would exceed the backend's 30,000-patch per-image limit. The resized image is sent as WebP, or JPEG when useJpegForImages = true.

OpenAI-compatible request headers

The openai provider sends these attribution headers with chat-completions requests:

Header	Value
HTTP-Referer	https://github.com/CutieZone/CireilClaw
X-OpenRouter-Categories	personal-agent,cli-agent
X-OpenRouter-Title	CireilClaw

These headers support OpenRouter application attribution and are sent for every openai provider because the route supports OpenAI-compatible APIs.

Use customHeaders for additional provider-specific request headers.

Reload

The runtime watches engine.toml and applies changes live to subsequent turns.