Configuration

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>：

environments:
  modal:
    token_id: null
    token_secret: null
    app_name: agentcompass-sandboxes
    timeout: 43200
    operation_timeout: 1800

Benchmark 参数放在 benchmarks.<benchmark_id>：

benchmarks:
  screenspot:
    category: desktop
  swebench_verified:
    prepare_mode: prebaked
    eval_timeout: 1800

Harness 参数放在 harnesses.<harness_id>：

harnesses:
  mini_swe_agent:
    launch_mode: remote
    step_limit: 250
    command_timeout: 2400

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

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 文件。

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 的完整字段索引见配置参考。

快速开始

核心模块

执行环境

实战指南

配置来源

常用控制项

作用域参数

私有配置文件

完整参考

​配置来源

​常用控制项

​作用域参数

​私有配置文件

​完整参考

配置来源

常用控制项

作用域参数

私有配置文件

完整参考