QClaw 实践应用：把 QQ 私聊配置成一个可用的 AI Agent 入口

QQ 机器人接入大模型后，最容易做到的是"能回复"。但真正放到日常使用里，只能回复还不够。它还需要知道自己是什么角色、适合处理哪些问题、遇到隐私和权限类请求时应该怎么拒绝，以及怎样把一段零散内容整理成更容易阅读的结果。

这次实践中，我用 QClaw 连接 Agent 创建 QQ 机器人时，先从最稳定的 QQ 私聊入口开始验证。相比直接追求复杂场景，私聊链路更容易复现，也更适合验证 Agent 的模型调用、人设规则和回复质量。

把 QQ 私聊当作 AI Agent 的入口。

也就是说，用户通过 QQ 私聊向机器人发送问题、粘贴群聊记录、让它整理通知草稿或给出排查建议；QClaw 负责把消息交给 Agent，Agent 再调用蓝耘 MaaS 自定义模型生成回复。

本文用 QClaw 配置一个"QQ 私聊助理"Agent，目标是完成三类基础任务：

1. 说明自己的能力边界。
2. 对用户粘贴的讨论内容做总结和待办整理。
3. 起草通知文案，并为后续扩展简单答疑和配置排查打基础。

@toc

---

一、整体方案

这次实践的配置顺序如下：

蓝耘 MaaS 自定义模型配置
-> QClaw 创建 QQ 私聊助理 Agent
-> QQ 远控通道绑定这个 Agent
-> 通过 QQ 私聊验证效果

实际运行时，消息流是这样的：

QQ 私聊消息
-> QClaw 消息接入
-> 已绑定的 Agent
-> 蓝耘 MaaS 自定义模型
-> QQ 私聊返回回复

这里面 QClaw 主要负责三件事：

1. 提供 QQ 私聊入口。
2. 管理 Agent 的身份、人设和边界规则。
3. 调用自定义大模型生成回复。

蓝耘 MaaS 负责提供模型能力。QClaw 的自定义大模型配置支持 OpenAI 兼容协议，因此可以把接口地址、API Key 和模型名称填进去，让 Agent 使用蓝耘 MaaS 中的模型来生成回复。

这篇文章重点不放在服务器部署，而是放在一个可复现的最小闭环上：先配置自定义模型，再创建可用 Agent，最后把这个 Agent 接入 QQ 私聊入口。

二、准备工作

1. 可正常打开的 QClaw 客户端

首先需要准备一个可以正常打开的 QClaw 客户端。进入主界面后，左侧可以看到"对话、专家、任务、文件、连接、记忆、Lab"等入口。

在主界面中，QClaw 默认提供了一个 Agent，也可以点击左侧的"新建 Agent"创建新的助手。页面中间可以直接输入任务或问题，底部的模型选择区域可以切换自动模式、内置模型或自定义大模型。

2. QQ 私聊测试环境

建议准备一个测试 QQ 账号和一个可以正常私聊的测试窗口。

测试阶段先按 QQ 私聊来验证。当前这条链路里，QClaw 连接的 Agent 可以通过 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 绑定，也只能停在"消息进来了，但 Agent 无法稳定回答"的状态。

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 帮你生成或更新 Agent 配置。

进入方式很直接：

1. 回到 QClaw 主界面。
2. 点击左侧的"+ 新建 Agent"。
3. 进入"创建我的专属 Agent"页面。
4. 在创建方式中选择"自定义创建"。

从页面上可以看到，QClaw 提供了四种创建方式：

创建方式	适合场景
从网络创建	输入人名或网页链接，让 Agent 基于公开信息生成设定
从文件创建	上传演讲稿、访谈记录、读书笔记、聊天截图等文本资料
从 Skill 创建	粘贴 Skill 分享链接，或输入 Skill 站内名称
自定义创建	直接在输入框中描述人设、知识领域和对话风格

本文要做的是一个 QQ 私聊助理，不依赖某个网页人物，也不需要上传资料文件，所以选择"自定义创建"更合适。

这次 Agent 的定位是：

面向 QQ 私聊的个人 AI 助理，负责内容总结、待办整理、通知草稿、简单答疑和配置排查建议。

