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_access 與
workspace-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 預設為關閉。啟用後的行為如下:
| 設定 | 預設值 | 行為 |
|---|---|---|
enabled | false | 只有在指令的網路存取已開啟時,才啟動沙盒網路。 |
domains | 未設定 | 採用允許清單機制,因此在新增 allow 規則之前,不允許存取任何外部目的地。支援精確主機比對、限定範圍的萬用字元,以及全域 * 允許規則;deny 一律優先。 |
unix_sockets | 未設定 | 在新增明確的 allow 規則之前,不允許存取任何 Unix 通訊端目的地。 |
allow_local_binding | false | 封鎖本機與私人網路目的地,除非你新增指定確切本機 IP 位址或 localhost 的允許規則,或明確選擇開放更廣泛的本機/私人網路存取。 |
enable_socks5 | true | 在政策允許時提供 SOCKS5 支援。 |
enable_socks5_udp | true | 在 SOCKS5 可用時,允許透過 SOCKS5 傳輸 UDP。 |
allow_upstream_proxy | true | 讓沙盒網路使用環境中設定的上游代理伺服器。 |
dangerously_allow_non_loopback_proxy | false | 將接聽端點限制在回送介面上,除非你刻意將其開放至 localhost 以外。 |
dangerously_allow_all_unix_sockets | false | 以允許清單控管 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-requestcodex --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-request | Codex 可以在工作區中讀取檔案、進行編輯及執行指令。在工作區外進行編輯或存取網路時,Codex 需要取得核准。 |
| 安全的唯讀瀏覽 | --sandbox read-only --ask-for-approval on-request | Codex 可以在唯讀沙盒內讀取檔案及執行指令。沙盒外的動作可能需要核准。 |
| 唯讀、非互動式執行(CI) | --sandbox read-only --ask-for-approval never | Codex 可以在唯讀沙盒內讀取檔案及執行指令;不會要求核准。 |
| 自動審查模式 | --sandbox workspace-write --ask-for-approval on-request -c approvals_reviewer=auto_review 或 approvals_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 seatbelt 和 codex sandbox landlock)。
作業系統層級的沙盒
Codex 會依作業系統採用不同的沙盒強制執行機制:
- macOS 使用 Seatbelt 政策,並透過
sandbox-exec搭配對應所選--sandbox模式的設定檔(-p)來執行指令。當受限讀取存取啟用平台預設規則時,Codex 會附加一組經過篩選的 macOS 平台政策,而非全面允許存取/System,以維持常用工具的相容性。 - Linux 預設使用
bwrap搭配seccomp。 - Windows 在 Windows 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 bwrap 或 seccomp 操作,沙盒可能無法運作。
在這種情況下,請將 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 沙盒。
若要試用:
- 安裝 Visual Studio Code 及 Dev Containers 擴充功能。
- 將 Codex 範例的
.devcontainer設定複製到你的程式碼庫,或直接從 Codex 程式碼庫開始。 - 在 VS Code 中執行 Dev Containers:在容器中開啟資料夾... ,然後選取
.devcontainer/devcontainer.secure.json。 - 容器啟動後,開啟終端並執行
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_request和codex.websocket_event(請求耗時,以及每則訊息的類型/是否成功/錯誤)codex.user_prompt(長度;除非明確啟用內容記錄,否則內容會被遮蔽)codex.tool_decision(已核准/已拒絕,決策來源:組態或使用者)codex.tool_result(耗時、是否成功、輸出片段)
相關的 OTel 指標(計數器與耗時直方圖的配對)包括 codex.api_request、codex.sse_event、codex.websocket.request、codex.websocket.event 和 codex.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 的安全性選項。設定與政策的詳細資訊請參閱該頁面。