终端 Shell 集成

了解 Roo Code 如何与你的 shell 集成以执行命令。终端问题和 shell 配置的故障排除指南。

终端 Shell 集成是一项关键功能，它使 Roo Code 能够在你的终端中执行命令并智能地处理它们的输出。AI 和你的开发环境之间的这种双向通信解锁了强大的自动化能力。

什么是 Shell 集成？

Shell 集成在 Roo Code 中自动启用，并直接连接到你的终端的命令执行生命周期，无需你进行任何设置。这个内置功能允许 Roo：

通过 execute_command 工具代表你执行命令。
实时读取命令输出，无需手动复制粘贴。
自动检测和修复正在运行的应用程序中的错误。
观察命令退出代码以确定成功或失败。
在你导航项目时跟踪工作目录更改。
无需用户干预即可智能地对终端输出做出反应。
使用出现在命令执行消息旁边的停止按钮，直接从聊天界面停止正在运行的命令。

当你要求 Roo 执行任务时，例如安装依赖项、启动开发服务器或分析构建错误，shell 集成在后台工作，使这些交互平稳而有效。

终端 Shell 集成故障排除

Shell 集成内置于 Roo Code 中，在大多数情况下会自动工作。如果你看到“Shell Integration Unavailable”消息或遇到命令执行问题，请尝试以下解决方案：

将 VSCode/Cursor 更新到最新版本（需要 VSCode 1.93+）。
确保选择了兼容的 shell：命令面板（Ctrl+Shift+P 或 Cmd+Shift+P）→ “Terminal: Select Default Profile” → 选择 bash、zsh、PowerShell 或 fish。
Windows PowerShell 用户：运行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser，然后重新启动 VSCode。
WSL 用户：将 . "$(code --locate-shell-integration-path bash)" 添加到你的 ~/.bashrc 中。

命令执行回退

Roo Code 有一个用于执行命令的回退机制。如果你选择使用 VS Code 的终端集成（通过 取消勾选 “Disable terminal shell integration” 设置），并且该集成随后失败，则此功能最为相关。

工作原理： 如果 Roo Code 配置为使用 VS Code 的终端集成，但无法连接或遇到问题，它可能会自动尝试使用后台进程直接执行命令。这是一个回退，以确保命令仍然尝试运行。
通知： 如果使用了此回退，你可能会在聊天中看到一条通知，指示命令正在运行，但没有 Roo 的内联终端或 VS Code 的 shell 集成的全部功能（例如，实时输出流或精确的退出代码检测可能会受到限制）。
解决方法： 如果你遇到此回退，通常表示你的 VS Code shell 集成设置有问题。请查看本文档中的故障排除步骤，或考虑使用 Roo Code 推荐的内联终端，方法是确保勾选“Disable terminal shell integration”设置。

图片：Roo Code 推荐的内联终端示例。

终端集成设置

Roo Code 提供了设置来微调它与终端的交互方式。要访问这些设置：

点击 Roo Code 侧边栏右上角的 ⚙️ 图标。
在打开的设置窗格中，从左侧菜单中选择“Terminal”组。

基本设置

终端输出限制

此设置控制 Roo Code 从你的命令中捕获多少输出。如果你担心令牌使用或 Roo 在处理非常长的输出时显得缓慢（你仍然会得到开头和结尾），请考虑降低它。如果你经常需要长命令的更多中间内容直接在 Roo 的上下文中，请考虑增加它，但要留意潜在的令牌成本。默认值： 500 行。

压缩进度条输出

保持此功能启用（默认）以获得更清晰的输出和节省令牌。它使 Roo Code 处理动态输出（如进度条或旋转器）更像一个真实的终端，只显示最终状态。只有在极少数情况下，当你特别需要调试进度条或类似动态显示的中间原始输出时，才禁用此功能。

高级设置

重要
需要重新启动终端以应用这些设置
对高级终端设置的更改仅在重新启动终端后生效。要重新启动终端：

点击终端面板中的垃圾桶图标以关闭当前终端。
使用“Terminal”→ “New Terminal”或 Ctrl+ (反引号) 打开一个新终端。

更改任何这些设置后，请务必重新启动所有打开的终端。

此设置控制 Roo Code 的终端会话是否使用与你的主 VSCode/Cursor 环境相同的环境变量（如 PATH、API 密钥等）。它直接反映了 VSCode 的全局设置 terminal.integrated.inheritEnv。如果你希望 Roo 命令与你的常规 VSCode 终端中可用的相同上下文和工具一起运行，请保持此功能启用（VSCode 的默认设置）。只有当你需要一个完全干净、隔离的环境用于 Roo 的终端任务或正在排查复杂的环境变量冲突时，才考虑禁用它。

