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

# 安装

> 使用 pip、uv 或 conda 从源码安装 AgentCompass。

<Note>
  AgentCompass 面向源码 checkout 开发和运行。请从项目根目录以 editable mode 安装；模型 endpoint 放在 Setup 页面配置。
</Note>

## 系统要求

* Python 3.10 或更新版本（推荐 3.12+）。
* `git`，用于克隆和更新源码 checkout。
* `wget` 和 `unzip`，用于自动下载或准备数据集。
* 可选的环境依赖或凭据，例如 Docker、Modal、Daytona 或 HBox。

## 克隆仓库

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

## 安装 Python 依赖

任选一种方式即可。将 `<compatible_python_version>` 替换成 AgentCompass 支持的 Python 版本，例如 `3.12` 或 `3.13`。

<Tabs>
  <Tab title="pip + venv">
    ```bash theme={null}
    python -m venv .venv
    source .venv/bin/activate

    python -m pip install --upgrade pip
    python -m pip install -r requirements.txt
    python -m pip install -e .
    ```
  </Tab>

  <Tab title="uv">
    ```bash theme={null}
    uv venv --python <compatible_python_version>
    source .venv/bin/activate

    uv pip install -r requirements.txt
    uv pip install -e .
    ```
  </Tab>

  <Tab title="conda">
    ```bash theme={null}
    conda create -n <env_name> python=<compatible_python_version>
    conda activate <env_name>

    python -m pip install --upgrade pip
    python -m pip install -r requirements.txt
    python -m pip install -e .
    ```
  </Tab>
</Tabs>

运行 SWE-bench Verified 快速开始前，请在同一个环境中安装 benchmark 和 harness 可选依赖：

```bash theme={null}
uv pip install -r requirements/swe.txt
uv pip install -r requirements/mini-swe-agent.txt
```

Docker 快速开始还要求 Docker 已安装并正在运行：

```bash theme={null}
docker version
```

## 验证 CLI

如果已经激活环境：

```bash theme={null}
agentcompass --version

agentcompass --help

agentcompass list benchmark
```

如果使用 `uv`，也可以不手动激活 `.venv`：

```bash theme={null}
uv run agentcompass --version

uv run agentcompass --help

uv run agentcompass list benchmark
```

## 从源码更新

使用 rebase 拉取最新代码，让本地提交保持在线性历史顶部。如果 worktree 有未提交改动，请先 commit 或 stash；如果 requirements 或 package metadata 有变化，再重新安装 editable 依赖。

<Tabs>
  <Tab title="pip + venv">
    ```bash theme={null}
    git pull --rebase
    source .venv/bin/activate

    python -m pip install -r requirements.txt
    python -m pip install -e .
    ```
  </Tab>

  <Tab title="uv">
    ```bash theme={null}
    git pull --rebase

    uv pip install -r requirements.txt
    uv pip install -e .
    ```
  </Tab>

  <Tab title="conda">
    ```bash theme={null}
    git pull --rebase
    conda activate <env_name>

    python -m pip install -r requirements.txt
    python -m pip install -e .
    ```
  </Tab>
</Tabs>

## 数据缓存与输出目录

AgentCompass 默认使用可预测的本地目录：

| 路径                       | 用途                                                    |
| ------------------------ | ----------------------------------------------------- |
| `data/`                  | 下载或准备后的 benchmark 数据集；已有数据会作为本地数据缓存被复用。               |
| `results/`               | 评测输出，路径形如 `results/<benchmark>/<model>/<timestamp>/`。 |
| run directory 内的 `logs/` | 单次 evaluation 的运行日志。                                  |

需要时可以覆盖目录：

```bash theme={null}
agentcompass run <benchmark> <harness> <model> --data-dir <data_dir> --results-dir <results_dir>
```

## 常见问题

| 现象                                | 检查项                                                                   |
| --------------------------------- | --------------------------------------------------------------------- |
| `agentcompass: command not found` | 激活环境，重新运行 `python -m pip install -e .`，或使用 `uv run agentcompass ...`。 |
| Python 版本不匹配                      | 运行 `python --version`，并用 Python `>=3.10` 重新创建环境。                      |
| 数据集准备失败                           | 检查 `wget`、`unzip`、网络连接，以及 `data/` 或 `--data-dir` 的写权限。                |
| 远程环境启动失败                          | 检查 Docker、Modal、Daytona 或 HBox 的凭据和环境配置。                              |
| 运行时模型 provider 报错                 | 在 Setup 页面配置 model endpoint、API key、protocol 和 provider 命名。           |

## 不做 editable install

如果没有安装 console script，可以从源码路径运行：

```bash theme={null}
PYTHONPATH=src python -m agentcompass.cli run \
  swebench_verified \
  mini_swe_agent \
  glm-5.2 \
  --env docker \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY" \
  --model-api-protocol openai-chat
```