配置参考

所有配置选项详解。

默认配置文件路径：~/.config/WenZi/config.json。只需包含你想修改的字段，其余字段将使用默认值。

配置目录解析

配置目录按以下优先级解析：

1. 命令行参数 -- 将目录路径作为第一个位置参数传入：wenzi /path/to/config-dir
2. NSUserDefaults -- 通过设置界面保存的自定义目录（存储在 io.github.airead.wenzi / config_dir 下）
3. 默认路径 -- ~/.config/WenZi/

配置文件始终是解析后目录中的 config.json。

完整默认配置

{
  "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
  }
}

配置项说明

通用设置

音频设置

语音识别（ASR）

输出设置

AI 增强

词汇检索

对话历史

注意： 对话历史超过 20,000 条记录时会自动轮转归档。旧记录按月归档到 conversation_history_archives/ 目录下的 JSONL 文件中。此上限不可配置。

提示词缓存优化： 对话历史采用追加式构建，保持系统提示词前缀稳定不变，从而让大模型 API 的提示词缓存（OpenAI、DeepSeek 等）可以复用已缓存的 KV 状态。当条目数达到 refresh_threshold 或总字符数达到 max_history_chars 时，会以最近 max_entries 条为基础重建。大多数 API 提供商要求缓存前缀至少达到 1024 tokens（约 500-700 个中文字符）。如果你使用的增强模式提示词较短，建议适当增大 max_entries（如改为 20），以确保重建后系统提示词能超过此阈值。

max_entries（基础条目数）和 refresh_threshold（最大条目数）均可在 Settings > AI 的 Conversation History 开关下方配置。

剪贴板增强

反馈设置

界面

脚本

日志设置

环境变量