> ## Documentation Index
> Fetch the complete documentation index at: https://oma-codex-339-workspace-permissions.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 更新环境

> 通过 OMA API 更新环境。

<Info>每个请求都必须发送 `?beta=true`。</Info>


## OpenAPI

````yaml /openapi/oma.zh.json post /v1/environments/{environment_id}
openapi: 3.1.0
info:
  title: OMA API 参考
  version: 1.0.0
  description: Open Managed Agents 应用 API 参考。
servers:
  - url: http://localhost:38080
    description: 本地 OMA 服务器
security:
  - omaApiKey: []
  - omaBearer: []
paths:
  /v1/environments/{environment_id}:
    post:
      summary: 更新环境
      description: 通过 OMA API 更新环境。
      operationId: beta_update_environment_v1_environments__environment_id__post
      parameters:
        - name: beta
          in: query
          required: true
          description: 为此接口启用 Beta API 合同，必须为 `true`。
          schema:
            type: boolean
            enum:
              - true
        - name: environment_id
          in: path
          required: true
          schema:
            type: string
            x-stainless-cli-data-alias: id
            title: 环境 ID
          example: env_011CZkZ9X2dpNyB7HsEFoRfW
        - name: anthropic-beta
          in: header
          required: false
          schema:
            type: string
            items:
              type: string
            description: |-
              用于指定要使用的 beta 版本的可选请求头。

              要使用多个 beta，请使用逗号分隔的列表（如 `beta1,beta2`），或为每个 beta 分别指定该请求头。
            title: Anthropic-Beta
            x-stainless-override-schema:
              x-stainless-param: betas
              x-stainless-extend-default: true
              type: array
              description: 用于指定一个或多个 Beta 版本的可选请求头。
              items:
                $ref: '#/components/schemas/AnthropicBeta'
            x-default: managed-agents-2026-04-01
          description: |-
            用于指定要使用的 beta 版本的可选请求头。

            要使用多个 beta，请使用逗号分隔的列表（如 `beta1,beta2`），或为每个 beta 分别指定该请求头。
        - name: anthropic-version
          in: header
          required: false
          schema:
            type: string
            description: |-
              你想使用的 OMA API 版本。

              在此处阅读更多关于版本控制和我们版本历史的信息。
            title: Anthropic-Version
          description: |-
            你想使用的 OMA API 版本。

            在此处阅读更多关于版本控制和我们版本历史的信息。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BetaPublicEnvironmentUpdateRequest'
      responses:
        '200':
          description: 成功的响应
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaEnvironment'
        4XX:
          description: |-
            错误响应。

            详见我们的错误文档。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