运行时环境

在 macOS（以及可能的其他操作系统）上，提供给 VSCode 和 Roo Code 的环境可能会因 VSCode 的启动方式而异。如果从命令行 vscode 命令启动，VSCode 和 Roo Code 将继承启动它的 shell 的环境，并且一切通常都会正常。如果从 Finder、Dock 或 Spotlight 启动，从 .zshrc 或 .zprofile 导出的环境可能会丢失。如果你在其中一个文件中设置了环境变量，并且发现运行 VSCode 时它们丢失了，请将它们移动到 .zshenv，然后注销并重新登录，以便窗口管理器能够获取新的环境设置。

禁用终端 shell 集成

此设置决定了 Roo Code 如何执行终端命令。

保持此复选框勾选（推荐）： Roo Code 将使用其内置的内联终端执行命令，直接在聊天界面中显示输出。此方法通常很健壮，提供清晰的输出，是大多数用户通过 Roo Code 与终端命令交互的首选方式。它确保命令在 Roo Code 管理的一致环境中运行。

图片：Roo Code 的内联终端，当“禁用终端 shell 集成”被勾选时处于活动状态。

取消勾选此复选框（以使用 VS Code 的终端集成）： Roo Code 将尝试直接在你的活动 VS Code 终端面板中运行命令。此替代方法对于某些特定的边缘情况可能很有用，在这些情况下，你明确需要命令在你的完全自定义的 VS Code shell 环境中运行，或者需要与 VS Code 终端的特定功能进行交互。然而，根据你的 shell 设置和 VS Code 版本，这有时可能不太可靠。

以下设置是高级选项，仅在你 取消勾选 了 “Disable terminal shell integration”（选择使用 VS Code 的终端集成而不是 Roo Code 推荐的内联终端）时适用：

终端 shell 集成超时

如果 shell 集成已启用但你仍然看到“Shell Integration Unavailable”，尤其是在复杂的 shell 设置（例如，带有许多插件的 Zsh，或加载缓慢的公司环境）中，你的 shell 可能需要太长时间才能初始化。增加此值以让你的 shell 有更多时间向 Roo Code 发出就绪信号。尝试以 5-10 秒的增量增加。默认值： 15s（如 UI 所示）。

终端命令延迟

如果命令输出似乎不完整，或者 Roo 似乎错过了命令输出的结尾（即使启用了 shell 集成），一个小延迟可能会有所帮助。引入一个小的延迟（例如，50ms 或 100ms）。这会给终端更多时间来刷新所有输出，然后 Roo Code 才会认为命令完成。这是针对 VSCode 终端或某些 shells 中潜在的时间问题的解决方法（参见 VSCode 错误 #237208）。默认值： 0ms。

启用 PowerShell 计数器解决方法

特定于 PowerShell 用户。如果你发现 Roo Code 难以连续多次运行完全相同的 PowerShell 命令，或者 PowerShell 命令的输出捕获不可靠，请启用此功能。这会向命令添加一个唯一的计数器，以帮助 PowerShell 区分它们。

清除 ZSH EOL 标记

特定于 Zsh 用户。如果一行没有以换行符结尾，Zsh 有时会在其末尾添加一个特殊字符（通常是 %）。如果 Roo Code 似乎错误地解释或被 Zsh 命令的输出混淆，尤其是在输出的最后一行似乎包含一个意外字符时，请启用此功能。这会尝试移除该标记（PROMPT_EOL_MARK=''）。

启用 Oh My Zsh 集成

适用于流行的 Zsh 框架 Oh My Zsh 的用户。如果你使用 Oh My Zsh 并遇到一般性的终端命令执行或输出渲染问题，而其他设置无法解决，请启用此功能。这有助于 Roo Code 通过设置 ITERM_SHELL_INTEGRATION_INSTALLED=Yes 来与其特定的 shell 集成机制对齐。可能需要重新启动 IDE。

启用 Powerlevel10k 集成

适用于 Zsh 的 Powerlevel10k 主题的用户。如果你的 Powerlevel10k 提示（可能非常复杂）似乎干扰了 Roo Code 正确检测命令边界、解析输出或跟踪当前工作目录的能力，请启用此功能。这会设置 POWERLEVEL9K_TERM_SHELL_INTEGRATION=true。

启用 ZDOTDIR 处理

