Agent Configuration

OpenClacky supports any OpenAI-compatible LLM provider and offers a range of agent behavior settings. Configuration can be set via a config file or environment variables.

Config File

Location: ~/.clacky/config.yml

This file is created automatically when you run openclacky for the first time and configure a model through the setup wizard.

Full Example

settings:
  enable_compression: true
  enable_prompt_caching: true
  compression_threshold: 150000
  message_count_threshold: 200
  memory_update_enabled: true
  skill_evolution:
    enabled: true
    auto_create_threshold: 12
    reflection_mode: llm_analysis
  max_running_agents: 10
  max_idle_agents: 10
  default_working_dir:

models:
  - type: default
    api_key: sk-...
    base_url: https://api.openai.com/v1
    model: gpt-4o
    anthropic_format: false

  - type: lite
    api_key: sk-...
    base_url: https://api.openai.com/v1
    model: gpt-4o-mini
    anthropic_format: false

Settings

The settings section controls agent behavior. All settings are optional — if omitted, defaults are used.

Setting	Type	Default	Description
`enable_compression`	bool	`true`	Enable automatic conversation history compression to reduce context length and save tokens
`enable_prompt_caching`	bool	`true`	Enable prompt caching for supported LLM providers to reduce costs on repeated prompts
`compression_threshold`	int	`150000`	Token count threshold that triggers conversation compression
`message_count_threshold`	int	`200`	Message count threshold that triggers conversation compression
`memory_update_enabled`	bool	`true`	Enable automatic long-term memory updates based on conversation context
`skill_evolution.enabled`	bool	`true`	Enable automatic skill evolution — the agent can refine and improve skills based on usage patterns
`skill_evolution.auto_create_threshold`	int	`12`	Number of similar tasks before the agent suggests creating a new skill
`skill_evolution.reflection_mode`	string	`llm_analysis`	How the agent reflects on skill performance. Currently only `llm_analysis` is supported
`max_running_agents`	int	`10`	Maximum number of concurrently running agent sessions
`max_idle_agents`	int	`10`	Maximum number of idle agent sessions kept in memory
`default_working_dir`	string	(empty)	Default working directory for agent sessions. If empty, uses the directory where `openclacky` was launched

Models

The models section is an array of configured LLM providers. Each entry represents one model configuration.

Single Model

models:
  - type: default
    api_key: sk-...
    base_url: https://api.anthropic.com
    model: claude-sonnet-4-5
    anthropic_format: true

Two Models (Default + Lite)

OpenClacky supports a default model (for main agent tasks) and a lite model (for lightweight subtasks). Configure both for cost optimization:

models:
  - type: default
    api_key: sk-...
    base_url: https://api.openai.com/v1
    model: gpt-4o
    anthropic_format: false

  - type: lite
    api_key: sk-...
    base_url: https://api.openai.com/v1
    model: gpt-4o-mini
    anthropic_format: false

Fields

Field	Required	Description
`type`	Yes	`default` or `lite`
`api_key`	Yes	Your API key
`base_url`	Yes	API endpoint URL
`model`	Yes	Model name (as accepted by the provider)
`anthropic_format`	No	Set `true` for Anthropic-compatible APIs (Claude models). Set `false` for OpenAI-compatible APIs. Default: `true`

Environment Variables

You can configure the model entirely via environment variables — no config file needed. Useful for CI/CD or containerized deployments.

Default Model

Variable	Description
`CLACKY_API_KEY`	API key
`CLACKY_BASE_URL`	API base URL
`CLACKY_MODEL`	Model name (default: `claude-sonnet-4-5`)
`CLACKY_ANTHROPIC_FORMAT`	`true` or `false` (default: `true`)

Lite Model

Variable	Description
`CLACKY_LITE_API_KEY`	API key for lite model
`CLACKY_LITE_BASE_URL`	API base URL for lite model
`CLACKY_LITE_MODEL`	Model name (default: `claude-haiku-4`)
`CLACKY_LITE_ANTHROPIC_FORMAT`	`true` or `false` (default: `true`)

Priority: config file > environment variables. If a config file exists, environment variables are used only to fill in missing model types.

Provider Examples

Anthropic (Claude)

models:
  - type: default
    api_key: sk-ant-...
    base_url: https://api.anthropic.com
    model: claude-sonnet-4-5
    anthropic_format: true

OpenAI

models:
  - type: default
    api_key: sk-...
    base_url: https://api.openai.com/v1
    model: gpt-4o
    anthropic_format: false

DeepSeek

models:
  - type: default
    api_key: sk-...
    base_url: https://api.deepseek.com/v1
    model: deepseek-chat
    anthropic_format: false

Any OpenAI-Compatible Provider

models:
  - type: default
    api_key: your-key
    base_url: https://your-provider.com/v1
    model: your-model-name
    anthropic_format: false

Switching Models at Runtime

Web UI: Click the model name in the status bar to switch between configured models.
CLI: Use /config in the chat to switch models.

The switch persists for that session only — to change the default, edit ~/.clacky/config.yml.