Configuration

GodeX is configured through a single YAML file, typically named godex.yaml. The configuration file controls every aspect of the gateway: which port to listen on, which providers to enable, how sessions are stored, what gets logged, and how traces are recorded. The system reads the file, interpolates environment variables, applies CLI overrides, and validates every field before the server starts.

At a Glance

Section	Purpose	Required
server	Listen address, port, idle timeout	Yes (has defaults)
default_provider	Provider used when model omits prefix	Yes
providers	Map of provider name to config	Yes
models	Model aliases and wildcard mapping	No
session	Conversation history backend	Yes (has defaults)
logging	Log level, console, and file output	Yes (has defaults)
trace	Request/response tracing	Yes (has defaults)

Config Loading Pipeline

The raw YAML file passes through a multi-stage pipeline before becoming the validated GodeXConfig object that the rest of the system consumes (src/config/builder.ts:17-39).

The file is read from disk by loadConfigFromFile (src/config/reader.ts:5-35), then each section is parsed by dedicated functions in src/config/sections/.

Environment Variable Interpolation

String values in the providers section support ${VAR} syntax. The interpolation is recursive, so nested objects and arrays under providers are all processed. This lets you keep API keys out of your config file.

providers:
  deepseek:
    spec: deepseek
    credentials:
      api_key: ${DEEPSEEK_API_KEY}

The resolveEnvVarsDeep function handles this by walking the object tree it is given (src/config/env-interpolation.ts:9-20):

Expression	Behavior
${MY_VAR}	Replaced with process.env.MY_VAR
${MISSING_VAR}	Left as the literal ${MISSING_VAR}
Non-string values	Passed through unchanged

Server Section

Controls the HTTP server configuration. Parsed in src/config/sections/server.ts:10-37.

server:
  port: 5678
  host: "0.0.0.0"
  idle_timeout: 0

Field	Type	Default	Description
port	number	5678	Listen port. Override: --port, GODEX_PORT
host	string	0.0.0.0	Listen address. Override: --host, GODEX_HOST
idle_timeout	number	0	Idle connection timeout in seconds

Priority order for port: CLI flag > YAML value > GODEX_PORT env > default 5678.

Provider Section

Each provider entry maps a logical name to a provider spec with credentials. Parsed in src/config/sections/providers.ts:4-40.

providers:
  deepseek:
    spec: deepseek
    credentials:
      api_key: ${DEEPSEEK_API_KEY}
    endpoint:
      base_url: https://api.deepseek.com
    timeout_ms: 30000

Field	Type	Required	Description
spec	string	No (defaults to key name)	Provider spec name (e.g. deepseek, zhipu, minimax)
credentials.api_key	string	Yes	Bearer token for the provider API
endpoint.base_url	string	No	Override the provider's default base URL
timeout_ms	number	No	Per-request timeout in milliseconds

When spec is omitted, the provider key name is used as the spec (src/config/sections/providers.ts:17-19). Startup fails when the resolved spec — explicit or key name — is not a registered provider definition.

Models Section

Model aliases let you map friendly model names to concrete provider/model pairs. The wildcard * acts as a catch-all.

models:
  aliases:
    "gpt-5.5": deepseek/deepseek-v4-pro
    "glm": zhipu/glm-5.1
    "*": deepseek/deepseek-v4-flash

Alias	Resolves To	Behavior
gpt-5.5	deepseek/deepseek-v4-pro	Exact match
glm	zhipu/glm-5.1	Exact match
*	deepseek/deepseek-v4-flash	Fallback for any unmatched model

Session Section

Controls how conversation history is persisted for multi-turn support via previous_response_id. Parsed in src/config/sections/session.ts:5-27.

session:
  backend: sqlite
  sqlite:
    path: ./data/sessions.db

Field	Type	Default	Description
backend	"memory" | "sqlite"	memory	Storage backend for response sessions
sqlite.path	string	Auto	Path to the SQLite database file

Logging Section

Controls structured logging output via LogTape. Parsed in src/config/sections/logging.ts:9-67.

logging:
  level: info
  console:
    enabled: true
    level: info
  file:
    enabled: true
    level: debug
    dir: ./logs
    filename: godex.log
    max_size: 10           # 10 MB per file
    max_files: 5

Field	Type	Default	Description
level	LogLevel	info	Global minimum log level. Override: --log-level, GODEX_LOG_LEVEL
console.enabled	boolean	-	Enable console output
console.level	LogLevel	inherits level	Console-specific log level
file.enabled	boolean	-	Enable file output
file.dir	string	required if enabled	Directory for log files
file.filename	string	required if enabled	Log file name
file.max_size	number	10	Max file size in MB before rotation
file.max_files	number	-	Max number of rotated files to keep

