配置概述 Config
ChatAI 插件提供灵活的配置系统，支持全局配置、群组配置和用户配置三级覆盖。本文对照 config 默认配置（config/config.js 的 getDefaultConfig()，对应提交 5351e7d7）编写。
配置层级
优先级说明
低层级配置会覆盖高层级配置。例如：群组配置会覆盖全局配置中的同名项。
配置方式
Web 管理面板（推荐）
推荐方式
Web 面板提供可视化配置界面，修改实时生效，无需重启。
txt
#ai管理面板（命令注册见 apps/Management.js。）
配置文件
配置文件位于：
plugins/chatai-plugin/config/config.yaml注意
直接修改配置文件后需要执行 #ai重载配置 或重启生效。
文件加载时先执行 migrateTriggerAccessLists（旧版触发黑白名单迁移），再与默认配置深合并并保存，因此新增默认键会自动补入文件。
配置页面
| 模块 | 说明 | 文档 | 重要度 |
|---|---|---|---|
| 基础配置 | basic / admin / llm（默认模型、场景模型、备选） | 基础配置 | ⭐⭐⭐ |
| 渠道配置 | channels 数组字段、Key 策略、备选模型 | 渠道配置 | ⭐⭐⭐ |
| 渠道高级配置 | channel 端点 / 认证 / 图片 / 超时 / 重试 / 配额 / 覆盖 | 渠道高级配置 | ⭐⭐ |
| 模型配置 | 模型参数与选型说明 | 模型配置 | ⭐⭐⭐ |
| 触发配置 | 私聊/群聊触发与黑白名单 | 触发配置 | ⭐⭐ |
| 上下文配置 | context / 自动摘要 / 压缩 | 上下文配置 | ⭐⭐ |
| 人格隔离配置 | personality / presets | 人格隔离配置 | ⭐⭐ |
| 工具组配置 | toolGroups / skills.yaml 分组与调度 | 工具组配置 | ⭐ |
| 记忆配置 | memory / 群聊上下文采集 | 记忆配置 | ⭐⭐ |
| MCP 配置 | mcp 超时与 Server 暴露、builtinTools | MCP 配置 | ⭐⭐ |
| 代理配置 | proxy profiles 与 scopes | 代理配置 | ⭐ |
| 前端配置 | Web 面板使用与登录 | 前端配置 | ⭐ |
| 功能配置 | features 各事件段、AI 绘图、tools 工具调用 | 功能配置 | ⭐⭐ |
| 伪人 / 主动聊天 / 游戏 / 会话追踪 | bym / proactiveChat / game / conversationTracking | 伪人配置 | ⭐ |
| 错误通知 | errorNotify 运维告警 | 错误通知 | ⭐ |
| 思考 / 渲染 / 输出优化 | thinking / render / output / streaming / loadBalancing / probe / voice / web / images / redis / update / bilibili | 思考 / 渲染 / 输出优化配置 | ⭐⭐ |
| 高级配置 | 层级总览、热重载、安全提示 | 高级配置 | ⭐⭐ |
顶层配置段索引
config/config.js 默认配置的全部顶层键与对应文档：
| 顶层键 | 文档 | 顶层键 | 文档 |
|---|---|---|---|
basic | 基础配置 | admin | 基础配置 |
llm | 基础配置 | bym | 伪人配置 |
game | 伪人配置 | proactiveChat | 伪人配置 |
conversationTracking | 伪人配置 | tools | 功能配置 |
toolGroups | 工具组配置 | builtinTools | MCP 配置 |
channels | 渠道配置 | mcp | MCP 配置 |
bilibili | 共享高级配置 | redis | 共享高级配置 |
images | 共享高级配置 | web | 共享高级配置 |
update | 共享高级配置 | proxy | 代理配置 |
context | 上下文配置 | memory | 记忆配置 |
presets | 人格隔离配置 | personality | 人格隔离配置 |
loadBalancing | 共享高级配置 | thinking | 共享高级配置 |
render | 共享高级配置 | output | 共享高级配置 |
features | 功能配置 | voice | 共享高级配置 |
streaming | 共享高级配置 | probe | 共享高级配置 |
trigger | 触发配置 | errorNotify（非默认段） | 错误通知 |
核心配置项速查
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
basic.commandPrefix | string | '#ai' | 命令前缀 |
basic.debug | boolean | false | 调试模式 |
basic.showThinkingMessage | boolean | true | 是否发送「思考中...」提示 |
basic.quoteReply | boolean | true | 回复时引用触发消息 |
llm.defaultModel | string | 'qwen/qwen3-next-80b-a3b-instruct' | 默认模型 |
trigger.private.mode | string | 'prefix' | 私聊触发模式（'always' / 'prefix' / 'off'） |
trigger.group.at | boolean | true | @ 机器人触发 |
context.maxMessages | number | 20 | 最大上下文消息数 |
context.maxTokens | number | 4000 | 最大上下文 Token 数 |
memory.enabled | boolean | false | 启用长期记忆 |
环境变量
说明
插件配置系统未核实到对 OPENAI_API_KEY 等外部环境变量名或 ${VAR} 形式的显式解引用逻辑。安全实践要求敏感信息（渠道 apiKey / apiKeys、mcp.server.apiKey、probe.secretKey 等）以本地配置管理，避免提交公开仓库。
配置热重载
修改配置后，无需重启即可生效：
txt
#ai重载配置热重载范围
大部分配置支持热重载，但以下配置需要重启：
- Web 服务端口（
web.port）。端口占用时服务端会自动尝试切换（src/services/webServer.js）
配置备份
重要
定期备份配置文件，避免配置丢失。
bash
cp config/config.yaml config/config.yaml.bakpowershell
copy config\config.yaml config\config.yaml.bak配置迁移
自动迁移
从旧版本升级时，插件会自动合并新增配置项，保留已有配置（mergeConfig 深合并，对象按键合并，数组与标量覆盖；触发黑白名单另由 migrateTriggerAccessLists 迁移到 trigger.private / trigger.group）。
下一步
| 文档 | 说明 | 推荐阅读 |
|---|---|---|
| 基础配置 | basic / admin / llm 核心设置 | ⭐⭐⭐ |
| 渠道配置 | 配置 API 渠道 | ⭐⭐⭐ |
| 模型配置 | 模型参数调优 | ⭐⭐ |
| 高级配置 | 配置层级总览与安全提示 | ⭐⭐ |