本指南介绍如何为现有项目配置模型、托管工具和数据保留控制。这些控制决定项目工作负载可以使用哪些功能，以及适用哪项已获批准的保留政策。它们不会向用户或服务账户授予项目访问权限。
完成主要工作流程后，您将获得一套可重复使用的配置，用于：
- 将项目可用的模型限制为一组已获批准的模型。
- 为每个受支持的托管工具明确设置权限。
- 将组织的默认数据保留政策应用于项目。
开始之前
完成 Terraform 提供程序设置，并将管理 API 密钥导出为环境变量 OPENAI_ADMIN_KEY。您还需要：
- 现有项目的 ID。
- 您的组织可用的模型 ID。
- 如果您计划管理项目的数据保留设置，组织需已启用数据保留控制。
评估此工作流程时，请使用测试项目。要为某个项目禁用托管工具，组织级工具策略必须已将该工具限制为仅供选定项目使用。如果组织已为所有项目启用某个工具，单个项目就无法禁用该工具。
限制模型访问权限
openai_project_model_permissions 将模型允许列表或拒绝列表应用于单个项目。此示例仅允许使用 gpt-5.4-mini：
resource "openai_project_model_permissions" "application" {
project_id = "proj_123"
mode = "allow_list"
model_ids = ["gpt-5.4-mini"]
}将 mode 设置为：
allow_list，仅允许使用model_ids中的模型。deny_list，允许使用除model_ids所列模型之外的其他可用模型。
每个模型 ID 都必须对组织可见，您添加到策略中的任何微调模型快照也不例外。Terraform 会在下次生成并应用执行计划时，使模式和模型列表与配置保持一致。
配置托管工具
openai_project_hosted_tool_permissions 管理五项项目级工具权限。请设置每个字段，确保经过审查的配置完整描述整套策略：
resource "openai_project_hosted_tool_permissions" "application" {
project_id = "proj_123"
file_search_enabled = true
web_search_enabled = false
image_generation_enabled = false
mcp_enabled = false
code_interpreter_enabled = true
}这些字段控制文件搜索、网页搜索、图像生成、远程 MCP 服务器和代码解释器。每个组织的托管工具策略都有三种模式：允许所有项目、拒绝所有项目或允许选定项目。将字段设置为 true 会允许该项目使用相应工具，但仍须满足组织的其他资格和数据保留要求。将字段设置为 false 会将该项目从该工具策略的选定项目中移除。如果组织当前允许所有项目使用该工具，将字段设置为 false 就会失败。为单个项目禁用工具之前，请先将组织的工具策略改为允许选定项目。
Terraform 会从 OpenAI 刷新全部五个值，并在下次生成执行计划时，将通过控制台进行的更改报告为配置漂移。
配置数据保留
openai_project_data_retention 将已获批准的数据保留类型应用于单个项目。除非项目已有获批的覆盖设置，否则请继承组织的当前政策：
resource "openai_project_data_retention" "application" {
project_id = "proj_123"
type = "organization_default"
}提供程序还接受 none、zero_data_retention、modified_abuse_monitoring、enhanced_zero_data_retention 和 enhanced_modified_abuse_monitoring。可用模式及允许的模式转换取决于您的组织配置和项目的数据驻留区域。
选择项目的覆盖设置前，请查阅您的数据以及您的组织与 OpenAI 签订的协议。
管理组织默认设置
仅当现有组织级设置由 Terraform 管理时，才使用 openai_organization_data_retention：
resource "openai_organization_data_retention" "default" {
type = "zero_data_retention"
}此资源用于更改现有组织设置，不会为组织开通数据保留计划。某些转换需要支持团队协助，某些数据保留层级之间则不支持转换。
从配置中移除 openai_project_hosted_tool_permissions 或
openai_project_data_retention，会将该资源从
Terraform 状态中移除，但不会更改远程设置。移除
openai_project_model_permissions 则会删除项目的模型权限配置。
审查销毁计划时，请注意这些行为差异。
检测在 Terraform 之外进行的更改
生成执行计划，以刷新远程状态并将其与经过审查的配置进行比较：
terraform plan -detailed-exitcode退出码 0 表示没有更改，2 表示执行计划包含更改，1 表示 Terraform 遇到了错误。应用执行计划前，请调查意外更改。对于管理员出于应急需要进行的更改，请先了解其目的，不要自动覆盖。
运行完整示例
以下示例同时管理全部三项项目控制。创建 main.tf：
terraform {
required_version = ">= 1.0"
required_providers {
openai = {
source = "openai/openai"
version = ">= 1.0.0"
}
}
}
provider "openai" {}
variable "project_id" {
type = string
description = "ID of the existing OpenAI project."
}
variable "model_permission_mode" {
type = string
description = "Whether model_ids is an allowlist or denylist."
default = "allow_list"
validation {
condition = contains(["allow_list", "deny_list"], var.model_permission_mode)
error_message = "The model permission mode must be allow_list or deny_list."
}
}
variable "model_ids" {
type = list(string)
description = "Model IDs included in the project model policy."
}
variable "hosted_tools" {
type = object({
file_search = bool
web_search = bool
image_generation = bool
mcp = bool
code_interpreter = bool
})
description = "Hosted tools enabled for the project."
}
variable "project_data_retention_type" {
type = string
description = "Approved data-retention type for the project."
validation {
condition = contains([
"organization_default",
"none",
"zero_data_retention",
"modified_abuse_monitoring",
"enhanced_zero_data_retention",
"enhanced_modified_abuse_monitoring",
], var.project_data_retention_type)
error_message = "Provide a supported project data-retention type."
}
}
resource "openai_project_model_permissions" "application" {
project_id = var.project_id
mode = var.model_permission_mode
model_ids = var.model_ids
}
resource "openai_project_hosted_tool_permissions" "application" {
project_id = var.project_id
file_search_enabled = var.hosted_tools.file_search
web_search_enabled = var.hosted_tools.web_search
image_generation_enabled = var.hosted_tools.image_generation
mcp_enabled = var.hosted_tools.mcp
code_interpreter_enabled = var.hosted_tools.code_interpreter
}
resource "openai_project_data_retention" "application" {
project_id = var.project_id
type = var.project_data_retention_type
}
output "controlled_project_id" {
value = var.project_id
}
output "model_permission_mode" {
value = openai_project_model_permissions.application.mode
}
output "project_data_retention_type" {
value = openai_project_data_retention.application.type
}创建 terraform.tfvars，填写现有项目 ID、可见的模型 ID、托管工具策略以及已获批准的数据保留类型：
project_id = "proj_123"
model_permission_mode = "allow_list"
model_ids = ["gpt-5.4-mini"]
hosted_tools = {
file_search = true
web_search = true
image_generation = true
mcp = true
code_interpreter = true
}
project_data_retention_type = "organization_default"此示例启用了所有托管工具，因此在组织策略为所有项目启用工具的情况下也能运行。只有在相应的组织级策略采用选定项目访问模式后，才能将值改为 false。应用配置前，请确认模型 ID 和数据保留类型对您的组织可用。
初始化 Terraform，然后审查并应用已保存的执行计划：
terraform init
terraform fmt
terraform validate
terraform plan -out=tfplan
terraform show tfplan
terraform apply tfplan首次执行计划应包含三个待添加的资源。对于托管工具和数据保留控制，添加资源意味着 Terraform 开始管理项目中已有的单例设置，并不会创建独立的远程对象。模型权限资源则会创建或更新项目的模型权限配置。
再次运行 terraform plan，确认该配置不会产生进一步更改。如果出现配置漂移，请先确定是否有其他管理员或自动化流程更改了项目控制设置，再应用下一次更新。