qq-mode-console

安装与配置

npm install        # 安装依赖（postinstall 会自动修补 @snowluma/sdk 的 ESM 打包 bug）

复制 config.example.json 为 config.json 后编辑：

Windows CMD 用户请用：copy config.example.json config.json

⚠️ 真实 config.json 与 state/ 不会进入公开仓库，仓库只提供脱敏的 config.example.json 模板。

字段	说明
dsh.baseUrl	DSH Web 地址，默认 http://127.0.0.1:3080
dsh.provider / dsh.model / dsh.reasoningEffort	DSH 会话使用的模型/推理强度；若你的 DSH 没有示例中的模型，改成 DSH 设置页里可用的模型即可（选择失败只打日志，不阻塞启动）
dsh.authToken	DSH launch token（进程启动凭据）。通常应留空：留空时桥接用 ~/.dsh/.credentials.yaml 里持久化的签名密钥离线铸造会话 Cookie，不依赖任何进程期状态（DSH 0.1.7 起启动 token 只存在于内存、日志里那条是上一个进程的陈旧值，换 Cookie 只会 401）。只有显式填了才会优先走 token 交换
dsh.authHeader / dsh.authPrefix	保留字段，当前新版 DSH 链路使用 Cookie 交换，不再直接发送该鉴权头
snowluma.wsUrl	SnowLuma OneBot WebSocket 地址（如 ws://127.0.0.1:3001）
snowluma.httpUrl	OneBot HTTP API 地址（如 http://127.0.0.1:3000）；不要填 WebSocket 端口，否则会报 HTTP 426
snowluma.accessToken	OneBot accessToken，未配置留空
snowluma.followDiscoveredEndpoint	默认 true。换 QQ 账号后 token 与端口都会变，桥接会自愈：重新发现并跟随 SnowLuma 的端点（同时写回 config.json）。想跑第二个实例 / 指向另一份 SnowLuma 安装（多账号、测试）时设为 false —— 那时只自愈 token，绝不动 URL，也不写回 URL。详见「已知行为」
snowluma.silenceWarnMs	上游静默告警阈值（毫秒），默认 600000（10 分钟）。已连接但这么久没收到任何事件包（含心跳）时打警告；这只是提示，不确定性的判断交给 good
snowluma.launcherPath / homeDir	SnowLuma 安装目录（用于 token/端点自发现）。⚠️ 桥接不会启动或停止 SnowLuma（见 LICENSE）
agentPreset	QQ 会话使用的 DSH agent preset，默认 qq-chat（改性格见下文）
socialV2.agentPreset	reserved2 模式使用的 DSH agent preset，默认 qq-chat-v2
socialV2.initialPromptMaxChars	会话「初始提示词」（控制台为某个群/私聊预写的环境说明）的字数上限，默认 2000，允许 100~8000。越界值会在启动时收敛并保持原文件不动
socialV2.media	图片/表情的上限：maxBytes（单条消息总字节，默认 8MB）、maxPixels（单张像素，默认 64MP）、maxCount（单条最多处理几张，默认 5）。越界值启动时收敛
webSearch.provider	联网搜索后端：auto（默认，优先 DeepSeek、失败回退 Bing）/ deepseek（仅 DeepSeek，无凭据时报错）/ bing
webSearch.apiKeyEnv / apiKey	搜索凭据的环境变量名（默认 DEEPSEEK_API_KEY）/ 直接写死 key（不推荐）。都不设置时读 DSH 的 $DSH_HOME/.credentials.yaml 里同名 ref
webSearch.baseURL / model / maxUses / maxResults	搜索端点（默认 https://api.deepseek.com/anthropic/v1，必须 https 且解析到公网）、模型（默认 deepseek-v4-flash）、单次搜索最多用几次工具、返回条数上限
workspaceTitle	QQ 会话在 DSH 界面中的归组名称，默认「QQ 聊天」
allow.private / allow.groups	白名单（QQ 号/群号数组）；留空且 allowAllWhenEmpty: true 时放行全部
deny.*	黑名单，优先于白名单
ackMessage	消息投递后的立即回复，空字符串关闭
sendDelayMs	QQ 连续发送间隔，防止触发频率限制
consolePort	本地控制台端口，默认 3100
consoleToken	控制台访问令牌；留空时启动自动生成并保存到 state/console-token

⚠️ allowAllWhenEmpty: true 表示「白名单没填就全部放行」——把 agent 接入 QQ 等于把账号控制权交给了模型，建议先填白名单。

DSH 端安装（必做：装 preset + 挂 MCP）

桥接和控制台能跑起来还不够，DSH 端还需要安装两个聊天 preset（qq-chat / qq-chat-v2）并挂载 MCP。单机新装同样必须执行这一步（不是只有「另一台设备」才需要），装完还要重启 DSH：

node scripts/setup-dsh.mjs

全新环境下脚本会把 DSH 默认模式设为 reserved2（二代仿真），并创建本地 state/mode.json 兜底；这样 AI 使用 qq_send_message 等工具收发消息时，DSH 会自动使用 qq-chat-v2 模式。如果本机已存在旧的 state/mode.json 或 DSH 设置值，脚本会保留不覆盖。之后可在桥接控制台（默认 http://127.0.0.1:3100）顶部按钮切换模式，控制台会同时写入 DSH 设置与本地兜底文件。

详细步骤见 docs/guides/DSH_SETUP.md。