QQ 远程控制桥 TomoyoNatsume/dsh-qq-bridge

dsh-qq-bridge · 用 QQ 远程控制 DSH

更新 · 是什么 · 功能 · 快速开始 · 配置 · 安全 · 停止服务 · 常见问题 · 许可与致谢

想随时随地操控鲸鱼娘帮你干活？
把任务丢给鲸鱼娘就转头刷手机忘记盯进度？

把 DSH 绑定到 QQ：出门在外也能发任务，Web 对话完成后立刻提醒刷手机的你。
无需开放外部端口，无需配置公网地址~ 零安全风险~

QQ 远程控制 · 智能体回复提醒 · NapCat / 官方 QQ Bot 双路径

更新

v1.0.0 更新：支持 Web UI 中配置，告别繁琐的 CLI 配置

直接在 QQ 里对智能体说「请在 2026 年 9 月 1 号中午 12 点提醒我提交报告」，插件会创建一次性定时任务，到点后在同一个 QQ 会话触发智能体并主动发回提醒。

v0.4.0 更新：支持定时提示功能!

直接在 QQ 里对智能体说「请在 2026 年 9 月 1 号中午 12 点提醒我提交报告」，插件会创建一次性定时任务，到点后在同一个 QQ 会话触发智能体并主动发回提醒。

是什么

- 控制鲸鱼娘：

- web 会话完成提醒：

dsh-qq-bridge 是一个 DeepSeek Harness（DSH）Web 配置档插件，用来把 QQ 消息转成 DSH 智能体会话请求，再把智能体回复发回 QQ。最常用的链路是：

QQ 发送消息 -> NapCat / OneBot -> dsh-qq-bridge -> DSH Agent -> QQ 回复

默认推荐走 NapCat / OneBot：用一个 QQ 号登录 NapCat，然后从手机 QQ 给自己发消息，不需要额外准备机器人小号。也支持双号模式：一个 QQ 登录 NapCat，另一个 QQ 负责发指令。

如果不想使用 NapCat，也可以选择 腾讯官方 QQ 开放平台机器人。官方模式不需要扫码登录 NapCat，但需要在 QQ 开放平台创建机器人，并提供 AppID、AppSecret，再通过一次性 pair 配对写入管理员 openid。

当前不支持通过 QQ 的「我的电脑」会话完整交互；这类消息可以被日志捕获，但回复会回到当前 QQ 自身，链路不完整。项目背景和架构说明见 docs/project-overview.md，使用导图见 docs/usage-guide.html。

功能

- QQ 遥控智能体：白名单用户可直接在 QQ 里发任务，插件会转成 DSH live session，并把最终回复发回 QQ。
- 工作区、模型、权限和会话控制：支持 /dir、/new-session、/models、/model、/reasoningEff、/permission 等 bridge 侧指令，也支持用自然语言完成常用切换。
- 定时提醒和 memo：支持一次性定时任务和备忘记录，数据通过 DSH storageDomain 持久化。
- Web 会话完成提醒：非 QQ Web 会话结束后，可主动给管理员 QQ 发提醒；QQ 发起的会话只返回实际智能体回复。
- 双接入路径：默认推荐 NapCat / OneBot，本机个人使用更方便；也可切换腾讯官方 QQ Bot。

快速开始

当前自动安装向导只适配 Linux / WSL2 环境；原生 Windows 暂未适配。Windows 用户建议先在 WSL2 中使用。

系统要求

- 已安装 DSH / DeepSeek Harness，且 dsh web 可正常启动。
- Linux / WSL2 环境。Node.js 20+。
- 选择 NapCat 路径时，需要先安装 NapCat，并且需要一个可扫码登录的 QQ 号。
- 选择官方 QQ Bot 路径时，需要 QQ 开放平台机器人 AppID 和 AppSecret。

三步上手

1. 安装插件（推荐 npm 稳定版）：

