Configuration Reference

All configuration options explained.

Default config path: ~/.config/WenZi/config.json. Only the fields you want to change are needed; everything else uses defaults.

Config Directory Resolution

The config directory is resolved with the following priority:

1. CLI argument -- pass a directory path as the first positional argument: wenzi /path/to/config-dir
2. NSUserDefaults -- a custom directory saved via the Settings UI (stored under io.github.airead.wenzi / config_dir)
3. Default -- ~/.config/WenZi/

The config file is always config.json inside the resolved directory.

Full Default Configuration

{
  "hotkeys": {"fn": true},
  "audio": {
    "sample_rate": 16000,
    "block_ms": 20,
    "device": null,
    "max_session_bytes": 20971520,
    "silence_rms": 20
  },
  "asr": {
    "backend": "apple",
    "use_vad": true,
    "use_punc": true,
    "language": "zh",
    "model": "on-device",
    "preset": null,
    "temperature": 0.0,
    "default_provider": null,
    "default_model": null,
    "providers": {}
  },
  "output": {
    "method": "auto",
    "append_newline": false,
    "preview": true,
    "preview_type": "web"
  },
  "ai_enhance": {
    "enabled": false,
    "mode": "proofread",
    "default_provider": "ollama",
    "default_model": "qwen2.5:7b",
    "providers": {
      "ollama": {
        "base_url": "http://localhost:11434/v1",
        "api_key": "ollama",
        "models": ["qwen2.5:7b"]
      }
    },
    "thinking": false,
    "timeout": 30,
    "connection_timeout": 10,
    "max_retries": 2,
    "vocabulary": {
      "enabled": false,
      "top_k": 5,
      "build_timeout": 600,
      "auto_build": true,
      "auto_build_threshold": 10
    },
    "conversation_history": {
      "enabled": false,
      "max_entries": 10,
      "refresh_threshold": 50,
      "max_history_chars": 6000
    }
  },
  "clipboard_enhance": {
    "hotkey": "ctrl+cmd+v"
  },
  "feedback": {
    "sound_enabled": true,
    "sound_volume": 0.4,
    "visual_indicator": true,
    "restart_key": "cmd",
    "cancel_key": "space"
  },
  "ui": {
    "settings_last_tab": "general"
  },
  "logging": {
    "level": "INFO"
  },
  "scripting": {
    "enabled": false,
    "script_dir": null
  }
}

Options

General

Audio

ASR

Output

AI Enhancement

Vocabulary Retrieval

Conversation History

Note: Conversation history is automatically rotated when it exceeds 20,000 records. Older records are archived into monthly JSONL files under conversation_history_archives/. This limit is not configurable.

Prompt caching: History entries are appended incrementally to keep the system prompt prefix stable, which allows LLM API-level prompt caching (OpenAI, DeepSeek, etc.) to reuse cached KV state. When the entry count reaches refresh_threshold or total characters reach max_history_chars, the history is rebuilt with the most recent max_entries as a new base. Most API providers require the cached prefix to be at least 1024 tokens (~500–700 Chinese characters). If your enhancement mode prompt is short, consider increasing max_entries (e.g., to 20) so the system prompt exceeds this threshold right after a rebuild.

Both max_entries (Base entries) and refresh_threshold (Max entries) can be configured in Settings > AI under the Conversation History toggle.

Clipboard Enhancement

Feedback

UI

Scripting

Logging

Environment Variables