选择自定义创建后，在底部输入框中写清楚 Agent 的名称、用途、语言风格、边界规则和对用户的称呼。QClaw 会提示用户按内容修改 user、identity 和 soul 文件。可以把它理解为：用一段自然语言，让 QClaw 生成这个 Agent 的身份文件和行为规则。

可以直接输入下面这段：

请按照以下内容创建或更新我的 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 列表中会出现新的 Agent，例如"智能Agent"或自定义名称对应的条目。后续接入 QQ 时，就选择这个已经配置好的 Agent。

这里有两个细节值得注意：

1. 底部模型选择要切到前面配置好的自定义模型。
2. 自定义创建时不要只写一句"帮我创建一个助手"，最好把能力范围、回复风格和安全边界一起写进去。

这一步的重点不是让机器人"显得很聪明"，而是让它在私聊入口里可控。用户往往会把一段聊天、一个问题或一段配置错误直接丢给机器人，因此要明确要求它结构化、简短、不编造事实。

五、把创建好的 Agent 接入 QQ 私聊

Agent 创建完成后，再把它接入 QQ。这样在绑定 QQ 通道时，可以直接选择刚才配置好的"QQ 私聊助理"，而不是先绑定默认 Agent 再回头调整。

QClaw 把外部应用入口放在"连接"模块里。进入左侧"连接"后，可以看到文档知识、办公协同、邮件服务、生活服务、网盘存储、专业服务等不同类型的连接卡片，其中 QQ 位于远控通道相关配置中。

实际操作路径可以按下面走：

1. 打开 QClaw 左侧"设置"。

2. 进入"远控通道"。

   

3. 在通道列表中选择 QQ。

   

4. 选择前面创建好的 Agent。

   

5. 选择连接方式。

6. 按页面提示完成绑定。

QQ 通道提供了两种方式：

1. 快捷绑定。
2. WebSocket 长连接。

如果只是做个人测试，优先使用"快捷绑定"。页面会提示通过 QQ 扫码授权，自动创建机器人并快速完成绑定。完成后，QQ 私聊消息就可以进入 QClaw，并交给选中的 Agent 处理。

如果需要长期运行、接入已有机器人或做更稳定的服务化部署，可以再考虑 WebSocket 长连接方式。

这里要注意：QQ 接入时一定要选中已经配置好模型和人设规则的 Agent。这样后续私聊消息进入 QClaw 后，才能直接走到完整的 Agent 回复链路。

六、测试：用三个私聊用例验证 Agent 是否可用

模型和 Agent 配置完成后，我用三组私聊用例验证角色、总结能力和实用生成能力。测试都在 QQ 私聊窗口完成，重点看它是否真的按"QQ 私聊助理"的定位工作。

测试 1：角色自检

模拟输入：

你现在是什么角色？可以帮我做哪些事情？

实际结果：

机器人返回了"角色：QQ 私聊助理"，并把能力拆成内容总结、待办提取、通知草稿、简单答疑等几类。回复还补充了网页搜索、Word / Excel / PDF 处理、定时提醒、腾讯文档创建和写入等扩展能力。

这说明 Agent 人设已经生效，没有偏成普通闲聊机器人。这张图也能证明 QQ 私聊消息已经能够进入 QClaw，并由前面创建好的 Agent 返回结构化回复。

需要注意的是，扩展能力是否都能在当前环境里完整使用，还要看 QClaw 对应工具是否已授权和启用。因此正文里更稳妥的结论是：当前先验证 QQ 私聊中的总结、通知和简单答疑能力，工具类能力可以作为后续扩展。

测试 2：复制讨论内容做总结

模拟输入：

请帮我总结下面这段讨论，并提取待办：

小王：周五前要把活动页上线。
小李：接口还差优惠券状态字段。
小张：设计稿今晚 8 点前补最后一版。
运营：上线前需要确认埋点和短信文案。

实际结果：

机器人先输出了"讨论总结"，把活动页上线、接口字段、设计稿、埋点和短信文案几个事项分开说明；随后又生成了"待办提取"表格，表格中包含事项、负责人和截止时间。

Agent 不只是复述原文，而是把"小李补充优惠券状态字段接口""小张补最后一版设计稿""运营确认埋点方案和短信文案""小王负责活动页上线"等内容整理成了可执行任务。

