跳转到主要内容

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 定义了 Session 运行的容器模板——操作系统、网络策略、预装依赖。你可以为不同场景创建不同的环境：严格隔离的安全审计环境、预装数据科学库的分析环境、或者开放网络的通用开发环境。

​
环境是什么

Environment 是 Session 的基础设施层：
  • 容器类型 — 目前支持 cloud（云端托管容器）
  • 网络策略 — 控制容器的出站网络访问
  • 依赖包 — 预装系统包、Python 包、Node.js 包
每个 Session 启动时会基于指定的 Environment 模板创建隔离的运行实例。

​
字段说明

字段类型必填说明
idstring—系统生成，env_ 前缀
namestring是环境名称
configobject是环境配置（类型、网络、包）
config.typestring是容器类型，当前固定为 "cloud"
config.networkingstring/object否网络策略
config.packagesobject否预装依赖包配置
statusstring—环境状态：ready
created_atstring—创建时间
updated_atstring—最后更新时间

​
默认环境

每个账号都有一个名为 default 的预置环境，配置为： 
{
  "id": "env_default",
  "name": "default",
  "config": {
    "type": "cloud",
    "networking": "unrestricted"
  },
  "status": "ready"
}
大多数场景直接使用 default 环境即可，无需额外创建。
default 环境不可删除，但可以通过创建新环境来满足特殊需求。

​
网络策略

config.networking 支持三种模式。"unrestricted" 可以使用字符串简写形式；limited 和 allowlist 必须使用对象格式。
模式值说明
完全开放"unrestricted"容器可以访问任意外部地址
受限{"type": "limited", "allow_package_managers": true}仅允许访问已知安全的公共服务和包管理器
白名单{"type": "allowlist", "domains": [...]}仅允许访问指定域名

​
networking 对象字段

字段类型说明
networking.typestring网络策略类型：unrestricted / limited / allowlist
networking.allow_package_managersbooleanlimited 模式下是否允许包管理器（pip / npm / apt 等）访问
networking.domainsarrayallowlist 模式下允许的域名列表

​
完全开放

{
  "config": {
    "type": "cloud",
    "networking": "unrestricted"
  }
}
适用于需要下载依赖、访问外部 API 的通用开发任务。

​
受限模式

{
  "config": {
    "type": "cloud",
    "networking": {
      "type": "limited",
      "allow_package_managers": true
    }
  }
}
适用于不需要任意外网访问、但仍需通过包管理器拉依赖的任务。

​
白名单模式

{
  "config": {
    "type": "cloud",
    "networking": {
      "type": "allowlist",
      "domains": [
        "api.github.com",
        "registry.npmjs.org",
        "pypi.org"
      ]
    }
  }
}
适用于安全合规要求高的场景，精确控制可访问的外部服务。

​
预装依赖

通过 config.packages 指定容器启动时预装的依赖： 
{
  "config": {
    "type": "cloud",
    "networking": "unrestricted",
    "packages": {
      "apt": ["git", "build-essential", "libssl-dev"],
      "pip": ["pandas", "numpy", "scikit-learn"],
      "npm": ["typescript", "eslint", "prettier"]
    }
  }
}
包管理器字段说明
aptpackages.aptDebian/Ubuntu 系统包
pippackages.pipPython 包
npmpackages.npmNode.js 包（全局安装）
预装依赖会增加环境初始化时间。只添加确实需要的包，其余可在 Session 运行时按需安装。

​
创建环境

# 创建一个数据科学专用环境
curl -s -X POST https://openapi.qoder.sh/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-science",
    "config": {
      "type": "cloud",
      "networking": "unrestricted",
      "packages": {
        "apt": ["build-essential"],
        "pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter"]
      }
    }
  }' | jq .
成功返回 201 Created： 
{
  "id": "env_ds456",
  "name": "data-science",
  "config": {
    "type": "cloud",
    "networking": "unrestricted",
    "packages": {
      "apt": ["build-essential"],
      "pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter"]
    }
  },
  "status": "ready",
  "created_at": "2026-05-18T10:00:00Z",
  "updated_at": "2026-05-18T10:00:00Z"
}

​
创建安全受限环境

# 创建一个仅允许访问内部 API 的安全环境
curl -s -X POST https://openapi.qoder.sh/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "secure-internal",
    "config": {
      "type": "cloud",
      "networking": {
        "type": "allowlist",
        "domains": ["internal-api.mycompany.com", "git.mycompany.com"]
      },
      "packages": {
        "apt": ["git", "curl"]
      }
    }
  }' | jq .

​
查询环境

# 列出所有环境
curl -s https://openapi.qoder.sh/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT"

# 获取单个环境详情
curl -s https://openapi.qoder.sh/api/v1/cloud/environments/env_ds456 \
  -H "Authorization: Bearer $QODER_PAT"

​
更新环境

# 为已有环境添加新的依赖包
curl -s -X PUT https://openapi.qoder.sh/api/v1/cloud/environments/env_ds456 \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-science",
    "config": {
      "type": "cloud",
      "networking": "unrestricted",
      "packages": {
        "apt": ["build-essential", "libpq-dev"],
        "pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter", "sqlalchemy"]
      }
    }
  }' | jq .
更新环境不会影响已运行的 Session。新配置仅对后续创建的 Session 生效。

​
删除环境

# 删除自定义环境
curl -s -X DELETE https://openapi.qoder.sh/api/v1/cloud/environments/env_ds456 \
  -H "Authorization: Bearer $QODER_PAT"

​
环境选型建议

场景推荐配置
通用开发default 环境，无需额外配置
数据分析预装 pandas/numpy，开放网络
安全审计白名单网络，最小依赖
前端开发预装 Node.js 生态工具，开放 npm registry
CI/CD 集成预装 git/docker CLI，白名单模式

​
常见问题

Q: 环境创建后需要等待多久才能使用？ A: 环境创建后状态直接为 ready，可立即用于创建 Session。实际的容器初始化（包括安装依赖）发生在 Session 启动时。 Q: 预装包的版本可以指定吗？ A: pip 和 npm 包支持版本指定，如 "pandas==2.1.0" 或 "typescript@5.0.0"。apt 包使用系统源的默认版本。 Q: networking 设置错误导致 Agent 运行失败怎么办？ A: 创建一个新的环境（或更新现有环境），修改网络策略后重新启动 Session。 Q: 一个账号最多能创建多少个环境？ A: 无硬性限制，但建议按实际需求创建，避免管理混乱。建议通过命名规范分类。

​
下一步