bash
pnpm dsh plugin --profile web add @yachangchang/dsh-qq-bridge

也可以直接从 GitHub 安装当前仓库：

bash
pnpm dsh plugin --profile web add github:TomoyoNatsume/dsh-qq-bridge

插件会作为 DSH bundle 写入 dsh.profile.bundles。刚安装时默认 enabled: false，不会连接 QQ，也不会启动 bridge。

2. 启动 dsh web，进入左下角“设置” → QQ bridge。两种模式均先显示“通用配置”卡片，其中的模型、工作目录、访问模式等修改自动保存；卡片后切换接入方式，再显示 NapCat 或官方 QQ Bot 配置卡片。平台卡片不自动保存：NapCat 点击“启动/重启Napcat”，官方 QQ Bot 点击“保存并启动”，校验后提交并启用。进入 NapCat 设置页时会自动触发一次状态检测，也可点击“刷新状态”重新检测；卡片标题旁依次异步检测安装、启动、登录三个状态，并显示“正在检测”：安装通过 PATH 查找 napcat 指令，启动通过 napcat status 中的运行 QQ 判断，登录通过给运行 QQ 自发消息并回读验证；官方模式不显示状态 tag。

3. 保存成功后，在 QQ 里发送：

text
ping

如果发送 ping 后没反应，请运行 napcat log <你的QQ号>，或查看 ~/Napcat/log/napcat_<你的QQ号>.log 确认 NapCat 是否已经扫码登录。

NapCat 安装

选择 NapCat 路径前，本机需要有 napcat 命令。

默认：安装当前最新版

Linux / WSL2 推荐先使用 NapCat 官方 Rootless 安装器： bash
cd ~
curl -o napcat.sh https://raw.githubusercontent.com/NapNeko/NapCat-Installer/main/script/install.sh
bash napcat.sh --docker n --cli y

安装后确认命令可用： bash napcat help

只需要安装 NapCat CLI，不需要自己先启动 QQ 后台。设置页填写 NapCat 登录 QQ 后点击“启动/重启Napcat”，目标 QQ 未运行时插件会先执行 napcat stop 顶掉现有 NapCat 实例，再按这个 QQ 号执行 napcat start <QQ>。首次使用时请打开 ~/Napcat/log/napcat_<你的QQ号>.log 或执行 napcat log <你的QQ号> 查看日志并扫码登陆；NapCat 生成 OneBot 配置文件后，插件会继续写入正向 WebSocket 配置。

NapCat 扫码登录时请打开 setup 打印的日志。日志里可能有多个二维码，请拉到最后一个二维码扫码；如果二维码过期，在 setup 里选择“二维码过期”，它会重启 NapCat 生成新的登录请求。

遇到“强制下线”：固定版本修复方案

这不是默认安装方式。只有在正常安装后频繁出现 [KickedOffLine]、扫码后仍很快被强制下线时，再尝试下面的已验证组合：

- QQ 3.2.21-42086
- NapCat 4.15.19
- 全新 QQ profile（不复用旧的 ~/.config/QQ）
- Rootless NapCat 目录 ~/Napcat

腾讯原 CDN 已删除 QQ 3.2.21-42086 的独立 DEB/RPM。项目提供了一个修复脚本，它会直接从 NapCat v4.15.19 的固定镜像仓库下载并校验所需文件，不需要安装 Docker，也不会启动 Docker 容器。修复后的 QQ/NapCat 仍然是本机 Rootless 运行。

修复脚本会停止旧 NapCat，将 ~/.config/QQ 和 ~/Napcat 移入带时间戳的备份目录，然后全新安装固定版本。QQ 会退出登录，安装后需要重新扫码。脚本已在 Linux x86_64 验证。

如果已经 clone 了本项目，在项目根目录执行： bash bash scripts/reinstall-napcat-4.15.19.sh

