> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment 结构

> Environment 对象和配置字段结构。

## Environment 对象

创建、查询、列表、更新和归档接口都会返回该结构。

| 字段            | 类型                                        | 说明                                                                          |
| ------------- | ----------------------------------------- | --------------------------------------------------------------------------- |
| `id`          | string                                    | Environment ID，前缀为 `env_`                                                   |
| `type`        | string                                    | 固定值 `"environment"`                                                         |
| `name`        | string                                    | Environment 名称                                                              |
| `description` | string                                    | Environment 描述                                                              |
| `config`      | [Environment config](#environment-config) | Environment 配置                                                              |
| `metadata`    | object                                    | [Metadata 对象](/zh/cloud-agents/api/conventions/schemas#metadata-对象)，默认 `{}` |
| `archived_at` | string \| null                            | UTC 归档时间；未归档时为 `null`                                                       |
| `created_at`  | string                                    | UTC 创建时间                                                                    |
| `updated_at`  | string                                    | UTC 最后更新时间                                                                  |

## Environment config

| 字段             | 类型                                                | 必填 | 说明                                                                          |
| -------------- | ------------------------------------------------- | -- | --------------------------------------------------------------------------- |
| `type`         | string                                            | 是  | `"cloud"` 或 `"self_hosted"`                                                 |
| `networking`   | [Environment networking](#environment-networking) | 否  | 网络访问配置                                                                      |
| `packages`     | [Environment packages](#environment-packages)     | 否  | Environment 关联的包声明                                                          |
| `setup_script` | string                                            | 否  | 用户 setup script 文本，详见 [Environment setup script](#environment-setup-script) |

`self_hosted` config 必须严格为：

```json theme={null}
{"type": "self_hosted"}
```

其他 config 字段仅适用于 `type` 为 `"cloud"` 的 Environment。

## Environment packages

`packages` 是包管理器到软件包规格字符串数组的映射。Cloud Environment 响应会包含 `type` 以及 `apt`、`npm`、`pip`；省略的数组会返回为 `[]`。

| key    | 类型        | 说明                  | 示例                                   |
| ------ | --------- | ------------------- | ------------------------------------ |
| `type` | string    | 响应中固定为 `"packages"` | `"packages"`                         |
| `apt`  | string 数组 | Debian/Ubuntu 系统包声明 | `["git", "curl", "build-essential"]` |
| `npm`  | string 数组 | Node.js package 声明  | `["typescript@5.0.0", "eslint"]`     |
| `pip`  | string 数组 | Python package 声明   | `["pandas", "PyYAML==6.0.1"]`        |

## Environment setup script

`setup_script` 是 sandbox 准备阶段、`packages` 安装完成之后执行的一段 shell 脚本，用 `/bin/bash -lc` 运行。常用于克隆代码、写配置文件、warmup 缓存等无法用 `packages` 表达的初始化步骤。

| 约束   | 值                              |
| ---- | ------------------------------ |
| 类型   | string                         |
| 最大长度 | 64 KB                          |
| 解释器  | `/bin/bash -lc`                |
| 超时   | 10 分钟                          |
| 执行时机 | sandbox 准备阶段，`packages` 安装完成之后 |

执行成功后会在沙箱内写入完成标记，本次 sandbox 内不会重复执行；沙箱被回收重建后会再次执行。

脚本以非零状态退出会导致 Session 启动失败。错误响应中会带上 `setup_script` 的 exit code 与 stderr 摘要，便于定位失败原因。

```json theme={null}
{
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"},
    "setup_script": "set -euo pipefail\n[ -d /workspace/.git ] || git clone https://github.com/me/repo /workspace\ncd /workspace && pnpm install --frozen-lockfile"
  }
}
```

## Environment networking

| 字段                       | 类型        | 必填 | 说明                                           |
| ------------------------ | --------- | -- | -------------------------------------------- |
| `type`                   | string    | 是  | 可选值：`limited`、`unrestricted`                 |
| `allowed_hosts`          | string 数组 | 否  | 随 config 返回的 host allowlist，默认 `[]`          |
| `allow_package_managers` | boolean   | 否  | 随 config 返回的 package manager 访问标记，默认 `false` |
| `allow_mcp_servers`      | boolean   | 否  | 随 config 返回的 MCP server 访问标记，默认 `false`      |

## 相关

<CardGroup cols={2}>
  <Card title="云端环境" icon="server" href="/zh/cloud-agents/environments">
    选择 Agent 运行的容器、网络与依赖。
  </Card>
</CardGroup>