> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cowagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# v2.2.2

> CowAgent 2.2.2：新增访客独立页面和窗口嵌入，支持自定义主题，主模型原生多模态输入，新模型接入，工具、通道与安全性完善

🌐 [English](https://docs.cowagent.ai/releases/v2.2.2.md) | [中文](https://docs.cowagent.ai/zh/releases/v2.2.2.md)

## 🌐 访客页面

可将 Agent 分享为独立的对话页面，或以对话窗口的形式嵌入网站，访客打开链接即可对话，无需登录，适用于产品咨询、知识库问答、在线客服等场景：

* **独立页面**：每个页面生成独立链接，访客保留历史会话，支持自定义名称、图标、主题色、欢迎语与引导问题。

![访客页面](https://cdn.link-ai.tech/doc/guest-share-page-zh.png)

* **窗口嵌入**：复制一段代码即可嵌入网站，页面右下角显示对话入口，可限制允许嵌入的网站，配置时可直接预览嵌入效果。

![嵌入网页](https://cdn.link-ai.tech/doc/guest-share-embed-zh.png)

* **数据隔离**：访客使用的 Agent 只能调用为该页面开放的工具、技能和参考资料，无法访问你的记忆、对话和工作空间，不提供命令执行，联网请求仅限公网地址；新建页面默认不开启文件写入、文件发送与联网搜索。
* **参考资料**：可直接选择知识库或其中的某个分类作为只读资料，并为每项附上用途说明。
* **访问控制**：支持访问密码、每人每日提问次数与有效期；可按访客查看对话记录，随时重置链接、停用或删除页面。

![编辑访客页面](https://cdn.link-ai.tech/doc/guest-share-editor-zh.png)

Thanks @LanydLi #3113

相关文档：[访客页面](https://docs.cowagent.ai/zh/extensions/guest-share.md)

## 🎨 自定义主题

Web 控制台与桌面客户端支持主题切换，两端共用同一主题目录：

* **导入主题**：将主题 zip 包或文件夹拖入即可导入，支持自定义配色、背景壁纸与新对话页图标，主题保存在 `~/cow/system/themes/`。
* **Agent 生成主题**：描述想要的风格或附上参考图，Agent 即可生成配色、壁纸与图标，生成后可直接切换使用。
* **内置主题**：提供 Meadow、Ocean、Clay、Sakura、Lavender 五套配色，均适配浅色与深色模式。

![自定义主题](https://cdn.link-ai.tech/doc/custom-theme-zh.png)

相关文档：[自定义主题](https://docs.cowagent.ai/zh/extensions/custom-theme.md)

## 🖼 主模型图像理解优化

主模型具备视觉能力时，图片作为多模态输入直接参与推理，单次调用完成理解与回答，避免经图像理解工具转述造成的细节损失，界面还原、图表分析等任务效果显著提升（Thanks @592774447 #3608）。

* **启用条件**：图像理解模型设为「自动」或与主模型一致时生效，无需额外配置。
* **上下文开销**：仅当前轮次携带图片，历史轮次保留图片引用，不重复计入 Token；请求因图片被拒绝时自动降级为纯文本重试。
* **厂商适配**：Claude、Gemini、通义千问按各自原生格式传图。
* **识别精度**：图片压缩上限提升至 3MB / 3072px，保留更多文字与细节。

## 🔗 集成配置与访问地址

「配置」页新增「集成配置」，Web 控制台与桌面客户端均已支持，集中管理访客页面、对话 API 与访问地址：

* **访问地址**：可在线修改监听 IP 与端口，保存后直接切换到新地址，无需重启，新地址不可用时恢复原地址；显示本机局域网地址，并可设置对外展示地址，用于分享链接与嵌入代码。
* **HTTPS 与域名**：支持控制台直接启用 HTTPS，并补充 nginx 反向代理部署说明（Thanks @anshlakhera048 #3774、@592774447 #3768）。
* **登录保护**：同一来源连续输错密码将被临时锁定；本机访问单独计数，外部猜测密码不会导致本机无法登录。
* **对话 API**：同一会话的并发请求按顺序处理（Thanks @rudycelekli #3751）。

![集成配置](https://cdn.link-ai.tech/doc/integrations-zh.png)

相关文档：[Web 控制台 - 访问地址](https://docs.cowagent.ai/zh/channels/web.md#访问地址)

## 🤖 模型能力

* **新模型**：新增 `kimi-k3.1-pro`（Kimi 默认模型）、`MiniMax-M3.1-Flash`、`gpt-6.1-terra`（OpenAI 默认模型）、`claude-sonnet-5-5`、`claude-haiku-5-5`、`gemini-4-argon`（Gemini 默认模型）（Thanks @octo-patch #3791）。
* **小米 MiMo**：新增 `mimo-v2.5-asr` 语音识别；对话模型升级至 V2.6，旧模型 ID 自动映射（Thanks @592774447 #3788）。
* **模型显示名称**：自定义厂商的模型可设置显示名称，模型选择器中展示该名称，调用时仍使用原始模型 ID（Thanks @592774447 #3852）。
* **默认上下文**：Agent 默认上下文上限由 64K 提升至 200K Token，最大步数由 30 提升至 100，保留轮次由 20 提升至 30。
* **流式输出**：Claude 流式过程中的错误会如实返回，不再静默结束；兼容以断开连接作为结束标志的流式响应；各厂商流式连接在任意退出路径下均正确释放（Thanks @rudycelekli #3693, #3822、@a1094174619 #3847）。
* **OpenAI**：Responses 接口正确处理拒答内容、截断的工具参数与失败响应；图像接口重试时保留自定义地址（Thanks @rudycelekli #3691, #3692, #3702, #3706）。
* **追加消息**：智谱、通义千问、MiniMax 在工具结果之后保留运行中追加的消息；Gemini 非对象类型的工具结果正确封装（Thanks @rudycelekli #3825, #3826, #3827、@pei711 #3843）。
* **语音**：修复 MiniMax、Google、OpenAI 语音接口的连接释放、错误识别与地址拼接问题，相同文本重复合成时输出文件互不覆盖，手动朗读对应所点击的消息版本（Thanks @rudycelekli #3688, #3700, #3708, #3710, #3714, #3720, #3803）；识别结果异常时返回错误提示，各类回复路径下及时清理临时文件（Thanks @c020627 #3759, #3835, #3837、@rudycelekli #3815）。
* **其他**：Gemini 用量统计计入思考 Token，非流式响应同样返回准确的 Token 用量（Thanks @pcbeingused333 #3850, #3855）；ModelScope 流式响应兼容空 `choices` 数据块，模型能力列表互不干扰，识图失败时及时清理临时文件（Thanks @rudycelekli #3704, #3813, #3821）。

## 🧩 技能与工具

* **联网搜索**：接入 DeepSeek 官方 Search 与 Fetch API，配置 DeepSeek 密钥后自动启用并作为默认搜索厂商（Thanks @anshlakhera048 #3776、@592774447 #3775）；可单独停用某个搜索厂商并保留凭证；无需密钥的匿名搜索需显式开启（Thanks @rudycelekli #3705）。
* **技能**：桌面客户端技能页显示图标与版本；可通过 `skill_hub_url` 配置自定义技能仓库，按名称安装和搜索，未收录的技能自动从默认 Skill Hub 获取；对话中的技能命令仅作用于当前 Agent。
* **技能管理**：替换安装失败时保留原技能，启用 / 停用失败时恢复原状态，兼容带 BOM 的文件及多种元数据格式，单个配置项损坏不再影响其他技能（Thanks @rudycelekli #3685, #3690, #3695, #3696, #3698, #3711, #3753, #3754、@c020627 #3760）。
* **终端**：修复 Windows 下命令无输出、多行 Python 命令被截断的问题（Thanks @keeponlight #3795、@rudycelekli #3811、@Nolan527 #3793）；超长行截断后仍保留完整输出（Thanks @rudycelekli #3779）；Windows 下完整输出日志保留命令原有的换行，按提示的行号回读时位置准确（Thanks @tanishqbaweja #3858）。
* **语法校验**：写入前的语法校验兼容 `tsconfig.json`、VS Code 配置、Helm 模板等带注释或模板语法的文件，`package.json` 等严格 JSON 文件仍会拦截注释并给出修改提示（Thanks @tanishqbaweja #3853）。
* **文件读写与搜索**：模糊匹配编辑不再在替换内容前后多出空行，覆盖写入时保留文件原有的换行符，Windows 下不再统一转为 CRLF（Thanks @tanishqbaweja #3854, #3856）；超长行可按偏移读取，保留 CR 换行与模糊匹配时的缩进，编码回退失败时不覆盖原文件，拒绝读写目录与特殊文件，文件读取记录限定在当前对话内；未安装 ripgrep 时目录过滤同样生效（Thanks @rudycelekli #3689, #3715, #3752, #3770, #3772, #3794, #3799, #3810）。
* **文档解析**：完整读取 Word 内容控件、域结果与合并单元格，Excel 读取超出声明范围的单元格（Thanks @ningyixi #3786, #3787、@rudycelekli #3773, #3777, #3798）。
* **浏览器**：快照可限定到指定元素，截图保存到当前项目，输入框必须提供明确文本才会填写；浏览器配置目录精确匹配，相似路径不再误判为占用；Windows 下进程探测增加超时保护（Thanks @rudycelekli #3724, #3725, #3727, #3802、@c020627 #3769）。
* **图像理解**：压缩图片保持原始显示方向，模型返回空结果时继续尝试备用厂商（Thanks @rudycelekli #3712, #3726, #3806）。
* **MCP 与定时任务**：MCP 连接失败按工具调用失败返回，忽略损坏的授权记录；定时任务执行结果准确对应到具体运行，执行期间修改的计划不再被覆盖，被拒绝的操作如实返回失败，旧版提醒迁移更可靠（Thanks @rudycelekli #3713, #3745, #3781, #3782, #3807, #3808）。

## 🤝 多 Agent 协作

* **子 Agent**：仅在深度调研等必要场景下委派，临近超时时自动收尾并返回已有结果；本地委派遵循配置的超时时间，参数错误或模板目录不可读时不再中断（Thanks @rudycelekli #3783、@c020627 #3761）。
* **团队协作**：@提及可正确识别紧随其后的句末标点（Thanks @c020627 #3738）。
* **上下文**：循环检测提示在模型使用后即移除，不再残留于上下文（Thanks @NotZhu #3851）；清除上下文后的新消息正常保留，通道对话的执行步骤写入历史短暂失败后自动重试，不再丢失工具记录（Thanks @rudycelekli #3734, #3804）。

## 📡 通道能力

* **微信**：扫码登录更稳定，二维码过期自动刷新，可选配置 `weixin_proxy` 代理（Thanks @c020627 #3838）；发送文件保留原始文件名与类型（Thanks @6vision #3817）；修复媒体下载失败时连接未释放的问题（Thanks @rudycelekli #3750）。
* **飞书**：富文本消息支持解析文件及多语言正文。
* **文件发送**：飞书、钉钉、企业微信智能机器人、微信客服发送文件时保留原始文件名。
* **钉钉**：群聊文件按发送者区分，及时清理媒体临时文件（Thanks @rudycelekli #3762、@c020627 #3828）。
* **企业微信 / 公众号**：企业微信转存图片保持原始显示方向（Thanks @c020627 #3845）；公众号未配置对话前缀时关注欢迎语正常发送（Thanks @rudycelekli #3707）。
* **Telegram / Discord / Slack**：支持发送远程链接形式的文件；群聊 @ 机器人时完整匹配用户名，超大附件在下载前拦截，不再回复工作区系统通知（Thanks @rudycelekli #3716, #3764, #3765, #3818, #3819, #3820）。
* **插件**：群管理员按 ID 精确匹配（Thanks @rudycelekli #3763）。

## 🛡 安全加固

* **定时任务权限**：定时执行的 Agent 任务沿用创建时所在会话的权限模式，只读会话中创建的任务无法执行写操作（Thanks @EddieMurphy89 #3833）。
* **访客请求防护**：代表访客发起的网络请求强制拦截本机与内网地址；访客页面密码不可与控制台密码相同。
* **控制台密码**：新设置的密码至少 6 位，输入时提示密码强度，已设置的密码不受影响。
* **资源限制**：模型返回文件的下载大小受限（Thanks @c020627 #3832）。
* **安全策略**：新增安全策略文档与私密漏洞报告渠道。

## 🛠 体验优化与修复

* **对话交互**：回复生成过程中可自由上翻查看，回到底部按钮与输入框对齐，滚动到顶部时自动加载更早的消息（Thanks @LYLMagui #3785）；点击输入区空白处自动聚焦输入框（Thanks @Rofds #3830）。
* **流畅度**：修复回复集中到达时界面卡顿的问题；长会话中屏幕外的消息不再参与渲染，输入与滚动更流畅（Thanks @zkjqd #3792）。
* **宽屏适配**：桌面客户端的对话区域随窗口宽度自适应（Thanks @zkjqd #3844、@592774447 #3839）。
* **会话**：重启后保留上下文用量图（Thanks @xiao115255 #3767、@jiangch1128 #3619）；主模型调用失败时使用备用模型生成标题；消息发送失败时显示具体原因；删除失败时保留原有对话记录（Thanks @rudycelekli #3809）；产物索引失败时不再产生重复的对话记录。
* **文件显示**：发送工作空间外的文件时自动复制到工作空间，控制台中可正常显示；无法加载的图片显示文件名提示；桌面客户端的文件预览支持在文件夹中显示。
* **知识图谱**：修复交叉引用无法解析导致节点无标题、连线全部丢失的问题；兼容相对知识库根目录、文件名、尖括号等写法，以及知识库目录位于软链接下的情况。
* **控制台**：配置保存失败时保留正在运行的配置，工作空间文件并发保存时提示冲突；修复工作空间文件刷新、编辑器内容校验、偏好设置保存与请求取消范围等问题；已注册 Agent 工作空间中的产物可正常访问，知识库文档替换更可靠（Thanks @rudycelekli #3733, #3746, #3747, #3748, #3749, #3755, #3784, #3801, #3805）。
* **Agent 初始化**：空的身份文件不再跳过初始引导，并发初始化不再覆盖已有配置（Thanks @rudycelekli #3722, #3730）；轨迹评测正确校验预期工具与执行状态（Thanks @xiong-wei1 #3849, #3848）。
* **日志与 CLI**：实时日志在文件截断后继续输出，数据目录不可写时保留控制台输出；后台启动服务时脱离标准输入，修复权限不足时进程 ID 丢失、更新状态文件损坏等问题（Thanks @rudycelekli #3686, #3687, #3709, #3717, #3719, #3780, #3800, #3812, #3814）。
* **配置与备份**：并发创建数据目录不再报错，远程推送的配置写入实际读取的数据目录，恢复备份后保留技能脚本的可执行权限（Thanks @rudycelekli #3723, #3778、@c020627 #3823）。
* **桌面客户端**：内置后端的版本号与客户端保持一致（Thanks @592774447 #3839）；Windows 安装时文件复制异常后自动重新解压；修复从终端或启动器打开客户端后，对方退出导致日志不断写入、占满磁盘的问题（Thanks @ClearloveUzi7 #3860）。

## 📦 升级方式

* **源码部署**：执行 `cow update` 一键升级，或在 Web 控制台侧边栏版本菜单中一键更新，也可手动拉取代码后重启。详见 [更新升级文档](https://docs.cowagent.ai/zh/guide/upgrade.md)。
* **桌面客户端**：可在客户端内自动检查并一键更新，或前往 [下载页](https://cowagent.ai/zh/download/) 获取最新版本。

**发布日期**：2026.10.30 | [Full Changelog](https://github.com/zhayujie/CowAgent/compare/2.2.1...2.2.2)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.