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

# 配置 Environment

选择 provider 和传入 Environment 参数是两件事：provider 决定任务由哪一种 Environment 实现执行，参数决定该 Environment 如何创建和运行。建议只设置需要改变的字段，其余字段交给 provider 默认值或适用的 [Recipe](/zh/user_guide/other_features/recipes) 补齐。

Environment 参数必须在公开 schema 中声明，可通过 `agentcompass config docs env <provider-id>` 查看。未声明字段（包括拼写错误和所有 provider 专属参数）统一报“未知参数”错误。出站访问通过通用网络策略配置，再由适配器在内部生成对应的原生 API 选项。

所有 provider 共用一份 schema。Provider ID 只选择实现及其支持的能力，不会增加公开参数。`setup` 包含 `image`、`workdir`、`build_timeout_seconds` 和 `os`；`evaluation_setup` 为独立 verifier 使用相同结构。资源、网络和环境变量字段也全部通用。Host 凭证通过适配器已有的环境变量或 SDK 配置提供，不属于任务执行设置。

<Note>
  Recipe 默认由 AgentCompass 自动匹配。常规评测不需要设置或改写 Recipe；只有 Benchmark 文档明确要求替代 Recipe、排查匹配问题或加载团队自定义逻辑时，才需要手动配置。
</Note>

## 选择 provider 与配置入口

下列入口都能提供 Environment 参数。选择哪一种，取决于这些值只用于当前评测，还是需要在其他运行或程序中复用：

