把QQ机器人接入大模型，听起来挺酷，但真正落地到日常使用，光“能回复”是远远不够的。它得清楚自己是谁，能干什么，遇到涉及隐私或权限的问题该怎么有礼貌地拒绝，还得有能力把用户扔过来的一堆零散信息，整理成一眼就能看懂的结论。
这次实践，我选择从最稳定的QQ私聊入口开始。相比一上来就搞复杂的群聊场景，私聊链路简单、容易复现，用来验证模型调用、人设规则和最终的回复质量，是最稳妥的方案。换句话说，整个流程就是：用户通过QQ私聊发来问题、粘贴群聊记录，或者让机器人帮忙整理个通知草稿；QClaw负责中转消息，Agent则调用部署在蓝耘MaaS上的自定义模型，生成最终回复。
我们的目标很明确：用QClaw配置一个“QQ私聊助理”Agent，并让它能完成三类核心任务：
1. 清晰地说明自己的能力边界。 2. 对用户粘贴的讨论内容进行总结并提取待办事项。 3. 起草通知文案，并为后续扩展简单答疑和配置排查打好基础。
---一、整体方案
整个配置链路清晰，按顺序来不容易出错：
```text 蓝耘 MaaS 自定义模型配置 -> QClaw 创建 QQ 私聊助理 Agent -> QQ 远控通道绑定这个 Agent -> 通过 QQ 私聊验证效果 ```实际运行时的消息流是这样的：
```text QQ 私聊消息 -> QClaw 消息接入 -> 已绑定的 Agent -> 蓝耘 MaaS 自定义模型 -> QQ 私聊返回回复 ```这里的关键组件分工明确。QClaw负责三件事：提供QQ私聊入口、管理Agent的身份人设和边界规则、调用大模型生成回复。蓝耘MaaS则提供底层模型能力。由于QClaw的自定义大模型配置支持OpenAI兼容协议，我们只需把接口地址、API Key和模型名称填好，就能让它随心调用蓝耘MaaS上的模型。
这篇文章的重点不在服务器部署，而在于打造一个可复现的最小闭环：先配置自定义模型，再创建可用的Agent，最后把这个Agent接入QQ私聊。这样一步步走下来，你就能看到一个能真正工作的原型。
二、准备工作
1. 确保QClaw客户端正常运行
首先，你得有一个能正常打开的QClaw客户端。进入主界面后，左侧可以看到“对话、专家、任务、文件、连接、记忆、Lab”等入口。
QClaw默认会提供一个Agent，你也可以点击左侧的“新建Agent”来创建新的助手。页面中间可以直接输入任务或问题，底部的模型选择区域则方便你切换自动模式、内置模型或自定义大模型。
2. 准备一个QQ私聊测试环境
建议准备一个测试QQ账号和一个可以正常私聊的测试窗口。测试阶段先在私聊里验证，这个链路足够确认模型接入、Agent人设和常见任务的效果。至于更复杂的群聊接入，可以等后续验证稳定后再扩展。
私聊测试阶段重点看这三件事：
1. QQ私聊是否能成功触发Agent回复？ 2. Agent能否按人设完成内容总结和待办整理？ 3. Agent能否生成可以直接使用的通知草稿？3. 准备好蓝耘MaaS的API Key和模型名称
登录蓝耘官网，准备好以下三项关键信息：
1. MaaS API Key。
2. 模型调用名称。 模型名称示例：`deepseek-v4-flash`
3. OpenAI-compatible Base URL。 蓝耘的Base URL是：`https://maas-api.lanyun.net/v1`注意，所有敏感信息，如API Key、Token、QQ号、二维码等，在截图里务必打码处理。
三、配置自定义大模型：接入蓝耘MaaS
在把QClaw接入QQ之前，强烈建议先把模型配置好。道理很简单：Agent的核心是模型，如果模型链路不通，就算绑定了QQ，消息进来了也只能干瞪眼。QClaw的自定义模型入口藏在对话页底部的模型下拉菜单里。
操作路径如下：
1. 回到QClaw主界面。 2. 点击输入框左下角的模型选择区域。 3. 在模型列表中找到“自定义大模型”。
4. 点击后进入自定义配置弹窗。
配置弹窗里主要有四类信息，对照填写即可：
| 配置项 | 填写内容 | | --- | --- | | 接口地址 | `https://maas-api.lanyun.net/v1` | | API 协议类型 | OpenAI 兼容协议 | | API Key | 蓝耘 MaaS 控制台生成的 Key | | 模型名称 | 蓝耘控制台中的模型调用名称，例如 `deepseek-v4-flash` |保存前务必仔细检查三点：
1. 接口地址要带 `/v1`，一个字符都不能少。 2. API Key 要完整复制，不能漏字符。 3. 模型名称要和蓝耘控制台里显示的完全一致。保存后，回到QClaw主界面新建一个对话，在模型选择里切换到刚才配置好的自定义模型，然后发送一句简单的测试问题：“你好，简单介绍一下你能做什么。” 如果能正常返回内容，就说明QClaw到蓝耘MaaS的模型链路已经跑通了。
四、创建“QQ 私聊助理”Agent
模型配置好，我们就可以创建Agent了。QClaw创建Agent的方式比较特别，它不只是让你填几个固定字段，而是先让你选择创建方式，再通过输入框描述你想要的Agent人设、知识范围和对话风格，由QClaw帮你生成或更新配置。
进入方式很直接：
1. 回到QClaw主界面。 2. 点击左侧的“新建Agent”。 3. 进入“创建我的专属Agent”页面。 4. 在创建方式中选择“自定义创建”。
从页面上可以看到，QClaw提供了四种创建方式，各有侧重：
| 创建方式 | 适合场景 | | --- | --- | | 从网络创建 | 输入人名或网页链接，让 Agent 基于公开信息生成设定 | | 从文件创建 | 上传演讲稿、访谈记录、读书笔记、聊天截图等文本资料 | | 从 Skill 创建 | 粘贴 Skill 分享链接，或输入 Skill 站内名称 | | 自定义创建 | 直接在输入框中描述人设、知识领域和对话风格 |我们要做的“QQ私聊助理”，不依赖特定网页人物，也不需要上传文件，因此“自定义创建”是最合适的选择。这次Agent的定位很清晰：一个通过QQ私聊使用的个人AI助理，负责内容总结、待办整理、通知草稿、简单答疑和配置排查建议。
选择自定义创建后，在底部输入框中详细描述Agent的名称、用途、语言风格、边界规则和对用户的称呼。QClaw会提示你按内容修改 `user`、`identity` 和 `soul` 文件。你可以把它理解为：用一段自然语言，让QClaw生成这个Agent的身份文件和行为规则。下面是我直接输入的一段描述，你可以参考：
```text 请按照以下内容创建或更新我的 Agent 配置。 你的名称是「QQ 私聊助理」。 你的身份是：你是一个通过 QQ 私聊使用的 AI Agent，负责帮助用户总结内容、整理待办、起草通知、回答简单问题和给出配置排查建议。 你的语言风格是：简洁、清楚、结构化，优先使用中文要点列表，不说空话，不输出过长内容。 回复要求： 1. 使用简洁中文。 2. 优先输出结构化要点。 3. 用户粘贴聊天记录、会议记录或讨论内容时，先总结要点，再提取待办。 4. 不确定的信息要说明需要补充上下文。 5. 不编造用户没有提供过的事实。 6. 涉及账号、付款、隐私、权限等敏感问题时，提醒用户通过正式渠道确认。 7. 单次回复尽量控制在 300 字以内，除非用户要求展开。 你可以帮我做： 1. 总结用户粘贴的讨论内容。 2. 提取待办事项。 3. 起草 QQ 通知、群公告或提醒文案。 4. 给出简单问题排查建议。 你不能做： 1. 查询、编造或泄露他人的手机号、账号、登录信息等隐私内容。 2. 假装自己已经访问后台或完成真实业务操作。 3. 在信息不足时编造结论。 4. 声称自己已经被拉入群聊或能读取群聊历史。 请称呼我为「管理员」。 ```发送后，QClaw会根据这段内容生成或更新Agent。创建完成后，左侧Agent列表中就会出现新的条目。后续接入QQ时，直接选择这个配置好的Agent就行。
这里有两个细节：一是底部模型选择要切换到前面配置好的自定义模型；二是自定义创建时，不要只写一句“帮我创建一个助手”，最好把能力范围、回复风格和安全边界都写进去。这一步的核心不是让机器人显得多聪明，而是让它在私聊入口里保持可控。用户可能会直接把一段聊天、一个问题或一堆配置错误丢给机器人，因此必须明确要求它结构化、简短、不编造事实。
五、把创建好的 Agent 接入 QQ 私聊
Agent创建完成后，再把它接入QQ。这样在绑定QQ通道时，可以直接选择刚才配置好的“QQ私聊助理”，而不是先绑定默认Agent再回头调整。QClaw把外部应用入口放在了“连接”模块里。进入左侧“连接”后，可以看到文档知识、办公协同、邮件服务等各类连接卡片，QQ位于远控通道相关配置中。
实际操作路径如下：
1. 打开QClaw左侧“设置”。 2. 进入“远控通道”。
3. 在通道列表中选择QQ。
4. 选择前面创建好的Agent。
5. 选择连接方式。 6. 按页面提示完成绑定。
QQ通道提供了两种方式：“快捷绑定”和“WebSocket长连接”。如果只是做个人测试，优先选择“快捷绑定”。页面会提示通过QQ扫码授权，自动创建机器人并快速完成绑定。完成后，QQ私聊消息就能进入QClaw，并交给选中的Agent处理。如果需要长期运行或接入已有机器人，再考虑WebSocket长连接方式。
关键提醒：QQ接入时，一定要选中已经配置好模型和人设规则的Agent。这样后续所有私聊消息才能走到完整的Agent回复链路。
六、测试：用三个私聊用例验证 Agent 是否可用
模型和Agent都配置好后，我用三组私聊用例验证了角色认知、总结能力和实用生成能力。所有测试都在QQ私聊窗口完成，重点看它是否真的像一个合格的“QQ私聊助理”在工作。
测试 1：角色自检
模拟输入：“你现在是什么角色？可以帮我做哪些事情？”
实际结果：机器人返回了“角色：QQ私聊助理”，并把能力拆解为内容总结、待办提取、通知草稿、简单答疑等几类。回复还补充了网页搜索、Word/Excel/PDF处理、定时提醒、腾讯文档创建等扩展能力。这说明Agent人设已经生效，没有偏成普通的闲聊机器人。这个结果也证明了QQ私聊消息已经能够进入QClaw，并由我们创建好的Agent返回了结构化回复。
需要注意的是，扩展能力是否都能用，还要看QClaw对应工具是否已授权和启用。因此，更稳妥的结论是：当前先验证QQ私聊中的总结、通知和简单答疑能力，工具类能力可以留作后续扩展。
测试 2：复制讨论内容做总结
模拟输入：
```text 请帮我总结下面这段讨论，并提取待办： 小王：周五前要把活动页上线。 小李：接口还差优惠券状态字段。 小张：设计稿今晚 8 点前补最后一版。 运营：上线前需要确认埋点和信息文案。 ```
实际结果：机器人先输出了“讨论总结”，把活动页上线、接口字段、设计稿、埋点和信息文案几个事项分开说明；随后又生成了“待办提取”表格，表格中包含事项、负责人和截止时间。Agent不只是复述原文，而是把讨论内容整理成了可执行的任务。这一轮测试比较符合私聊入口的使用方式：用户不需要把机器人拉进群，只要把需要整理的讨论内容复制给它，就能得到清晰的总结和待办。
测试 3：起草通知文案
模拟输入：“请根据下面信息写一段QQ通知：今晚 22:00-23:00 做系统维护，期间后台可能短暂无法访问，维护完成后会同步通知。”
实际结果：机器人生成了“系统维护通知”草稿，保留了维护时间，说明了影响范围，并承诺维护完成后会同步通知。这段回复语气正式，适合直接复制使用；同时没有额外承诺输入里没有的信息。对于日常运营、值班提醒这类轻量写作任务，私聊入口已经够用。
下面用表格汇总测试结果：
| 测试用例 | 预期结果 | 实际结果 | 是否可用 | 备注 | | --- | --- | --- | --- | --- | | 角色自检 | 能说明 QQ 私聊助理能力和边界 | 返回 QQ 私聊助理定位，并列出内容总结、待办提取、通知草稿、简单答疑等能力 | 可用 | Agent 人设已生效 | | 讨论内容总结 | 能提取要点、待办和时间 | 输出讨论总结，并生成包含事项、负责人、截止时间的待办表格 | 可用 | 能把复制来的讨论内容整理成可执行任务 | | 通知文案起草 | 能生成清晰通知 | 生成系统维护通知，保留维护时间、影响范围和后续同步说明 | 可用 | 文案可直接复制使用 |这三组测试不追求数量，而是覆盖最核心的三件事：角色是否生效、总结任务是否能完成、生成内容是否可直接使用。只要这三项稳定，后续再扩展资料整理、故障排查等能力会更有底气。
七、常见问题排查
1. QClaw 能打开，但 QQ 私聊里没有回复
优先检查这几点：
1. QQ 通道是否已经完成绑定？ 2. 绑定时是否选择了正确的 Agent？ 3. 当前是否在正确的 QQ 私聊窗口发消息？ 4. Agent 是否已启用？ 5. QClaw 的日志里是否有消息接收记录？如果日志里完全没有消息，优先排查QQ接入；如果日志里有消息但模型没有返回内容，再排查模型配置。
2. 自定义模型保存后调用失败
优先检查这几点：
1. 接口地址是否确定是 `https://maas-api.lanyun.net/v1`？ 2. API 协议类型是否选择了“OpenAI 兼容协议”？ 3. API Key 是否完整无误？ 4. 模型名是否和蓝耘控制台显示的完全一致？ 5. 配置修改后，是否需要重新选择模型或重启 QClaw？ 6. 当前网络是否能正常访问模型 API？这类问题通常不是Agent人设导致的。只有模型能正常返回之后，再去调整人设和边界规则才有意义。
3. 回复内容不符合角色定位
可以从Agent的自定义创建内容入手，重点检查 `user`、`identity` 和 `soul` 文件对应的身份与规则：
1. 是否明确了机器人身份是“QQ 私聊助理”？ 2. 是否明确了它能做什么、不能做什么？ 3. 是否限制了回复长度？ 4. 是否要求它在不确定时说明缺少上下文？八、优化建议
当基础Agent跑通后，还可以在几个方向上继续优化。
1. 给不同任务创建不同 Agent
比如，可以分别创建“资料整理助手”、“通知文案助手”、“配置排查助手”。每个Agent使用不同的人设和边界规则，效果会比一个通用机器人处理所有场景更稳定、更精准。
2. 固定高频任务的输入格式
例如，可以约定这样的输入格式：
```text 请总结以下内容，并输出：要点、待办、风险。 请根据以下信息写一段通知，要求简洁正式。 请根据以下现象列一个排查清单。 ```这样用户知道怎么提问，Agent也更容易判断任务类型。
3. 控制输入上下文长度
私聊里可以粘贴讨论内容，但一次粘贴太长时，模型可能被无关信息干扰。建议先从较短片段开始，根据实际效果调整输入长度。
4. 固定安全边界
涉及隐私、账号、付款、权限、后台状态的问题，建议在Agent的身份文件或自定义创建描述中固定规则：
```text 不能查询、编造或泄露个人隐私、账号状态、付款结果和后台权限信息；需要用户通过正式授权渠道确认。 ```这一条对QQ私聊场景同样重要，因为用户很容易把临时问题、账号问题或半开玩笑式的请求直接发给机器人，边界必须清晰。
九、总结
这次实践的配置链路可以概括为：
```text QClaw 客户端 -> 蓝耘 MaaS 自定义模型 -> QQ 私聊助理 Agent -> QQ 远控通道 -> 私聊场景验证 ```QClaw的价值不只是“把模型接到QQ”，而是可以**把模型包装成更有明确角色的Agent**。它有身份、有输出风格，也有安全边界。蓝耘MaaS通过OpenAI兼容协议接入后，负责提供底层模型能力；QClaw则负责把这份能力放进QQ私聊这个日常入口里。
从实际复现角度看，当前最稳妥的实践方式是先把QQ私聊跑通——角色自检、讨论总结、通知草稿都可以在私聊里完成。等后续群聊接入能力确认后，还可以在这个基础上继续扩展。这样整理出来的QClaw实践链路更可靠，也更容易让读者跟着操作。
