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

# OpenSandbox 接入

`opensandbox` 是 AgentCompass 对 OpenSandbox 生命周期服务的客户端适配器，不是一种具体的 sandbox runtime。AgentCompass 使用官方 Python SDK 请求创建 sandbox，并通过 OpenSandbox 的统一命令与文件接口操作它；真正的工作负载由服务端配置的 runtime 创建，部署位置和隔离强度也由服务端决定。选择 `--env opensandbox` 不会在 AgentCompass 侧选择底层 runtime。

## 理解接入关系

OpenSandbox 官方架构将客户端、生命周期服务和 runtime backend 分开。当前官方服务支持 Docker 和 Kubernetes runtime，具体选择与安全配置都发生在 OpenSandbox 服务端。详见 [OpenSandbox 架构说明](https://open-sandbox.ai/architecture/)。

<div style={{overflowX:'auto'}}>
  <table style={{width:'100%', minWidth:'680px', tableLayout:'fixed'}}>
    <thead>
      <tr><th style={{width:'210px'}}>层级</th><th>负责的内容</th></tr>
    </thead>

    <tbody>
      <tr><td style={{width:'210px'}}>AgentCompass 的 <code>opensandbox</code> 适配器</td><td>把 Environment 的创建、命令和文件操作转换为 OpenSandbox SDK 调用。</td></tr>
      <tr><td style={{width:'210px'}}>OpenSandbox 生命周期服务</td><td>处理 API 鉴权、sandbox 生命周期和请求转发。</td></tr>
      <tr><td style={{width:'210px'}}>服务端 runtime</td><td>实际创建工作负载、拉取镜像，并决定部署位置、隔离方式和可用资源。</td></tr>
    </tbody>
  </table>
</div>

因此，使用该适配器前，必须先准备 OpenSandbox 服务，并在服务端选择与评测要求匹配的 runtime。AgentCompass 不会部署该服务，也不会替你配置 Docker、Kubernetes、镜像仓库凭证或底层隔离机制。

## 接入前准备

1. 按 OpenSandbox 的[快速入门](https://open-sandbox.ai/getting-started/)和[安装说明](https://open-sandbox.ai/getting-started/installation)部署生命周期服务。
2. 在服务端[配置 runtime 和鉴权](https://open-sandbox.ai/getting-started/configuration)。实际 runtime 必须能够拉取评测镜像，并提供 Benchmark 与 Harness 需要的命令、目录和资源。
3. 确认 AgentCompass host 能访问生命周期服务，而且服务端代理能够转发 sandbox 的命令和文件请求。
4. 如果服务启用了鉴权，准备有权创建和销毁 sandbox 的 API key。

连接信息默认从 `OPEN_SANDBOX_DOMAIN` 和 `OPEN_SANDBOX_API_KEY` 读取，也可以写入私有配置文件的 `domain` 和 `api_key`。生产部署应启用 API key；不要将真实密钥提交到仓库。

<a id="运行一个任务" />

## 使用 `run` 验证配置

当前适配器只支持从镜像创建 sandbox，因此必须显式提供与服务端 runtime 和评测任务都兼容的镜像。下面通过 [`sample_ids`](/zh/user_guide/modules/benchmarks/overview#共享-benchmark-字段) 只运行一个任务：

```bash theme={"system"}
agentcompass run <benchmark> <harness> "$MODEL_NAME" \
  --env opensandbox \
  --env-params '{"image":"registry.example.com/eval-image:tag"}' \
  --benchmark-params '{"sample_ids":["<sample-id>"]}'
```

请将占位符替换为实际组件和样本 ID。上面是 `agentcompass run` 的最小验证示例；模型端点等通用参数见 [`agentcompass run`](/zh/user_guide/using_agentcompass/cli/run)。

`opensandbox` 同样支持 `agentcompass launch`。在编排文件的 `defaults.environment` 中设置所有请求共享的配置，或在 `requests[].environment` 中设置单个请求；`id: opensandbox` 与适配器参数写在同一层。详见 [`launch` 的映射规则](/zh/user_guide/using_agentcompass/cli/launch#映射规则)。

AgentCompass 目前没有面向 `opensandbox` 的内置专属 [Recipe](/zh/user_guide/other_features/recipes)，不会自动选择镜像或 workspace。

<a id="provider-参数" />

## 参数参考

参数可以通过 `--env-params` 传入，也可以写在配置文件的 `environments.opensandbox` 中。

前面“使用 `run` 验证配置”的完整命令已经展示了最小参数：当前适配器必须显式提供 `image`。

### 连接与凭证

| 字段        | 默认值                                                 | 说明                                                                                                                                   |
| --------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `api_key` | `OPEN_SANDBOX_API_KEY`                              | OpenSandbox 生命周期服务的 API 密钥，不是镜像仓库或底层 runtime 的凭证。仅当服务端未启用 API 鉴权时才可留空。                                                               |
| `domain`  | `OPEN_SANDBOX_DOMAIN`；未设置时由 SDK 使用 `localhost:8080` | 生命周期服务的根地址。可以写 `host[:port]`，也可以写带 `http://` 或 `https://` 的地址；不带 scheme 时使用 HTTP，连接 HTTPS 服务时必须显式写出 `https://`。不要包含 `/v1`，SDK 会自动追加。 |

### 镜像与启动

| 字段           | 默认值  | 说明                                                                                                                                |
| ------------ | ---- | --------------------------------------------------------------------------------------------------------------------------------- |
| `image`      | 无，必填 | 请求服务端 runtime 拉取的容器镜像。当前 AgentCompass 适配器只支持从镜像创建；私有仓库凭证需要在 OpenSandbox 服务端或 runtime 侧配置。                                         |
| `entrypoint` | `[]` | 传给 OpenSandbox 的容器入口参数数组，例如 `["bash","-lc","python app.py"]`，不能写成单个 shell 命令字符串。保持空列表时，SDK 使用 `["tail","-f","/dev/null"]` 作为默认入口。 |

### 标识与元数据

当前 AgentCompass 适配器不提供 OpenSandbox sandbox 名称或元数据参数；`--env-params` 和 `environments.opensandbox` 中没有对应字段。

### 工作区与环境变量

<div style={{overflowX:'auto'}}>
  <table style={{width:'100%', minWidth:'760px', tableLayout:'fixed'}}>
    <thead>
      <tr><th style={{width:'260px'}}>字段</th><th style={{width:'100px'}}>默认值</th><th>说明</th></tr>
    </thead>

    <tbody>
      <tr><td style={{width:'260px'}}><code>default\_workspace\_root</code></td><td style={{width:'100px'}}><code>/workspace/</code></td><td>Benchmark 未指定任务工作目录时，提供给 Harness 的非空默认路径。该字段不会创建目录或配置存储；镜像或任务准备步骤必须确保该路径可用。</td></tr>
      <tr><td style={{width:'260px'}}><code>env\_variables</code></td><td style={{width:'100px'}}><code>\{}</code></td><td>创建 sandbox 和执行命令时注入的环境变量映射，例如 <code>\{"LANG":"C.UTF-8"}</code>。键必须符合 <code>\[A-Za-z\_]\[A-Za-z0-9\_]\*</code>，值会转换为字符串。</td></tr>
      <tr><td style={{width:'260px'}}><code>shared\_storage</code></td><td style={{width:'100px'}}><code>\[]</code></td><td>按顺序匹配的已有共享挂载路径映射，不会创建或挂载存储。每项包含 AgentCompass host 上的 <code>host\_path</code> 和同一内容在 sandbox 中的 <code>env\_path</code>。上传源路径命中映射时，AgentCompass 从对应的 <code>env\_path</code> 在 sandbox 内复制；未命中时通过 API 上传。</td></tr>
    </tbody>
  </table>
</div>

下面的对象可以直接作为 `--env-params` 的一部分，或写入 `environments.opensandbox`：

```json theme={"system"}
{
  "shared_storage": [
    {
      "host_path": "/mnt/shared",
      "env_path": "/mnt/shared"
    }
  ]
}
```

`shared_storage.host_path` 和 `shared_storage.env_path` 都必须是绝对路径，不能包含 `..`，也不能是文件系统根目录。`host_path` 必须是 host 上已存在的目录；`env_path` 必须已由 OpenSandbox 部署或 runtime 暴露到每个 sandbox，并且具备读取和访问权限。同一上传源路径匹配多个 `host_path` 时，列表中靠前的映射生效。

### 资源

| 字段          | 默认值  | 说明                                                                                                                                           |
| ----------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `resources` | `{}` | 传给 OpenSandbox `resourceLimits` 的字符串映射，例如 `{"cpu":"2","memory":"4Gi"}`；键、单位和可用规格由服务端 runtime 解释。未提供时，当前 SDK 使用 `{"cpu":"1","memory":"2Gi"}`。 |

### 网络

当前 AgentCompass 适配器不提供 OpenSandbox 专属网络参数，也尚未接入共享网络策略；`network_policy`、`run_network_policy` 和 `verifier_network_policy` 只能使用 `public`。OpenSandbox 服务端或 runtime 配置的网络限制仍然生效。

### 生命周期与超时

<div style={{overflowX:'auto'}}>
  <table style={{width:'100%', minWidth:'760px', tableLayout:'fixed'}}>
    <thead>
      <tr><th style={{width:'240px'}}>字段</th><th style={{width:'100px'}}>默认值</th><th>说明</th></tr>
    </thead>

    <tbody>
      <tr><td style={{width:'240px'}}><code>lifecycle\_seconds</code></td><td style={{width:'100px'}}><code>43200</code></td><td>请求服务端设置的自动过期时间（秒），必须为正数。即使 AgentCompass 保留 Environment，服务端仍可按该时间清理 sandbox。</td></tr>
      <tr><td style={{width:'240px'}}><code>request\_timeout\_seconds</code></td><td style={{width:'100px'}}><code>120</code></td><td>OpenSandbox SDK HTTP 请求的超时（秒），必须为正数；不替代 sandbox 内命令的执行超时。</td></tr>
      <tr><td style={{width:'240px'}}><code>ready\_timeout\_seconds</code></td><td style={{width:'100px'}}><code>120</code></td><td>创建请求发出后，等待 sandbox 内 execd（命令与文件服务）通过健康检查的最长时间（秒），必须为正数；它不表示 <code>entrypoint</code> 启动的应用已经就绪。</td></tr>
    </tbody>
  </table>
</div>

## 参数参考来源

* 运行 `agentcompass config docs env opensandbox`，可以查看当前安装版本实际支持的字段、类型和默认值。
* OpenSandbox SDK 的连接、创建参数和默认行为见[官方 Python SDK 文档](https://github.com/opensandbox-group/OpenSandbox/blob/main/sdks/sandbox/python/README.md)。

支持的字段、类型和默认值以 `agentcompass config docs env opensandbox` 的输出为准；其中 `default_workspace_root` 和 `shared_storage` 是 AgentCompass 适配器字段。生命周期服务和 server-side runtime 如何解释请求，以上游 SDK、服务端配置和具体 runtime 为准。

## AgentCompass 适配范围

* 当前适配器只支持从 `image` 创建 sandbox，不支持 OpenSandbox API 提供的其他启动来源。
* 当前适配器尚未把 AgentCompass 的共享[网络策略](/zh/user_guide/modules/environments/configuration/network)转换为 OpenSandbox `networkPolicy`，因此这里只接受 `public`，也不能按阶段切换。OpenSandbox 平台本身支持[出站网络策略](https://open-sandbox.ai/components/egress)，服务端或 runtime 的限制仍可能影响实际网络访问。
* AgentCompass host 通过 OpenSandbox 生命周期服务代理命令与文件请求，因此服务端代理必须可用。
* 正常关闭 Environment 时会请求销毁 sandbox；当前没有 `delete_on_close` 一类的参数。`--keep-environment` 只跳过 AgentCompass 的主动销毁，不会覆盖服务端的 `lifecycle_seconds`。
* 命令自身的执行超时由 Harness 或调用方传入，不由 `request_timeout_seconds` 控制。

## 故障排查

<div style={{overflowX:'auto'}}>
  <table style={{width:'100%', minWidth:'720px', tableLayout:'fixed'}}>
    <thead>
      <tr><th style={{width:'260px'}}>现象</th><th>检查内容</th></tr>
    </thead>

    <tbody>
      <tr><td style={{width:'260px'}}>提示 <code>image</code> 必填</td><td>在 <code>--env-params</code> 或 <code>environments.opensandbox.image</code> 中提供可拉取的容器镜像。</td></tr>
      <tr><td style={{width:'260px'}}>生命周期请求或鉴权失败</td><td>检查 <code>domain</code>、<code>api\_key</code> 和 OpenSandbox 服务日志；<code>api\_key</code> 不负责底层 runtime 或镜像仓库鉴权。</td></tr>
      <tr><td style={{width:'260px'}}>创建失败或镜像无法拉取</td><td>检查 OpenSandbox 服务端 runtime、镜像仓库凭证及 Docker / Kubernetes 日志。</td></tr>
      <tr><td style={{width:'260px'}}>sandbox 一直没有就绪</td><td>检查 sandbox 中的执行服务健康状态和服务端代理，再根据实际启动时间调整 <code>ready\_timeout\_seconds</code>。</td></tr>
      <tr><td style={{width:'260px'}}>资源请求被拒绝</td><td>确认 <code>resources</code> 的键、单位和规格能被所连接的服务端 runtime 接受。</td></tr>
      <tr><td style={{width:'260px'}}>共享存储校验失败</td><td>确认两个路径已指向同一份预先挂载的内容，并且 sandbox 侧路径可读、可访问。</td></tr>
      <tr><td style={{width:'260px'}}>提示网络模式不支持</td><td>当前 AgentCompass 适配器没有接入共享网络策略，请保持三个阶段均为 <code>public</code>。</td></tr>
    </tbody>
  </table>
</div>

## 相关页面

* [OpenSandbox 官方架构](https://open-sandbox.ai/architecture/)
* [OpenSandbox 服务端配置](https://open-sandbox.ai/getting-started/configuration)
* [OpenSandbox Python SDK](https://github.com/opensandbox-group/OpenSandbox/blob/main/sdks/sandbox/python/README.md)
* [OpenSandbox API](https://open-sandbox.ai/api/)
* [Environment 概览](/zh/user_guide/modules/environments/overview)
* [配置 Environment](/zh/user_guide/modules/environments/configuration/overview)
* [运行控制](/zh/user_guide/using_agentcompass/run_controls)
* [CLI 配置文件](/zh/user_guide/using_agentcompass/cli/config)