下载与安装失败
- 官网下载缓慢或中断
尝试更换浏览器或开启下载工具；企业内网用户请确认防火墙未拦截官网域名，必要时联系网络管理员添加白名单。
- Windows 安装被拦截
若弹出"Windows 已保护你的电脑"，点击"更多信息"→"仍要运行"；若杀毒软件已隔离安装包，需进入隔离区恢复，并将 CodeBuddy 安装目录加入信任白名单。
- macOS 提示"无法打开"或"已损坏"
前者前往 系统设置 > 隐私与安全性 > 安全性 点击"仍要打开"；后者在终端执行 xattr -cr /Applications/CodeBuddy.app 清除扩展属性后重试。
- Linux AppImage 无法启动
确认已执行 chmod +x 赋予执行权限；若提示缺少 FUSE，安装 libfuse2 即可。Wayland 环境下出现界面异常时，可强制以 XWayland 模式启动。
- VS Code 插件搜索不到
确认网络可正常访问官方扩展市场；若身处受限网络，可前往官网下载 .vsix 文件，通过扩展面板的"从 VSIX 安装"手动部署。
启动异常
- 客户端白屏、闪退或持续加载
先完全退出程序后重新打开；无效则卸载并重新安装最新版本。Windows 用户可尝试右键以管理员身份运行，或检查是否与其他安全软件进程冲突。
- VS Code 安装插件后侧边栏空白
重启 VS Code；若仍无显示，检查是否与其他 AI 插件冲突，或尝试在命令面板（Ctrl+Shift+P / Cmd+Shift+P）输入"CodeBuddy"手动唤起。
登录环节问题
- 手机号/邮箱收不到验证码
确认号码或地址拼写无误；检查垃圾短信箱或邮件垃圾箱；确认手机未开启拦截规则。企业内网需排查是否屏蔽了短信网关或邮件服务器，等待 60 秒后重新获取。
- 第三方扫码无响应
确认手机端已点击"确认授权"；检查客户端网络连通性。若长时间未跳转，建议直接改用验证码方式登录。
- 企业 SSO 登录失败
向 IT 管理员核实企业标识码是否正确，并确认你的账号已被添加到该组织成员列表。若企业内部认证平台会话过期，需先在浏览器中重新登录企业门户，再回到 CodeBuddy 重试。
- 登录状态频繁失效
长时间未操作或检测到网络环境变动（如切换 VPN、代理）时，系统会要求重新验证，云端数据不会丢失。若一天内多次掉线，建议检查网络代理配置，保持 IP 段相对稳定。