For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
主要導覽

代理核准與安全性

如何透過沙盒、核准與網路控制安全地操作 Codex

Codex 有助於保護您的程式碼與資料,並降低遭濫用的風險。

本頁說明如何安全操作 Codex,包括沙盒、核准 與網路存取。如果您要尋找的是用於掃描已連線 GitHub 程式碼庫的 產品 Codex Security,請參閱 Codex Security

預設情況下,智慧體執行時會關閉網路存取。在本機,Codex 使用由作業系統強制執行的沙盒,限制其可存取的範圍(通常是目前的工作區),並透過核准政策控管何時必須先停下來徵詢您的同意,才能執行動作。

如需概略了解 ChatGPT 桌面版應用程式、 Codex CLI 與 IDE 擴充功能中的沙盒運作方式,請參閱沙盒。 如需更全面的企業安全性概覽,請參閱 Codex 安全性白皮書

從已停止支援的 untrusted 核准政策遷移

Codex 與 ChatGPT Work 不再支援 approval_policy = "untrusted"。 這項已停止支援的設定可能導致任一用戶端無法啟動。請將它從 使用者或專案組態、設定檔、啟動指令碼及受管理的 預設設定中移除。如需以互動方式進行唯讀操作:

sandbox_mode = "read-only"
approval_policy = "on-request"

或執行 codex --sandbox read-only --ask-for-approval on-request

使用 on-request 時,沙盒允許的指令無須核准即可執行、 讀取可存取的檔案,並在網路存取已啟用時使用網路。

若要保留較嚴格的指令核准規則,請勿明確設定 approval_policy,並在使用者層級的 ~/.codex/config.toml 中新增專案項目:

[projects."/path/to/project"]
trust_level = "untrusted"

這樣一來,除非執行政策規則允許,否則指令都需要核准。 這也會停用專案本機組態。明確設定 on-request 會覆寫依專案決定的政策;受管理的 allowed_approval_policies 必須 包含 untrusted,才能允許使用依專案決定的政策。

沙盒與核准

Codex 的安全性控制由兩個相互配合的層面構成:

  • 沙盒模式:Codex 執行模型產生的指令時,技術上能執行哪些操作(例如可寫入哪些位置,以及是否能存取網路)。
  • 核准政策:Codex 在哪些情況下必須先徵詢您的同意,才能執行動作(例如離開沙盒、使用網路,或執行受信任指令集以外的指令)。

Codex 會依執行環境使用不同的沙盒模式:

  • Codex 雲端:在由 OpenAI 管理的隔離容器中執行,防止存取您的主機系統或無關資料。採用兩階段執行模型:設定階段先於智慧體階段執行,期間可以存取網路以安裝指定的相依套件;接著進入智慧體階段,預設以離線方式執行,除非您為該環境啟用網際網路存取。為雲端環境設定的機密資訊僅在設定階段可用,並會在智慧體階段開始前移除。
  • Codex CLI / IDE 擴充功能:透過作業系統層級的機制強制執行沙盒政策。預設不允許網路存取,且寫入權限僅限於目前使用的工作區。您可以依可接受的風險程度,調整沙盒、核准政策及網路設定。

使用 Auto 預設組合(例如 --sandbox workspace-write --ask-for-approval on-request)時,Codex 可以自動在工作目錄中讀取檔案、進行編輯及執行指令。

Codex 若要編輯工作區以外的檔案,或執行需要網路存取的指令,會要求核准。如果您只想對話或規劃而不進行變更,請使用 /permissions 指令切換至 read-only 模式。

對於標示會產生副作用的應用程式(連接器)工具呼叫,即使動作不是 shell 指令或檔案變更,Codex 也可以要求核准。當工具帶有破壞性註記時,破壞性的應用程式/MCP 工具呼叫一律需要核准(除非工具帶有優先採用的讀取註記)。

安全監控與暫停的任務

GPT-6 Astra 在 Codex 與 ChatGPT Work 中提供安全監控。監控以非同步方式執行,若偵測到模型行為可能不安全,就可能暫停任務。觸發暫停的活動可能已經發生,任務才暫停;監控無法取代沙盒、權限或結果審查。

