DeepSeek 对接 QQ 完整教程:用 DeepSeek Harness 打造自己的 AI 机器人

DeepSeek 对接 QQ 完整教程:用 DeepSeek Harness 打造自己的 AI 机器人

封面

最近想把大模型接到 QQ 里,让机器人替我回答问题。折腾了一圈,最后用 DeepSeek Harness(dsh)+ QQ 开放平台机器人 跑通了整套链路。这篇把从零配置到排错的完整过程写下来,包括我实际踩过的几个坑——尤其是那两个不仔细看根本发现不了的坑。

一、这套方案是怎么工作的

整体链路

消息流向很简单:

  1. 用户在 QQ 里给机器人发消息;
  2. QQ 开放平台把消息通过 WebHook 推送到本机运行的 DeepSeek Harness;
  3. Harness 里的 im-qqbot 插件接收消息,交给 llm-pi-ai 调用大模型;
  4. 模型返回内容,再由插件回发到 QQ。

核心是两个配置文件:

文件 作用
~/.dsh/profiles/desktop/cordis.patch.yml 定义模型供应商、模型列表、默认模型、QQ 机器人参数
~/.dsh/.credentials.yaml 集中存放密钥,配置里通过环境变量名引用,避免明文散落

二、准备工作

需要三样东西:

  • 一个 QQ 开放平台机器人应用(拿 AppID 和 AppSecret)
  • 一个大模型接口:DeepSeek 官方 API,或任意 OpenAI 兼容的中转接口
  • DeepSeek Harness 客户端:本文用的是 Windows 桌面版

提醒:如果用第三方中转站,接口不是官方的,密钥也不要在公开场合泄露。

三、创建 QQ 开放平台机器人

  1. 打开 QQ 开放平台,登录开发者账号;
  2. 创建应用,类型选择「机器人」;
  3. 在应用详情里记下 AppID 和 AppSecret;
  4. 配置回调地址,指向 DeepSeek Harness 提供的 WebHook 地址;
  5. 设置单聊(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 号字符串。

七、启动与测试

  1. 完全退出 DeepSeek Harness(任务栏、托盘都要退干净);
  2. 重新启动客户端;
  3. 在模型选择里确认能看到刚才配置的模型;
  4. 用白名单里的 QQ 给机器人发一条消息,看是否正常回复。

如果机器人没反应,按下面的顺序排查。

八、常见问题速查

常见问题速查表

补充几点:

  • 503 model_not_found:九成是模型 ID 写错,调 /v1/models 核对。
  • 返回一堆 HTML:baseURL 少了 /v1。
  • 402 余额不足:这是某个供应商的账户问题,跟其他供应商的 key 无关,别混着查。
  • 改了配置没生效:客户端只在启动时读配置,必须彻底退出再开。
  • 机器人不回复:先确认 AppID/AppSecret 没错,再确认发送方在白名单里。

九、写在最后

整套配置的核心就三点:接口地址带 /v1、模型 ID 照抄接口返回值、改完配置重启客户端。剩下的都是常规操作。

跑通之后,换模型、换供应商都很方便——只要在 providers 里再加一组配置,然后改一下 agent-default-model 的指向就行。

如果你也在折腾类似的东西,希望这篇能帮你少走点弯路。


本文所用接口与密钥均为示例,请替换成你自己的。

打赏
评论区
头像