> ## 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.

# Configuration

> AgentCompass 如何把 YAML 默认值、CLI 参数、recipe 和组件参数合并成一次 run request。

AgentCompass 会把配置放在拥有该行为的模块作用域内。Runtime 控制项放在 `runtime` 和 `execution`；provider 默认值放在 `environments.<provider>`；benchmark 过滤和数据参数放在 `benchmarks.<id>`；harness 控制项放在 `harnesses.<id>`。

这种拆分是有意设计的。它允许你切换 sandbox provider 而不修改 benchmark 代码，调优 harness 而不改变 dataset selection，并把 model credentials 保持为 run-local 输入。

## 配置来源

| 来源                        | 常见用途                                                                            |
| ------------------------- | ------------------------------------------------------------------------------- |
| `config/defaults.yaml`    | 仓库级 runtime、execution、provider、benchmark、harness 和 analysis 默认值。                |
| 自定义 `--config` 文件         | 私有凭据、站点级 provider endpoint 或团队默认配置。                                             |
| CLI flags / Python kwargs | 单次 run 覆盖项，例如 `--env`、`--task-concurrency`、model endpoint、`--benchmark-params`。 |
| Recipes                   | sandbox 启动前，根据 benchmark/provider 组合改写 image、workspace、snapshot 和 resource。     |

CLI flags 和 Python keyword arguments 会覆盖 YAML 默认值。之后 recipe 会为兼容的 benchmark/provider 组合适配执行计划，并在 recipe 实现允许时保留显式 user override。

## 常用控制项

| 需求                       | 字段或参数                                               |
| ------------------------ | --------------------------------------------------- |
| 修改结果目录                   | `runtime.results_dir` 或 `--results-dir`             |
| 修改数据/cache 目录            | `runtime.data_dir` 或 `--data-dir`                   |
| 限制单次 run 的任务并发           | `execution.task_concurrency` 或 `--task-concurrency` |
| 限制进程级 provider session 数 | `runtime.provider_limits.<provider>`                |
| 只跑部分任务                   | `--benchmark-params '{"sample_ids":["<task-id>"]}'` |
| 开启或跳过后置 analysis         | `execution.enable_analysis` 或 CLI analysis flags    |
| 控制 recipe 匹配             | `execution.enabled_recipes`                         |
| 加载受信任的外部 recipe          | `runtime.recipe_dirs` 或可重复的 `--recipe-dir`          |

## 作用域参数

Provider 参数放在 `environments.<provider>`：

```yaml theme={null}
environments:
  modal:
    token_id: null
    token_secret: null
    app_name: agentcompass-sandboxes
    timeout: 43200
    operation_timeout: 1800
```

Benchmark 参数放在 `benchmarks.<benchmark_id>`：

```yaml theme={null}
benchmarks:
  screenspot:
    category: desktop
  swebench_verified:
    prepare_mode: prebaked
    eval_timeout: 1800
```

Harness 参数放在 `harnesses.<harness_id>`：

```yaml theme={null}
harnesses:
  mini_swe_agent:
    launch_mode: remote
    step_limit: 250
    command_timeout: 2400
```

如果只是一次性运行，优先用 CLI JSON 覆盖，不要修改共享默认配置：

```bash theme={null}
agentcompass run \
  screenspot \
  qwen3vl_gui \
  your-model \
  --env <env-provider> \
  --benchmark-params '{"category":"desktop"}' \
  --harness-params '{"temperature":0}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY"
```

## 私有配置文件

当某些值对你的机器或团队长期稳定，但不适合提交到仓库时，使用私有 config 文件。

```bash theme={null}
agentcompass run \
  swebench_verified \
  mini_swe_agent \
  your-model \
  --config configs/private.yaml \
  --env <env-provider> \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY"
```

Secrets 尽量放在环境变量中。Modal 可以使用 `MODAL_TOKEN_ID` 和 `MODAL_TOKEN_SECRET`；Daytona 可以使用 `DAYTONA_API_KEY`；模型访问可以使用 `MODEL_BASE_URL` 和 `MODEL_API_KEY`。

## 完整参考

当前 `config/defaults.yaml` 的完整字段索引见 [配置参考](/zh/reference/configuration)。