1. 为什么要在 QClaw 里接蓝耘 MaaS 做文档 AgentQClaw 是一个 AI Agent 编排入口它能管理角色人设、调度工具、维护对话上下文但它本身不生产模型能力。真正决定回复质量的是背后接的模型服务。蓝耘 MaaS 提供 OpenAI 兼容协议接口把 DeepSeek、GLM、Qwen 等模型收在同一套入口里切换模型只需要改一个模型名称字段不用为每个厂商单独维护鉴权和 SDK。这条链路适合谁适合已经在用 QClaw 做日常助手、想让 Agent 把生成结果直接沉淀到腾讯文档的人。比如你经常需要整理会议纪要、起草通知、生成赏析类内容然后手动复制粘贴到云文档——这套配置就是把这个手动步骤自动化。整体数据流是这样的你在 QClaw 对话框输入一句话指令QClaw 把任务交给已配置的 AgentAgent 调用蓝耘 MaaS 的自定义模型生成内容如果腾讯文档 MCP 已连接Agent 会进一步调用工具把内容创建为云文档并返回链接。三个组件的分工要拆清楚QClaw 负责入口、人设和工具调度蓝耘 MaaS 负责中文内容生成和结构化输出腾讯文档 MCP 负责把结果落成可分享文档。各司其职后续换模型不用重配 MCP换文档工具也不用重配模型。下面从零开始把这条链路完整跑通。2. 前置准备蓝耘 MaaS Key 与 TaoToken 统一配置在动手配 QClaw 之前先把模型侧的凭证准备好。这一步的核心是拿到三样东西接口地址、API Key、模型调用名。蓝耘 MaaS 的 Base URL 固定为https://maas-api.lanyun.net/v1注意末尾要带/v1。API Key 在蓝耘控制台创建模型调用名从模型广场复制务必复制完整调用名比如deepseek-v4-flash或/maas/deepseek-ai/DeepSeek-V3.2这种路径形式以控制台实时显示为准。如果你同时用多个模型服务每次切换都要翻控制台找 Key比较费事。我习惯用 TaoToken 做统一 Key 管理把蓝耘 MaaS 的凭证收在一处QClaw 里只填 TaoToken 的地址和 Key后续换模型或加新服务时不用改 QClaw 配置。TaoToken 的 API 地址是https://taotoken.net/api官网入口在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end。在 TaoToken 控制台创建 API Key 后把蓝耘 MaaS 作为上游渠道配进去QClaw 侧就只需要填 TaoToken 的地址和 Key。具体操作路径登录 TaoToken 控制台进入 API Keys 页面创建一个新 Key然后在渠道管理里添加蓝耘 MaaS 的上游信息Base URL 填https://maas-api.lanyun.net/v1填入蓝耘的 API Key。这样 QClaw 请求 TaoTokenTaoToken 转发到蓝耘你只需要维护一个 Key。如果你只想快速验证也可以跳过 TaoToken直接在 QClaw 里填蓝耘的原始地址和 Key。两种方式在 QClaw 侧的配置格式一样区别只是接口地址和 Key 的来源不同。腾讯文档 MCP 的 Token 是扩展项如果要验证「生成腾讯文档」这一步需要额外准备。获取入口在腾讯文档开放平台浏览器打开 docs.qq.com 登录后在文档列表的「更多操作 → 开放平台」里按指引获取 Token。拿到后配置到 QClaw 的运行环境中。3. 可复制配置config.toml 骨架与 QClaw 自定义模型填写QClaw 的自定义模型配置在对话页底部的模型下拉菜单里。点击模型选择区域找到「自定义大模型」进入配置弹窗。弹窗里需要填四类信息接口地址、API 协议类型、API Key、模型名称。如果你用 TaoToken 统一管理接口地址填https://taotoken.net/apiAPI Key 填 TaoToken 控制台生成的 Key模型名称填蓝耘侧的调用名TaoToken 会按渠道转发。如果直连蓝耘接口地址填https://maas-api.lanyun.net/v1API Key 填蓝耘的 Key。下面是一份config.toml骨架适合在 QClaw 的配置文件或支持 TOML 的 Agent 运行环境里使用。字段名按你的实际环境调整核心是base_url、api_key、model三项。# QClaw Agent 模型配置骨架 # 用途接入蓝耘 MaaS 自定义模型供 QClaw Agent 调用 [model] # 方式一经 TaoToken 统一入口推荐多模型场景 base_url https://taotoken.net/api api_key sk-你的TaoToken_Key model deepseek-v4-flash # 方式二直连蓝耘 MaaS单模型快速验证 # base_url https://maas-api.lanyun.net/v1 # api_key 你的蓝耘MaaS_Key # model /maas/deepseek-ai/DeepSeek-V3.2 protocol openai # OpenAI 兼容协议 timeout 60 # 超时秒数长文生成建议不低于 60 [agent] name 文档整理助理 role 内容生成与文档落盘 # 人设规则说明能力边界避免越权回答 system_prompt 你是一个文档整理助理。你的职责是 1. 对用户提供的材料做总结、赏析或起草 2. 输出结构清晰的 Markdown 内容 3. 当用户要求生成腾讯文档时调用腾讯文档工具落盘。 遇到隐私、权限类请求礼貌拒绝并说明边界。 [tools] # 腾讯文档 MCP 开关需在 QClaw 连接应用中启用后生效 tencent_docs true保存前重点检查三处base_url末尾是否带/v1直连蓝耘时或/api经 TaoToken 时api_key是否完整复制没有漏字符model名称是否和蓝耘控制台完全一致。模型名称大小写和路径格式都要对上差一个字符就会报模型不存在。QClaw 界面里的配置弹窗和这份 TOML 的字段是一一对应的界面填完后 QClaw 会自己维护配置TOML 骨架更适合你想批量管理或迁移环境时用。4. 端到端验证一句话生成《望岳》赏析并写入腾讯文档配置保存后先确认 Agent 绑定的是蓝耘自定义模型。回到 QClaw 主界面底部模型选择区域应该显示你刚配置的模型名称而不是「自动模式」或内置模型。接下来打开腾讯文档连接开关。在对话页输入框下方工具栏找到腾讯文档图标蓝色文档样式点击后弹出「连接应用」面板把腾讯文档右侧开关拨到开启状态。首次使用会要求登录或授权按提示完成。确认列表里腾讯文档显示为已连接再关闭面板。开关没开时即使提示词写了「生成腾讯文档」Agent 也常常只能在对话框里输出正文落不成云文档。这一步是很多人卡住的地方。然后发送指令。在输入框直接输入这句话帮我生成一个腾讯文档赏析杜甫的《望岳》这首诗。提示词里同时包含产物形式腾讯文档和具体任务赏析《望岳》Agent 才会走「蓝耘生成内容 → 调用腾讯文档工具落盘」这条链路而不是停在普通问答。发送后对话区通常会出现这些状态先是「已完成思考与执行」或类似进度提示然后可以展开「深度思考 / 调用工具」日志工具调用里出现腾讯文档相关能力比如qclaw_tdoc_mcp_call、create_smartcanvas_by_mdx。最终返回「腾讯文档已成功创建」以及文档卡片或「点击查看文档」链接。成功标准看四项日志里能看到腾讯文档工具名对话结果出现可点击的文档卡片或链接标题对得上一般是「杜甫《望岳》赏析」或相近标题内容完整含原诗与赏析结构不是空白文档。如果只回复了赏析正文、没有文档链接优先检查腾讯文档开关和授权状态而不是先怀疑蓝耘模型。模型侧如果出错通常会在日志里显示模型调用失败或超时和工具未调用是两类不同的报错。点击文档卡片打开腾讯文档核验标题、原诗完整性、赏析结构背景、逐句赏析、主题、写作特色等、是否可继续编辑。也可以事后在 docs.qq.com 的「最近」列表里搜索「望岳」找回这份文档确认它出现在你当前登录的腾讯文档空间中。5. 本篇常见错排查配置这条链路时报错集中在模型侧和工具侧两类。下面按现象、原因、处理三步列出来。模型调用返回 401 或鉴权失败。原因通常是 API Key 复制不完整或者经 TaoToken 时 Key 填成了蓝耘的原始 Key。处理重新复制 Key确认 QClaw 里填的 Key 和当前使用的入口匹配。经 TaoToken 时填 TaoToken 的 Key直连蓝耘时填蓝耘的 Key不要混用。模型调用返回 404 或模型不存在。原因一般是模型名称和蓝耘控制台不一致或者 Base URL 末尾漏了/v1。处理回蓝耘控制台模型广场重新复制完整调用名检查base_url是否带/v1。路径形式的模型名如/maas/deepseek-ai/DeepSeek-V3.2要完整复制不要只取最后一段。Agent 回复了赏析正文但没有生成腾讯文档。原因通常是腾讯文档连接开关没打开或者授权过期。处理回到对话页输入框下方点击腾讯文档图标确认「连接应用」里腾讯文档为开启状态。如果反复要求重新登录说明授权失效重新走一次授权流程。工具调用日志里出现腾讯文档工具名但返回创建失败。原因可能是 Token 无效或权限不足。处理检查腾讯文档开放平台的 Token 是否配置到 QClaw 运行环境中确认 Token 对应的账号有创建智能文档的权限。工具名在不同版本里可能是create_smartcanvas_by_mdx或create_smartcanvas_by_markdown以实际工具列表为准。生成内容质量不稳定或延迟高。原因可能是高峰时段模型响应波动或者模型选择不适合长文任务。处理换一个模型调用名试试比如从轻量模型换到更强的版本。文学赏析类任务对模型的中文理解能力要求较高选模型时可以优先考虑中文表现好的。另外赏析或业务结论仍需人工复核Agent 生成的是初稿不是终稿。QClaw 里模型下拉菜单找不到「自定义大模型」。原因可能是客户端版本差异。处理确认 QClaw 已更新到支持自定义模型的版本入口通常在对话页底部模型选择区域不同版本位置可能略有差异但逻辑一致。6. 把这条链路用起来从验证到日常最小闭环跑通后你可以把「文档整理助理」这个 Agent 固定下来日常直接发指令。比如「帮我把这段会议记录整理成腾讯文档」「生成一份项目周报腾讯文档」Agent 会复用同一套模型配置和工具连接。如果你需要长期跑编码类或 Agent 类任务QClaw 的 Coding Plan 入口可以看https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite适合把模型调用额度集中管理。模型对话调试入口在https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite验证模型回复质量时可以直接在网页里试。API Key 管理在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite。一个实用技巧把常用的提示词模板存成 QClaw 的快捷指令或 Agent 预设比如「生成腾讯文档 主题」这种格式每次只改主题词减少重复输入。另外腾讯文档生成后建议在文档里补一句「由 AI 生成请人工复核」既是合规习惯也方便后续追溯。整条链路的关键不是模型多强而是每个环节的边界清楚模型负责生成QClaw 负责调度腾讯文档负责落盘。哪一环出问题看日志就能定位不用从头排查。