DeepSeek 对接 QQ 完整教程:用 DeepSeek Harness 打造自己的 AI 机器人
最近想把大模型接到 QQ 里,让机器人替我回答问题。折腾了一圈,最后用 DeepSeek Harness(dsh)+ QQ 开放平台机器人 跑通了整套链路。这篇把从零配置到排错的完整过程写下来,包括我实际踩过的几个坑——尤其是那两个不仔细看根本发现不了的坑。
一、这套方案是怎么工作的
消息流向很简单:
- 用户在 QQ 里给机器人发消息;
- QQ 开放平台把消息通过 WebHook 推送到本机运行的 DeepSeek Harness;
- Harness 里的
im-qqbot插件接收消息,交给llm-pi-ai调用大模型; - 模型返回内容,再由插件回发到 QQ。
核心是两个配置文件:
| 文件 | 作用 |
|---|---|
~/.dsh/profiles/desktop/cordis.patch.yml |
定义模型供应商、模型列表、默认模型、QQ 机器人参数 |
~/.dsh/.credentials.yaml |
集中存放密钥,配置里通过环境变量名引用,避免明文散落 |
二、准备工作
需要三样东西:
- 一个 QQ 开放平台机器人应用(拿 AppID 和 AppSecret)
- 一个大模型接口:DeepSeek 官方 API,或任意 OpenAI 兼容的中转接口
- DeepSeek Harness 客户端:本文用的是 Windows 桌面版
提醒:如果用第三方中转站,接口不是官方的,密钥也不要在公开场合泄露。
三、创建 QQ 开放平台机器人
- 打开 QQ 开放平台,登录开发者账号;
- 创建应用,类型选择「机器人」;
- 在应用详情里记下 AppID 和 AppSecret;
- 配置回调地址,指向 DeepSeek Harness 提供的 WebHook 地址;
- 设置单聊(C2C)白名单,把允许使用的 QQ 号加进去。
这两项后面要填进配置:
AppID = 你的AppID
AppSecret = 你的AppSecret
四、安装 DeepSeek Harness
桌面版一路下一步安装即可。安装目录记住,后面重启要用。本文示例目录为 D:\deepseek。
安装后第一次启动会生成配置目录:
C:\Users\你的用户名\.dsh\
├── .credentials.yaml # 密钥
└── profiles\desktop\cordis.patch.yml # 主配置
改完配置必须完全退出客户端再重开,配置只在启动时加载。
五、配置大模型(最容易踩坑的一步)
打开 cordis.patch.yml,找到 llm-pi-ai 这一节,按下面结构配置供应商:
- id: llm-pi-ai
name: '@deepseek-ai/dsh-llm-pi-ai'
config:
providers:
deepseek-ai:
displayName: 我的模型服务
apiKeyEnv: DEEPSEEK_AI_API_KEY
api: openai-completions
baseURL: https://chatapi.onechats.top/v1
models:
- id: deepseek-v4.1-flash
name: DeepSeek V4.1 Flash
contextWindow: 1000000
input:
- text
- image
坑一:baseURL 必须带 /v1
我一开始填的是 https://chatapi.onechats.top,结果一直报错。用 curl 测了一下才发现:不带 /v1 时服务器返回的是网站首页 HTML,根本不是 API 响应。
# 正确
https://chatapi.onechats.top/v1/chat/completions → JSON
# 错误
https://chatapi.onechats.top/chat/completions → 网页 HTML
如果用 DeepSeek 官方接口,对应地址是 https://api.deepseek.com/v1。
坑二:模型 ID 必须和接口返回的完全一致
我按模型全名填了 deepseek-ai/DeepSeek-V4.1-Flash,接口直接返回:
{"error":{"code":"model_not_found","message":"No available channel for model ..."}}
原因是这个中转站上的正确 ID 是小写短名 deepseek-v4.1-flash。不要凭印象写模型名,先调接口拿准确列表:
curl https://chatapi.onechats.top/v1/models \
-H "Authorization: Bearer sk-你的密钥"
返回里的 id 字段就是你要填的值。命名规则各家不统一,有的是 deepseek-ai/DeepSeek-V4-Pro 这种带前缀的,有的是 deepseek-v4.1-flash 这种短名。
配置默认模型
同一文件里还有一处指定默认用哪个模型,两处要对应上:
- id: agent-default-model
name: "@deepseek-ai/dsh-agent-default-model"
config:
provider: deepseek-ai
model: deepseek-v4.1-flash
密钥单独放
在 ~/.dsh/.credentials.yaml 里写:
version: 1
refs:
DEEPSEEK_AI_API_KEY: sk-你的密钥
配置里用 apiKeyEnv: DEEPSEEK_AI_API_KEY 引用这个名字即可,不要在 cordis.patch.yml 里明文写密钥。
六、配置 QQ 机器人
在同一个 cordis.patch.yml 末尾加上 im-qqbot 插件配置:
- id: im-qqbot
config:
appId: "你的AppID"
appSecret: 你的AppSecret
access:
c2cMode: allowlist
c2cAllow:
- 你的QQ号
说明:
c2cMode: allowlist表示只允许白名单里的 QQ 号私聊,安全性更好;- 想让所有人都能用,可把模式改成公开,但要注意成本;
- 白名单填的是 QQ 号字符串。
七、启动与测试
- 完全退出 DeepSeek Harness(任务栏、托盘都要退干净);
- 重新启动客户端;
- 在模型选择里确认能看到刚才配置的模型;
- 用白名单里的 QQ 给机器人发一条消息,看是否正常回复。
如果机器人没反应,按下面的顺序排查。
八、常见问题速查
补充几点:
- 503 model_not_found:九成是模型 ID 写错,调
/v1/models核对。 - 返回一堆 HTML:baseURL 少了
/v1。 - 402 余额不足:这是某个供应商的账户问题,跟其他供应商的 key 无关,别混着查。
- 改了配置没生效:客户端只在启动时读配置,必须彻底退出再开。
- 机器人不回复:先确认 AppID/AppSecret 没错,再确认发送方在白名单里。
九、写在最后
整套配置的核心就三点:接口地址带 /v1、模型 ID 照抄接口返回值、改完配置重启客户端。剩下的都是常规操作。
跑通之后,换模型、换供应商都很方便——只要在 providers 里再加一组配置,然后改一下 agent-default-model 的指向就行。
如果你也在折腾类似的东西,希望这篇能帮你少走点弯路。
本文所用接口与密钥均为示例,请替换成你自己的。





