Claude-Code-Workflow/.claude/skills/command-guide/guides/troubleshooting.md

常见问题与解决方案

在使用 Gemini CLI 的过程中，您可能会遇到一些问题。本指南旨在帮助您诊断和解决这些常见问题，确保您能顺利使用 CLI。

1. 命令执行失败或未找到

问题描述:

• 您输入的命令没有响应，或者系统提示“命令未找到”。
• 命令执行后出现错误信息，但您不理解其含义。

可能原因:

• 命令拼写错误。
• CLI 未正确安装或环境变量配置不正确。
• 命令所需的依赖项缺失。
• 命令参数不正确或缺失。

解决方案:

1. 检查拼写: 仔细核对您输入的命令是否正确，包括命令名称和任何参数。
2. 查看帮助: 使用 gemini help 或 gemini [command-name] --help 来查看命令的正确用法、可用参数和示例。
3. 验证安装: 确保 Gemini CLI 已正确安装，并且其可执行文件路径已添加到系统的环境变量中。您可以尝试重新安装 CLI。
4. 检查日志: CLI 通常会生成日志文件。查看这些日志可以提供更详细的错误信息，帮助您定位问题。
5. 更新 CLI: 确保您使用的是最新版本的 Gemini CLI。旧版本可能存在已知错误，通过 gemini version 检查并更新。

2. 权限问题

问题描述:

• CLI 尝试读取、写入或创建文件/目录时，提示“权限被拒绝”或类似错误。
• 某些操作（如安装依赖、修改系统配置）失败。

可能原因:

• 当前用户没有足够的权限执行该操作。
• 文件或目录被其他程序占用。

解决方案:

1. 以管理员身份运行: 尝试以管理员权限（Windows）或使用 sudo（Linux/macOS）运行您的终端或命令提示符。

   # Windows (在命令提示符或 PowerShell 中右键选择“以管理员身份运行”)
   # Linux/macOS
   sudo gemini [command]
   

2. 检查文件/目录权限: 确保您对目标文件或目录拥有读/写/执行权限。您可能需要使用 chmod (Linux/macOS) 或修改文件属性 (Windows) 来更改权限。
3. 关闭占用程序: 确保没有其他程序正在使用您尝试访问的文件或目录。

3. 配置问题

问题描述:

• CLI 行为异常，例如无法连接到 LLM 服务，或者某些功能无法正常工作。
• 提示缺少 API 密钥或配置项。

可能原因:

• 配置文件（如 .gemini.json 或相关环境变量）设置不正确。
• API 密钥过期或无效。
• 网络连接问题导致无法访问外部服务。

解决方案:

1. 检查配置文件: 仔细检查 Gemini CLI 的配置文件（通常位于用户主目录或项目根目录）中的设置。确保所有路径、API 密钥和选项都正确无误。
2. 验证环境变量: 确认所有必要的环境变量（如 GEMINI_API_KEY）都已正确设置。
3. 网络连接: 检查您的网络连接是否正常，并确保没有防火墙或代理设置阻止 CLI 访问外部服务。
4. 重新初始化配置: 对于某些配置问题，您可能需要使用 gemini cli-init 命令重新初始化 CLI 配置。

   gemini cli-init
   

4. 智能代理 (LLM) 相关问题

问题描述:

• 智能代理的响应质量不佳，不相关或不准确。
• 代理响应速度慢，或提示达到速率限制。

可能原因:

• 提示不够清晰或缺乏上下文。
• 选择了不适合当前任务的 LLM 模型。
• LLM 服务提供商的速率限制或服务中断。

解决方案:

1. 优化提示: 尝试使用 enhance-prompt 命令来优化您的输入，提供更清晰、更具体的上下文信息。
2. 选择合适的工具: 根据任务类型，使用 --tool 标志选择最合适的 LLM 模型（如 codex 适用于代码生成，gemini 适用于复杂推理）。

   gemini analyze --tool gemini "分析这个复杂算法"
   

3. 检查 API 密钥和配额: 确保您的 LLM 服务 API 密钥有效，并且没有超出使用配额。
4. 重试或等待: 如果是速率限制或服务中断，请稍后重试或联系服务提供商。

5. 寻求帮助

如果以上解决方案都无法解决您的问题，您可以：

• 查阅官方文档: 访问 Gemini CLI 的官方文档获取更全面的信息。
• 社区支持: 在相关的开发者社区或论坛中提问。
• 提交问题: 如果您认为是 CLI 的 bug，请在项目的问题跟踪器中提交详细的问题报告。

希望本指南能帮助您解决遇到的问题，让您更好地利用 Gemini CLI！