dsh-qq-onebot

dsh plugin --profile web add dsh-qq-onebot

dsh-qq-onebot

把 QQ 接成 DeepSeek Harness 的一个前端：私聊、群聊都能和同一个 Agent 聊；语音听得懂、图片看得见，还能戳一戳、贴表情、点赞。

底层走 OneBot v11 协议，默认搭配 NapCat。不用公网 IP、不用备案、不用企业主体。

⚠️ 先说清楚：NapCat 属于「QQ 协议端」，跑在你自己登录的 QQ 客户端上，不符合腾讯的用户协议。用小号、别和常用号同一台设备、别发垃圾消息，账号有被风控或封禁的可能。插件只负责把 OneBot 消息转给 Agent，协议端本身怎么合规、怎么稳，由你自己负责。场景能用 QQ 官方机器人 的，优先用官方的。

📢 这是个公开仓库：MIT，随便取用、改、再发。作者是个人不是公司，没有客服、没有 SLA，能回 issue 但不保证秒回。

提 issue 或贴日志之前，请先把 token、真实 QQ 号、本机路径 抹掉——发出去就收不回来了。

🔌 一台 NapCat 的 WS 只该被一个 Agent 连着：再装一个 dsh-onebot-hub 之类的插件会抢同一条消息，两边都只收到一半（日志里每行出现两次就是证据）。细节见 [和别的 OneBot 插件共存](#和别的-onebot-插件共存)。

你的 QQ 客户端  ←→  NapCat（协议端，注入 QQ）
                        ↕  OneBot v11 WebSocket
                dsh-qq-onebot 插件（跑在 DSH 宿主进程里）
                        ↕  进程内 ctx.agents
                  你的 Agent（你自己的预设、工具、记忆）

它能干什么

特性 · 说明

一个 QQ 会话 = 一个持久 Agent 会话 · 有历史、有记忆，不会聊两句就忘

每个会话一个独立工作目录 · 自带 AGENTS.md 和 记忆区/，彼此看不见，也碰不到宿主自己的私人记忆

语音转文字 · 本地 vosk 离线识别，不联网、不上传，结果直接进对话

群里默认 @ 才理 · 被某人 @ 过一次后 60 秒内不用再 @ 也能接（窗口按「群 + 人」算，别人蹭不到）

分得清谁在跟自己说话 · 引用算叫我、[SILENT] 可以不接、同类机器人单独开关、跳过的群消息也进上下文

不会把自己聊丢 · 窗口快满时补回聊天规矩；再撑满就换新会话，旧的最近聊天先落盘再接上

十个互动工具 · qq_poke / qq_react / qq_like / qq_send_image / qq_send_file / qq_face / qq_mface / qq_reply / qq_send / qq_recall

问答能转回 QQ · ask_user_question 抛的问题会变成一条 QQ 消息，回个数字就行

三步跑通

1. 装 NapCat，登录小号

下载 Windows 一键版（NapCat.Shell.Windows.OneKey.zip），解压运行 NapCatInstaller.exe——它装一份独立的 QQ，不会碰你现有的 QQ。登录小号，打开 WebUI（默认 http://127.0.0.1:6099），在「网络配置」里新建 WebSocket 服务器：

项 · 填什么

地址 · 127.0.0.1

端口 · 3001（被占用就换一个，记住它）

Token · 自己编一串，比如 my-token-2026

消息格式 · array（重要，别选 string）

⚠️ NapCat 的 QQ 和你桌面的 QQ 是两套程序。 重装 / 重启 NapCat 时别用 Get-Process -Name QQ | Stop-Process 一把全杀——那会把自己正在用的 QQ 也踢下线。按进程路径挑，或者在 NapCat 自己的托盘 / WebUI 里退。

2. 装插件

先把 DSH 完全退出（托盘也要退掉，插件文件被占用会装到一半失败）。

# 从 npm 装（推荐）
dsh plugin --profile desktop add dsh-qq-onebot

# 或从 Releases 下载 dsh-qq-onebot-1.0.0.tgz
dsh plugin --profile desktop add "D:\下载\dsh-qq-onebot-1.0.0.tgz"

不想用打好的包，也可以直接装源码目录（git clone，或下 Source code (zip) 解压）：

dsh plugin --profile desktop add "D:\dsh-qq-onebot-1.0.0"

三个容易踩的坑：

• 必须用 DSH 自带的 dsh，不能 npx @deepseek-ai/dsh。 desktop 这份 profile 由桌面端独占管理，npx 会直接报 profile "desktop" is managed exclusively by the Electron application。PATH 里找不到 dsh 就用完整路径：

  & "$env:LOCALAPPDATA\Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop add "D:\dsh-qq-onebot-1.0.0"

• --profile 不能省，省了直接报 error: --profile <name> is required。
• 写绝对路径，相对路径是按你敲命令那一刻的当前目录算的。

装完它会自动写进 $DSH_HOME/profiles/desktop/package.json 的 dsh.profile.bundles（默认就启用），启动后在 设置 → 插件 里能看到。想确认装没装上：

dsh plugin --profile desktop why dsh-qq-onebot

3. 重启 DSH，填连接信息

重新打开 DSH → 设置 → QQ，把 wsUrl 和 accessToken 填进去就行（34 项都在那个面板上，改完即时生效）。

设置里没看到 QQ 这一项？ 别慌，不用等修——两条路都能救。

① 直接写设置文件（不用重启宿主）：$DSH_HOME/dsh-qq/settings.json，Windows 一般是 C:\Users\<用户名>\.dsh\dsh-qq\settings.json。插件第一次启动时会在那儿放一份带说明的骨架，改成：

```json

{

"wsUrl": "ws://127.0.0.1:3001",

"accessToken": "my-token-2026"

}

```

保存后约 800ms 自动生效。

② 看日志找原因：插件启动时会自检浏览器半端，日志里有 客户端半端自检通过：id=... 就是好的；如果是 客户端半端自检失败（client-id-mismatch / no-inject ...），那句话本身就说明了设置页为什么没出现。日志在 <workspaceRoot>/logs/dsh-qq-<日期>.log（workspaceRoot 默认是进程 cwd）。也可以看 $DSH_HOME/dsh-qq/ 下有没有东西——一个文件都没有，通常就是浏览器半端根本没被加载。

想直接写 profile 配置也可以，改 $DSH_HOME/profiles/desktop/cordis.patch.yml 里 dsh-qq 那一段（整段替换，不是往下叠）：

- id: dsh-qq
  name: dsh-qq
  config:
    wsUrl: ws://127.0.0.1:3001
    accessToken: my-token-2026
    cwd: D:/my-agent                     # Agent 工作目录，不填用进程 cwd
    workspaceRoot: D:/my-agent/QQ会话    # 每个会话的独立目录（不填用 <cwd>/会话）
    persona: |                           # 它是谁、什么脾气（不填就是个普通助手）
      你叫小满，是个住在电脑里的助手。说话简短、带点懒，被夸的时候会嘴硬。
    provider: deepseek-official          # 想指定模型时才填
    model: deepseek-flash

日志里看到 已连接 ws://127.0.0.1:3001 就成了，给小号发条私聊试试。

最常改的几个配置

配置 · 默认 · 什么时候改

persona · 空 · 想让它有名字、有性格、有称呼

ownerIds / ownerLabel · [] / 主人 · 想在群里认出主人，优先响应

requireMention · true · 群里不 @ 也想让它接话

groupMode / privateMode · open / allowlist · 只想在指定群 / 指定人那里开；私聊默认只认白名单

groupReplyGapMs · 20000 · 觉得回得太密（防刷屏、防风控）

rateLimitPerMin · 12 · 每个会话每分钟最多发几条

contextGuard · true · 不想要自动换会话就关掉

chatLog · true · 不想记原始流水就关掉

全部 50+ 项见 [docs/configuration.md](docs/configuration.md)。

想深入看哪块

想看 · 去哪

它是谁、群里怎么认主人、上下文守卫、认时间、引用与沉默判断 · [docs/persona.md](docs/persona.md)

所有配置项的默认值和含义 · [docs/configuration.md](docs/configuration.md)

长期跑、看门狗、定时写日记、开机自启 · [docs/deployment.md](docs/deployment.md)

改代码、跑测试、目录结构 · [docs/development.md](docs/development.md)

测试怎么做、踩坑记录、排障 · [TESTING.md](TESTING.md) · [tools/README.md](tools/README.md)

在 DSH 设置里调它

不想手改 YAML 的话，设置 → QQ 那一节就是个面板，34 项都能点着改：

分组 · 能改什么

状态 · 连接点、登录账号、家目录、设置文件；「重连」「重新读一遍」两个按钮

连接 · wsUrl、accessToken、selfId

它人设 · persona、personaFile、ownerLabel

补充提示 · directPrompt、groupPrompt

记忆区与工作区 · workspaceRoot、isolateByPeer

群里怎么说话 · requireMention、groupWakeMs、groupReplyGapMs、groupMinGapMs、rateLimitPerMin、historyLimit

谁能跟它说话 · privateMode、privateAllow、ownerIds、groupMode、groupAllow

同类机器人 · botChatEnabled、peerBots

其它 · debug、textChunkLimit、splitDelayMs

改完立刻生效（wsUrl / accessToken 要点「重连」；reconnectMs / selfId / workspaceRoot / isolateByPeer / asrPython 要重启宿主）。设置写在 $DSH_HOME/dsh-qq/settings.json，只覆盖你显式设过的键，清空就回默认——不动 profile 的 cordis.patch.yml。

谁能跟它说话（⚠️ 默认只认白名单）

私聊默认 privateMode: allowlist，而 privateAllow 默认是

…(truncated)