没有 clone 项目时，可以单独下载脚本后执行： bash
curl -fLO \
https://raw.githubusercontent.com/TomoyoNatsume/dsh-qq-bridge/main/scripts/reinstall-napcat-4.15.19.sh
bash reinstall-napcat-4.15.19.sh

脚本会在替换旧安装前显示将要执行的操作并要求确认。完成后按提示启动、扫码和验证： bash napcat start <你的QQ号> napcat log <你的QQ号> napcat status <你的QQ号>

napcat status <你的QQ号> 应能识别正在运行的实例。然后回到 DSH Web 设置页完成 OneBot 配置。

保持这套固定组合时，不要执行 napcat update 或 napcat rebuild，它们会替换 QQ/NapCat 版本。如需升级，先备份 ~/.config/QQ 和 ~/Napcat。

设置 / setup 当前版本由设置页负责写入 bridge 配置并同步 QQ 专用 preset；也可以手动进入 ~/.dsh/profiles/web/ 执行 pnpm exec dsh-qq-bridge setup，通过 CLI 进行旧版 setup。

设置页具体说明：
- 选择 NapCat / OneBot 或 腾讯官方 QQ Bot。两种不同路径，前者为社区插件连接 QQ，非官方，功能强、限制少、通用性广，但小号容易被强制下线。后者为官方开放平台提供的 Bot，对接更稳，但是功能较少。
- NapCat 路径需要输入 QQ 号（用来登录在 DSH 服务上、负责接收消息的号）、选择模型、单号/双号模式。单号模式下自己发送消息，自己接收（在 QQ 的好友列表里可以找到自己）。双号模式下两个号互相通信，需要输入发送端 QQ 号。
- 可勾选「掉线后自动重启并提示扫码」。自动恢复独立监听 NapCat 日志（单号、双号均支持），只处理启用后的新增 [KickedOffLine] 下线通知。10 秒后执行 napcat restart <登录QQ>，用户打开 NapCat WebUI 或执行 napcat log <登录QQ> 查看二维码并扫码。插件不再读取旧版密码设置，启动/重启时会移除继承的密码回退环境变量；不清除 QQ 本地登录数据，仍有效的快速登录可由 NapCat 自行复用。
- 等待扫码期间不会反复重启。10 分钟最多自动重启一次，每小时最多三次；重启失败时提示检查本机 CLI。扫码后收到 QQ 消息会恢复监控。请勿与旧的 scripts/keep-napcat-alive.sh 同时运行。本功能管理本机 NapCat CLI，不管理远程或 Docker 服务。
- 账号与设备排查及本机证据见 NapCat 掉线排查记录。
- NapCat 路径会检查 napcat status <QQ>；目标 QQ 未启动时会先执行 napcat stop 顶掉现有 NapCat 实例，再自动执行 napcat start <QQ>。用户只需先安装 NapCat CLI，不必手动启动 QQ 后台。
- NapCat 路径会自动配置 OneBot 正向 WebSocket：127.0.0.1:3001。如果尚未找到 OneBot 配置文件，设置页会提示打开 NapCat 日志或执行 napcat log <QQ> 扫码登陆；如果配置成功，设置页会提示继续查看日志，确保已经扫码登陆。
- 官方 QQ Bot 路径会要求先创建机器人，输入 AppID、AppSecret、沙箱开关，并通过 pair 自动配置 adminOpenId。

如果你是从旧版 setup 写 profile 的方式迁移到 bundle，新版启动时会自动清理 ~/.dsh/profiles/web/cordis.patch.yml 里旧的 id: dsh-qq-bridge 插入项，并在同目录留下 cordis.patch.yml.dsh-qq-bridge.bak 备份，避免 bundle 和手写 profile 同时挂载同一个插件。

验证

从手机 QQ 发送： text ping

成功后再试： text 当前工作目录是什么列出当前工作目录下的目录和文件 /dir /home/xxx/project /models /model deepseek-v4-pro /reasoningEff high /permission workspace-write /new-session 帮我把工作目录改到 /home/xxx/project 请在 2026 年 9 月 1 号中午 12 点提醒我提交报告

