安装

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

​

前置条件

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

Linux / WSL

在 Ubuntu、Debian 和基于 Ubuntu 的 WSL 发行版中，运行：

sudo apt-get update
sudo apt-get install -y \
  build-essential \
  ca-certificates \
  curl \
  git \
  unzip \
  wget

其他 Linux 发行版请使用对应的软件包管理器安装这些工具。Git 的安装方式参考 Git 官方安装页面。

macOS

macOS 已内置 curl、unzip 和 CA 证书。运行以下命令安装 Xcode Command Line Tools（用于本地构建），并通过 Homebrew 安装 Git 和 wget：

xcode-select --install
brew install git wget

Windows

Windows 已内置 curl.exe，PowerShell 可通过 Expand-Archive 解压文件。使用 WinGet 安装 Git：

winget install --id Git.Git --exact --source winget

也可以按照 Scoop 官方说明安装 Scoop，再用它管理 Git 和 wget：

scoop install git wget

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

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

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

git --version
curl --version

​

安装 AgentCompass

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

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

git clone https://github.com/open-compass/AgentCompass.git
cd AgentCompass

然后选择一种安装方式：

uv（推荐）

按照 uv 官方安装指南安装 uv。

Linux、WSL 或 macOS：

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：

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 安装指南。

pip + venv

先从 Python 官方下载页面安装 Python 3.12。

Linux、WSL 或 macOS：

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

Windows PowerShell：

py -3.12 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .

Conda

安装并初始化 Conda 后，运行：

conda create -n agentcompass python=3.12
conda activate agentcompass
python -m pip install --upgrade pip
python -m pip install -e .

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

python --version
agentcompass --version

​

按需安装可选依赖

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

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

uv pip install -e ".[swebench,mini-swe-agent]"

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

agentcompass run <benchmark> <harness> <model> --auto-install-dependencies

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

如需准备离线环境或查看所有可选依赖，请参阅依赖管理。

​

Environment

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

各 Environment 的适用场景、参数、资源和网络配置详见用户指南中的 Environment。

host_process

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

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

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

有关参数和安全限制，请参阅 host_process 指南。

Docker

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

AgentCompass 支持在 Linux 和 WSL 2 上使用本地 Docker。按照 Docker Engine 安装指南完成安装后，运行以下命令进行验证：

docker version
docker info
docker run --rm hello-world

如果 Docker 只能通过 sudo 运行，请按照 Linux 安装后指南配置当前用户的访问权限：

sudo groupadd docker
sudo usermod -aG docker "$USER"
newgrp docker
docker run --rm hello-world

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

加入 docker 用户组相当于在 host 上授予该用户根用户权限。

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

有关镜像仓库凭证、验证方法和参数，请参阅 Docker 指南。

Daytona

Daytona 在云端 sandbox 中运行任务，可用于 Linux、WSL、Windows 和 macOS。先创建账号，再创建具有 sandbox 访问权限的 API 密钥，然后设置凭证：

export DAYTONA_API_KEY="..."

Windows PowerShell：

$env:DAYTONA_API_KEY = "..."

API 端点、target 和组织信息均为可选配置。切勿将凭证提交到代码仓库。完整设置方法见 Daytona 指南。

Modal

Modal 在云端 sandbox 中运行任务，可用于 Linux、WSL、Windows 和 macOS。先创建账号，再按照用户账号设置指南或服务用户指南创建令牌，然后设置凭证：

export MODAL_TOKEN_ID="..."
export MODAL_TOKEN_SECRET="..."

Windows PowerShell：

$env:MODAL_TOKEN_ID = "..."
$env:MODAL_TOKEN_SECRET = "..."

Modal 命令行工具也可以将凭证写入 ~/.modal.toml。切勿将令牌提交到代码仓库。完整设置方法见 Modal 指南。

​

支持的操作系统

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

操作系统	安装并使用 AgentCompass	host_process	本地 Docker	Daytona / Modal
Linux	支持	支持	支持	支持
WSL 2（安装参考）	支持	支持	支持	支持
Windows	支持	不支持	不支持	支持
macOS	支持	有限支持	不支持	支持

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

​

故障排查

现象	处理方法
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 中可选依赖安装失败	在任务镜像中预装所需依赖，或在禁用网络访问前完成准备。