如果任務暫停,請閱讀通知,並在有偵測結果可供查看時加以審查。只有在確認任務能安全繼續後,才恢復執行。如果通知指出任務已結束,或未提供恢復執行的選項,您就無法從該介面恢復執行。

介面與資料控制偵測結果與恢復執行
提供偵測結果與恢復執行流程,且未套用此處所列資料控制的 Codex 與 ChatGPT Work 用戶端恢復執行前,請先審查偵測結果。
Codex CLI 與行動版無法查看完整偵測結果或恢復執行。任務會結束。
零資料保留、調整版濫用監控,或美國以外的資料儲存駐留無法查看完整偵測結果或恢復執行。任務會結束。

安全監控會評估任務執行期間的模型行為。 自動核准審查則會針對原本就需要核准的個別動作, 在執行前進行評估。即使某個動作已通過 自動核准審查,該動作所屬的任務仍可能在稍後被監控機制暫停。

網路存取 Elevated Risk

若使用 Codex 雲端,請參閱智慧體網際網路存取,以啟用完整網際網路存取或網域允許清單。

在 ChatGPT 桌面版應用程式、Codex CLI 或 IDE 擴充功能中,預設的 workspace-write 沙盒模式會關閉網路存取,除非您在組態中啟用:

[sandbox_workspace_write]
network_access = true

網路隔離

網路存取透過目的地規則控制,這些規則適用於指令啟動的指令碼、 程式與子程序。當指令的網路存取 已啟用時,可開啟 network_proxy 功能,讓這些流量 受到您所設定的網路政策限制。單純新增網域規則並不會 啟用 Proxy。

[features.network_proxy]
enabled = true
domains = { "api.openai.com" = "allow", "example.com" = "deny" }

對於單次 CLI 工作階段,若只需開關功能,請使用布林值簡寫;若還需設定政策選項,則使用表格形式:

codex \
  -c 'features.network_proxy=true' \
  -c 'sandbox_workspace_write.network_access=true'

codex \
  -c 'features.network_proxy.enabled=true' \
  -c 'features.network_proxy.domains={ "api.openai.com" = "allow", "example.com" = "deny" }' \
  -c 'sandbox_workspace_write.network_access=true'

這項功能會改變已啟用的網路存取所受的管制方式;它本身不會授予 網路存取權。請搭配使用 sandbox_workspace_write.network_accessworkspace-write 組態,決定是否允許指令存取網路:

  • 網路關閉 + network_proxy 開啟:網路維持關閉,這項功能不會產生作用。
  • 網路開啟 + network_proxy 關閉:網路維持開啟,可不受限制地直接 對外連線。
  • 網路開啟 + network_proxy 開啟:網路維持開啟,對外流量會 受到已設定的網路政策限制。

Proxy 功能也適用於權限設定檔。 設定檔中的 network.enabled = true 會授予指令網路存取權,而 features.network_proxy = true 則會啟用該設定檔所定義的 網域規則管制:

default_permissions = "project-edit"

[features]
network_proxy = true

[permissions.project-edit]
extends = ":workspace"

[permissions.project-edit.network]
enabled = true

[permissions.project-edit.network.domains]
"api.openai.com" = "allow"

如果您在此範例中省略 Proxy 功能,指令就能直接存取網路, 而 api.openai.com 允許規則不會限制其連線目的地。

管理員管理的 experimental_network 要求與使用者的 功能開關彼此獨立。這些要求不需要 features.network_proxy,也能設定並啟動沙盒網路,但如果目前的 沙盒關閉了網路存取,它們並不會將其開啟。請參閱受管理的設定, 了解管理員端 requirements.toml 的結構。

網路政策

網域規則以允許清單為基礎:

  • 明確指定的主機僅會比對該主機本身。
  • *.example.com 會比對 api.example.com 等子網域,但不會比對 example.com
  • **.example.com 會同時比對根網域與子網域。
  • 全域 * 允許規則會比對任何未被拒絕的公用主機。請將 * 視為廣泛的網路存取權,並盡可能優先使用範圍明確的規則。
  • deny 一律優先於 allow,而全域 * 僅適用於允許規則。

本機與私人網路目的地

