> ## Documentation Index
> Fetch the complete documentation index at: https://cat.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 终端集成故障排除指南

> 解决 Cline 中终端集成问题的完整指南

本指南帮助您解决 Cline 中的终端集成问题。终端集成对于 Cline 执行命令和读取其输出至关重要，使其能够理解错误、测试结果和命令响应。

> [!TIP]
>
> 如果您遇到终端问题，请尝试在 Cline 设置的"终端设置"下切换到更简单的 shell，如 `bash`
>
> 这能解决大多数终端集成问题。

## 快速诊断流程图

按照此流程图快速识别您的问题：

```mermaid
graph TD
    A[终端问题] --> B{Cline 能执行命令吗？}
    B -->|否| C[Shell 集成不可用]
    B -->|是| D{Cline 能看到输出吗？}
    D -->|否| E[输出捕获失败]
    D -->|是| F{输出是否损坏？}
    F -->|是| G[字符过滤问题]
    F -->|否| H{命令是否挂起？}
    H -->|是| I[长时间运行命令问题]
    H -->|否| J[检查终端设置]

    C --> K[尝试解决方案 1]
    E --> L[尝试解决方案 2]
    G --> M[尝试解决方案 3]
    I --> N[尝试解决方案 4]

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style K fill:#9f9,stroke:#333,stroke-width:2px
    style L fill:#9f9,stroke:#333,stroke-width:2px
    style M fill:#9f9,stroke:#333,stroke-width:2px
    style N fill:#9f9,stroke:#333,stroke-width:2px
```

## 常见问题和快速解决方案

### 1. Shell 集成不可用

**症状：**

* 消息："Shell Integration Unavailable"
* 命令执行但 Cline 无法读取输出
* 终端手动工作正常但与 Cline 一起使用时不行

**快速解决方案：**

#### macOS

* **切换到 bash**

  1. 前往 Cline 设置
  2. 左键点击 **"终端设置"** 标签
  3. 导航到 **"默认终端配置文件"** 并从下拉菜单中选择 **"bash"**

* **临时禁用 Oh-My-Zsh**：

  1. 如果使用 zsh，在终端中输入 `mv ~/.zshrc ~/.zshrc.backup`
  2. 重启 VSCode

* **设置环境**：
  1.a 对于 Zsh 用户，使用以下 Zsh 命令之一编辑您的 shell 配置文件：

  * `nano ~/.zshrc`
  * `vim ~/.zshrc`
  * `code ~/.zshrc`

  1.b 对于 Bash 用户

  * nano \~/.bash\_profile

  2. 将以下内容添加到您的 shell 配置中：`export TERM=xterm-256color`
  3. 保存您的配置

#### Windows

* **使用 PowerShell 7**

  1. 从 Microsoft Store 安装
  2. 前往 Cline 设置
  3. 左键点击 **"终端设置"** 标签
  4. 导航到 **"默认终端配置文件"** 并从下拉菜单中选择 **"PowerShell 7"**

* **禁用 Windows ConPTY**

  1. 导航到您的 VSCode 设置
  2. 在设置搜索栏中输入 "Integrated: Windows Enable Conpty"
  3. 取消选中该选项

* **尝试命令提示符**
  1. 前往 Cline 设置
  2. 左键点击 **"终端设置"** 标签
  3. 导航到 **"默认终端配置文件"** 并从下拉菜单中选择 **"Command Prompt"**

#### Linux

* **切换到 bash**
  1. 前往 Cline 设置
  2. 左键点击 **"终端设置"** 标签
  3. 导航到 **"默认终端配置文件"** 并从下拉菜单中选择 **"bash"**

* **设置 TERM 变量**：
  1. 编辑您的 shell 配置（`~/.bashrc` 或 `~/.zshrc`）
  2. 添加：`export TERM=xterm-256color`
  3. 重新加载配置：`source ~/.bashrc`

### 2. 输出捕获失败

**症状：**

* 命令执行但 Cline 显示"无输出"
* 部分输出缺失

**解决方案：**

* 增加 Shell 集成超时到 10 秒
* 在 Cline 设置中启用"使用 Shell 集成"
* 尝试不同的终端配置文件

### 3. 字符过滤问题

**症状：**

* 输出包含奇怪字符或乱码
* 颜色代码显示为文本

**解决方案：**

* 在终端设置中禁用颜色输出
* 设置 `TERM=xterm-256color`
* 使用更简单的 shell

### 4. 长时间运行命令问题

**症状：**

* 命令似乎挂起
* Cline 等待很长时间

**解决方案：**

* 使用 Ctrl+C 停止命令
* 为长时间运行的任务使用后台执行
* 增加命令超时设置

## 高级故障排除

如果基本解决方案不起作用，请尝试：

1. **重启 VSCode**：很多终端问题可以通过重启解决
2. **检查 VSCode 版本**：确保使用最新版本
3. **清除终端状态**：关闭所有终端窗口并重新打开
4. **检查权限**：确保 Cline 有执行命令的权限

## 测试终端集成

要验证终端集成是否正常工作：

1. 打开 Cline
2. 请求执行简单命令，如 `echo "Hello World"`
3. 检查 Cline 是否能看到输出

如果仍有问题，请使用 `/reportbug` 命令报告问题。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.