components:
  schemas:
    BetaPublicEnvironmentUpdateRequest:
      properties:
        config:
          anyOf:
            - oneOf:
                - $ref: '#/components/schemas/BetaCloudConfigParams'
                - $ref: '#/components/schemas/BetaSelfHostedConfigParams'
              discriminator:
                propertyName: type
                mapping:
                  cloud:
                    $ref: '#/components/schemas/BetaCloudConfigParams'
                  self_hosted:
                    $ref: '#/components/schemas/BetaSelfHostedConfigParams'
            - type: 'null'
          title: 配置
          description: 更新后的环境配置
        description:
          anyOf:
            - type: string
              maxLength: 1024
            - type: 'null'
          title: 描述
          description: 环境的更新描述
          examples:
            - 包含数据分析软件包的 Python 环境。
        metadata:
          additionalProperties:
            anyOf:
              - type: string
              - type: 'null'
          type: object
          title: 元数据
          description: 用户提供的元数据键值对。将值设为 null 或空字符串可删除该键。
        name:
          anyOf:
            - type: string
              maxLength: 256
              minLength: 1
            - type: 'null'
          title: 名称
          description: 环境的更新名称
        scope:
          anyOf:
            - type: string
              enum:
                - organization
                - account
            - type: 'null'
          title: 作用域
          description: 此环境的可见性范围。'organization' 使该环境对所有账号可见。'account' 将可见性限制为仅所属账号。
      additionalProperties: false
      type: object
      title: PublicEnvironmentUpdateRequest
      description: 更新环境的公开 API 请求（不包含 org/account 字段）。
      example:
        description: 包含数据分析包的 Python 环境。
    BetaEnvironment:
      properties:
        archived_at:
          anyOf:
            - type: string
            - type: 'null'
          title: 归档时间
          description: 环境被归档时的 RFC 3339 时间戳，未归档时为 null
          examples:
            - null
        config:
          oneOf:
            - $ref: '#/components/schemas/BetaCloudConfig'
            - $ref: '#/components/schemas/BetaSelfHostedConfig'
          title: 配置
          description: 环境配置（OMA Cloud 或自托管）
          discriminator:
            propertyName: type
            mapping:
              cloud:
                $ref: '#/components/schemas/BetaCloudConfig'
              self_hosted:
                $ref: '#/components/schemas/BetaSelfHostedConfig'
          examples:
            - type: cloud
              networking:
                type: limited
                allowed_hosts:
                  - api.example.com
                allow_package_managers: true
                allow_mcp_servers: false
              packages:
                type: packages
                pip:
                  - pandas
                  - numpy
                npm: []
                apt: []
                cargo: []
                gem: []
                go: []
        created_at:
          type: string
          title: 创建时间
          description: 环境创建时间的 RFC 3339 时间戳
          examples:
            - '2026-03-15T10:00:00Z'
        description:
          type: string
          title: 描述
          description: 用户提供的环境描述
          examples:
            - 包含数据分析软件包的 Python 环境。
        id:
          type: string
          title: ID
          description: 环境标识符（例如 'env_...'）
          examples:
            - env_011CZkZ9X2dpNyB7HsEFoRfW
        metadata:
          additionalProperties:
            type: string
          type: object
          title: 元数据
          description: 用户提供的元数据键值对
          examples:
            - key: value
        name:
          type: string
          title: 名称
          description: 环境的人类可读名称
          examples:
            - python-data-analysis
        scope:
          type: string
          enum:
            - organization
            - account
          title: 作用域
          description: 此环境的可见性范围。'organization' 表示对所有账号可见。'account' 表示仅对所属账号可见。
        type:
          type: string
          const: environment
          title: 类型
          description: 对象类型（始终为 'environment'）
          default: environment
          examples:
            - environment
        updated_at:
          type: string
          title: 更新时间
          description: 环境最后更新时间的 RFC 3339 时间戳
          examples:
            - '2026-03-15T10:00:00Z'
      type: object
      required:
        - archived_at
        - config
        - created_at
        - description
        - id
        - metadata
        - name
        - type
        - updated_at
      title: Environment
      description: 适用于云端和自托管环境的统一环境资源。
      example:
        type: environment
        id: env_011CZkZ9X2dpNyB7HsEFoRfW
        name: python-data-analysis
        description: 包含数据分析包的 Python 环境。
        config:
          type: cloud
          networking:
            type: limited
            allowed_hosts:
              - api.example.com
            allow_package_managers: true
            allow_mcp_servers: false
          packages:
            type: packages
            pip:
              - pandas
              - numpy
            npm: []
            apt: []
            cargo: []
            gem: []
            go: []
        metadata: {}
        archived_at: null
        created_at: '2026-03-15T10:00:00Z'
        updated_at: '2026-03-15T10:00:00Z'
    BetaErrorResponse:
      properties:
        error:
          discriminator:
            mapping:
              api_error:
                $ref: '#/components/schemas/BetaAPIError'
              authentication_error:
                $ref: '#/components/schemas/BetaAuthenticationError'
              billing_error:
                $ref: '#/components/schemas/BetaBillingError'
              invalid_request_error:
                $ref: '#/components/schemas/BetaInvalidRequestError'
              not_found_error:
                $ref: '#/components/schemas/BetaNotFoundError'
              overloaded_error:
                $ref: '#/components/schemas/BetaOverloadedError'
              permission_error:
                $ref: '#/components/schemas/BetaPermissionError'
              rate_limit_error:
                $ref: '#/components/schemas/BetaRateLimitError'
              timeout_error:
                $ref: '#/components/schemas/BetaGatewayTimeoutError'
            propertyName: type
          oneOf:
            - $ref: '#/components/schemas/BetaInvalidRequestError'
            - $ref: '#/components/schemas/BetaAuthenticationError'
            - $ref: '#/components/schemas/BetaBillingError'
            - $ref: '#/components/schemas/BetaPermissionError'
            - $ref: '#/components/schemas/BetaNotFoundError'
            - $ref: '#/components/schemas/BetaRateLimitError'
            - $ref: '#/components/schemas/BetaGatewayTimeoutError'
            - $ref: '#/components/schemas/BetaAPIError'
            - $ref: '#/components/schemas/BetaOverloadedError'
          title: 错误
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: 请求 ID
        type:
          const: error
          default: error
          title: 类型
          type: string
      required:
        - error
        - request_id
        - type
      title: ErrorResponse
      type: object
    BetaCloudConfigParams:
      properties:
        networking:
          anyOf:
            - oneOf:
                - $ref: '#/components/schemas/BetaUnrestrictedNetwork'
                - $ref: '#/components/schemas/BetaLimitedNetworkParams'
              discriminator:
                propertyName: type
                mapping:
                  limited:
                    $ref: '#/components/schemas/BetaLimitedNetworkParams'
                  unrestricted:
                    $ref: '#/components/schemas/BetaUnrestrictedNetwork'
            - type: 'null'
          title: 网络配置
          description: 网络配置策略。更新时省略则保留现有值。
          examples:
            - type: limited
              allowed_hosts:
                - api.example.com
              allow_package_managers: true
        packages:
          anyOf:
            - $ref: '#/components/schemas/BetaPackagesParams'
            - type: 'null'
          description: 包管理器配置。更新时省略则保留现有值。
          examples:
            - pip:
                - pandas
                - numpy
        type:
          type: string
          const: cloud
          title: 类型
          description: 环境类型
          examples:
            - cloud
      additionalProperties: false
      type: object
      required:
        - type
      title: CloudConfigParams
      description: |-
        `cloud` 环境配置的请求参数。

        字段默认为 null；更新时，省略的字段将保留
        现有值。
      example:
        type: cloud
        networking:
          type: limited
          allowed_hosts:
            - api.example.com
          allow_package_managers: true
        packages:
          pip:
            - pandas
            - numpy
    BetaSelfHostedConfigParams:
      properties:
        type:
          type: string
          const: self_hosted
          title: 类型
          description: 环境类型
      additionalProperties: false
      type: object
      required:
        - type
      title: SelfHostedConfigParams
      description: '`self_hosted` 环境配置的请求参数。'
    BetaCloudConfig:
      properties:
        networking:
          oneOf:
            - $ref: '#/components/schemas/BetaUnrestrictedNetwork'
            - $ref: '#/components/schemas/BetaLimitedNetwork'
          title: 网络配置
          description: 网络配置策略。
          discriminator:
            propertyName: type
            mapping:
              limited:
                $ref: '#/components/schemas/BetaLimitedNetwork'
              unrestricted:
                $ref: '#/components/schemas/BetaUnrestrictedNetwork'
          examples:
            - type: limited
              allowed_hosts:
                - api.example.com
              allow_package_managers: true
              allow_mcp_servers: false
        packages:
          $ref: '#/components/schemas/BetaPackages'
          description: 包管理器配置。
          examples:
            - type: packages
              pip:
                - pandas
                - numpy
              npm: []
              apt: []
              cargo: []
              gem: []
              go: []
        type:
          type: string
          const: cloud
          title: 类型
          description: 环境类型
          examples:
            - cloud
      type: object
      required:
        - networking
        - packages
        - type
      title: CloudConfig
      description: '`cloud` 环境配置。'
      example:
        type: cloud
        networking:
          type: limited
          allowed_hosts:
            - api.example.com
          allow_package_managers: true
          allow_mcp_servers: false
        packages:
          type: packages
          pip:
            - pandas
            - numpy
          npm: []
          apt: []
          cargo: []
          gem: []
          go: []
    BetaSelfHostedConfig:
      properties:
        type:
          type: string
          const: self_hosted
          title: 类型
          description: 环境类型
      additionalProperties: false
      type: object
      required:
        - type
      title: SelfHostedConfig
      description: 自托管环境的配置。
    BetaAPIError:
      properties:
        message:
          default: Internal server error
          title: 消息
          type: string
        type:
          const: api_error
          default: api_error
          title: 类型
          type: string
      required:
        - message
        - type
      title: APIError
      type: object
    BetaAuthenticationError:
      properties:
        message:
          default: Authentication error
          title: 消息
          type: string
        type:
          const: authentication_error
          default: authentication_error
          title: 类型
          type: string
      required:
        - message
        - type
      title: AuthenticationError
      type: object
    BetaBillingError:
      properties:
        message:
          default: Billing error
          title: 消息
          type: string
        type:
          const: billing_error
          default: billing_error
          title: 类型
          type: string
      required:
        - message
        - type
      title: BillingError
      type: object
    BetaInvalidRequestError:
      properties:
        message:
          default: Invalid request
          title: 消息
          type: string
        type:
          const: invalid_request_error
          default: invalid_request_error
          title: 类型
          type: string
      required:
        - message
        - type
      title: InvalidRequestError
      type: object
    BetaNotFoundError:
      properties:
        message:
          default: Not found
          title: 消息
          type: string
        type:
          const: not_found_error
          default: not_found_error
          title: 类型
          type: string
      required:
        - message
        - type
      title: NotFoundError
      type: object
    BetaOverloadedError:
      properties:
        message:
          default: Overloaded
          title: 消息
          type: string
        type:
          const: overloaded_error
          default: overloaded_error
          title: 类型
          type: string
      required:
        - message
        - type
      title: OverloadedError
      type: object
    BetaPermissionError:
      properties:
        message:
          default: Permission denied
          title: 消息
          type: string
        type:
          const: permission_error
          default: permission_error
          title: 类型
          type: string
      required:
        - message
        - type
      title: PermissionError
      type: object
    BetaRateLimitError:
      properties:
        message:
          default: Rate limited
          title: 消息
          type: string
        type:
          const: rate_limit_error
          default: rate_limit_error
          title: 类型
          type: string
      required:
        - message
        - type
      title: RateLimitError
      type: object
    BetaGatewayTimeoutError:
      properties:
        message:
          default: Request timeout
          title: 消息
          type: string
        type:
          const: timeout_error
          default: timeout_error
          title: 类型
          type: string
      required:
        - message
        - type
      title: GatewayTimeoutError
      type: object
    BetaUnrestrictedNetwork:
      properties:
        type:
          type: string
          const: unrestricted
          title: 类型
          description: 网络策略类型
      additionalProperties: false
      type: object
      required:
        - type
      title: UnrestrictedNetwork
      description: 不受限制的网络访问。
    BetaLimitedNetworkParams:
      properties:
        allow_mcp_servers:
          anyOf:
            - type: boolean
            - type: 'null'
          title: 允许 MCP 服务器
          description: 允许出站访问智能体上配置的 MCP 服务端点，即使其未列在 `allowed_hosts` 数组中。默认为 `false`。
        allow_package_managers:
          anyOf:
            - type: boolean
            - type: 'null'
          title: 允许软件包管理器
          description: 允许出站访问 `allowed_hosts` 数组中未列出的公共软件包注册表（PyPI、npm 等）。默认为 `false`。
        allowed_hosts:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: 允许的主机
          description: 指定容器可访问的域名。
        type:
          type: string
          const: limited
          title: 类型
          description: 网络策略类型
      additionalProperties: false
      type: object
      required:
        - type
      title: LimitedNetworkParams
      description: |-
        受限网络的请求参数。

        字段默认为 null；更新时，省略的字段将保留
        现有值。
    BetaPackagesParams:
      properties:
        apt:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Apt
          description: 要安装的 Ubuntu/Debian 软件包
        cargo:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Cargo
          description: 要安装的 Rust 包
        gem:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Gem
          description: 要安装的 Ruby 包
        go:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Go
          description: 要安装的 Go 包
        npm:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Npm
          description: 要安装的 Node.js 包
        pip:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Pip
          description: 要安装的 Python 包
        type:
          type: string
          const: packages
          title: 类型
          description: 包配置类型
          default: packages
      additionalProperties: false
      type: object
      title: PackagesParams
      description: >-
        指定此环境中可用的包（及其可选的版本）。


        指定版本时，请使用相应包管理器的版本语义，例如对 `pip` 使用
        `package==1.0.0`。你需要自行验证该包和版本确实存在。不指定版本时安装最新版本。
    BetaLimitedNetwork:
      properties:
        allow_mcp_servers:
          type: boolean
          title: 允许 MCP 服务器
          description: 除 `allowed_hosts` 数组中列出的主机外，还允许出站访问配置在该智能体上的 MCP 服务器端点。
        allow_package_managers:
          type: boolean
          title: 允许软件包管理器
          description: 除 `allowed_hosts` 数组中列出的主机外，还允许出站访问公共包注册表（PyPI、npm 等）。
        allowed_hosts:
          items:
            type: string
          type: array
          title: 允许的主机
          description: 指定容器可访问的域名。
        type:
          type: string
          const: limited
          title: 类型
          description: 网络策略类型
      type: object
      required:
        - allow_mcp_servers
        - allow_package_managers
        - allowed_hosts
        - type
      title: LimitedNetwork
      description: 受限的网络访问。
    BetaPackages:
      properties:
        apt:
          items:
            type: string
          type: array
          title: Apt
          description: 要安装的 Ubuntu/Debian 软件包
        cargo:
          items:
            type: string
          type: array
          title: Cargo
          description: 要安装的 Rust 包
        gem:
          items:
            type: string
          type: array
          title: Gem
          description: 要安装的 Ruby 包
        go:
          items:
            type: string
          type: array
          title: Go
          description: 要安装的 Go 包
        npm:
          items:
            type: string
          type: array
          title: Npm
          description: 要安装的 Node.js 包
        pip:
          items:
            type: string
          type: array
          title: Pip
          description: 要安装的 Python 包
        type:
          type: string
          const: packages
          title: 类型
          description: 包配置类型
          default: packages
      type: object
      required:
        - apt
        - cargo
        - gem
        - go
        - npm
        - pip
      title: Packages
      description: 此环境中可用的包（及其版本）。
  securitySchemes:
    omaApiKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: OMA 工作区 API 密钥。
      x-default: sk-ant-local-default
    omaBearer:
      type: http
      scheme: bearer
      description: 以 Bearer 令牌形式发送的 OMA 工作区 API 密钥。

````