这一轮测试比较符合私聊入口的使用方式：用户不需要把机器人拉进群，只要把需要整理的讨论内容复制给它，就能得到总结和待办表格。

测试 3：起草通知文案

模拟输入：

请根据下面信息写一段 QQ 通知：
今晚 22:00-23:00 做系统维护，期间后台可能短暂无法访问，维护完成后会同步通知。

实际结果：

机器人生成了"系统维护通知"草稿，保留了 22:00-23:00 的维护时间，也说明了维护期间后台可能短暂无法访问，并写明维护完成后会第一时间同步通知。

这段回复的优点是语气比较正式，适合直接复制到 QQ 或团队通知里；同时没有额外承诺"数据不受影响"之类输入里没有的信息。对于日常运营、值班提醒、系统维护通知这类轻量写作任务，私聊入口已经够用。

可以用下面的表格记录测试结果：

测试用例	预期结果	实际结果	是否可用	备注
角色自检	能说明 QQ 私聊助理能力和边界	返回 QQ 私聊助理定位，并列出内容总结、待办提取、通知草稿、简单答疑等能力	可用	Agent 人设已生效
讨论内容总结	能提取要点、待办和时间	输出讨论总结，并生成包含事项、负责人、截止时间的待办表格	可用	能把复制来的讨论内容整理成可执行任务
通知文案起草	能生成清晰通知	生成系统维护通知，保留维护时间、影响范围和后续同步说明	可用	文案可直接复制使用

这里的测试不追求数量，而是覆盖最核心的三件事：角色是否生效、总结任务是否能完成、生成内容是否可直接使用。只要这三项稳定，后续再扩展资料整理、故障排查、值班提醒等能力会更稳。

七、常见问题排查

1. QClaw 能打开，但 QQ 私聊里没有回复

优先检查：

1. QQ 通道是否已经完成绑定。
2. 绑定时是否选择了正确的 Agent。
3. 当前是否在正确的 QQ 私聊窗口发消息。
4. Agent 是否启用。
5. 日志里是否有消息接收记录。

如果日志里完全没有消息，优先排查 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. 限制回复长度。
5. 要求不确定时说明缺少上下文。

八、优化建议

当基础 Agent 跑通后，可以继续做几类优化。

1. 给不同任务创建不同 Agent

可以分别创建"资料整理助手""通知文案助手""配置排查助手"。不同 Agent 使用不同人设和边界规则，效果会比一个通用机器人处理所有场景更稳定。

2. 固定高频任务输入格式

例如：

请总结以下内容，并输出：要点、待办、风险。
请根据以下信息写一段通知，要求简洁正式。
请根据以下现象列一个排查清单。

用户知道怎么提问，Agent 也更容易判断任务类型。

3. 控制输入上下文长度

私聊里可以粘贴讨论内容，但一次粘贴太长时，模型可能被无关信息干扰。建议先从较短片段开始，根据实际效果调整输入长度。

4. 固定安全边界

涉及隐私、账号、付款、权限、后台状态的问题，建议在 Agent 的身份文件或自定义创建描述中固定规则：

不能查询、编造或泄露个人隐私、账号状态、付款结果和后台权限信息；需要用户通过正式授权渠道确认。

这一条对 QQ 私聊场景同样重要，因为用户很容易把临时问题、账号问题或半开玩笑式请求直接发给机器人。

九、总结

这次实践的配置链路可以概括为：

QClaw 客户端
-> 蓝耘 MaaS 自定义模型
-> QQ 私聊助理 Agent
-> QQ 远控通道
-> 私聊场景验证

QClaw 的价值不只是"把模型接到 QQ"，而是可以把模型包装成更明确的 Agent：它有角色、有输出风格，也有安全边界。蓝耘 MaaS 通过 OpenAI 兼容协议接入后，负责提供底层模型能力；QClaw 则负责把这份能力放进 QQ 私聊这个日常入口里。

从实际复现角度看，当前更稳的实践方式是先把 QQ 私聊跑通：角色自检、讨论总结、通知草稿都可以在私聊里完成。等后续群聊接入能力确认后，还可以在这个基础上继续扩展群聊版本。这样整理出来的 QClaw 实践链路更可信，也更方便读者照着操作。