MBAgent 常见问题 FAQ
本文汇总 MBAgent 使用中的常见问题与解决方案。如果您遇到的问题不在本文中，请联系候鸟客服。
一、安装与启动
Q1.1：双击 MBAgent 图标没反应
可能原因：
- 候鸟浏览器没有启动
- 候鸟账号没登录
- 工作目录权限不足
解决：
- 启动候鸟浏览器并登录
- 检查 MBAgent 工作目录是否存在
- 以管理员权限启动 MBAgent
Q1.2：启动后一直显示"选择工作目录"
原因：候鸟浏览器主程序没有启动，MBAgent 无法读取候鸟账号信息。
解决：
- 关闭 MBAgent
- 启动候鸟浏览器并登录
- 重新启动 MBAgent
Q1.3：启动后中文显示乱码
解决：
- Windows 设置 → 时间和语言 → 语言 → Windows 显示语言 → 简体中文（中国）
- 重启电脑
Q1.4：安装时提示"已安装更新版本"
解决：
- 控制面板 → 程序与功能 → 卸载旧版候鸟
- 删除
C:\Program Files\Mbbrowser - 重新安装新版本
二、连接候鸟浏览器
Q2.1：MBAgent 显示"等待候鸟 CDP"
可能原因：
- 候鸟浏览器未启动
- ControlV2 端口被占用
- 防火墙拦截
解决：
- 启动候鸟浏览器
- 检查候鸟 → 设置 → ControlV2 是否开启
- 关闭防火墙 / 杀毒软件
Q2.2：AI 操作不了候鸟浏览器
排查步骤：
- 进入 "设置 → 官方服务检测"
- 点击 "候鸟客户端 ControlV2" 的 "开始检测"
- 查看具体失败步骤
Q2.3：AI 操作候鸟总是失败
可能原因：
- 候鸟账号额度用完
- 候鸟环境损坏
- 网络问题
解决：
- 检查候鸟账号 AI 额度
- 在候鸟浏览器里手动测试该环境
- 联系候鸟客服
Q2.4：能否控制远程候鸟浏览器？
✅ 可以，但需要：
- 远程机器启动候鸟浏览器
- 暴露 ControlV2 端口
- 在 MBAgent 里配置远程 IP + 端口
⚠️ 仅在可信网络（VPN / 内网）使用。
三、模型与 Provider
Q3.1：模型列表是空的
原因：候鸟账号未开通 AI 模型额度。
解决：
- 访问候鸟控制台
- 进入 "AI 模型" → 开通额度
- 回到 MBAgent → 刷新模型列表
Q3.2：切换 Provider 后列表没变化
排查：
- 检查该 Provider 是否配置了 API Key
- 测试连接是否成功
- 重启 MBAgent
Q3.3：自建 Provider 连不上
排查：
- 检查 API Key 和 Base URL 是否正确
- 测试网络连通性（ping / curl）
- 查看 MBAgent 日志（
%LOCALAPPDATA%\mbagent\logs\）
Q3.4：模型响应很慢
可能原因：
- 网络问题
- 模型过载
- 上下文太长
解决：
- 切换到更快模型
- 压缩会话历史（
/compact） - 检查网络
四、任务与定时
Q4.1：定时任务没有按预期触发
排查：
- 检查 cron 表达式
- 检查 MBAgent 是否启动（未安装 Daemon）
- 查看任务历史
- 确认系统时间
Q4.2：电脑休眠时任务不执行
解决：
- 安装 MBAgent Daemon
- 设置电脑不休眠
- 配置唤醒定时器
Q4.3：任务一直失败
排查：
- 单独运行任务，看错误
- 检查候鸟浏览器在线状态
- 简化任务描述，逐步排查
- 联系候鸟客服
Q4.4：定时任务消耗太多 Token
解决：
- 用便宜模型
- 关闭"显示思考过程"
- 减少执行频率
- 优化提示词
五、文件与附件
Q5.1：上传大文件失败
限制：
- 单文件建议 < 50 MB
- 超大文件（>100 MB）请用 AI 工具读取路径
解决：
- 压缩文件（zip）
- 用 Read 工具让 AI 自己读
- 分块上传
Q5.2：AI 看不到图片
可能原因：
- 当前模型不支持多模态
- 图片太大
- 图片格式不支持
解决：
- 切换到支持多模态的模型（gpt-5、claude-sonnet-4）
- 压缩图片
- 转成 JPG / PNG
Q5.3：AI 修改的文件没保存
排查：
- 是否点错了"拒绝"
- 工作目录是否有写权限
- 检查 AI 记忆库里是否记录了错误路径
六、权限与安全
Q6.1：如何撤回 AI 的错误操作？
步骤：
- 立即按
Esc停止 AI - 查看操作日志
- 手动撤销 AI 的错误操作
Q6.2：AI 删除了我的文件，怎么恢复？
情况 1：文件在沙盒内（工作目录）
- 如果开启了"备份"，从备份恢复
- 否则需要用专业恢复工具
情况 2：文件在沙盒外（系统目录）
- ⚠️ 这种操作默认会被拦截
- 如果发生了，请立即联系候鸟客服
预防：
- 让 AI 操作重要文件前先备份
- 用 Ask 模式（弹窗确认）
Q6.3：API Key 安全吗？
✅ 安全：
- MBAgent 不会上传 API Key
- Key 仅存储在 Windows 凭据管理器
- 卸载 MBAgent 时凭据会清除
⚠️ 建议：
- 定期轮换 API Key
- 不要在记忆库或会话里贴明文 Key
七、AI 记忆库
Q7.1：AI 似乎没"记住"我之前说的话
排查：
- 检查 AI 记忆库是否存在该记忆
- 重新让 AI 记忆并确认
- 检查工作目录是否变更
Q7.2：AI 用了错误的记忆
解决：
- 编辑该记忆
- 修正或删除
Q7.3：如何备份记忆库？
- 找到目录：
%LOCALAPPDATA%\mbagent\memory\ - 复制整个文件夹
- 存到安全位置
八、界面与显示
Q8.1：界面卡顿
可能原因：
- 系统资源不足
- 太多会话 / KMS / MCP 加载
- 主题渲染问题
解决：
- 关闭不需要的标签
- 减少会话数量
- 切换主题（深色 < 浅色）
- 重启 MBAgent
Q8.2：字体显示异常
解决：
- 检查系统字体是否完整
- 在 MBAgent 设置里切换字体
Q8.3：标签栏看不到
解决：
- 设置 → 界面与导航 → 显示哪些标签 → 全部勾选
- 重启 MBAgent
九、性能优化
Q9.1：MBAgent 占用内存高
正常范围：
- 空闲时：200-500 MB
- 复杂任务：1-2 GB
- 高并发：2-4 GB
优化：
- 关闭不需要的会话
- 减少并发任务数
- 卸载不用的 MCP 服务
Q9.2：AI 回复慢
可能原因：
- 模型服务器延迟
- 网络问题
- 上下文太长
优化：
- 切换到更快模型
- 压缩历史
- 检查网络
十、更新与升级
Q10.1：如何更新 MBAgent？
MBAgent 随候鸟浏览器一起更新：
- 候鸟浏览器启动时自动检测新版本
- 弹出更新提示
- 点击 "立即更新"
- 更新后重启
Q10.2：更新后数据丢失了？
不会：
- AI 记忆库、会话、KMS 都保留
- 仅配置文件可能被重置
如果数据丢失：
- 检查备份目录
- 从备份恢复
- 联系候鸟客服
Q10.3：能否回滚到旧版本？
可以，但需要：
- 备份当前数据
- 卸载当前版本
- 安装旧版本
- 恢复数据
⚠️ 注意：旧版本可能不支持新功能。
十一、错误代码
BROWSER_AUTO_UNAVAILABLE
含义：浏览器自动化能力不可用。 原因：Playwright MCP browser 未启动。 解决：
- 安装 Node.js 和 npx
- 让 MBAgent 自动安装 Playwright
- 重启 MBAgent
CONTROL_V2_DISCOVERING
含义：正在发现候鸟客户端实例。 原因：刚刚启动或正在扫描。 解决：等待几秒后重试。
CONTROL_V2_HANDSHAKE_SPEC_MISMATCH
含义：MBAgent 和候鸟客户端使用的 ControlV2 规范版本不同。 解决：
- 更新候鸟浏览器到最新版
- 更新 MBAgent 到最新版
TOOL_ENABLE_PREREQUISITE_MISSING
含义：工具的前置条件未满足。 解决：
- 检查是否启用了对应的 Skill
- 检查候鸟账号授权等级
Houniao RAG 知识库当前不可用
含义：候鸟官方 RAG 知识库服务异常。 解决：
- 检查候鸟账号是否有效
- 检查网络
- 联系候鸟客服
候鸟客户端 ControlV2 当前不可用
含义：候鸟浏览器 ControlV2 协议异常。 解决：
- 重启候鸟浏览器
- 重启 MBAgent
- 查看候鸟浏览器 → 设置 → ControlV2
十二、获取帮助
官方渠道
- 官方文档：https://help.mbbrowser.com/mbagent
- 候鸟控制台：https://www.mbbrowser.com/console
- 客服微信：见候鸟官网
- 客服邮箱：support@mbbrowser.com
自助排查
- 查看 MBAgent 日志：
%LOCALAPPDATA%\mbagent\logs\ - 查看候鸟浏览器日志
- 用 "设置 → 官方服务检测" 检查服务状态
反馈问题
联系客服时，请提供：
- MBAgent 版本号
- 候鸟浏览器版本号
- Windows 版本
- 完整错误信息
- 操作步骤
- 必要时提供日志文件
下一步：返回 MBAgent 栏目简介 或 下载安装 MBAgent。