# 常见问题与解决方案

在使用 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）运行您的终端或命令提示符。
    ```bash
    # 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 配置。
    ```bash
    gemini cli-init
    ```

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

**问题描述**:
- 智能代理的响应质量不佳，不相关或不准确。
- 代理响应速度慢，或提示达到速率限制。

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

**解决方案**:
1.  **优化提示**: 尝试使用 `enhance-prompt` 命令来优化您的输入，提供更清晰、更具体的上下文信息。
2.  **选择合适的工具**: 根据任务类型，使用 `--tool` 标志选择最合适的 LLM 模型（如 `codex` 适用于代码生成，`gemini` 适用于复杂推理）。
    ```bash
    gemini analyze --tool gemini "分析这个复杂算法"
    ```
3.  **检查 API 密钥和配额**: 确保您的 LLM 服务 API 密钥有效，并且没有超出使用配额。
4.  **重试或等待**: 如果是速率限制或服务中断，请稍后重试或联系服务提供商。

## 5. 寻求帮助

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

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

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