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

`agentcompass config` 用于查看配置文件合并后的值，或查询当前安装中组件接受的配置字段。

```bash theme={"system"}
agentcompass config {show|docs}
```

## `config show`

`config show` 合并内置默认值与已加载的配置文件，并将结果输出为 YAML 或 JSON：

```bash theme={"system"}
agentcompass config show [OPTIONS]
```

未提供组件选择器时，命令只输出 `runtime` 和 `execution`。使用 `--benchmark`、`--harness` 或 `--env` 可加入指定组件的配置；每个选择器都支持以空格分隔多个 ID，也可以重复使用。

```bash theme={"system"}
agentcompass config show \
  --config examples/configs/swebench_verified.yaml \
  --benchmark swebench_verified \
  --harness mini_swe_agent \
  --env docker
```

| 参数 | 说明 |
| - | - |
| `--config <path>` | 加载额外的 YAML 或 JSON 配置文件；可重复指定，后指定的文件优先。 |
| `--benchmark <id>...` | 显示指定 Benchmark 的内置默认值和配置文件覆盖。 |
| `--harness <id>...` | 显示指定 Harness 的内置默认值和配置文件覆盖。 |
| `--env <id>...` | 显示指定 Environment 的内置默认值和配置文件覆盖。 |
| `--format yaml\|json` | 选择输出格式；默认为 `yaml`。 |

这些选择器只决定输出哪些组件配置，不会改变评测使用的组件；配置文件中的其他组件也不会自动显示。

`config show` 会遮盖常见密钥、令牌和密码字段，但私有端点等信息不一定会被识别。分享或提交输出前仍需检查其内容。

## `config docs`

`config docs` 查询一个已注册组件声明的字段、类型、内置默认值和说明：

```bash theme={"system"}
agentcompass config docs KIND COMPONENT-ID
```

例如：

```bash theme={"system"}
agentcompass config docs benchmark swebench_verified
agentcompass config docs harness mini_swe_agent
agentcompass config docs env docker
```

| 位置参数 | 取值 | 说明 |
| - | - | - |
| `KIND` | `benchmark`、`harness` 或 `env` | 组件类型。 |
| `COMPONENT-ID` | 已注册的组件 ID | 要查询的组件。可通过 [`agentcompass list`](/zh/user_guide/using_agentcompass/cli/list) 查找。 |

该命令显示组件代码中声明的结构，不读取配置文件；较长的默认值会缩略显示。若要查看配置文件合并后的结果，请使用 `config show`，其中的敏感字段仍会被遮盖。待测 Model 的参数不属于 `config docs` 的查询范围，具体字段见[配置 Model](/zh/user_guide/modules/models/overview)。

## 配置文件结构

配置文件适合保存可在多次运行中复用的默认值。支持的顶层部分如下：