如果是自己前台启动的 DSH web，启动成功后会看到类似界面：

配置

推荐在 DSH Web 左下角「设置」里的 QQ bridge 页面修改配置并保存。通过设置页保存时，NapCat 模式会写入本机 OneBot 配置，当前 DSH Web 进程会按新配置启动或重启 bridge。

如果要手动排查，bundle 配置会进入 DSH profile 的 bundles 配置；旧版 setup 仍会写这个文件： text ~/.dsh/profiles/web/cordis.patch.yml

改完后重启 dsh web。重启 DSH web 时不需要再导出 DSH_QQ_TOKEN 或 DSH_PERMISSION_MODE；setup 或设置页已经把必要配置写入本机配置。

选择 QQ 接入方式

NapCat / OneBot

默认推荐走 NapCat / OneBot，适合个人本机使用。setup 会检查 napcat 命令、启动状态和登录日志，自动配置 OneBot 正向 WebSocket 到 127.0.0.1:3001，并创建或复用 OneBot access token。

支持两种用法：

- 双号模式：一个 QQ 号登录 DSH，监听消息；另一个 QQ 号给 DSH 发送指令。推荐新用户直接用这个。
- 单号模式：同一个 QQ 登录 NapCat，并从手机 QQ 给自己发消息。

双号模式下，登录 DSH 的账号不建议用不常用小号，因为不常用的号登录可能会被腾讯服务端 kill 掉。

单号模式下，可以收到 Agent 完成自动提醒，但可能无法收到消息提示。

配置示例： yaml platform: napcat napcat: wsUrl: ws://127.0.0.1:3001 token: "<NapCat OneBot access token>"

已移除自发消息保活及相关设置，旧版 selfKeepAlive 配置不再生效。设置页和重启恢复检测只查询 OneBot 的账号信息和在线状态，不发送 QQ 探测消息；接口返回在线不等同于已经验证消息投递。

每条保活消息都会附带唯一 uid。Bridge 最多等待 OneBot 动作响应 2 秒；连续 3 次超时会在 DSH 日志中将 NapCat 登录状态标记为 logged-out，任意一次成功则立即标记或恢复为 logged-in。

腾讯官方 QQ Bot

官方路径适合想用开放平台机器人账号的用户。需要先到 QQ 开放平台机器人控制台 创建机器人，然后输入 AppID、AppSecret 和沙箱开关。

第一次配置时不需要手动找 adminOpenId：setup 会临时连接 QQBot 网关，生成一次性 pair ，你用管理员 QQ 发给机器人后，插件会自动读取 sender openid、回复「配对成功」，并写入 official.adminOpenId。
由于腾讯开放平台规则限制，当前插件若走 QQ Bot 路径，则不支持 Agent 完成自动提醒 功能。

官方 QQ Bot 的主动提醒有额度限制。插件在官方模式下默认关闭 notifications.agentReply.enabled，避免触发 40034122 / 召回消息已达区间上限。

切到腾讯官方 QQ Bot 时，推荐重新运行 setup。手动配置示例： yaml platform: official official: appId: "<QQ 开放平台 AppID>" appSecret: "<QQ 开放平台 AppSecret>" adminOpenId: "<管理员 openid>"
allowlistOpenIds: []
sandbox: false
access:
adminQq: 0
allowlist: []
commandPrefix: ""
mode: whitelist
notifications:
agentReply:
enabled: false

adminOpenId 是「你的 QQ 用户在这个机器人应用下的 openid」，不是 QQ 号，也不是 AppID。第一次不知道它时，用 setup 自动配对最稳。

更改模型

修改 agent.provider 和 agent.model： yaml agent: provider: deepseek-official model: deepseek-v4-pro cwd: "~" preset: dsh-qq-bridge ackMessage: 收到，正在处理...