預設情況下,allow_local_binding = false 會封鎖回送、連結本機與 私人網路目的地:

  • 特定例外:當指令需要存取單一本機目標時, 請新增以明確的本機 IP 位址字面值或 localhost 為對象的允許規則。
  • 更廣泛的存取:只有在您確實打算 擴大本機或私人網路的可存取範圍時,才設定 allow_local_binding = true
  • 萬用字元:萬用字元規則不算是明確的本機例外。
  • 解析後的位址:解析為本機或私人 IP 位址的主機名稱,即使符合允許清單,仍會遭到封鎖。

DNS 重新繫結防護

允許主機名稱之前,Codex 會盡可能執行 DNS 與 IP 分類檢查:

  • 若查詢失敗或逾時,就會封鎖存取。
  • 解析為非公用位址的主機名稱會遭到封鎖。
  • 這項檢查可降低 DNS 重新綁定的風險,但無法完全消除。若要徹底防止重新綁定,就必須讓解析出的 IP 位址一路固定到傳輸層。

如果威脅範圍涵蓋惡意 DNS,也應在更底層實施對外連線控管。

危險設定

以下兩項設定會刻意擴大信任邊界:

  • dangerously_allow_non_loopback_proxy = true 可讓代理伺服器的接聽端點 開放給回送介面以外的連線。
  • dangerously_allow_all_unix_sockets = true 會略過 Unix 通訊端允許清單。

請僅在嚴格控管的環境中使用這些設定。啟用 Unix 通訊端代理功能時,即使要求綁定至非回送介面,接聽端點仍僅限於回送介面,避免沙盒網路成為遠端存取本機常駐程式的橋樑。

network_proxy 預設為關閉。啟用後的行為如下:

設定預設值行為
enabledfalse只有在指令的網路存取已開啟時,才啟動沙盒網路。
domains未設定採用允許清單機制,因此在新增 allow 規則之前,不允許存取任何外部目的地。支援精確主機比對、限定範圍的萬用字元,以及全域 * 允許規則;deny 一律優先。
unix_sockets未設定在新增明確的 allow 規則之前,不允許存取任何 Unix 通訊端目的地。
allow_local_bindingfalse封鎖本機與私人網路目的地,除非你新增指定確切本機 IP 位址或 localhost 的允許規則,或明確選擇開放更廣泛的本機/私人網路存取。
enable_socks5true在政策允許時提供 SOCKS5 支援。
enable_socks5_udptrue在 SOCKS5 可用時,允許透過 SOCKS5 傳輸 UDP。
allow_upstream_proxytrue讓沙盒網路使用環境中設定的上游代理伺服器。
dangerously_allow_non_loopback_proxyfalse將接聽端點限制在回送介面上,除非你刻意將其開放至 localhost 以外。
dangerously_allow_all_unix_socketsfalse以允許清單控管 Unix 通訊端存取,除非你刻意略過這項保護。

指令網路代理未涵蓋的流量

網路代理會篩選在本機指令沙盒內執行的指令碼、程式和子程序。它不會篩選網頁搜尋、應用程式或連接器工具呼叫、MCP 伺服器連線、瀏覽器或電腦活動、Codex 雲端任務,或用戶端的模型與身分驗證請求。這些功能各自使用獨立的服務連線、功能設定、工作區政策或環境控制措施。

瀏覽器工具在存取來源之前,會另外檢查受管理的網路拒絕規則與排他性允許清單。 瀏覽器來源政策可進一步限制網站存取、 上傳、下載及開發人員工具。請參閱 受管理的瀏覽器控制措施

對於受管理的使用者,請將指令網路政策與其他控制措施搭配使用,例如 allowed_web_search_modes、已核准的 mcp_servers,以及 應用程式、外掛程式、瀏覽器或電腦的功能要求。請參閱 受管理的設定

你也可以控制網頁搜尋工具,而不必授予啟動的指令完整網路存取權。Codex 預設使用網頁搜尋快取來取得結果。此快取是由 OpenAI 維護的網頁結果索引,因此快取模式會傳回已建立索引的結果,而不會擷取即時網頁。這可減少接觸任意即時內容中提示注入的機會,但你仍應將網頁結果視為不受信任的內容。如果你使用 --yolo 或其他完整存取權沙盒設定,網頁搜尋預設會使用即時結果。使用 --search 或設定 web_search = "live" 可允許即時瀏覽,也可將其設為 "disabled" 來關閉工具:

web_search = "cached"  # default
# web_search = "disabled"
# web_search = "live"  # same as --search

如果外部網頁存取應由搜尋索引控管,請設定 web_search = "indexed"。 在 Codex 中啟用網路存取或網頁搜尋時,請謹慎行事。 提示注入可能導致智慧體擷取並遵循不受信任的指示。

預設值與建議

  • Codex 啟動時會偵測資料夾是否受版本控制,並提供以下建議:
    • 受版本控制的資料夾:Auto(工作區寫入 + 提出要求時核准)
    • 未受版本控制的資料夾:read-only
  • 視你的設定而定,Codex 也可能以 read-only 模式啟動,直到你明確信任工作目錄為止(例如透過初始設定提示或 /permissions)。
  • 工作區包含目前的目錄及 /tmp 等暫存目錄。使用 /status 指令可查看工作區包含哪些目錄。
  • 若要接受預設值,請執行 codex
  • 你可以明確指定這些設定:
    • codex --sandbox workspace-write --ask-for-approval on-request
    • codex --sandbox read-only --ask-for-approval on-request

可寫入根目錄中的受保護路徑

在預設的 workspace-write 沙盒政策中,可寫入的根目錄仍包含受保護路徑:

  • 無論 <writable_root>/.git 是目錄還是檔案,都會受到唯讀保護。
  • 如果 <writable_root>/.git 是指標檔案(gitdir: ...),解析出的 Git 目錄路徑也會受到唯讀保護。
  • <writable_root>/.agents 以目錄形式存在時,會受到唯讀保護。
  • <writable_root>/.codex 以目錄形式存在時,會受到唯讀保護。
  • 保護會遞迴套用,因此這些路徑下的所有內容都是唯讀的。

執行時不顯示核准提示

你可以使用 --ask-for-approval never 或簡寫 -a never 來停用核准提示。

這個選項適用於所有 --sandbox 模式,因此你仍可控制 Codex 的自主程度。Codex 會在你設定的限制內盡力完成工作。

如果你需要 Codex 在不顯示核准提示的情況下讀取檔案、進行編輯,並執行可存取網路的指令,請使用 --sandbox danger-full-access(或 --dangerously-bypass-approvals-and-sandbox 旗標)。使用前請謹慎評估。

若要採取折衷做法,approval_policy = { granular = { ... } } 可讓特定類別的核准提示維持互動式處理,同時自動拒絕其他類別。細粒度政策涵蓋沙盒核准、execpolicy-rule 提示、MCP 提示、request_permissions 提示,以及技能指令碼核准。

核准請求的自動審查

預設情況下,核准請求會交由你處理:

approvals_reviewer = "user"

核准請求的自動審查適用於互動式核准,例如 approval_policy = "on-request" 或細粒度核准政策。設定 approvals_reviewer = "auto_review" 後,符合條件的核准請求 會在 Codex 執行前先交由審查智慧體評估:

approval_policy = "on-request"
approvals_reviewer = "auto_review"

如需審查智慧體的完整生命週期、觸發條件、設定優先順序 及失敗時的行為,請參閱 自動審查

審查智慧體只會評估原本就需要核准的動作,例如 要求提升沙盒權限、遭封鎖的網路請求、request_permissions 提示,或 具有副作用的應用程式與 MCP 工具呼叫。沙盒範圍內的動作 會繼續執行,不會增加額外的審查步驟。

審查政策會檢查資料外洩、憑證探查、持續削弱安全性的行為,以及破壞性動作。低風險與中風險動作可在政策允許時繼續執行。政策會拒絕極嚴重風險的動作。高風險動作必須有充分的使用者授權,且不能符合任何拒絕規則。若提示詞建構、審查工作階段或剖析失敗,系統會採取封閉式失敗處理,阻止動作執行。逾時會另外顯示,但動作同樣不會執行。

預設審查政策 位於開源 Codex 程式碼庫中。企業可以透過受管理要求中的 guardian_policy_config 替換該政策內租用戶專屬的區段。 也支援本機的 [auto_review].policy 文字, 但受管理要求的優先順序較高。如需設定詳細資訊,請參閱 受管理的設定