| 配置路径 | 内容 |
| - | - |
| `runtime` | 结果与数据目录、评测总时限、日志、进度和 [Environment provider 限制](/zh/user_guide/using_agentcompass/run_controls#安全扩展并发)等运行级设置。 |
| `execution` | 任务并发、重试、环境保留和结果分析等执行设置。 |
| `benchmarks.<id>` | 指定 Benchmark 的配置字段。 |
| `harnesses.<id>` | 指定 Harness 的配置字段。 |
| `environments.<id>` | 指定 Environment 的配置字段。 |

组件字段直接写在对应 ID 下，不要再嵌套一层 `params`。`--config` 加载的运行配置不支持顶层 `models`；待测 Model 通过 `agentcompass run` 参数、`agentcompass launch` 编排请求或 Python SDK 提供。

仓库中的 [`examples/configs/swebench_verified.yaml`](https://github.com/open-compass/AgentCompass/blob/main/examples/configs/swebench_verified.yaml) 展示了这些部分的组合写法。它只选择一个 SWE-bench Verified 样本，适合验证配置与运行环境；删除 `benchmarks.swebench_verified.sample_ids` 即可选择完整数据集。

设置 `MODEL_NAME`、`MODEL_BASE_URL` 和 `MODEL_API_KEY` 后，在仓库根目录中运行：

```bash theme={"system"}
agentcompass run swebench_verified mini_swe_agent "$MODEL_NAME" \
  --env docker \
  --config examples/configs/swebench_verified.yaml \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY"
```

## 覆盖顺序

`config show` 按以下顺序合并配置，优先级从低到高：

1. 内置 `runtime`、`execution` 和组件默认值。
2. `$XDG_CONFIG_HOME/agentcompass/config.yaml`；未设置 `XDG_CONFIG_HOME` 时使用 `~/.config/agentcompass/config.yaml`。
3. 从当前工作目录向上找到的最近一个 `config.yaml`。
4. 显式指定的 `--config` 文件；可重复使用，后指定的文件覆盖先指定的文件。

普通映射会递归合并；标量和列表由高优先级值整体替换。Environment 公共字段使用下述专门规则。不存在的用户级或项目级文件会被忽略，显式指定但不存在的文件会报错。

`config show` 只反映上述配置文件层。实际评测中，显式的 `run`/`launch` CLI 选项、编排文件字段和 Python SDK 参数优先于配置文件；单评测请求的[依赖自动安装](/zh/user_guide/using_agentcompass/dependencies#自动安装)还可由环境变量 `AGENTCOMPASS_AUTO_INSTALL_DEPENDENCIES` 覆盖，`launch` 不读取该变量。[Recipe](/zh/user_guide/other_features/recipes) 随后按具体任务适配执行计划：它通常会保留兼容的显式镜像和资源设置，但仍可能调整 Benchmark 或 Harness 必需的工作区、网络或执行设置。因此，`config show` 的结果不是某次评测的完整运行计划。

## Environment 分层合并

配置文件保留各自的层级，选中 provider 后再按优先级合并。CLI、Python SDK 和编排请求中的显式覆盖使用相同规则：

| 公共字段 | 合并规则 |
| - | - |
| `resources`、`run_resources`、`evaluation_resources` | 资源数量和型号按字段覆盖；未指定或为 `null` 的字段继承低优先级值。高优先级 `gpu: 0` 清除继承的 `gpu_type`；`ignore_gpu_type: true` 清除继承的型号约束但保留 GPU 数量。 |
| `setup`、`evaluation_setup` | 按字段覆盖；未指定或为 `null` 的字段继承低优先级值。 |
| `baseline_network_policy`、`evaluation_baseline_network_policy`、`run_network_policy`、`evaluation_network_policy` | 非 `null` 的高优先级策略整体替换对应的低优先级策略，不继承旧的主机名单。省略或 `null` 表示继承。 |
| `env_variables`、`run_env_variables`、`evaluation_env_variables`、`evaluation_environment_env_variables` | 按变量名合并，同名变量由高优先级值覆盖。 |
| `evaluation_environment_mode`、`require_startup_env` | 非 `null` 的高优先级值覆盖低优先级值；`require_startup_env` 显式设为 `false` 也会覆盖。省略或 `null` 表示继承。 |

例如，低优先级资源为 `gpu: 1, gpu_type: A100`，高优先级只指定 `gpu: 0`，最终不再保留型号约束；低优先级网络为 `allowlist` 并带有主机名单，高优先级指定 `no-network`，最终也不会保留旧名单。

同层冲突与跨层覆盖不同。在同一个资源声明中同时指定 `gpu: 0` 和 `gpu_type: A100`，或在同一个网络策略中同时指定 `no-network` 和非空 `allowed_hosts`，都会报错，即使更高层还有覆盖。同层互斥组合先检查，完整的有效值校验在覆盖完成后进行；配置文件中的同层冲突会标明文件来源。

加载配置文件时检查结构；只有选中的 provider 才进行上述字段解析和语义检查。未使用 provider 的旧字段或无效资源值不会阻断本次评测。`config show` 展示合并结果，不替代实际评测的最终有效值和 provider 能力校验。

## 环境变量与敏感信息

配置文件支持使用完整的 `${VAR}` 引用环境变量。例如：

```yaml theme={"system"}
environments:
  docker:
    setup:
      image: ${TASK_IMAGE}
```

普通配置字段中的环境变量在配置文件合并后解析；`environments` 下的普通字段则在选中 provider 后，按文件层分别解析，再执行上述合并规则。变量未设置时会得到空字符串；不支持 `https://${HOST}/api` 这类在同一字段中拼接变量的写法。

例如，低优先级 `setup.image` 引用未设置的 `TASK_IMAGE` 时，高优先级的有效镜像可以覆盖该空值；如果最终镜像仍为空，实际评测会报错。

任务环境变量映射是例外：`env_variables` 及其阶段专用映射中的引用在配置加载时保留，在执行进程中合并任务与请求覆盖后再解析。缺少必需的变量且没有提供默认值时会报错，不会静默注入空字符串。

不要将密钥、令牌或私有端点提交到版本控制。若必须使用包含敏感值的私有配置文件，请将其排除在版本控制之外。


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