- provider：DSH 里已配置好的模型提供方。
- model：该 provider 下的模型 id。
- cwd：QQ Agent 默认工作目录，默认是 ~；/dir <目录> 会覆盖当前 QQ 会话的后续 session 目录。
- preset：QQ 会话使用的 DSH agent preset。setup 会安装 dsh-qq-bridge 专用 preset；普通 Web 会话不选它就不会看到 QQ 回复风格 skill。

更改确认消息和超时

收到有效 QQ 指令后，插件会先回复 agent.ackMessage。设为空字符串 "" 可以关闭确认消息： yaml agent: ackMessage: 收到，正在处理...

默认情况下，QQ 对话不会限制 Agent 等待时间，会一直等到本轮 DSH Agent 完成。需要保留超时保护时，可手动设置 timeoutMs 和 timeoutMessage： yaml agent: timeoutMs: 120000 timeoutMessage: agent 无响应，请稍后重试。

手动 YAML 中的 timeoutMs 是内部毫秒字段。设置 timeoutMs 后，超时会回复 timeoutMessage。

QQ 回复风格 Skill

setup 会同步一个 QQ 专用 preset 到： text ~/.dsh/.agent-presets/dsh-qq-bridge

这个 preset 挂载随附的回复风格 skill： text ~/.dsh/.agent-presets/dsh-qq-bridge/skills/qq-session-reply-style/SKILL.md ~/.dsh/.agent-presets/dsh-qq-bridge/skills/qq-session-reply-style/references/reply-style.md

默认规则：

- 先给结论。
- 回复尽量简明扼要。
- 不用 Markdown 风格，用纯文本，可以多用 emoji。

插件只会在 QQ 会话的第 1、30、60... 个 Agent 回合主动发送 /qq-session-reply-style，让 DSH 的 skill 工具加载入口文件并按模块读取回复风格；其它 QQ 回合只附加一句很短的临时风格标记，避免每轮塞入大段 prompt。

如果你要改 QQ 回复风格，优先改上面的 references/reply-style.md；SKILL.md 只作为入口和模块索引。注意保留「只适用于 dsh-qq-bridge QQ 会话、不要写入记忆、不要影响普通 DSH Web 会话」的限制。

如果不想要 QQ 专属回复风格，改成： yaml agent: qqReplyStyleSkill: enabled: false

更改指令前缀

修改 access.commandPrefix： yaml access: commandPrefix: /dsh

例如改成 /ai 后，QQ 里就要发送： text /ai ping

更改允许使用的人

NapCat 模式使用 QQ 号鉴权。只允许自己使用： yaml access: adminQq: <你的QQ号>
allowlist: []
mode: whitelist

允许额外 QQ： yaml access: adminQq: <你的QQ号>
allowlist: [10001, 10002]
mode: whitelist

官方 QQ Bot 模式使用 openid 鉴权： yaml platform: official official: adminOpenId: "<管理员 openid>"
allowlistOpenIds: ["<允许的用户 openid>"]
access:
adminQq: 0
allowlist: []
mode: whitelist

不建议把 mode 改成 open，除非你明确知道风险。

单号模式日志

单号模式会读取 NapCat 日志，把「自己给自己」的消息转成内部消息： yaml selfLogInput: enabled: true logPath: /home/<你的Linux用户名>/Napcat/log/napcat_<你的QQ号>.log pollIntervalMs: 1000 replayOnStart: false

如果你是「主号发给机器人小号」，通常可以关闭： yaml selfLogInput: enabled: false

Agent 回复提醒 notifications.agentReply.enabled 控制「非 QQ 会话中智能体完成一轮回复后，主动给管理员发提醒」： yaml notifications: agentReply: enabled: true

NapCat 模式默认开启；官方 QQ Bot 模式默认关闭。QQ 自身发起的对话不会再额外发送「主人，您收到一条 Agent 回复...」提醒，只保留实际 Agent 回复。