Zsh 用户的高级选项，用于自定义 Zsh 启动文件位置。如果你使用 ZDOTDIR 来指定你的 Zsh 配置文件（如 .zshrc）的自定义目录，请启用此功能。此设置通过为其自己的集成脚本创建一个隔离的、临时的 ZDOTDIR，帮助 Roo Code 正确处理此类设置，从而防止与你的个人 Zsh 环境发生冲突。

Shell 集成的工作原理

Shell 集成将 Roo 实时连接到你的终端的命令执行过程：

连接： 当你打开终端时，VS Code 会与你的 shell 建立一个特殊连接。
命令跟踪： VS Code 通过检测以下内容来监控你的终端活动：

何时出现新提示。
何时你输入命令。
何时命令开始运行。
何时命令结束（以及是成功还是失败）。
你当前所在的目录。

不同的 Shell，相同的结果： 每种 shell 类型（Bash、Zsh、PowerShell、Fish）在幕后的实现方式略有不同，但它们都为 Roo 提供了相同的功能。
信息收集： Roo 可以看到正在运行哪些命令、它们在哪里运行、它们需要多长时间、它们是否成功以及它们的完整输出——所有这些都无需你复制和粘贴任何东西。

故障排除 Shell 集成

PowerShell 执行策略（Windows）

PowerShell 默认限制脚本执行。要配置：

以管理员身份打开 PowerShell。
检查当前策略：Get-ExecutionPolicy。
设置适当的策略：Set-ExecutionPolicy RemoteSigned -Scope CurrentUser。

常见策略：

Restricted：不允许任何脚本（默认）。
RemoteSigned：本地脚本可以运行；下载的脚本需要签名。
Unrestricted：所有脚本都运行并带有警告。
AllSigned：所有脚本都必须签名。

手动 Shell 集成安装

如果自动集成失败，请将适当的行添加到你的 shell 配置中：

Bash (~/.bashrc)：

[[ "$TERM_PROGRAM" == "vscode" ]] && . "$(code --locate-shell-integration-path bash)"

Zsh (~/.zshrc)：

[[ "$TERM_PROGRAM" == "vscode" ]] && . "$(code --locate-shell-integration-path zsh)"

PowerShell ($Profile)：

if ($env:TERM_PROGRAM -eq "vscode") { . "$(code --locate-shell-integration-path pwsh)" }

Fish (~/.config/fish/config.fish)：

string match -q "$TERM_PROGRAM" "vscode"; and . (code --locate-shell-integration-path fish)

终端自定义问题

如果你使用终端自定义工具：

Powerlevel10k：

# Add before sourcing powerlevel10k in ~/.zshrc
typeset -g POWERLEVEL9K_TERM_SHELL_INTEGRATION=true

或者： 在 Roo Code 中启用 “Powerlevel10k Integration” 设置。

验证 Shell 集成状态

使用以下命令确认 shell 集成处于活动状态：

Bash：

set | grep -i '[16]33;'
echo "$PROMPT_COMMAND" | grep vsc
trap -p DEBUG | grep vsc

Zsh：

functions | grep -i vsc
typeset -p precmd_functions preexec_functions

PowerShell：

Get-Command -Name "*VSC*" -CommandType Function
Get-Content Function:\Prompt | Select-String "VSCode"

Fish：

functions | grep -i vsc
functions fish_prompt | grep -i vsc

活跃 shell 集成的视觉指示器：

终端标题栏中的 shell 集成指示器。
命令检测高亮显示。
终端标题中的工作目录更新。
命令持续时间和退出代码报告。

WSL 终端集成方法

当使用适用于 Linux 的 Windows 子系统（WSL）时，有两种不同的方法可以在 VSCode 中使用 WSL，每种方法对 shell 集成都有不同的影响：

方法 1：带 WSL 终端的 VSCode Windows

在此设置中：

VSCode 在 Windows 中本地运行。
你在 VSCode 中使用 WSL 终端集成功能。
Shell 命令通过 WSL 桥接执行。
由于 Windows-WSL 通信，可能会遇到额外的延迟。
Shell 集成标记可能会受到 WSL-Windows 边界的影响：你必须确保 source "$(code --locate-shell-integration-path <shell>)" 在 WSL 环境中为你的 shell 加载，因为它可能不会自动加载；参见上文。

方法 2：在 WSL 内运行的 VSCode

在此设置中：

你直接从 WSL 中使用 code . 启动 VSCode。
VSCode 服务器在 Linux 环境中本地运行。
直接访问 Linux 文件系统和工具。
Shell 集成的性能和可靠性更好。
由于 VSCode 在 Linux 环境中本地运行，shell 集成会自动加载。
推荐用于 WSL 开发的方法。

