> ## Documentation Index
> Fetch the complete documentation index at: https://opencompass-docs-preview-pr-335-0.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 安装

AgentCompass 目前需要从源码安装。本页介绍如何准备 host 环境、安装 AgentCompass、配置可选依赖，以及验证本地或远程 Environment。

## 前置条件

安装前，请根据操作系统准备 Git、CA 证书、下载与解压工具，以及本地构建工具：

<Tabs>
  <Tab title="Linux / WSL">
    在 Ubuntu、Debian 和基于 Ubuntu 的 WSL 发行版中，运行：

    ```bash theme={"system"}
    sudo apt-get update
    sudo apt-get install -y \
      build-essential \
      ca-certificates \
      curl \
      git \
      unzip \
      wget
    ```

    其他 Linux 发行版请使用对应的软件包管理器安装这些工具。Git 的安装方式参考 [Git 官方安装页面](https://git-scm.com/downloads/)。
  </Tab>

  <Tab title="macOS">
    macOS 已内置 `curl`、`unzip` 和 CA 证书。运行以下命令安装 Xcode Command Line Tools（用于本地构建），并通过 [Homebrew](https://brew.sh/) 安装 Git 和 wget：

    ```bash theme={"system"}
    xcode-select --install
    brew install git wget
    ```
  </Tab>

  <Tab title="Windows">
    Windows 已内置 `curl.exe`，PowerShell 可通过 `Expand-Archive` 解压文件。使用 WinGet 安装 Git：

    ```powershell theme={"system"}
    winget install --id Git.Git --exact --source winget
    ```

    也可以按照 [Scoop](https://scoop.sh/) 官方说明安装 Scoop，再用它管理 Git 和 wget：

    ```powershell theme={"system"}
    scoop install git wget
    ```

    如果工作负载依赖 `/bin/sh`、POSIX 路径或 Unix 构建工具，请改用 WSL 2。
  </Tab>
</Tabs>

运行评测前，还需准备 model 端点凭证和一种受支持的 Environment。具体要求见[支持的操作系统](#支持的操作系统)。

完成上述准备后，确认 Git 和 `curl` 可用：

```bash theme={"system"}
git --version
curl --version
```

## 安装 AgentCompass

请在独立的虚拟环境中安装 AgentCompass。除非你清楚它们的依赖解析方式，否则不要在同一环境中混用 `uv`、`pip` 和 `conda`。

先克隆代码仓库并进入项目目录：

```bash theme={"system"}
git clone https://github.com/open-compass/AgentCompass.git
cd AgentCompass
```

然后选择一种安装方式：

<Tabs>
  <Tab title="uv（推荐）">
    按照 [`uv` 官方安装指南](https://docs.astral.sh/uv/getting-started/installation/)安装 `uv`。

    Linux、WSL 或 macOS：

    ```bash theme={"system"}
    curl -LsSf https://astral.sh/uv/install.sh | sh
    uv python install 3.12
    uv venv --python 3.12
    source .venv/bin/activate
    uv pip install -e .
    ```

    Windows PowerShell：

    ```powershell theme={"system"}
    winget install --id=astral-sh.uv -e
    uv python install 3.12
    uv venv --python 3.12
    .venv\Scripts\Activate.ps1
    uv pip install -e .
    ```

    如果 host 尚未安装 Python 3.12，`uv` 会通过上述命令安装并管理 Python 3.12 runtime。详情见 [uv Python 安装指南](https://docs.astral.sh/uv/guides/install-python/)。
  </Tab>

  <Tab title="pip + venv">
    先从 [Python 官方下载页面](https://www.python.org/downloads/)安装 Python 3.12。

    Linux、WSL 或 macOS：

    ```bash theme={"system"}
    python3.12 -m venv .venv
    source .venv/bin/activate
    python -m pip install --upgrade pip
    python -m pip install -e .
    ```

    Windows PowerShell：

    ```powershell theme={"system"}
    py -3.12 -m venv .venv
    .venv\Scripts\Activate.ps1
    python -m pip install --upgrade pip
    python -m pip install -e .
    ```
  </Tab>

  <Tab title="Conda">
    安装并初始化 [Conda](https://docs.conda.io/projects/conda/en/stable/user-guide/install/) 后，运行：

    ```bash theme={"system"}
    conda create -n agentcompass python=3.12
    conda activate agentcompass
    python -m pip install --upgrade pip
    python -m pip install -e .
    ```
  </Tab>
</Tabs>

**验证安装：** 激活环境后，确认 Python 版本正确，且 AgentCompass 命令行工具可用：

```bash theme={"system"}
python --version
agentcompass --version
```

如果要用 [`agentcompass view`](/zh/user_guide/using_agentcompass/cli/view) 浏览结果，从源码安装时还需要安装 Node.js 20.19+ 或 22.12+，首次运行时会自动构建查看器前端。

## 按需安装可选依赖

基础安装仅包含 AgentCompass 的核心依赖，其他组件的依赖无需全部预装。开始评测时，AgentCompass 会按需检查所选 Benchmark 和 Harness 的可选依赖。

如果你要运行 SWE-bench，或在 host 上以本地模式使用 mini-swe-agent，可以提前安装这两组可选依赖：

```bash theme={"system"}
uv pip install -e ".[swebench,mini-swe-agent]"
```

若检查发现依赖缺失，AgentCompass 会停止运行并给出安装命令。完成安装后，重新运行原命令即可。你也可以为可信的内置组件启用自动安装：

```bash theme={"system"}
agentcompass run <benchmark> <harness> <model> --auto-install-dependencies
```

<Note>
  `--auto-install-dependencies` 只会在运行 AgentCompass 的 host Python 环境中安装依赖，不会修改 Docker、Daytona 或 Modal Environment。这些环境所需的依赖由任务镜像或环境配置提供。
</Note>

如需准备离线环境或查看所有可选依赖，请参阅[依赖管理](/zh/user_guide/using_agentcompass/dependencies)。

## Environment

请根据所选 Benchmark 的要求准备相应的 Environment；运行多个 Benchmark 时，可能需要配置不同的 Environment。

各 Environment 的适用场景、参数、资源和网络配置详见[用户指南中的 Environment](/zh/user_guide/modules/environments/overview)。

<Tabs>
  <Tab title="host_process">
    `host_process` 会以普通子进程直接执行命令，使用 host 的真实文件系统，并继承 host 上已安装的工具、权限和网络设置。它启动快，但不提供隔离，执行结果也可能受 host 状态影响。

    Linux 和 WSL 2 完全支持这种方式。macOS 仅适用于 Benchmark 文档明确支持的轻量任务或依赖外部服务的任务，因为相关软件包、工具、路径和评测脚本仍可能依赖 Linux。原生 Windows 不受支持，因为当前实现和常见工作流依赖 `/bin/sh`、POSIX 路径、权限和信号。

    <Warning>
      不要使用 `host_process` 运行不可信或能够执行命令的 agent。它可以读取、修改或删除当前用户可访问的文件，还可以直接启动进程。
    </Warning>

    有关参数和安全限制，请参阅 [`host_process` 指南](/zh/user_guide/modules/environments/providers/host_process)。
  </Tab>

  <Tab title="Docker">
    Docker 会为任务创建隔离的容器，任务所需的依赖和文件系统布局由镜像提供。相比 `host_process`，Docker 的运行环境更一致，但首次运行可能需要拉取大型镜像。

    AgentCompass 支持在 Linux 和 WSL 2 上使用本地 Docker。按照 [Docker Engine 安装指南](https://docs.docker.com/engine/install/)完成安装后，运行以下命令进行验证：

    ```bash theme={"system"}
    docker version
    docker info
    docker run --rm hello-world
    ```

    如果 Docker 只能通过 `sudo` 运行，请按照 [Linux 安装后指南](https://docs.docker.com/engine/install/linux-postinstall/)配置当前用户的访问权限：

    ```bash theme={"system"}
    sudo groupadd docker
    sudo usermod -aG docker "$USER"
    newgrp docker
    docker run --rm hello-world
    ```

    如果安装 Docker 时已经创建了 `docker` 用户组，可以跳过第一条命令。

    <Warning>
      加入 `docker` 用户组相当于在 host 上授予该用户根用户权限。
    </Warning>

    在 WSL 2 中，请选择一种部署方式：在 WSL 发行版内安装 Docker Engine，或启用 Docker Desktop 的 [WSL 集成](https://docs.docker.com/desktop/features/wsl/)。不要同时维护两个 Docker 守护进程。请将代码仓库存放在 WSL 的 Linux 文件系统中，例如 `~/code/AgentCompass`，而不是 `/mnt/c/`。

    有关镜像仓库凭证、验证方法和参数，请参阅 [Docker 指南](/zh/user_guide/modules/environments/providers/docker)。
  </Tab>

  <Tab title="Daytona">
    Daytona 在云端 sandbox 中运行任务，可用于 Linux、WSL、Windows 和 macOS。先创建账号，再创建具有 sandbox 访问权限的 [API 密钥](https://www.daytona.io/docs/en/api-keys/)，然后设置凭证：

    ```bash theme={"system"}
    export DAYTONA_API_KEY="..."
    ```

    Windows PowerShell：

    ```powershell theme={"system"}
    $env:DAYTONA_API_KEY = "..."
    ```

    API 端点、`target` 和组织信息均为可选配置。切勿将凭证提交到代码仓库。完整设置方法见 [Daytona 指南](/zh/user_guide/modules/environments/providers/daytona)。
  </Tab>

  <Tab title="Modal">
    Modal 在云端 sandbox 中运行任务，可用于 Linux、WSL、Windows 和 macOS。先创建账号，再按照[用户账号设置指南](https://modal.com/docs/guide/modal-user-account-setup)或[服务用户指南](https://modal.com/docs/guide/service-users)创建令牌，然后设置凭证：

    ```bash theme={"system"}
    export MODAL_TOKEN_ID="..."
    export MODAL_TOKEN_SECRET="..."
    ```

    Windows PowerShell：

    ```powershell theme={"system"}
    $env:MODAL_TOKEN_ID = "..."
    $env:MODAL_TOKEN_SECRET = "..."
    ```

    Modal 命令行工具也可以将凭证写入 `~/.modal.toml`。切勿将令牌提交到代码仓库。完整设置方法见 [Modal 指南](/zh/user_guide/modules/environments/providers/modal)。
  </Tab>
</Tabs>

## 支持的操作系统

AgentCompass 安装在你的终端上，评测任务可以直接在 host 上运行，也可以在本机 Docker 容器或云端 sandbox 中运行：

| 操作系统 | 安装并使用 AgentCompass | host\_process | 本地 Docker | Daytona / Modal |
| - | - | - | - | - |
| Linux | 支持 | 支持 | 支持 | 支持 |
| WSL 2（[安装参考](https://learn.microsoft.com/windows/wsl/install)） | 支持 | 支持 | 支持 | 支持 |
| Windows | 支持 | 不支持 | 不支持 | 支持 |
| macOS | 支持 | 有限支持 | 不支持 | 支持 |

<Warning>
  即使 Docker Desktop 能够在原生 Windows 或 macOS 上启动 Linux 容器，AgentCompass 目前也不支持将其用作本地 Benchmark 环境。编程、终端及其他依赖 Linux 的工作负载请使用 WSL 2、Daytona 或 Modal。
</Warning>

## 故障排查

| 现象 | 处理方法 |
| - | - |
| Python 版本不匹配 | 运行 `python --version`；使用 Python `>=3.12` 重新创建环境。 |
| `agentcompass: command not found` | 确认环境已激活，然后重新以可编辑模式安装，或使用 `uv run agentcompass`。 |
| `uv`、`pip` 或数据集下载失败 | 检查 DNS、代理和 CA 证书，并确认可以通过 HTTPS 访问软件包索引。 |
| `Cannot connect to the Docker daemon` | 启动 Docker，然后在同一个 Linux 或 WSL 命令行环境中运行 `docker info`。 |
| Docker 在 Windows 可用、在 WSL 不可用 | 为正在使用的 WSL 2 发行版启用 Docker Desktop 集成。 |
| WSL 中代码仓库操作很慢 | 将代码仓库从 `/mnt/c/` 移到 WSL 的 Linux 文件系统。 |
| Daytona 启动失败 | 检查 API 密钥；如果配置了 API 端点或 `target`，也请确认其设置正确。 |
| Modal 身份验证失败 | 运行 `modal token info`，确认当前工作区使用了正确的凭证。 |
| 受限 sandbox 中可选依赖安装失败 | 在任务镜像中预装所需依赖，或在禁用网络访问前完成准备。 |


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