DSH 默认权限

setup 可选修改 ~/.dsh/settings.yaml： yaml permission: defaultPreset: workspace-write

可选项：

- workspace-write：较安全。智能体只能写工作区和允许的临时目录，越权操作需要网页端审批。
- danger-full-access：最省心但风险最高。智能体可直接访问本机进程权限能访问的路径，且不会弹出审批。

这里配置的是 DSH 后续新会话的默认权限；QQ 里发送 /permission <preset> 会通过 DSH 原生命令切换当前 QQ live session 的权限，不会改写 settings.yaml。
- 保持现有 settings：setup 不修改 DSH 全局默认权限。

这个默认值只影响之后新建的 Web 会话，不改变已经打开的会话。

本地回显测试

只想测试 QQ 链路、不接 DSH Agent 时，可以用本地回显模式： bash
DSH_QQ_ADMIN=<你的QQ号> \
DSH_QQ_TOKEN=<NapCat OneBot access token> \
DSH_QQ_SELF_LOG=true \
bash scripts/start-local-echo.sh

发送 ping，预期回复： text echo: ping

正式使用 pnpm dsh web 时，以 cordis.patch.yml 为准，不需要这些环境变量。

指令

QQ Agent 消息处理

在 QQ 里直接发送消息即可触发 DSH： text 当前工作目录是什么帮我把工作目录改到 /home/xxx/project 请在 2026 年 9 月 1 号中午 12 点提醒我提交报告

插件会先发送确认消息，随后把智能体的最终回复发回 QQ。默认前缀为空，白名单用户的所有消息都会进入智能体；可在 access.commandPrefix 中改回 /dsh、/ai 等前缀。

如果 QQ 消息到达时 Web UI 里有非 QQ 主会话正在运行，插件会先回复 当前 Web 会话正在运行，请稍后...，并把这条 QQ Agent 消息放入全局 FIFO 队列；等 Web 会话结束后再发送正常确认消息并执行。QQ 自己的 qq-... 会话和子代理不会触发这个阻塞，bridge 侧控制命令也会继续立即处理。

Bridge 侧指令

默认 commandPrefix: "" 时，白名单用户可直接发送下面的 bridge 侧指令；如果配置了 /dsh、/ai 等前缀，则需要写成 /dsh /dir /home/xxx/project 这种形式。bridge 侧指令不会进入智能体。

内置控制命令优先于 Agent 消息处理；命中后会独占消费，不会把控制命令误发给智能体。模型和推理等级切换会按 Web UI 的 model selection 机制在下一次模型请求生效，正在运行的请求不受影响。权限切换会调用 DSH 原生 /permission command，作用于当前 QQ 会话的 live session。

| 指令 | 示例 | 作用 | 作用范围 |
| /help | /help | 查看 bridge 侧控制指令说明。 | 当前 QQ 会话 |
| /dir <目录> | /dir /home/xxx/project | 切换当前 QQ 会话工作目录；目录存在时下一条消息会使用新的 Agent session。 | 当前 QQ 会话 |
| /models | /models | 列出当前服务商可用模型。 | 当前 QQ 会话 |
| /model <模型名> | /model deepseek-v4-pro | 切换当前 QQ 会话模型；模型名必须和 /models 列出的 id 完全一致。 | 当前 QQ 会话 |
| /reasoningEff <等级> | /reasoningEff high | 切换当前 QQ 会话推理等级。 | 当前 QQ 会话 |
| /permission | /permission | 查看当前权限 preset 和可用 preset。 | 当前 QQ live session |
| /permissions | /permissions | 同 /permission，用于查看权限 preset。 | 当前 QQ live session |
| /permission <preset> | /permission workspace-write | 调用 DSH 原生 /permission command 切换当前 live session 权限。 | 当前 QQ live session |
| /new-session | /new-session | 为当前聊天新开 Agent session；保留工作目录、模型、推理等级和 memo/timer。 | 当前 QQ 聊天 |

