故障排除

本文档提供常见问题的解决方案。

---

安装问题

问题：安装脚本下载失败

症状：运行安装命令时报网络错误

解决方案：

1. 检查网络连接
2. 尝试使用代理
3. 手动下载安装：访问 https://carrycode.ai/releases

问题：权限被拒绝

症状：Permission denied 错误

解决方案：

# Linux/macOS
sudo sh install.sh

# Windows
以管理员身份运行 PowerShell

问题：找不到 carry 命令

症状：安装成功但无法运行

解决方案：

1. 确认安装路径在 PATH 中
2. 重新加载终端配置：source ~/.bashrc 或 source ~/.zshrc
3. 检查安装位置：ls /usr/local/bin/carry

---

连接问题

问题：无法连接到 AI 服务

症状：提示网络错误或超时

解决方案：

1. 检查网络连接
2. 如果使用代理，配置代理环境变量
3. 尝试更换 AI 服务商
4. 检查 API Key 是否正确

问题：API Key 无效

症状：提示 API Key 错误

解决方案：

1. 确认 API Key 复制完整
2. 登录服务商后台检查 Key 状态
3. 重新生成 API Key

---

界面问题

问题：界面显示错乱

症状：字符显示位置不对

解决方案：

1. 切换主题：/theme
2. 更换终端应用
3. 检查终端编码设置（应为 UTF-8）

问题：中文显示乱码

症状：中文字符显示异常

解决方案：

1. 确认终端支持 UTF-8
2. 设置环境变量：export LANG=en_US.UTF-8

问题：主题不生效

症状：切换主题后没有变化

解决方案：

1. 重新启动 CarryCode
2. 检查配置文件格式

---

功能问题

问题：AI 无法读取文件

症状：提示文件不存在或权限不足

解决方案：

1. 确认文件路径正确
2. 检查文件权限
3. 确认文件在工作区内

问题：AI 无法执行命令

症状：命令执行失败

解决方案：

1. 检查审批模式设置
2. 确认命令语法正确
3. 检查命令权限

问题：MCP 服务器连接失败

症状：MCP 服务器无法连接

解决方案：

1. 确认服务器正在运行
2. 检查服务器地址
3. 测试网络连接
4. 查看服务器日志

---

性能问题

问题：响应速度慢

症状：AI 回复等待时间长

解决方案：

1. 选择网络更好的服务商
2. 使用更轻量的模型
3. 检查本地网络速度

问题：内存占用高

症状：系统内存占用过大

解决方案：

1. 压缩会话上下文：/compact
2. 创建新会话
3. 关闭不必要的应用

问题：Token 超限

症状：提示 token 超出限制

解决方案：

1. 使用 /compact 压缩上下文
2. 创建新会话
3. 使用更简洁的提示词

---

配置问题

问题：配置文件格式错误

症状：配置不生效

解决方案：

1. 检查 JSON 格式是否正确
2. 使用 JSON 验证工具
3. 删除配置文件重新配置

问题：AGENTS.md 不生效

症状：规则没有应用

解决方案：

1. 确认文件在项目根目录
2. 检查文件格式
3. 重新启动 CarryCode

---

会话问题

问题：会话无法保存

症状：重启后对话丢失

解决方案：

1. 检查会话目录权限
2. 确认磁盘空间充足
3. 查看日志文件

问题：无法切换会话

症状：切换会话失败

解决方案：

1. 确认会话名称正确
2. 检查会话文件是否存在
3. 重启 CarryCode

---

更新问题

问题：更新失败

症状：/update 命令失败

解决方案：

1. 检查网络连接
2. 手动下载新版本
3. 重新安装

问题：更新后功能异常

症状：新版本出现问题

解决方案：

1. 回滚到旧版本
2. 删除配置重新设置
3. 报告问题到 GitHub

---

获取帮助

如果以上方法都无法解决问题：

1. 查看文档：https://docs.carrycode.ai
2. 社区支持：https://carrycode.ai
3. 报告问题：https://github.com/carrycode/carrycode/issues