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

# 终端与沙箱

Agent 在执行任务时会直接在终端中运行 shell 命令。Qoder 采用分层安全模型，根据当前运行模式和命令的风险等级，自动决定命令是直接执行、在沙箱中隔离执行，还是暂停等待你确认。目标是在保持自动化效率的同时，防止意外的破坏性操作。

## 执行模式

Qoder 根据不同的使用场景提供不同的执行模式，在自动化效率和安全保护之间取得平衡。

### Agent 模式

* **直接执行的命令**：当终端执行不在内置风险类别中的常规开发命令（如 `npm install`、`git status`、`python test.py`）会直接自动运行，无需干预。
* **触发确认的命令**：命中潜在风险类别或在你配置的黑名单中的命令，会暂停执行并等待你在 IDE 中批准或拒绝。

### Experts 模式

Experts 模式自动化程度更高。

* **直接执行的命令**：所有不在内置风险类别中的命令都会直接执行，不检查用户自定义的黑名单。
* **沙箱执行的命令**：潜在危险命令自动在沙箱中执行，无需你确认。
* **权限升级**：如果命令在沙箱中因限制而失败，或模型判断该命令在沙箱内一定会失败，AI 会分析原因并可能请求升级权限。此时 Qoder 暂停并询问你是否批准在终端中执行。

## 潜在危险命令

涉及文件删除、磁盘操作、权限管理、网络配置等类别的命令会被系统识别为潜在风险。在 Agent 模式下，这类命令会暂停并等待你确认；在 Experts 模式下，这类命令会自动进入沙箱执行。
此外，AI 模型会根据命令语义独立判断风险，即使命令不在上述类别中。

## 沙箱

沙箱是 Experts 模式下使用的隔离执行环境，潜在危险命令在其中运行，确保它们只能访问工作区目录，防止误操作影响系统文件。

### 平台要求

* **macOS**：开箱即用，无需额外配置。基于系统自带的 Seatbelt 框架实现内核级隔离。
* **Windows**：基于自研沙箱引擎实现，随 IDE 分发。支持 Windows 7 及以上所有版本。无需安装 WSL 或其他额外依赖，在原生 Windows 终端中直接工作。
* **Linux**：需要安装 bubblewrap（`bwrap`）。基于内核的 user namespace 构建轻量隔离环境。首次使用时，如果检测到 `bwrap` 未安装，Qoder 会弹窗引导一键安装（自动识别 `apt` / `dnf` / `yum` / `pacman` / `zypper`）。如果不安装，将降级为非沙箱执行并给出提示。

### 沙箱的工作方式

沙箱在允许工作区操作的同时，阻止未经授权的访问：

* **文件系统**：工作区目录可写，其余目录只读；`~/.ssh` 等敏感路径对沙箱内进程不可见。

### 沙箱升级流程

Experts 模式下，命令在沙箱中执行时可能发生以下情况：

1. 命令在沙箱中执行并失败。
2. AI 分析失败原因，判断是否为沙箱限制导致。
3. 如果是沙箱限制导致，AI 请求升级权限。
4. Qoder 暂停，询问你是否批准。
5. 你批准后，命令在终端直接执行（无沙箱限制）。

你可以选择取消该命令，让 Agent 尝试其他操作；或者选择在终端中执行，不受沙箱限制重新运行该命令。

### 注意事项

* **域名级网络过滤**：目前网络控制为粗粒度的开/关模式，精细到域名级的过滤能力正在规划中。
* **Linux 容器环境**：在 Docker 等容器内使用 Qoder 时，沙箱的隔离能力受限，目前仅做文件系统和网络隔离。
* **Windows 沙箱为用户态机制**：目标场景是防住误伤性写入和意外外联，不能完全覆盖对抗性攻击（如进程已获取提权能力）。
* **Shell 主题兼容性**：某些 shell 主题（例如 Powerlevel9k/Powerlevel10k）可能会干扰终端输出。如果命令输出出现截断或格式错乱，建议在 Agent 运行时禁用该主题或切换到更简洁的提示符。