File discovery

The first file that exists wins:

  1. $CLAI_CONFIG
  2. ./clai.edn
  3. ~/.config/clai/config.edn (under $XDG_CONFIG_HOME when set)

A missing, unreadable, or non-map file falls back to the built-in defaults rather than failing startup. clai.config/candidates and clai.config/config-path report what would be loaded.

Keys

Every key is optional. Unknown keys are allowed and ignored.

KeyTypeDefaultPurpose
:modelnon-empty stringgemma3Model name, optionally prefixed with a provider.
:provider:ollama / :openrouter:ollamaProvider for a model name that does not name one.
:system-promptstringbuilt-in promptPrepended to every session’s history.
:max-tool-roundspositive integer8Consecutive tool-call rounds before the agent gives up.
:compact-after-tokensnon-negative integercompaction defaultHistory budget; 0 disables compaction.
:optionsmap{}Provider-neutral chat options.
:thinkbooleanprovider defaultOllama :think / OpenRouter reasoning.
:formatstring or mapnoneOllama :format / OpenRouter response_format.
:ollamamapclient defaultsOllama connection settings.
:openroutermapclient defaultsOpenRouter connection settings.
:postgresmapdevelopment databaseSession, note, plugin, and auth storage.
:openprojectmapdisabledEnables the OpenProject tools.
:toolsvector of stringsevery built-in toolTool ids to expose; [] disables tools.
:pluginsvector of stringsevery enabled pluginPlugin names or database ids; [] disables plugins.

Model and provider resolution

clai.config/resolve-model checks :model, then $CLAI_MODEL, then gemma3. clai.config/resolve-provider checks :provider, then $CLAI_PROVIDER, then :ollama; an unknown provider is logged and replaced by the default.

A model name can always pick its own provider:

NameProviderModel
gemma3:providergemma3
ollama:gemma3:7bOllamagemma3:7b
openrouter:gemma3:7bOpenRoutergemma3:7b
anthropic/claude-sonnet-4OpenRouteranthropic/claude-sonnet-4

An id containing / is treated as an OpenRouter id.

:ollama

KeyEnvironmentDefault
:hostOLLAMA_HOSThttp://localhost:11434
:api-keyOLLAMA_API_KEYnone
:timeoutnoneclient default

:openrouter

KeyEnvironmentDefault
:api-keyOPENROUTER_API_KEYnone
:base-urlOPENROUTER_BASE_URLhttps://openrouter.ai/api/v1
:timeoutnoneclient default
:referernonenone
:titlenonenone

:referer and :title are optional attribution headers OpenRouter shows on its activity page.

:postgres

The connection is opened lazily and schema/schema.sql is applied on the first session operation. Omitted keys fall back to CLAI_POSTGRES_*, then the standard PG* variables, then the development defaults.

KeyEnvironmentDefault
:urlCLAI_POSTGRES_URL, DATABASE_URLnone
:hostCLAI_POSTGRES_HOST, PGHOSTlocalhost
:portCLAI_POSTGRES_PORT, PGPORT5432
:databaseCLAI_POSTGRES_DATABASE, CLAI_POSTGRES_DB, PGDATABASEclai
:userCLAI_POSTGRES_USER, PGUSERclai
:passwordCLAI_POSTGRES_PASSWORD, PGPASSWORDsecret
:ssl-modeCLAI_POSTGRES_SSL_MODE, CLAI_POSTGRES_SSLMODE, PGSSLMODEclient default
:connect-timeoutCLAI_POSTGRES_CONNECT_TIMEOUTclient default
:socket-timeoutCLAI_POSTGRES_SOCKET_TIMEOUTclient default
:application-nameCLAI_POSTGRES_APPLICATION_NAMEclai

:url is a full JDBC URL and replaces the host/port/database form. Its credentials replace the user/password defaults.

:openproject

The tools are only enabled when this map (or the environment) provides a URL and credentials. Omitted keys fall back to OPENPROJECT_* variables.

KeyEnvironment
:urlOPENPROJECT_URL, OPENPROJECT_BASE_URL
:base-urlOPENPROJECT_URL, OPENPROJECT_BASE_URL
:api-keyOPENPROJECT_API_KEY, OPENPROJECT_TOKEN
:tokenOPENPROJECT_API_KEY, OPENPROJECT_TOKEN
:usernameOPENPROJECT_USERNAME
:passwordOPENPROJECT_PASSWORD
:projectOPENPROJECT_PROJECT
:typeOPENPROJECT_TYPE
:timeoutOPENPROJECT_TIMEOUT

:url may be the instance root or its /api/v3 API root. :project is the default project for new work packages, and :type the default type.

Other environment variables

VariablePurpose
CLAI_CONFIGHighest-priority config file path
CLAI_MODELDefault model when :model is absent
CLAI_PROVIDERDefault provider when :provider is absent
CLAI_MAX_TOOL_ROUNDSTool-round cap
CLAI_COMPACT_AFTER_TOKENSHistory token budget (0 disables compaction)
CLAI_WEB_ROOTDirectory the daemon serves the React build from
CLAI_DAEMON_URLDaemon URL used by the Vite web dev proxy
  • clai.config/chat-options selects :options, :think, and :format for a provider.
  • clai.config/tool-specs resolves the model-facing tool definitions from :tools and an agent’s registry.
  • clai.config/make-clients builds one provider client per configured provider.
  • clai.config/make-postgres-client builds the storage client.

Stored agent configurations in PostgreSQL override these file defaults for the sessions that select them.