自然语言控制

QQ 专用 Agent preset 还支持自然语言控制。智能体会输出私有 <dsh-qq-bridge-control>...</dsh-qq-bridge-control>，插件拦截后执行，不会把控制块内容发回 QQ。
自然语言控制可切换工作目录、模型、推理等级和权限，也可新开 Agent session、创建一次性定时任务或记录 memo。定时任务和 memo 会通过 DSH storageDomain 持久化；默认 Web JSON 后端会落到 ~/.dsh/storages/dsh_qq_bridge.json。memo 和 timer 按 QQ target（私聊用户或群）归属，同一个 target 下可跨 Agent session 访问，不跨不同 target。memo 会按稳定 item key 更新同一条记录，例如先记 TCL电视价格为3200、再改成 TCL电视价格为4000 会覆盖同一条。插件启动和每 2 小时扫描一次 pending timer，2 小时内到期的任务才会挂短计时器，到点后触发记录来源 Agent session 并主动发回原 QQ target，执行结束后删除该 timer。

| 用户说法示例 | Agent 控制动作 | 作用 |
| 帮我把工作目录改到 /home/xxx/project | set_cwd | 与 /dir <目录> 一致，切换当前 QQ 会话工作目录。 |
| 把模型改成 deepseek-v4-pro | set_model | 与 /model <模型名> 一致，动态切换当前 QQ 会话模型。 |
| 推理等级改成 high | set_reasoning_effort | 与 /reasoningEff <等级> 一致，动态切换当前 QQ 会话推理等级。 |
| 权限改成 workspace-write | set_permission | 与 /permission <preset> 一致，切换当前 QQ live session 权限。 |
| 帮我新开一个会话 | new_session | 与 /new-session 一致，为当前聊天新开 Agent session。 |
| 请在 2026 年 9 月 1 号中午 12 点提醒我提交报告 | schedule_task | 创建一次性持久化 timer；按 QQ target 归属，到点执行后删除。 |
| 记一下：2026/07/08 日收入 350 元 | save_memo | 持久化记录一条 memo；按 QQ target 和 item key 归属，同 target 可跨 Agent session 访问，同 key 会更新同一条。 |

安全

这个项目的定位是“私用 QQ 遥控自己的 DSH”，默认按本机私有服务来设计。建议保持下面几条。

保持白名单

默认 mode: whitelist，只允许 adminQq / allowlist，或官方模式下的 adminOpenId / allowlistOpenIds 触发。mode: open 表示任何能给这个 QQ 或机器人发消息的人都可能触发 DSH，只适合临时调试。

指令入口

默认 commandPrefix: ""，白名单用户的普通消息会直接进入 DSH。设置为 /dsh、/ai 等非空值后，只有以该前缀开头的消息才会进入 DSH。/dir <目录>、/new-session、/models、/model <模型名>、/reasoningEff <等级>、/permission [preset]、/permissions、/help 是内置 bridge 控制命令，默认空前缀时可直接发送。

OneBot 只监听本机

NapCat 正向 WebSocket 推荐： text 监听地址: 127.0.0.1 端口: 3001 access token: <随机 token>

不要把 NapCat OneBot WS 监听地址改成 0.0.0.0 或公网 IP，除非你已经准备好防火墙、内网/VPN 隔离和强 token。

不提交本机凭据

不要把 ~/.dsh/profiles/web/cordis.patch.yml、QQ 凭据、NapCat WebUI token、OneBot access token、QQ 开放平台 AppSecret、DeepSeek API Key 提交到仓库或公开日志。

shell handler 默认关闭

配置示例里保持： yaml shell: enabled: false

QQ 消息默认不会直接执行 shell 命令。即使之后扩展 shell 能力，也应继续保持白名单、强指令前缀和 DSH 自身权限控制。

