配置说明

配置系统概览

配置文件位置

py-xiaozhi 的配置文件存储在 用户数据目录 下（而非项目根目录），符合各平台规范：

平台	配置目录
Windows	`C:\Users\<用户名>\AppData\Local\py-xiaozhi\config\`
macOS	`~/Library/Application Support/py-xiaozhi/config/`
Linux	`~/.local/share/py-xiaozhi/config/`

<用户数据目录>/
├── config/
│   ├── config.json      # 主配置文件（运行时配置）
│   └── efuse.json       # 设备身份文件（自动生成）
├── logs/                # 日志文件
└── cache/               # 缓存文件

提示：二开开发者如需自定义应用名称，修改 src/constants/system.py 的 APP_NAME 即可改变数据目录名称。

配置层次结构

默认配置模板
- 位置：src/utils/config_manager.py 中的 DEFAULT_CONFIG
- 作用：提供系统默认配置值
- 用途：首次运行时自动生成配置文件的模板
运行时配置文件
- 位置：<用户数据目录>/config/config.json
- 作用：存储用户自定义配置
- 用途：系统运行时读取的实际配置
设备身份文件
- 位置：<用户数据目录>/config/efuse.json
- 作用：存储设备唯一标识和激活状态
- 用途：设备激活和身份验证

配置访问方式

配置系统支持点分隔路径访问，便于获取和修改嵌套配置：

python

# 获取配置示例
from src.utils.config_manager import ConfigManager
from src.utils.config_manager import get_config

config = get_config()  # 进程入口须先 initialize_config()

# 获取网络配置
websocket_url = config.get_config("SYSTEM_OPTIONS.NETWORK.WEBSOCKET_URL")

# 获取唤醒词配置
wake_words = config.get_config("WAKE_WORD_OPTIONS.WAKE_WORDS")

# 更新配置
config.update_config("WAKE_WORD_OPTIONS.USE_WAKE_WORD", True)
config.update_config("CAMERA.VLapi_key", "your_api_key_here")

# 重新加载配置
config.reload_config()

系统配置 (SYSTEM_OPTIONS)

基础系统配置

json

{
  "SYSTEM_OPTIONS": {
    "CLIENT_ID": "自动生成的客户端ID",
    "DEVICE_ID": "设备MAC地址",
    "WINDOW_SIZE_MODE": "screen_100",
    "NETWORK": {
      "OTA_VERSION_URL": "https://api.tenclass.net/xiaozhi/ota/",
      "WEBSOCKET_URL": "wss://api.tenclass.net/xiaozhi/v1/",
      "WEBSOCKET_ACCESS_TOKEN": "访问令牌",
      "MQTT_INFO": {
        "endpoint": "mqtt.server.com",
        "client_id": "xiaozhi_client",
        "username": "your_username",
        "password": "your_password",
        "publish_topic": "xiaozhi/commands",
        "subscribe_topic": "xiaozhi/responses"
      },
      "ACTIVATION_VERSION": "v2",
      "AUTHORIZATION_URL": "https://xiaozhi.me/"
    }
  }
}

配置项说明

配置项	类型	默认值	说明
`CLIENT_ID`	String	自动生成	客户端唯一标识符
`DEVICE_ID`	String	MAC地址	设备唯一标识符
`WINDOW_SIZE_MODE`	String	"screen_100"	窗口大小模式
`OTA_VERSION_URL`	String	官方OTA地址	OTA配置获取地址
`WEBSOCKET_URL`	String	由OTA下发	WebSocket服务器地址
`WEBSOCKET_ACCESS_TOKEN`	String	由OTA下发	WebSocket访问令牌
`ACTIVATION_VERSION`	String	"v2"	激活协议版本 (v1/v2)
`AUTHORIZATION_URL`	String	"https://xiaozhi.me/"	设备授权地址

服务端配置更换

更换自部署服务端

如需使用自行部署的服务端，只需修改OTA接口地址，系统会自动从OTA服务器获取WebSocket连接信息：
AUTHORIZATION_URL换成你们绑定设备的后台，例如xiaozhi.me这种，点击跳转时会自动打开这个网页

json

{
  "SYSTEM_OPTIONS": {
    "NETWORK": {
      "OTA_VERSION_URL": "https://your-server.com/xiaozhi/ota/",
      "AUTHORIZATION_URL": "https://xiaozhi.me/"
    }
  }
}

配置自动更新机制

系统启动时会通过以下流程自动更新配置：

OTA配置获取：向OTA_VERSION_URL发送POST请求
配置自动更新：系统自动更新MQTT和WebSocket配置
连接建立：使用更新后的配置建立连接

禁用配置自动更新

如果不需要配置自动更新，可以在以下位置注释相关代码：

1. 禁用OTA配置获取

在 src/core/system_initializer.py 中注释第三阶段：

python

# async def stage_3_ota_config(self):
#     """
#     第三阶段：OTA获取配置.
#     """
#     # 注释掉整个方法内容

2. 禁用WebSocket配置更新

在 src/core/ota.py 中注释更新方法：

python

async def update_websocket_config(self, response_data):
    """
    更新WebSocket配置信息.
    """
    # 注释掉配置更新逻辑
    return None

3. 手动配置WebSocket连接

直接在配置文件中配置固定的连接信息：

json

{
  "SYSTEM_OPTIONS": {
    "NETWORK": {
      "WEBSOCKET_URL": "wss://your-server.com/xiaozhi/v1/",
      "WEBSOCKET_ACCESS_TOKEN": "your_fixed_token"
    }
  }
}

唤醒词配置 (WAKE_WORD_OPTIONS)

Sherpa-ONNX 语音唤醒设置

json

{
  "WAKE_WORD_OPTIONS": {
    "USE_WAKE_WORD": true,
    "MODEL_PATH": "models/zh",
    "NUM_THREADS": 4,
    "PROVIDER": "cpu",
    "MAX_ACTIVE_PATHS": 2,
    "KEYWORDS_SCORE": 1.8,
    "KEYWORDS_THRESHOLD": 0.2,
    "NUM_TRAILING_BLANKS": 1,
    "WAKE_WORD": "你好小智",
    "WAKE_WORD_LANG": "zh"
  }
}

配置项说明

配置项	类型	默认值	说明
`USE_WAKE_WORD`	Boolean	true	是否启用语音唤醒
`MODEL_PATH`	String	"models"	Sherpa-ONNX模型文件目录
`NUM_THREADS`	Integer	4	模型推理线程数，影响响应速度
`PROVIDER`	String	"cpu"	推理引擎（cpu/cuda/coreml）
`MAX_ACTIVE_PATHS`	Integer	2	搜索路径数，影响准确性和速度
`KEYWORDS_SCORE`	Float	1.8	关键词增强分数，影响检测灵敏度
`KEYWORDS_THRESHOLD`	Float	0.2	检测阈值，越低越灵敏
`NUM_TRAILING_BLANKS`	Integer	1	尾随空白token数量
`WAKE_WORD`	String	"你好小智"	唤醒词文本
`WAKE_WORD_LANG`	String	"zh"	唤醒词语言（zh/en）

模型文件结构

bash

models/
├── encoder.onnx      # 编码器模型（已内置高精度版本）
├── decoder.onnx      # 解码器模型
├── joiner.onnx       # 连接器模型
├── tokens.txt        # 拼音token映射表
└── keywords.txt      # 关键词配置文件

自定义唤醒词

编辑 models/keywords.txt 添加唤醒词：

# 格式：拼音分解 @中文原文
n ǐ h ǎo x iǎo zh ì @你好小智
j iā w éi s ī @贾维斯
x iǎo zh ù sh ǒu @小助手
k āi sh ǐ g ōng z uò @开始工作

性能调优

速度优先配置

json

{
  "WAKE_WORD_OPTIONS": {
    "NUM_THREADS": 6,
    "MAX_ACTIVE_PATHS": 1,
    "KEYWORDS_THRESHOLD": 0.15,
    "KEYWORDS_SCORE": 1.5
  }
}

准确性优先配置

json

{
  "WAKE_WORD_OPTIONS": {
    "NUM_THREADS": 4,
    "MAX_ACTIVE_PATHS": 3,
    "KEYWORDS_THRESHOLD": 0.25,
    "KEYWORDS_SCORE": 2.2
  }
}

摄像头配置 (CAMERA)

视觉识别设置

json

{
  "CAMERA": {
    "backend": "auto",
    "device": "",
    "camera_index": 0,
    "frame_width": 640,
    "frame_height": 480,
    "fps": 30,
    "warm_up_frames": 5,
    "Local_VL_url": "https://open.bigmodel.cn/api/paas/v4/",
    "VLapi_key": "your_zhipu_api_key",
    "models": "glm-4v-plus"
  }
}

配置项说明

配置项	类型	默认值	说明
`backend`	String	`"auto"`	采集后端：`auto` / `opencv` / `picamera2`。`auto` 先 OpenCV，失败再试树莓派 CSI
`device`	String	`""`	设备路径（如 `"/dev/video0"`）。非空时优先于 `camera_index`，适合 Linux/Pi USB
`camera_index`	Integer	`0`	OpenCV 摄像头索引（桌面常用）
`frame_width`	Integer	`640`	期望画面宽度（驱动可能回落）
`frame_height`	Integer	`480`	期望画面高度
`fps`	Integer	`30`	帧率（配置保留；当前拍照为单帧采集）
`warm_up_frames`	Integer	`5`	打开后丢弃的预热帧数（USB/Pi 前几帧常无效）
`Local_VL_url`	String	智谱 API 地址	视觉模型 API 地址
`VLapi_key`	String	`""`	智谱 API 密钥；与 URL 都配置时走 VL 分析
`models`	String	`"glm-4v-plus"`	视觉模型名称

平台说明

场景	建议
电脑 USB / 内置摄像头	`backend=auto`，用 `camera_index`
树莓派 USB 摄像头	`backend=opencv`，`device` 设为 `/dev/videoX`，用户加入 `video` 组
树莓派官方 CSI	系统安装 `python3-picamera2`（不要在 macOS 上 pip 装 picamera2），`backend=auto` 或 `picamera2`

实现见 src/mcp/tools/camera/capture_backend.py；详细说明见摄像头工具。

摄像头测试

bash

# 扫描设备 / 试拍 / 写入配置
python scripts/camera_scanner.py
python scripts/camera_scanner.py --test
python scripts/camera_scanner.py --device /dev/video0 --test
python scripts/camera_scanner.py --backend picamera2 --test

# 程序内语音
# 「看看摄像头前有什么？」

快捷键配置 (SHORTCUTS)

全局快捷键设置

json

{
  "SHORTCUTS": {
    "ENABLED": true,
    "MANUAL_PRESS": {
      "modifier": "ctrl",
      "key": "j",
      "description": "按住说话"
    },
    "AUTO_TOGGLE": {
      "modifier": "ctrl",
      "key": "k",
      "description": "自动对话"
    },
    "ABORT": {
      "modifier": "ctrl",
      "key": "q",
      "description": "中断对话"
    },
    "MODE_TOGGLE": {
      "modifier": "ctrl",
      "key": "m",
      "description": "切换模式"
    },
    "WINDOW_TOGGLE": {
      "modifier": "ctrl",
      "key": "w",
      "description": "显示/隐藏窗口"
    }
  }
}

快捷键说明

快捷键	功能	说明
`Ctrl+J`	按住说话	按住期间录音，释放后发送
`Ctrl+K`	自动对话	开启/关闭自动对话模式
`Ctrl+Q`	中断对话	中断当前对话
`Ctrl+M`	切换模式	在不同对话模式间切换
`Ctrl+W`	显示/隐藏窗口	显示或隐藏主窗口

声学回声消除配置 (AEC_OPTIONS)

AEC音频处理设置

json

{
  "AEC_OPTIONS": {
    "ENABLED": false,
    "MUSIC_PARALLEL": true,
    "FRAME_DELAY": 3,
    "ENABLE_PREPROCESS": true
  }
}

配置项说明

配置项	类型	默认值	说明
`ENABLED`	Boolean	false	启用内置 WebRTC APM 回声消除（消除本应用 TTS/音乐的回声）
`MUSIC_PARALLEL`	Boolean	true	AEC 在位时 TTS 与音乐并行播放（音乐闪避）；AEC 旁路时自动回退为暂停音乐
`FRAME_DELAY`	Integer	3	延迟补偿帧数，实际补偿 = 40ms + N × 协议帧长
`ENABLE_PREPROCESS`	Boolean	true	启用噪声抑制/高通预处理

AEC功能说明

回声消除 (Echo Cancellation)

内置 libs/webrtc_apm（WebRTC 音频处理），三端开箱即用，无需系统配置
以本应用播放的 TTS/音乐混音作为参考信号（Self far），从麦克风信号中消除回声
引擎创建失败时自动旁路，不影响正常使用

噪声抑制 (Noise Suppression)

抑制背景噪声和环境干扰
提高语音识别准确性

对话模式影响

json

{
  "AEC_OPTIONS": {
    "ENABLED": true  // 启用时：实时对话模式（ListeningMode.REALTIME）
                     // 禁用时：回合制对话模式（ListeningMode.AUTO_STOP）
  }
}

AEC功能测试

bash

# 测试回声消除效果
# 1. 启用AEC，播放音乐同时说话
python main.py  # AEC启用时应无回声，且不会自言自语

# 2. 禁用AEC对比效果
# 修改配置文件 "ENABLED": false
python main.py  # AEC禁用时可能有回声

💡 内置 AEC 仅消除本应用播放的声音；如需消除其它软件的外放声音，参见回声消除中的系统级方案。

音频设备配置 (AUDIO_DEVICES)

音频输入输出设置

json

{
  "AUDIO_DEVICES": {
    "input_device_id": null,
    "input_device_name": null,
    "output_device_id": null,
    "output_device_name": null,
    "input_sample_rate": null,
    "output_sample_rate": null,
    "input_channels": 1,
    "output_channels": 2,
    "opus_output_sample_rate": 24000,
    "frame_duration": 20
  }
}

配置项说明

配置项	类型	默认值	说明
`input_device_id`	Integer	null	输入设备ID（自动检测）
`input_device_name`	String	null	输入设备名称
`output_device_id`	Integer	null	输出设备ID（自动检测）
`output_device_name`	String	null	输出设备名称
`input_sample_rate`	Integer	null	输入采样率（自动检测）
`output_sample_rate`	Integer	null	输出采样率（自动检测）
`input_channels`	Integer	1	输入声道数
`output_channels`	Integer	2	输出声道数
`opus_output_sample_rate`	Integer	24000	Opus解码采样率：24000(官方) 或 16000(第三方)
`frame_duration`	Integer	20	音频帧长度(ms)：20(低延迟) / 40(平衡) / 60(低CPU)

采样率与帧时长说明

Opus 解码采样率

24000: 官方服务器使用，音质较好
16000: 第三方服务器使用，兼容性更好

帧时长选择

帧时长主要影响输入编码和设备回调频率。服务端返回的音频帧时长由客户端自动检测（解析 Opus TOC 字节），无需手动匹配。

20ms: 低延迟，适合实时对话（x86 默认）
40ms: 平衡模式，延迟与性能兼顾
60ms: 低CPU占用，适合树莓派等性能受限设备

音频设备自动检测

系统启动时会自动检测可用的音频设备。如需手动指定设备，可以配置设备ID和名称：

json

{
  "AUDIO_DEVICES": {
    "input_device_id": 2,
    "input_device_name": "MacBook Air麦克风",
    "output_device_id": 1,
    "output_device_name": "MacBook Air扬声器"
  }
}

运行时优先按 设备名称 匹配（ID 会随热插拔变化）。

运行中热刷新（蓝牙等）

程序已启动后再连接蓝牙耳机时：

系统声音设置中确认设备已连接并可作输入/输出
打开 参数设置 → 音频设备 → 刷新设备
（会短暂停麦/播放，并重初始化 PortAudio 后重新枚举）
在列表中选中目标设备并 保存配置
→ 触发 CONFIG_CHANGED，AudioPlugin 会 reload_devices 切到新设备

若刷新后仍没有该设备：确认系统层已暴露音频端点，或退出后「先连蓝牙再启动」（冷启动枚举最稳）。

实现：refresh_portaudio_devices + 事件 AUDIO_DEVICES_REFRESH_REQUEST。

日志配置 (LOGGING)

日志系统设置

json

{
  "LOGGING": {
    "LEVEL": "INFO",
    "FORMAT_TYPE": "colored",
    "ENABLE_CONSOLE": true,
    "ENABLE_FILE": true,
    "ENABLE_ERROR_FILE": true,
    "ENABLE_JSON_FILE": false,
    "ENABLE_ASYNC": false,
    "ENABLE_SENSITIVE_FILTER": true,
    "MAX_BYTES": 10485760,
    "BACKUP_COUNT": 30,
    "ROTATION_WHEN": "midnight",
    "THIRD_PARTY_LEVELS": {
      "urllib3": "WARNING",
      "websockets": "WARNING",
      "asyncio": "WARNING",
      "paho": "WARNING",
      "PIL": "WARNING"
    }
  }
}

配置项说明

配置项	类型	默认值	说明
`LEVEL`	String	"INFO"	日志级别：DEBUG/INFO/WARNING/ERROR/CRITICAL
`FORMAT_TYPE`	String	"colored"	输出格式：colored/json/simple
`ENABLE_CONSOLE`	Boolean	true	是否启用控制台输出
`ENABLE_FILE`	Boolean	true	是否启用文件日志
`ENABLE_ERROR_FILE`	Boolean	true	是否单独记录错误日志
`ENABLE_JSON_FILE`	Boolean	false	是否启用JSON格式日志文件
`ENABLE_ASYNC`	Boolean	false	是否启用异步日志
`ENABLE_SENSITIVE_FILTER`	Boolean	true	是否过滤敏感信息
`MAX_BYTES`	Integer	10485760	单个日志文件最大字节数（10MB）
`BACKUP_COUNT`	Integer	30	保留的日志备份数量
`ROTATION_WHEN`	String	"midnight"	日志轮换时机：midnight/H/D
`THIRD_PARTY_LEVELS`	Object		第三方库日志级别配置

日志级别说明

级别	说明
DEBUG	详细调试信息，开发时使用
INFO	一般运行信息（默认）
WARNING	警告信息
ERROR	错误信息
CRITICAL	严重错误

开发调试配置

json

{
  "LOGGING": {
    "LEVEL": "DEBUG",
    "FORMAT_TYPE": "colored",
    "ENABLE_CONSOLE": true,
    "ENABLE_FILE": true
  }
}

生产环境配置

json

{
  "LOGGING": {
    "LEVEL": "WARNING",
    "FORMAT_TYPE": "json",
    "ENABLE_CONSOLE": false,
    "ENABLE_FILE": true,
    "ENABLE_JSON_FILE": true,
    "ENABLE_ASYNC": true
  }
}

协议配置详解

WebSocket 协议配置

WebSocket连接信息通常由OTA服务器自动下发，无需手动配置：

json

{
  "SYSTEM_OPTIONS": {
    "NETWORK": {
      "WEBSOCKET_URL": "wss://your-server.com/xiaozhi/v1/",
      "WEBSOCKET_ACCESS_TOKEN": "your_access_token"
    }
  }
}

配置要点：

URL必须以 ws:// 或 wss:// 开头
支持IP地址或域名
默认端口为8000，可根据服务器配置调整
访问令牌用于身份验证
通常由OTA服务器自动配置，无需手动设置

MQTT 协议配置

json

{
  "SYSTEM_OPTIONS": {
    "NETWORK": {
      "MQTT_INFO": {
        "endpoint": "mqtt.server.com",
        "port": 1883,
        "client_id": "xiaozhi_client_001",
        "username": "your_username",
        "password": "your_password",
        "publish_topic": "xiaozhi/commands",
        "subscribe_topic": "xiaozhi/responses",
        "qos": 1,
        "keep_alive": 60
      }
    }
  }
}

配置要点：

endpoint: MQTT服务器地址
port: 通常为1883（非加密）或8883（TLS加密）
client_id: 客户端唯一标识
qos: 消息质量等级（0-2）
keep_alive: 心跳间隔（秒）

设备激活配置

激活版本说明

json

{
  "SYSTEM_OPTIONS": {
    "NETWORK": {
      "ACTIVATION_VERSION": "v2",
      "AUTHORIZATION_URL": "https://xiaozhi.me/"
    }
  }
}

版本差异：

v1: 简化激活流程，无需验证码
v2: 完整激活流程，包含验证码验证

设备身份文件 (efuse.json)

json

{
  "serial_number": "SN-E3E1F618-902e16dbe116",
  "hmac_key": "b5bf012dd518080532f928b70ed958799f34f9224e80dd4128795a70a5baca24",
  "activation_status": false,
  "mac_address": "00:11:22:33:44:55",
  "device_fingerprint": {
    "cpu_info": "...",
    "memory_info": "...",
    "disk_info": "..."
  }
}

字段说明：

serial_number: 设备序列号
hmac_key: 设备验证密钥
activation_status: 激活状态
mac_address: 设备MAC地址
device_fingerprint: 设备指纹信息

配置管理实用技巧

1. 查找配置文件位置

bash

# macOS
open ~/Library/Application\ Support/py-xiaozhi/config/

# Linux
xdg-open ~/.local/share/py-xiaozhi/config/

# Windows (在文件资源管理器地址栏输入)
%LOCALAPPDATA%\py-xiaozhi\config

2. 配置文件生成

bash

# 首次运行自动生成配置
python main.py

# 重新生成默认配置（删除用户数据目录下的配置文件）
# macOS/Linux 示例：
rm ~/Library/Application\ Support/py-xiaozhi/config/config.json
python main.py

3. 配置备份与恢复

bash

# macOS/Linux 示例：
CONFIG_DIR=~/Library/Application\ Support/py-xiaozhi/config

# 备份配置
cp "$CONFIG_DIR/config.json" "$CONFIG_DIR/config.json.bak"

# 恢复配置
cp "$CONFIG_DIR/config.json.bak" "$CONFIG_DIR/config.json"

配置文件模板

完整配置示例

json

{
  "SYSTEM_OPTIONS": {
    "CLIENT_ID": "12345678-1234-1234-1234-123456789012",
    "DEVICE_ID": "00:11:22:33:44:55",
    "WINDOW_SIZE_MODE": "screen_100",
    "NETWORK": {
      "OTA_VERSION_URL": "https://api.tenclass.net/xiaozhi/ota/",
      "WEBSOCKET_URL": "wss://api.tenclass.net/xiaozhi/v1/",
      "WEBSOCKET_ACCESS_TOKEN": "your_access_token",
      "MQTT_INFO": {
        "endpoint": "mqtt.server.com",
        "client_id": "xiaozhi_client",
        "username": "your_username",
        "password": "your_password",
        "publish_topic": "xiaozhi/commands",
        "subscribe_topic": "xiaozhi/responses"
      },
      "ACTIVATION_VERSION": "v2",
      "AUTHORIZATION_URL": "https://xiaozhi.me/"
    }
  },
  "WAKE_WORD_OPTIONS": {
    "USE_WAKE_WORD": true,
    "MODEL_PATH": "models/zh",
    "NUM_THREADS": 4,
    "PROVIDER": "cpu",
    "MAX_ACTIVE_PATHS": 2,
    "KEYWORDS_SCORE": 1.8,
    "KEYWORDS_THRESHOLD": 0.2,
    "NUM_TRAILING_BLANKS": 1,
    "WAKE_WORD": "你好小智",
    "WAKE_WORD_LANG": "zh"
  },
  "CAMERA": {
    "backend": "auto",
    "device": "",
    "camera_index": 0,
    "frame_width": 640,
    "frame_height": 480,
    "fps": 30,
    "warm_up_frames": 5,
    "Local_VL_url": "https://open.bigmodel.cn/api/paas/v4/",
    "VLapi_key": "your_zhipu_api_key",
    "models": "glm-4v-plus"
  },
  "SHORTCUTS": {
    "ENABLED": true,
    "MANUAL_PRESS": {
      "modifier": "ctrl",
      "key": "j",
      "description": "按住说话"
    },
    "AUTO_TOGGLE": {
      "modifier": "ctrl",
      "key": "k",
      "description": "自动对话"
    },
    "ABORT": {
      "modifier": "ctrl",
      "key": "q",
      "description": "中断对话"
    },
    "MODE_TOGGLE": {
      "modifier": "ctrl",
      "key": "m",
      "description": "切换模式"
    },
    "WINDOW_TOGGLE": {
      "modifier": "ctrl",
      "key": "w",
      "description": "显示/隐藏窗口"
    }
  },
  "AEC_OPTIONS": {
    "ENABLED": false,
    "MUSIC_PARALLEL": true,
    "FRAME_DELAY": 3,
    "ENABLE_PREPROCESS": true
  },
  "AUDIO_DEVICES": {
    "input_device_id": null,
    "input_device_name": null,
    "output_device_id": null,
    "output_device_name": null,
    "input_sample_rate": null,
    "output_sample_rate": null,
    "input_channels": 1,
    "output_channels": 2,
    "opus_output_sample_rate": 24000,
    "frame_duration": 20
  },
  "LOGGING": {
    "LEVEL": "INFO",
    "FORMAT_TYPE": "colored",
    "ENABLE_CONSOLE": true,
    "ENABLE_FILE": true,
    "ENABLE_ERROR_FILE": true,
    "ENABLE_JSON_FILE": false,
    "ENABLE_ASYNC": false,
    "ENABLE_SENSITIVE_FILTER": true,
    "MAX_BYTES": 10485760,
    "BACKUP_COUNT": 30,
    "ROTATION_WHEN": "midnight",
    "THIRD_PARTY_LEVELS": {
      "urllib3": "WARNING",
      "websockets": "WARNING",
      "asyncio": "WARNING",
      "paho": "WARNING",
      "PIL": "WARNING"
    }
  }
}

可写目录自定义（缓存 / 日志 / 音乐）

配置文件仍在用户数据目录下的 config/config.json（可用 XIAOZHI_DATA_DIR 改变整个数据根）。

缓存、日志、音乐缓存、唤醒词目录可通过环境变量或配置 PATHS 自定义。修改并保存后，下次启动会将旧目录中尚未出现在新目录的文件复制到新路径（不删除旧目录）。

用途	环境变量	配置项	默认
用户数据根（含 config）	`XIAOZHI_DATA_DIR`	—	系统用户数据目录/`py-xiaozhi`
缓存	`XIAOZHI_CACHE_DIR`	`PATHS.CACHE_DIR`	`{数据根}/cache`
日志	`XIAOZHI_LOG_DIR`	`PATHS.LOG_DIR`	`{数据根}/logs`
音乐缓存	`XIAOZHI_MUSIC_CACHE_DIR`	`PATHS.MUSIC_CACHE_DIR`	`{缓存}/music`
唤醒词	`XIAOZHI_KEYWORDS_DIR`	`PATHS.KEYWORDS_DIR`	`{数据根}/keywords`
MCP 插件	—	`MCP_PLUGINS.DIR`	`{数据根}/mcp_plugins`

优先级：环境变量 > 配置 PATHS > 默认。

json

"PATHS": {
  "CACHE_DIR": "/Volumes/Data/xiaozhi-cache",
  "LOG_DIR": "/Volumes/Data/xiaozhi-logs",
  "MUSIC_CACHE_DIR": null,
  "KEYWORDS_DIR": null
}

配置说明 ​

配置系统概览 ​

配置文件位置 ​

配置层次结构 ​

配置访问方式 ​

系统配置 (SYSTEM_OPTIONS) ​

基础系统配置 ​

配置项说明 ​

服务端配置更换 ​

更换自部署服务端 ​

配置自动更新机制 ​

禁用配置自动更新 ​

唤醒词配置 (WAKE_WORD_OPTIONS) ​

Sherpa-ONNX 语音唤醒设置 ​

配置项说明 ​

模型文件结构 ​

自定义唤醒词 ​

性能调优 ​

速度优先配置 ​

准确性优先配置 ​

摄像头配置 (CAMERA) ​

视觉识别设置 ​

配置项说明 ​

平台说明 ​

摄像头测试 ​

快捷键配置 (SHORTCUTS) ​

全局快捷键设置 ​

快捷键说明 ​

声学回声消除配置 (AEC_OPTIONS) ​

AEC音频处理设置 ​

配置项说明 ​

AEC功能说明 ​

AEC功能测试 ​

音频设备配置 (AUDIO_DEVICES) ​

音频输入输出设置 ​

配置项说明 ​

采样率与帧时长说明 ​

音频设备自动检测 ​

运行中热刷新（蓝牙等） ​

日志配置 (LOGGING) ​

日志系统设置 ​

配置项说明 ​

日志级别说明 ​

开发调试配置 ​

生产环境配置 ​

协议配置详解 ​

WebSocket 协议配置 ​

MQTT 协议配置 ​

设备激活配置 ​

激活版本说明 ​

设备身份文件 (efuse.json) ​

配置管理实用技巧 ​

1. 查找配置文件位置 ​

2. 配置文件生成 ​

3. 配置备份与恢复 ​

配置文件模板 ​

完整配置示例 ​

可写目录自定义（缓存 / 日志 / 音乐） ​

配置说明

配置系统概览

配置文件位置

配置层次结构

配置访问方式

系统配置 (SYSTEM_OPTIONS)

基础系统配置

配置项说明

服务端配置更换

更换自部署服务端

配置自动更新机制

禁用配置自动更新

唤醒词配置 (WAKE_WORD_OPTIONS)

Sherpa-ONNX 语音唤醒设置

配置项说明

模型文件结构

自定义唤醒词

性能调优

速度优先配置

准确性优先配置

摄像头配置 (CAMERA)

视觉识别设置

配置项说明

平台说明

摄像头测试

快捷键配置 (SHORTCUTS)

全局快捷键设置

快捷键说明

声学回声消除配置 (AEC_OPTIONS)

AEC音频处理设置

配置项说明

AEC功能说明

AEC功能测试

音频设备配置 (AUDIO_DEVICES)

音频输入输出设置

配置项说明

采样率与帧时长说明

音频设备自动检测

运行中热刷新（蓝牙等）

日志配置 (LOGGING)

日志系统设置

配置项说明

日志级别说明

开发调试配置

生产环境配置

协议配置详解

WebSocket 协议配置

MQTT 协议配置

设备激活配置

激活版本说明

设备身份文件 (efuse.json)

配置管理实用技巧

1. 查找配置文件位置

2. 配置文件生成

3. 配置备份与恢复

配置文件模板

完整配置示例

可写目录自定义（缓存 / 日志 / 音乐）