本指南說明如何為現有專案套用模型、託管工具與資料保留控管。這些控管決定專案工作負載可使用哪些模型與工具，以及適用哪項已核准的保留政策。這些控管不會授予使用者或服務帳戶專案存取權。
完成主要工作流程後，你將獲得可重複使用的組態，用來：
- 限制專案只能使用一組已核准的模型。
- 明確設定每個受支援託管工具的權限。
- 將組織的預設資料保留政策套用至專案。
開始之前
完成 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，確認組態不會再產生變更。如果顯示組態漂移，請先確認是否有其他管理員或自動化變更了專案控管，再套用下一次更新。