单号模式不回放历史日志

单号模式默认： yaml selfLogInput: replayOnStart: false

这能避免 DSH 重启时把历史消息重新执行一遍。

停止服务

如果是前台运行的 pnpm dsh web，在终端按： text Ctrl+C

如果你曾用旧版 setup 后台启动过 DSH web，可以用遗留管理命令清理： bash dsh-qq-bridge web status dsh-qq-bridge web logs dsh-qq-bridge web stop

如果只想停 QQ 机器人能力，也可以在 DSH Web 的插件管理里禁用 dsh-qq-bridge，然后重启 dsh web。

常见问题

QQ 消息没回复

NapCat 模式先看日志： bash napcat log <你的QQ号>

重点检查：

- NapCat 是否还在线。
- NapCat 是否已经扫码登录；默认日志文件是 ~/Napcat/log/napcat_<你的QQ号>.log。
- 正向 WebSocket 是否开启，端口是否是 3001。
- ~/.dsh/profiles/web/cordis.patch.yml 里的 napcat.token 是否等于 OneBot access token。
- 如果你设置了非空 commandPrefix，消息是否以该前缀开头。
- adminQq 是否填的是发消息的 QQ。
- 单号模式下 selfLogInput.logPath 是否正确。

官方 QQ Bot 模式重点检查：

- platform 是否为 official。
- official.appId / official.appSecret 是否来自同一个机器人应用。
- 沙箱测试时 official.sandbox 是否为 true，正式环境是否为 false。
- official.adminOpenId 是否是给这个机器人发消息的用户 openid。
- 检查 access.mode 是否已经从临时 open 改回 whitelist。

发送后一直无回复

如果 DSH 卡在工具审批，通常是当前会话正在等待网页端确认。可以在 DSH Web 页面手动批准当前工具调用，或调整当前会话权限。修改 ~/.dsh/settings.yaml 后，需要重启 dsh web 并新建/刷新 Web 会话，新的默认权限才会生效。

官方 QQ Bot 日志出现 40034122

40034122 / 召回消息已达区间上限 通常是官方主动提醒额度耗尽。保持： yaml notifications: agentReply: enabled: false

这不代表正常对话回复失败。

返回 <tool_calls> 或 DSML 文本

通常是模型/工具调用模式不匹配，或插件版本不是最新构建。先执行： bash
npm run build

然后重启 DSH。推荐使用已验证过的 deepseek-v4-pro 配置。

临时调试时想用一次性 patch 启动

正式使用建议通过 setup 写入 ~/.dsh/profiles/web/cordis.patch.yml 后执行 pnpm dsh web。临时调试时，也可以把一次性 patch 写到 /tmp/dsh-qq-bridge-agent.patch.yml，并在 patch 里写入 napcat.token，然后从 DSH 项目目录执行： bash
pnpm dsh web --patch /tmp/dsh-qq-bridge-agent.patch.yml

后台运行并写日志： bash
pnpm dsh web --patch /tmp/dsh-qq-bridge-agent.patch.yml \
/tmp/dsh-qq-agent.log 2>&1 &

许可与致谢

本项目使用 MIT License 发布，见 LICENSE。第三方依赖、协议与外部项目说明见 THIRD_PARTY_NOTICES.md。

本项目会连接或参考以下项目/协议：

- NapCatQQ：提供 QQ / OneBot 运行端点。本项目不打包、不修改、不再分发 NapCatQQ，只要求用户自行安装并运行。
- 腾讯 QQ 开放平台：提供可选的官方机器人运行端点；本项目通过 @tencent-connect/qqbot-nodejs 连接。
- OneBot：聊天机器人接口标准，本项目通过 OneBot WebSocket 协议与 NapCat 通信。
- DeepSeek Harness / DSH：本插件运行所在的 Host / Agent 环境。
- ws、zod 等 npm 依赖：详见 THIRD_PARTY_NOTICES.md。