Valid log levels: trace, debug, info, warn, error.

Trace Section

Controls the request/response tracing subsystem. Parsed in src/config/sections/trace.ts:6-49.

trace:
  enabled: true
  path: ./data/trace.db
  capture_payload: false
  payload_max_bytes: 65536
  max_queue_size: 10000
  flush_interval_ms: 1000
  batch_size: 100

Field	Type	Default	Description
enabled	boolean	true	Enable or disable tracing
path	string	Auto	Path to the trace SQLite database
capture_payload	boolean	false	Record full request/response bodies
payload_max_bytes	number	65536	Max payload size to capture
max_queue_size	number	10000	In-memory trace event queue size
flush_interval_ms	number	1000	How often to flush traces to disk
batch_size	number	100	Number of traces per flush batch

Web Search Section

Controls built-in web search. GodeX can either let the provider handle search natively, or run the search itself ("GodeX-managed") and feed the results back into a continuation request. Parsed in src/config/sections/web-search.ts:10-73.

web_search:
  enabled: true
  mode: auto                 # auto | provider_native | godex_managed | disabled
  provider: none             # none | mock | zhipu
  on_unavailable: client_tool_call  # client_tool_call | fail | ignore
  max_iterations: 2
  timeout_ms: 10000

Field	Default	Description
enabled	true	Master switch
mode	auto	auto (prefer native, fall back to managed), provider_native, godex_managed, or disabled
provider	none	Search backend for godex_managed mode (none / mock / zhipu)
on_unavailable	client_tool_call	Fallback when managed search is configured but unavailable
max_iterations	2	Max managed search rounds per request
timeout_ms	10000	Per-search timeout (ms)

With the shipped defaults, providers that support native web search (Zhipu, Xiaomi) use it directly; others forward web_search calls to the client. Note that for native providers mode has no effect — they always use native search. To enable GodeX-managed search for non-native providers (DeepSeek, MiniMax), set provider: zhipu and add a providers.zhipu block with credentials.api_key to godex.yaml (the search backend reads the provider config, not just ZHIPU_API_KEY). See the Config Schema - Web Search for full field semantics.

Full Config Builder Flow

The buildConfig function in src/config/builder.ts:17-39 ties everything together.

CLI Overrides

The CLI layer can override specific config values without editing the YAML file. These overrides are passed to buildConfig via the ConfigOverrides interface (src/config/builder.ts:11-15).

CLI Flag	Config Path	Type
--port	server.port	number
--host	server.host	string
--config	(file path)	string
--log-level	logging.level	LogLevel

Complete Example

server:
  port: 5678
  host: "0.0.0.0"
  idle_timeout: 0

default_provider: deepseek

models:
  aliases:
    "gpt-5.5": deepseek/deepseek-v4-pro
    "glm": zhipu/glm-5.1
    "*": deepseek/deepseek-v4-flash

providers:
  deepseek:
    spec: deepseek
    credentials:
      api_key: ${DEEPSEEK_API_KEY}
    endpoint:
      base_url: https://api.deepseek.com
    timeout_ms: 30000
  zhipu:
    spec: zhipu
    credentials:
      api_key: ${ZHIPU_API_KEY}
  minimax:
    spec: minimax
    credentials:
      api_key: ${MINIMAX_API_KEY}

session:
  backend: sqlite
  sqlite:
    path: ./data/sessions.db

logging:
  level: info
  console:
    enabled: true
  file:
    enabled: true
    dir: ./logs
    filename: godex.log

trace:
  enabled: true
  capture_payload: false

Configuration Schema

The top-level GodeXConfig type is defined in src/config/schema.ts:62-70:

Next Steps

Topic	Description
Quick Start	Install and run GodeX in five minutes
Built-in Providers	Compare provider capabilities
Overview	Architecture and design concepts

References

• src/config/schema.ts:1-71 - All configuration type definitions
• src/config/reader.ts:5-35 - YAML file loader
• src/config/env-interpolation.ts:1-20 - ${VAR} interpolation
• src/config/builder.ts:11-39 - Config builder with overrides
• src/config/sections/server.ts:10-37 - Server config parser
• src/config/sections/providers.ts:4-40 - Provider config parser
• src/config/sections/session.ts:5-27 - Session config parser
• src/config/sections/logging.ts:9-67 - Logging config parser
• src/config/sections/trace.ts:6-49 - Trace config parser