| 入口 | 配置方式 | 适用场景 |
| - | - | - |
| [`agentcompass run`](/zh/user_guide/using_agentcompass/cli/run) | 使用 `--env <provider-id>` 选择 provider，使用 `--env-params '<json>'` 传入参数。 | 只为当前评测临时设置。 |
| [配置文件](/zh/user_guide/using_agentcompass/cli/config#配置文件结构) | 在 `environments.<provider-id>` 下保存该 provider 的默认参数；具体使用哪个 provider，仍由 `run`、`launch` 或 SDK 选择。 | 在多次评测中复用默认值。 |
| [Python SDK：单评测](/zh/user_guide/using_agentcompass/python_api#单评测请求) | 在 `run_evaluation()` 中使用 `environment="<provider-id>"` 选择 provider，并通过 `environment_params={...}` 传入参数。 | 从 Python 程序发起单评测请求。 |
| [`agentcompass launch`](/zh/user_guide/using_agentcompass/cli/launch) | 在编排文件的 `environment` 中，用 `id` 选择 provider，并将参数写在 `id` 旁边。 | 用 YAML 或 JSON 编排一个或多个评测请求。 |
| [Python SDK：多评测](/zh/user_guide/using_agentcompass/python_api#多评测请求) | 在 `OrchestrationSpec` 的 `defaults.environment` 或 `requests[].environment` 中使用与编排文件相同的结构。 | 从 Python 程序发起多评测请求。 |

### `agentcompass run`

使用 `--env <id>` 选择 provider；省略时默认使用 `host_process`。运行 `agentcompass list env` 可以查看当前安装中可用的 provider ID。

`--env-params` 接收一个 JSON 对象，用于设置本次评测的 Environment 参数；同名字段会覆盖配置文件中的值：

```bash theme={"system"}
agentcompass run <benchmark> <harness> "$MODEL_NAME" \
  --env docker \
  --env-params '{"setup":{"image":"python:3.13-slim"},"resources":{"cpu":2,"memory_mb":6144}}'
```

### 配置文件

可复用的 provider 参数直接写在 `environments.<id>` 下，不要增加 `params` 包装层：

```yaml theme={"system"}
environments:
  docker:
    setup:
      image: python:3.13-slim
    resources:
      cpu: 2
      memory_mb: 6144
```

运行时选择同一个 provider 并加载文件：

```bash theme={"system"}
agentcompass run <benchmark> <harness> "$MODEL_NAME" \
  --env docker \
  --config config.yaml
```

### Python SDK 单评测

SDK 使用 Python 字典传递参数，不需要把它们转换成 JSON 字符串：

```python theme={"system"}
from agentcompass import run_evaluation

result = run_evaluation(
    benchmark="swebench_verified",
    harness="mini_swe_agent",
    model="your-model",
    environment="docker",
    environment_params={
        "resources": {
            "cpu": 2,
            "memory_mb": 6144,
        },
    },
)
```

### `agentcompass launch` 与 SDK 多评测

在 `launch` 编排中，`id` 选择 provider，其他字段直接写在 `environment` 下：

```yaml theme={"system"}
defaults:
  environment:
    id: docker
    resources:
      cpu: 2
      memory_mb: 6144
```

编排文件中的每个评测请求都可以在自己的 `environment` 中覆盖这些默认值。Python SDK 的 `OrchestrationSpec` 使用相同的字段结构。完整说明见 [`agentcompass launch` 的映射规则](/zh/user_guide/using_agentcompass/cli/launch#映射规则)和 [Python SDK 的多评测请求](/zh/user_guide/using_agentcompass/python_api#多评测请求)。

<Warning>
  如果一个编排混用多个 provider，不要把某个 provider 的专属参数放在 `defaults.environment` 中。请求即使覆盖了 `environment.id`，仍会继承并合并 `defaults.environment` 的其他字段。此时应把专属参数写入各自的 `requests[].environment`。
</Warning>

## 嵌套字段怎么写

Provider 参数既可以是字符串、数字或布尔值，也可以是对象和列表。参数参考中的 `resources.cpu` 表示“`resources` 对象里的 `cpu` 字段”，不是名为 `resources.cpu` 的扁平键。

下面四种写法等价，都会为 Daytona 设置 2 个 vCPU 和 6 GiB 内存。

CLI 使用 JSON 对象：

```bash theme={"system"}
--env daytona \
  --env-params '{"resources":{"cpu":2,"memory_mb":6144}}'
```

配置文件保留 YAML 的嵌套结构：

```yaml theme={"system"}
environments:
  daytona:
    resources:
      cpu: 2
      memory_mb: 6144
```

Python SDK 使用嵌套字典：

```python theme={"system"}
from agentcompass import run_evaluation

result = run_evaluation(
    benchmark="<benchmark>",
    harness="<harness>",
    model="<model>",
    environment="daytona",
    environment_params={"resources": {"cpu": 2, "memory_mb": 6144}},
)
```

`launch` 编排将参数与 `id` 写在同一层，参数内部仍可嵌套：

```yaml theme={"system"}
defaults:
  environment:
    id: daytona
    resources:
      cpu: 2
      memory_mb: 6144
```

对象按字段递归合并，标量和列表则由后面的值整体替换。例如，配置文件已经设置 `resources.cpu: 2` 和 `resources.memory_mb: 6144`，本次请求只传入 `{"resources":{"memory_mb":8192}}` 时，结果是 2 个 vCPU 和 8192 MiB 内存。

不要额外增加 `params` 包装层，也不要把字段路径写成 `{"resources.cpu":2}`。嵌套字段、单位和可用值以相应 provider 的[参数参考](/zh/user_guide/modules/environments/overview#选择-provider)为准。

## 分清字段归属

Environment 参数由两类字段组成：

| 字段类别 | 字段或示例 | 说明 |
| - | - | - |
| 共享 setup 字段 | `setup.image`、`setup.workdir`、`setup.build_timeout_seconds`、`setup.os` | 描述与 provider 无关的启动要求。provider 会把支持的字段映射到 adapter，但不会把 workdir 当作 Benchmark workspace。 |
| 共享网络字段 | `network_policy`、`run_network_policy`、`verifier_network_policy` | 分别设置基础策略、agent 运行策略和验证策略；后两项未设置时继承基础策略。provider 必须支持所选模式，详见[网络策略](/zh/user_guide/modules/environments/configuration/network)。 |
| provider 字段 | 凭证、资源、调度位置和生命周期等 | 由所选 provider 定义。字段名、单位和默认值不能在不同 provider 之间直接照搬。 |

无论使用哪种入口，共享 setup 字段、共享网络字段和 provider 字段都写在同一层，不需要再增加 `params`。例如，在配置文件中，它们都直接写在 `environments.docker` 下。

## 查看字段与配置结果

查询当前安装版本中某个 provider 的专属字段、类型和默认值：

```bash theme={"system"}
agentcompass config docs env docker
```

查看内置默认值与配置文件合并后的结果：

```bash theme={"system"}
agentcompass config show \
  --env docker \
  --config config.yaml
```

`config show` 只展示内置值和配置文件的合并结果，不包含本次运行额外传入的 CLI、SDK 或编排字段，也不会展示 Recipe 在任务开始前补充的最终 Environment 设置。命令的完整行为见 [`agentcompass config`](/zh/user_guide/using_agentcompass/cli/config)。

## Environment 参数如何生效

Environment 参数不是一次性从某一个入口读取，而是按以下阶段逐步形成：

| 阶段 | 作用 |
| - | - |
| provider 默认值与配置文件 | 形成可复用的基础配置；配置文件中的值覆盖同名内置默认值。`config show` 展示到这一阶段为止的结果。 |
| 本次请求的显式参数 | `run` CLI、Python SDK 或编排请求中显式传入的字段覆盖配置文件中的同名值。 |
| [Recipe](/zh/user_guide/other_features/recipes) | 等具体任务确定后，根据 Benchmark、Harness 和 provider 的组合补充或调整镜像、Environment workdir、Benchmark workspace、资源、网络及必要的执行设置。因为这些调整与任务有关，所以不会出现在 `config show` 中。 |

下面的命令没有设置 Docker 镜像。匹配的 SWE-bench Verified Recipe 会根据样本补充镜像和任务工作区，因此通常只需选择 provider：

```bash theme={"system"}
agentcompass run swebench_verified mini_swe_agent "$MODEL_NAME" \
  --env docker
```

如果没有匹配的 Recipe，仍须按照 provider 页面提供其必填字段，例如 Docker 的任务镜像。Recipe 也不是一条“显式参数永远优先”的通用规则：内置 Recipe 通常会保留兼容的显式镜像和资源设置，但仍可能调整 Benchmark 或 Harness 必需的工作区、网络或执行设置。

只有确实需要改变默认行为时才传入 Environment 参数。不同 provider 的合法取值以相应 provider 页面和 `config docs` 输出为准。

<Note>
  评测总超时、并发和 Environment 启动速率属于[运行控制](/zh/user_guide/using_agentcompass/run_controls)。[Modal 的 `timeout`](/zh/user_guide/modules/environments/providers/modal) 和 [OpenSandbox 的 `lifecycle_seconds`](/zh/user_guide/modules/environments/providers/opensandbox) 等字段只限制单个 sandbox 的存活时间，不等同于评测总超时。
</Note>

## 相关页面

* [网络策略](/zh/user_guide/modules/environments/configuration/network)
* [资源限制](/zh/user_guide/modules/environments/configuration/resource_limits)
* [Environment provider 列表](/zh/user_guide/modules/environments/overview#选择-provider)

原生适配器可能要求某些变量保持特定值，用于启动 runner 或映射统一的 Model、execution 配置。用户声明的环境变量与这些约束冲突时，命令在启动前失败，错误只列出变量名。应修改对应的 Model、Harness 或 execution 配置，避免通过生成的变量覆盖它；相同值可以接受。这不会新增 CLI 字段。内部 Python runner 在可以自行引导模块导入时保留用户的 `PYTHONPATH`；mini-SWE-agent CLI 仍需要生成模块所在目录，会拒绝冲突的 `PYTHONPATH`。


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