为了在 WSL 中实现最佳 shell 集成，我们建议：

打开你的 WSL 发行版。
导航到你的项目目录。
使用 code . 启动 VSCode。
在 VSCode 中使用集成终端。

已知问题和解决方法

Cygwin (bash, zsh)

Cygwin 在 Windows 系统上提供了一个类似 Unix 的环境。要将 Cygwin 配置为 VS Code 中的终端：

从 https://www.cygwin.com/ 安装 Cygwin。
打开 VS Code 设置：

选择 File > Preferences > Settings。
点击右上角的“Open Settings (JSON)”图标。

将以下配置添加到你的 settings.json 中（在顶级大括号 {} 内）：

{
  "terminal.integrated.profiles.windows": {
    "Cygwin": {
      "path": "C:\\cygwin64\\bin\\bash.exe",
      "args": ["--login"],
      "env": {"CHERE_INVOKING": "1"}
    }
  },
  "terminal.integrated.defaultProfile.windows": "Cygwin"
}

注意： 如果你安装了 32 位 Cygwin，请使用 "C:\\cygwin\\bin\\bash.exe" 作为路径。

理解配置：

path：指向你的 Cygwin 安装中的 Bash 可执行文件。
args：--login 标志确保 shell 读取配置文件。
env：CHERE_INVOKING 环境变量告诉 Cygwin 使用当前目录作为工作目录。
terminal.integrated.defaultProfile.windows：将 Cygwin 设置为默认终端配置文件。

要打开一个新的 Cygwin 终端：

按 Ctrl+Shift+(反引号) 打开一个新的终端，或
按 F1，输入“Terminal: Create New Terminal (with Profile)”，然后选择“Cygwin”。

虽然我们的测试显示这在开箱即用的情况下可以工作，但如果你遇到 Cygwin 的 shell 集成问题，请确保你已按照 “手动 Shell 集成安装” 部分所述，将适当的 shell 集成挂钩添加到你的 Cygwin bash 配置文件中。

VS Code Shell 集成用于 Windows 上的 Fish + Cygwin

对于在 Cygwin 环境中运行 Fish 终端的 Windows 用户，以下是 VS Code 的 shell 集成工作原理：

（可选）找到 Shell 集成脚本： 在 VS Code 中打开你的 Fish 终端并运行以下命令：
```
code --locate-shell-integration-path fish
```
这将输出 shellIntegration.fish 脚本的路径。记下此路径。

更新你的 Fish 配置： 编辑你的 config.fish 文件（通常位于你的 Cygwin 主目录中的 ~/.config/fish/config.fish）。添加以下行，最好放在 if status is-interactive 块内或文件的末尾：

# Example config.fish structure
if status is-interactive
    # Your other interactive shell configurations...
    # automatic locate integration script:
    string match -q "$TERM_PROGRAM" "vscode"; and . (code --locate-shell-integration-path fish)

    # Or if the above fails for you:
    # Source the VS Code shell integration script
    # IMPORTANT: Replace the example path below with the actual path you found in Step 1.
    # Make sure the path is in a format Cygwin can understand (e.g., using /cygdrive/c/...).
    # source "/cygdrive/c/Users/YourUser/.vscode/extensions/..../shellIntegration.fish"
end

记住要用你从步骤 1 中找到的实际路径替换示例路径，并正确格式化以供 Cygwin 使用。

配置 VS Code 终端配置文件： 打开你的 VS Code settings.json 文件（Ctrl+Shift+P -> “Preferences: Open User Settings (JSON)”）。更新或添加 terminal.integrated.profiles.windows 下的 Fish 配置文件，如下所示：

