Configuration

nllclw is configured by OS environment variables first, config.json second, and .env third — OS env always wins. There is no default provider, API key, or model.

Source order#

1. OS environment variables — highest priority, for one-off overrides, service managers, and CI.
2. config.json in the user config directory — the normal long-lived setup, usually created by nllclw init.
3. .env in the same directory — a lower-priority alternative, created by nllclw init --env.

config.json lives at $XDG_CONFIG_HOME/nllclw/config.json, otherwise ~/.config/nllclw/config.json; on Windows, %APPDATA%\nllclw\config.json. nllclw uninstall removes the config and state directories.

config.json format#

A flat JSON object. Keys are the NLLCLW_* names with the prefix removed, lowercased: NLLCLW_API_KEY becomes api_key.

{
  "provider": "openrouter",
  "api_key": "sk-or-...",
  "model": "openai/gpt-chat-latest"
}

Rules: the top-level value must be an object; unknown keys are rejected; strings are accepted for every setting, integers and booleans only for matching settings; arrays, nested objects, floats, and null are rejected; the file is capped at 16 KiB.

The .env parser accepts KEY=VALUE lines, trims whitespace, ignores blanks and # comments, rejects unknown NLLCLW_* keys, and does not support quoting or interpolation. Same 16 KiB cap.

Completion keys#

Optional:

NLLCLW_BASE_URL must be https:// (or loopback http:// with the override), must have a host, and must not include userinfo, query string, or fragment. Trailing slashes are trimmed before /chat/completions is appended.

Memory keys#

Configured state paths must be relative JSONL subpaths under the user state directory: $XDG_STATE_HOME/nllclw, otherwise ~/.local/state/nllclw; on Windows, %LOCALAPPDATA%\nllclw.

Tool keys#

Shell keys are rejected by the default binary — they exist only in a -Dshell-tool=true build:

Search keys#

web_search stays disabled until one provider is configured. auto picks the first configured provider in order: Tavily, Brave, Exa, Firecrawl, then DuckDuckGo only when explicitly enabled.

Telegram keys#

WebSocket keys#

Scheduler and heartbeat keys#

Minimal configs#

OpenRouter:

{
  "provider": "openrouter",
  "api_key": "sk-or-...",
  "model": "openai/gpt-chat-latest"
}

OpenAI:

{
  "provider": "openai",
  "api_key": "sk-...",
  "model": "gpt-4o"
}

Ollama on loopback, through the compatible provider:

{
  "provider": "compatible",
  "base_url": "http://127.0.0.1:11434/v1",
  "allow_http_base_url": true,
  "api_key": "ollama",
  "model": "llama3.2"
}

Use OS env for one-off overrides with the same names converted back to NLLCLW_* — model becomes NLLCLW_MODEL.