创建 Environment

描述

创建可供 Agent Session 使用的运行环境配置。

路径

POST /api/v1/forward/environments

请求头

头部	必选	说明
`Authorization`	是	`Bearer <PAT 或 SAT>`
`Content-Type`	是	`application/json`
`Idempotency-Key`	否	建议创建请求携带。相同 key 和相同请求可安全重试。

请求体

字段	类型	必选	说明
`name`	string	是	Environment 名称；去除首尾空白后不能为空。
`description`	string	否	描述。
`config`	Environment config	否	Environment 运行时配置对象；省略时默认使用 `{"type":"cloud"}`。显式传入时不能为 `null` 或空对象。字段详见 schemas。
`metadata`	object	否	Environment metadata；省略时为 `{}`，显式传入时不能为 `null`。

config 的子字段（type / packages / setup_script）以及各自的取值约束，统一在 Environment config 中定义。self_hosted Environment 只允许 type 和可选的 setup_script；cloud Environment 可额外声明 packages。

示例请求

curl -sS --fail-with-body \
  -X POST "https://api.qoder.com/api/v1/forward/environments" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dev-env",
    "description": "Development environment",
    "config": {
      "type": "cloud"
    },
    "metadata": {
      "source": "console"
    }
  }'

带 packages 和 setup script 的请求

curl -sS --fail-with-body \
  -X POST "https://api.qoder.com/api/v1/forward/environments" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "doc-test-env-with-setup",
    "config": {
      "type": "cloud",
      "packages": {
        "npm": ["pnpm@9"]
      },
      "setup_script": "set -euo pipefail\n[ -d /workspace/.git ] || git clone https://github.com/me/repo /workspace\ncd /workspace && pnpm install --frozen-lockfile"
    }
  }'

示例响应

HTTP 201 Created

{
  "id": "env_xxx",
  "type": "environment",
  "name": "dev-env",
  "description": "Development environment",
  "config": {
    "type": "cloud",
    "packages": {
      "type": "packages",
      "apt": [],
      "cargo": [],
      "gem": [],
      "go": [],
      "npm": [],
      "pip": []
    }
  },
  "metadata": {
    "source": "console"
  },
  "archived_at": null,
  "created_at": "2026-07-23T10:00:00Z",
  "updated_at": "2026-07-23T10:00:00Z",
  "identity_id": null
}

响应字段

响应为 Environment 对象。config 会规范化为完整形态，cloud Environment 的 config.packages 会补齐 Environment packages 中所有保留 key 的空数组。

错误码

HTTP	type	触发条件
400	`invalid_request_error`	`name` 缺失或为空，请求体不是合法 JSON，或者 `config` / `metadata` 不符合上述约束。
400	`invalid_request_error`	传入保留键 `created_by` 时，`message` 为 `metadata key "created_by" is reserved`，可据此定位到具体字段。
401	`authentication_error`	缺少或无效的认证令牌。
403	`permission_error`	当前调用方无权访问该资源。
409	`conflict_error`	`Idempotency-Key` 对应不同请求，或创建流程处于需要人工恢复的中间状态。
413	`invalid_request_error`	请求体超过服务允许的大小。
429	`rate_limit_error`	当前调用方超过接口限流。
500/502/503	`api_error`	Forward 或依赖服务失败。

​描述

​路径

​请求头

​请求体

​示例请求

​带 packages 和 setup script 的请求

​示例响应

​响应字段

​错误码

描述

路径

请求头

请求体

示例请求

带 packages 和 setup script 的请求

示例响应

响应字段

错误码