{
  // ... other settings ...

  "terminal.integrated.profiles.windows": {
    // ... other profiles ...

    // Recommended: Use bash.exe to launch fish as a login shell
    "fish": {
      "path": "C:\\cygwin64\\bin\\bash.exe", // Or your Cygwin bash path
      "args": [
        "--login", // Ensures login scripts run (important for Cygwin environment)
        "-i",      // Ensures bash runs interactively
        "-c",
        "exec fish" // Replace bash process with fish
      ],
      "icon": "terminal-bash" // Optional: Use a recognizable icon
    }
    // Alternative (if the above fails): Launch fish directly
    "fish-direct": {
      "path": "C:\\cygwin64\\bin\\fish.exe", // Ensure this is in your Windows PATH or provide full path
      // Use 'options' here instead of 'args'; otherwise, you might encounter the error "terminal process terminated exit code 1".
      "options": ["-l", "-c"], // Example: login and interactive flags.
      "icon": "terminal-fish" // Optional: Use a fish icon
    }
  },

// Optional: Set fish as your default if desired

已知问题和解决方法

{
  // "terminal.integrated.defaultProfile.windows": "fish", // or "fish-direct" depending what you use.
  // ... other settings ...
}

*Note: Using `bash.exe --login -i -c "exec fish"` is often more reliable in Cygwin environments for ensuring the correct environment setup before `fish` starts. However, if that approach doesn't work, try the `fish-direct` profile configuration.*

4.  **Restart VS Code:**
Close and reopen Visual Studio Code completely to apply the changes.

5.  **Verify:**
Open a new Fish terminal in VS Code. The shell integration features (like command decorations, better command history navigation, etc.) should now be active. You can test basic functionality by running simple commands like `echo "Hello from integrated Fish!"`. <img src="/img/shell-integration/shell-integration-8.png" alt="Fish Cygwin Integration Example" width="600" />

This setup works reliably on Windows systems using Cygwin, Fish, and the Starship prompt, and should assist users with similar configurations.


### Shell Integration Failures After VSCode 1.98

**Issue**: After VSCode updates beyond version 1.98, shell integration may fail with the error "VSCE output start escape sequence (]633;C or ]133;C) not received".

**Solutions**:
1. **Set Terminal Command Delay**:
- Set the Terminal Command Delay to 50ms in Roo Code settings
- Restart all terminals after changing this setting
- This matches older default behavior and may resolve the issue, however some users have reported that a value of 0ms works better. This is a workaround for upstream VSCode problems.

2. **Roll Back VSCode Version**:
- Download VSCode v1.98 from [VSCode Updates](https://code.visualstudio.com/updates/v1_98)
- Replace your current VSCode installation
- No backup of Roo settings needed

3. **WSL-Specific Workaround**:
- If using WSL, ensure you launch VSCode from within WSL using `code .`

4. **ZSH Users**:
- Try enabling some or all ZSH-related workarounds in Roo settings
- These settings can help regardless of your operating system


### Ctrl+C Behavior

**Issue**: If text is already typed in the terminal when Roo tries to run a command, Roo will press Ctrl+C first to clear the line, which can interrupt running processes.

**Workaround**: Make sure your terminal prompt is empty (no partial commands typed) before asking Roo to execute terminal commands.

### Multi-line Command Issues

**Issue**: Commands that span multiple lines can confuse Roo and may show output from previous commands mixed in with current output.

**Workaround**: Instead of multi-line commands, use command chaining with `&amp;&amp;` to keep everything on one line (e.g., `echo a &amp;&amp; echo b` instead of typing each command on a separate line).

### PowerShell-Specific Issues

1. **Premature Completion**: PowerShell sometimes tells Roo a command is finished before all the output has been shown.
2. **Repeated Commands**: PowerShell may refuse to run the same command twice in a row.

**Workaround**: Enable the "PowerShell counter workaround" setting and set a terminal command delay of 150ms in the settings to give commands more time to complete.

### Incomplete Terminal Output

**Issue**: Sometimes VS Code doesn't show or capture all the output from a command.

**Workaround**: If you notice missing output, try closing and reopening the terminal tab, then run the command again. This refreshes the terminal connection.

### Python Virtual Environment (venv) Issues

**Issue**: Disabling shell integration will disable venv; venv is VSCode-managed, Roo does not know anything about it because disabling shell integration uses a completely different mechanism for running commands (execa).

**Workaround**: If you need to use Python virtual environments with Roo Code, you might be able to:

```bash
killall code # closes all vscode windows!
. venv/bin/activate
code

通过这种方式，环境在代码启动之前就已经配置好，因此 Roo 应该能够继承它。

故障排除资源

检查调试日志

当发生 shell 集成问题时，请检查调试日志：

打开 Help → Toggle Developer Tools → Console。
设置“Show All Levels”以查看所有日志消息。
查找包含 [Terminal Process] 的消息。
检查错误消息中的 preOutput 内容：

空 preOutput（''）表示 VSCode 没有发送任何数据。
这表明可能存在 VSCode shell 集成问题，或一个我们无法控制的上游错误。
缺少 shell 集成标记可能需要调整设置，以解决可能存在的上游错误或与 shell 初始化以及 VSCode 加载特殊 shell 集成挂钩相关的本地工作站配置问题。