在 ChatGPT 桌面版應用程式中,這些審查會顯示為自動審查項目,並標示「審查中」、「已核准」、「已拒絕」、「已中止」或「已逾時」等狀態。項目也可能包含受審查請求的風險等級與使用者授權評估。

自動審查會額外呼叫模型,因此可能增加 Codex 用量。 管理員可透過 allowed_approvals_reviewers 加以限制。

常見的沙盒與核准組合

用途旗標/組態效果
自動(預設組合)無需旗標 ,或使用 --sandbox workspace-write --ask-for-approval on-requestCodex 可以在工作區中讀取檔案、進行編輯及執行指令。在工作區外進行編輯或存取網路時,Codex 需要取得核准。
安全的唯讀瀏覽--sandbox read-only --ask-for-approval on-requestCodex 可以在唯讀沙盒內讀取檔案及執行指令。沙盒外的動作可能需要核准。
唯讀、非互動式執行(CI)--sandbox read-only --ask-for-approval neverCodex 可以在唯讀沙盒內讀取檔案及執行指令;不會要求核准。
自動審查模式--sandbox workspace-write --ask-for-approval on-request -c approvals_reviewer=auto_reviewapprovals_reviewer = "auto_review"沙盒邊界與標準的 on-request 模式相同,但符合條件的核准請求會交由自動審查處理,不會顯示給使用者。
具危險性的完整存取權--dangerously-bypass-approvals-and-sandbox(別名:--yolo Elevated Risk 無沙盒;無核准 (不建議)

非互動式執行請使用 codex exec --sandbox workspace-write;Codex 仍保留舊的 codex exec --full-auto 呼叫方式作為已棄用的相容途徑,並會輸出警告。

config.toml 中的組態

如需更完整的設定工作流程,請參閱基本設定進階設定組態參考資料

# Interactive approvals with a read-only sandbox
approval_policy = "on-request"
sandbox_mode    = "read-only"
allow_login_shell = false # optional hardening: disallow login shells for shell-based tools

# Optional: Allow network in workspace-write mode
[sandbox_workspace_write]
network_access = true

# Optional: granular approval policy
# approval_policy = { granular = {
#   sandbox_approval = true,
#   rules = true,
#   mcp_elicitations = true,
#   request_permissions = false,
#   skill_approval = false
# } }

你也可以將預設組合儲存為設定檔,然後使用 codex --profile profile-name 選取:

# ~/.codex/full_auto.config.toml
approval_policy = "on-request"
sandbox_mode    = "workspace-write"
# ~/.codex/readonly_quiet.config.toml
approval_policy = "never"
sandbox_mode    = "read-only"

在本機測試沙盒

若要查看指令在 Codex 沙盒中執行時的行為,請使用下列 Codex CLI 指令:

# macOS
codex sandbox macos [--permissions-profile <name>] [--log-denials] [COMMAND]...
# Linux
codex sandbox linux [--permissions-profile <name>] [COMMAND]...
# Windows
codex sandbox windows [--permissions-profile <name>] [COMMAND]...

sandbox 指令也可透過 codex debug 使用,各平台的輔助指令也有別名(例如 codex sandbox seatbeltcodex sandbox landlock)。

作業系統層級的沙盒

Codex 會依作業系統採用不同的沙盒強制執行機制:

  • macOS 使用 Seatbelt 政策,並透過 sandbox-exec 搭配對應所選 --sandbox 模式的設定檔(-p)來執行指令。當受限讀取存取啟用平台預設規則時,Codex 會附加一組經過篩選的 macOS 平台政策,而非全面允許存取 /System,以維持常用工具的相容性。
  • Linux 預設使用 bwrap 搭配 seccomp
  • WindowsWindows Subsystem for Linux 2(WSL2) 中執行時,使用 Linux 沙盒實作。Codex 對 WSL1 的支援持續到 0.114 版;從 0.115 版開始,Linux 沙盒改用 bwrap,因此不再支援 WSL1。直接在 Windows 上原生執行時,Codex 使用 Windows 沙盒實作。

Windows 上的 Codex IDE 擴充功能直接支援 WSL2。在 VS Code 設定中加入下列設定,即可在 WSL2 可用時,讓智慧體始終在其中執行:

{
  "chatgpt.runCodexInWindowsSubsystemForLinux": true
}

這可確保即使主機作業系統是 Windows,IDE 擴充功能仍會沿用 Linux 沙盒對指令、核准及檔案系統存取的處理方式。詳情請參閱 WSL 指南

直接在 Windows 上原生執行時,請在 config.toml 中設定原生沙盒模式:

[windows]
sandbox = "unelevated" # or "elevated"
# sandbox_private_desktop = true  # default; set false only for compatibility

詳情請參閱 Windows 設定指南

在 Docker 等容器化環境中執行 Linux 時,如果主機或容器的組態阻擋 Codex 所需的命名空間、setuid bwrapseccomp 操作,沙盒可能無法運作。

在這種情況下,請將 Docker 容器設定為提供所需的隔離,然後在容器內使用 --sandbox danger-full-access(或 --dangerously-bypass-approvals-and-sandbox 旗標)執行 codex

在 Dev Containers 中執行 Codex

如果主機無法直接執行 Linux 沙盒,或組織已將容器化開發訂為標準,請搭配 Dev Containers 執行 Codex,讓 Docker 提供外層隔離邊界。此方式適用於 Visual Studio Code Dev Containers 及相容工具。

請以 Codex 安全開發容器範例作為參考實作。此範例會安裝 Codex、常用開發工具、bubblewrap,以及透過防火牆實施的對外連線控制機制。

開發容器提供相當程度的保護,但無法防止所有攻擊。 如果你在容器內使用 --sandbox danger-full-access--dangerously-bypass-approvals-and-sandbox 執行 Codex,惡意專案 就能將開發容器內可存取的任何資料外洩, 包括 Codex 憑證。請僅對受信任的程式碼庫使用此方式,並 如同在其他權限提升環境中一樣,監控 Codex 的活動。

參考實作包含:

  • 已安裝 Codex 及常用開發工具的 Ubuntu 24.04 基礎映像檔;
  • 以允許清單控制對外存取的防火牆設定檔;
  • 用於在容器中重新開啟工作區的 VS Code 設定及擴充功能建議;
  • 用於持續保存指令歷程及 Codex 組態的掛載;
  • bubblewrap,讓 Codex 在容器授予所需能力時,仍可使用其 Linux 沙盒。

若要試用:

  1. 安裝 Visual Studio Code 及 Dev Containers 擴充功能
  2. 將 Codex 範例的 .devcontainer 設定複製到你的程式碼庫,或直接從 Codex 程式碼庫開始。
  3. 在 VS Code 中執行 Dev Containers:在容器中開啟資料夾... ,然後選取 .devcontainer/devcontainer.secure.json
  4. 容器啟動後,開啟終端並執行 codex

你也可以透過 CLI 啟動容器:

devcontainer up --workspace-folder . --config .devcontainer/devcontainer.secure.json

此範例有三個主要部分:

  • .devcontainer/devcontainer.secure.json 控制容器設定、能力、掛載、環境變數及 VS Code 擴充功能。
  • .devcontainer/Dockerfile.secure 定義以 Ubuntu 為基礎的映像檔及安裝的工具。
  • .devcontainer/init-firewall.sh 套用對外網路連線政策。

參考防火牆刻意設計為起點。如果你依賴網域允許清單來達成隔離,請實作符合環境需求的 DNS 重新繫結與 DNS 更新防護機制,例如依據 TTL 更新,或使用能辨識 DNS 的防火牆。

在容器內,請選擇下列其中一種模式:

  • 如果 Dev Container 設定檔授予 bwrap 建立內層沙盒所需的能力,請保持 Codex 的 Linux 沙盒啟用。
  • 如果你打算以容器作為安全邊界,請在容器內使用 --sandbox danger-full-access 執行 Codex,讓 Codex 不再嘗試建立第二層沙盒。

版本控制

搭配版本控制工作流程使用 Codex,效果最佳:

  • 在功能分支上工作,並在委派任務前確保 git status 顯示沒有未提交的變更。這樣更容易將 Codex 的修補與其他變更分開,並在需要時還原。
  • 優先使用以修補為基礎的工作流程(例如 git diff/git apply),而非直接編輯已追蹤的檔案。經常提交,以便小幅度回復變更。
  • 像處理其他 PR 一樣處理 Codex 的建議:執行針對性驗證、審查差異,並在提交訊息中記錄決策,以供稽核。

監控與遙測

Codex 支援自行選擇啟用的 OpenTelemetry(OTel)監控,協助團隊稽核使用情況、調查問題並滿足合規要求,同時保留本機預設的安全防護。遙測預設關閉;請在組態中明確啟用。

概覽

  • Codex 預設關閉 OTel 匯出,讓本機執行無須依賴外部遙測服務。
  • 啟用後,Codex 會產生結構化記錄事件,涵蓋對話、API 請求、SSE/WebSocket 串流活動、使用者提示詞(預設遮蔽內容)、工具核准決策及工具結果。
  • Codex 會以 service.name(發起來源)、CLI 版本及環境標籤標記匯出的事件,以區分開發、預備及正式環境的流量。

啟用 OTel(自行選擇啟用)

在 Codex 組態(通常位於 ~/.codex/config.toml)中加入 [otel] 區塊,選擇匯出器,並設定是否記錄提示詞文字。

[otel]
environment = "staging"   # dev | staging | prod
exporter = "none"          # none | otlp-http | otlp-grpc
log_user_prompt = false     # redact prompt text unless policy allows
  • exporter = "none" 會讓監測機制保持啟用,但不會將資料傳送至任何地方。
  • 若要將事件傳送至自己的收集器,請選擇以下其中一個選項:
[otel]
exporter = { otlp-http = {
  endpoint = "https://otel.example.com/v1/logs",
  protocol = "binary",
  headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
}}
[otel]
exporter = { otlp-grpc = {
  endpoint = "https://otel.example.com:4317",
  headers = { "x-otlp-meta" = "abc123" }
}}

Codex 會批次處理事件,並在關閉時送出所有尚未傳送的事件。Codex 只會匯出其 OTel 模組產生的遙測資料。

事件類別

代表性的事件類型包括:

  • codex.conversation_starts(模型、推理設定、沙盒/核准政策)
  • codex.api_request(嘗試次數、狀態/是否成功、耗時及錯誤詳細資訊)
  • codex.sse_event(串流事件類型、成功/失敗、耗時,以及 response.completed 的 Token 數量)
  • codex.websocket_requestcodex.websocket_event(請求耗時,以及每則訊息的類型/是否成功/錯誤)
  • codex.user_prompt(長度;除非明確啟用內容記錄,否則內容會被遮蔽)
  • codex.tool_decision(已核准/已拒絕,決策來源:組態或使用者)
  • codex.tool_result(耗時、是否成功、輸出片段)

相關的 OTel 指標(計數器與耗時直方圖的配對)包括 codex.api_requestcodex.sse_eventcodex.websocket.requestcodex.websocket.eventcodex.tool.call,以及各自對應的 .duration_ms 量測工具。

如需完整的事件目錄與組態參考資料,請參閱 GitHub 上的 Codex 組態文件

安全性與隱私權指引

  • 除非政策明確允許儲存提示詞內容,否則請維持 log_user_prompt = false。提示詞可能包含原始碼和敏感資料。
  • 僅將遙測資料傳送至你掌控的收集器,並依照合規要求設定保留限制與存取控制。
  • 請將工具引數與輸出視為敏感資料。在可行的情況下,優先在收集器或 SIEM 中遮蔽敏感內容。
  • 如果不希望 Codex 將工作階段記錄儲存在 CODEX_HOME 下,請檢查本機資料保留設定(例如 history.persistence / history.max_bytes)。請參閱進階設定組態參考資料
  • 如果在關閉網路存取的情況下執行 CLI,OTel 匯出功能將無法連線至收集器。若要匯出,請在 workspace-write 模式下允許對 OTel 端點的網路存取,或將收集器的網域加入核准清單後,從 Codex 雲端匯出。
  • 定期審查事件,檢查核准/沙盒設定是否變更,以及是否有非預期的工具執行。

OTel 為選用功能,旨在補充上述沙盒與核准保護機制,而非取代它們。

受管理的設定

企業管理員可以透過受管理的設定,為工作區設定 Codex 的安全性選項。設定與政策的詳細資訊請參閱該頁面。