OpenAI

2026年11月18日

工程

深入了解 Codex 沙箱

了解 Codex 如何依照你設定的限制,在你的電腦上執行命令。

作者:Michael Bolin,技術團隊成員

OpenAI 採取縱深防禦⁠(在新視窗中開啟)策略,讓智慧體安全地執行任務。訓練與對齊是這項工作的基礎,我們也在智慧體任務執行框架 Codex⁠(在新視窗中開啟) 中加入額外的防護措施。Codex 經常在你的電腦上執行命令,而這項操作也可能帶來風險。因此,我們打造了 Codex 沙箱,讓 Codex 能在你現有的環境中工作,且檔案系統與網路的存取範圍由你決定。

⁠(在新視窗中開啟)沙箱⁠(在新視窗中開啟)會限制程式執行時可以存取的資源。例如,整理照片時,你可以設定 Codex 沙箱,讓命令能讀取和修改 ~/Pictures 中的檔案,並封鎖網路存取,避免照片遭到上傳。進行程式碼審查時,你可以允許存取線上文件,同時讓原始碼檔案維持唯讀。使用者可透過⁠(在新視窗中開啟)權限設定檔⁠(在新視窗中開啟)指定 Codex 沙箱在這次工作階段內可存取哪些檔案系統與網路資源。

本文會先介紹 設計 Codex 沙箱預設值時的取捨,再說明沙箱的設計,以及任務執行框架如何透過沙箱執行命令。接著會介紹使用者與企業如何依需求調整權限,以及開發人員如何在自己的工具中使用同一套沙箱機制。最後,我們會探討 macOS、Linux 和 Windows 如何強制執行這些限制。

決定沙箱的界線

Codex 沙箱採用保守的預設值,同時保留完成實際工作所需的權限。例如,以 Git 程式碼庫作為工作區根目錄時,內建的 :workspace 權限設定檔會:

  • 允許在工作區內寫入,但讓 .git 和 .codex 等目錄維持唯讀。這讓 Codex 能編輯原始碼,不必每次變更都請求許可,同時防止直接修改 .codex/config.toml 或 .git/hooks 下的 Git 掛鉤。

  • 允許廣泛讀取檔案系統,但仍受使用者現有作業系統權限的限制。編譯器、執行階段與建置工具都需要程式碼庫之外的 SDK、程式庫和設定。若將讀取範圍限於工作區,許多常見工作流程就無法運作。開放較大範圍的讀取權限,也表示命令可能讀得到電腦其他位置的敏感檔案,例如含有 API 金鑰的設定檔。

  • 停用網路存取。這會阻擋直接上傳到外部服務的操作,包括把命令讀得到的資料擅自傳出去。下載相依套件等正當操作也會受阻,需要另外取得存取權。

這些限制可防止一大類不當行為,但有害操作仍可能發生。例如,智慧體可能將惡意程式碼注入本機安裝的套件,如 node_modules/prettier。這類變更可能不會出現在 git status 中,因為 Git 通常會忽略 node_modules。如果使用者的編輯器在儲存時執行該份 Prettier,只要儲存檔案,就可能在 Codex 沙箱外執行惡意程式碼。這就是我們採取縱深防禦策略的原因:沙箱限制命令可存取的資源,而訓練與對齊則協助模型依照使用者的意圖運用這些存取權。

若想了解如何在企業環境中調整沙箱權限,並搭配其他保護措施,請參閱 Codex 安全實務指南⁠(在新視窗中開啟)。

沙箱的設計

虛擬機器與容器⁠(在新視窗中開啟)常用來建立沙箱。Codex 則讓命令直接在使用者現有的環境中執行,由各平台的沙箱機制限制命令可做的事,無須把運算移到獨立環境。

對許多開發人員而言,筆記型電腦就是量身打造的開發環境,可隨時依自己的想法調整。要在 Docker 容器中重建這個環境可能得花不少功夫,而且有些工作流程仍依賴在主機上執行的工具。

假設你在 Mac 上用 Codex 開發 iOS 應用程式,並選擇在 Docker 容器內執行 Codex 來隔離作業,Codex 就無法執行由 Mac 原生執行檔組成的 iOS 建置工具鏈,也無法啟動 iPhone 模擬器來執行程式碼。以 Docker 為基礎的工作流程可以將建置與模擬器操作交由 Mac 主機處理,但這些操作會在容器沙箱外執行,因此需要另外施加限制。為了簡化這個流程,我們投入大量心力開發各作業系統專屬的沙箱機制,讓 Codex 能在最適合當前任務的環境中執行。

任務執行框架透過 macOS、Windows 和 Linux 共用的 API,提供這些作業系統專屬的沙箱機制。此 API 接受一個命令和一份權限設定檔。如果權限設定檔允許有限的網路存取,呼叫端就必須提供網路代理伺服器,由代理伺服器執行這些限制:

Python

1
# This is a simplified version of the actual API.
2
def spawn_command_under_sandbox(
3
program_and_args: list[str],
4
cwd: Path,
5
env: dict[str, str],
6
permission_profile: PermissionProfile,
7
network_proxy: NetworkProxy | None,
8
) -> Child:

此函式會在沙箱中啟動行程,並傳回 Child 控制代碼,供任務執行框架用來等待行程完成。每個子行程都會繼承父行程的沙箱限制,因此這些限制會套用至命令所啟動的整個行程樹,甚至包括原始行程結束後仍在執行的後代行程。

下圖說明從設定沙箱到執行命令,各元件如何配合運作。以下各節會逐一說明。

流程圖:工作階段的權限設定檔取決於本身的設定和集中管理的設定要求。Codex 任務執行框架會依 macOS、Linux 或 Windows 的沙箱限制啟動命令。子行程會繼承這些限制,另可選用網路代理伺服器來強制執行網域規則。

任務執行框架如何運用沙箱

如〈解析 Codex 智慧體迴圈〉一文所述,Codex 任務執行框架負責執行模型產生的工具呼叫。在程式設計任務中,最常用的是 shell 工具,執行命令的方式就像使用者在 Bash 等互動式 shell 中輸入命令一樣。這裡我們會探討單次執行的 ⁠(在新視窗中開啟)exec_command⁠(在新視窗中開啟) shell 工具⁠(在新視窗中開啟),說明任務執行框架如何運用沙箱達到預期的保護效果。

以下是 Codex 任務執行框架在
不使用沙箱的情況下,處理 exec_command 工具呼叫的簡化版本:

Python

1
# Illustrative implementation of the exec_command tool call.
2

3
class ExecCommandToolCall:
4
cmd: str
5
workdir: str | None = None
6
shell: str | None = None
7
login: bool = True
8
timeout_ms: int = 10_000
9

10

11
def perform_exec_command(tool_call: ExecCommandToolCall):
12
program_and_args = [
13
tool_call.shell or os.environ.get("SHELL") or "/bin/sh",
14
"-lc" if tool_call.login else "-c",
15
tool_call.cmd,
16
]
17
child = subprocess.Popen(
18
program_and_args,
19
# workdir defaults to the turn's cwd, assumed here to be the process cwd.
20
cwd=Path(tool_call.workdir or ".").absolute(),
21
stdout=subprocess.PIPE,
22
stderr=subprocess.STDOUT,
23
)
24
output, exit_code = collect_output(child, timeout_ms=tool_call.timeout_ms)
25
return {"output": output, "exit_code": exit_code}

若要讓命令在沙箱中執行,任務執行框架會將對 subprocess.Popen() 的呼叫改為 spawn_command_under_sandbox()。任務執行框架會提供權限設定檔,並在需要時提供網路代理伺服器:

Python

1
# Honoring the exec_command tool call while enforcing sandbox constraints.
2

3
def perform_exec_command_with_sandboxing(
4
tool_call: ExecCommandToolCall,
5
permission_profile: PermissionProfile,
6
network_proxy: NetworkProxy | None,
7
):
8
# ...build program_and_args as in the previous example...
9
child = spawn_command_under_sandbox(
10
program_and_args=program_and_args,
11
cwd=Path(tool_call.workdir or ".").absolute(),
12
env=os.environ.copy(),
13
permission_profile=permission_profile,
14
network_proxy=network_proxy,
15
)
16
output, exit_code = collect_output(child, timeout_ms=tool_call.timeout_ms)
17
return {"output": output, "exit_code": exit_code}

exec_command 工具也允許模型為個別命令申請不同權限。是否核准由任務執行框架決定:

Python

1
class ExecCommandToolCall:
2
# ...command-related fields...
3

4
# Per-command sandbox override. Defaults to "use_default".
5
sandbox_permissions: Literal[
6
"use_default",
7
"with_additional_permissions",
8
"require_escalated",
9
] = "use_default"
10

11
# User-facing approval question; only for "require_escalated".
12
justification: str | None = None
13

14
# Expand network or filesystem access; only for "with_additional_permissions".
15
# AdditionalPermissions supports fine-grained options.
16
additional_permissions: AdditionalPermissions | None = None

指定 use_default 時,任務執行框架會使用該回合的預設沙箱設定。with_additional_permissions 會請求擴大沙箱內的存取權,而 require_escalated 則會請求在沙箱外執行。任務執行框架會在執行命令前,依照使用者偏好設定評估請求。(例如,Codex 可能直接詢問使用者,也可能將請求交由自動審查⁠(在新視窗中開啟)處理。)若執行已獲授權,Codex 會將適當的 permission_profile 與 network_proxy,連同原始 ExecCommandToolCall 中的命令引數,一起傳給 perform_exec_command_with_sandboxing()。

spawn_command_under_sandbox() 主要由 shell 工具呼叫。任務執行框架在讀取、修改本機檔案時,也會使用同一套沙箱機制。透過 codex sandbox 命令,你也能讓自己的工具在沙箱中執行命令,後文會進一步介紹。接下來,我們將探討如何定義權限設定檔。

設定沙箱

具名的權限設定檔讓你能在不同專案中重複使用相同的檔案系統與網路限制。你可以在 config.toml 的 [permissions] 下定義自己的設定檔。例如,以下範例定義名為 dev 的設定檔,繼承⁠(在新視窗中開啟)內建的 :workspace 設定檔:

TOML

1
# Use the dev profile by default.
2
default_permissions = "dev"
3

4
[permissions.dev]
5
# This is displayed when /permissions is run in the Codex CLI.
6
description = "Development with extra read-only protections."
7

8
# A profile can be derived from an existing profile.
9
# Profiles starting with ":" are provided by Codex.
10
extends = ":workspace"
11

12
[permissions.dev.filesystem]
13
"~/build-cache" = "write"
14

15
[permissions.dev.filesystem.":workspace_roots"]
16
".devcontainer" = "read"
17
".vscode" = "read"
18
"**/*.env" = "deny"
19
"secrets" = "deny"

dev 設定檔新增了 ~/build-cache 的寫入權限,並對工作區內的檔案施加額外限制。檔案系統項目設為 read 時只允許讀取,設為 write 時允許讀寫,設為 deny 則完全禁止存取。

:workspace_roots 設定表可用來定義路徑規則,路徑以專案的工作區根目錄為基準。預設情況下,Codex CLI 以目前的工作目錄作為唯一的工作區根目錄,而 ChatGPT 桌面應用程式則使用專案的來源資料夾。Codex 會將每條規則套用至每個根目錄,因此 dev 中的 .vscode 項目會讓每個根目錄下的 .vscode 目錄都變成唯讀。

除了自身的規則,dev 也會從 :workspace 繼承下列保護措施:

TOML

1
[permissions.":workspace".filesystem.":workspace_roots"]
2
".agents" = "read"
3
".aws" = "read"
4
".codex" = "read"
5
".git" = "read"

網路權限

設定 Codex 沙箱的網路時,大致有三種選項:

  • 停用所有網路存取(:workspace 設定檔的預設值)

  • 啟用完整的直接網路存取(:danger-full-access 設定檔的預設值)

  • 僅允許透過代理伺服器存取網路,由代理伺服器根據權限設定檔決定放行哪些流量


若要讓
dev 直接存取網路,請在 config.toml 的最上層設定 permissions.dev.network.enabled = true。當網路代理伺服器停用時,此設定會授予完整的網路存取權。

若要將 dev 限制為只能連線到特定網域,請啟用網路代理伺服器,並設定代理伺服器的網域規則:

TOML

1
[permissions.dev.network]
2
enabled = true
3

4
[permissions.dev.network.domains]
5
"*.openai.com" = "allow"
6
# Allow requests to local services by hostname or by IPv4/IPv6 loopback address.
7
"localhost" = "allow"
8
"127.0.0.1" = "allow"
9
"::1" = "allow"
10
"evil.example" = "deny"
11

12
[features]
13
# If neither local config nor managed requirements enable the proxy,
14
# this profile allows direct network access; domain rules are not enforced.
15
network_proxy = true

網域規則可以指定完整網域名稱,也能使用萬用字元模式,其中明確的拒絕規則優先於允許規則。對其他網域的請求需要核准,否則會被封鎖,詳見下方的「網路代理伺服器」一節。

分層設定與強制執行限制

個別使用者可以設定跨專案套用的預設值,並針對個別受信任的專案覆寫這些預設值。企業管理員也可能希望為使用者設定預設值,並限制使用者可以變更哪些設定。Codex 支援分層設定,也允許管理員統一訂定設定要求,因此能兼顧這兩種需求。

如設定優先順序⁠(在新視窗中開啟)所述,Codex 會合併多個 config.toml 檔案中的設定。表格會以遞迴方式合併;值發生衝突時,以優先順序較高的來源為準。陣列則會整體替換。

這就是權限設定檔使用表格來設定檔案系統路徑與網路網域的原因。團隊可以在自己的設定中新增或覆寫個別項目,並自動繼承組織基礎設定中所有其他項目的變更:

TOML

1
[permissions.dev.filesystem.":workspace_roots"]
2
".idea" = "read"
3

4
[permissions.dev.network.domains]
5
"example.com" = "allow"

管理員也可以透過 requirements.toml 指定集中管理的設定要求⁠(在新視窗中開啟),限制使用者的設定選項。這些要求可以來自多個來源,包括系統檔案與雲端提供的政策。常見的使用情境是指定 allowed_permission_profiles,限制企業使用者可選擇的權限設定檔。例如,管理員可以指定下列雲端要求:

TOML

1
default_permissions = ":read-only"
2

3
[allowed_permission_profiles]
4
":read-only" = true
5
":danger-full-access" = false

雲端要求優先於 /etc/codex/requirements.toml 的系統要求檔,因此該檔案中的項目無法覆寫上方明確指定的 ":danger-full-access" = false。不指定 :workspace,其他層級就仍可提供這個項目。在最終合併的設定表中,如果某個設定檔的值為 false,或根本沒有對應項目,該設定檔便無法使用。

這樣的分工讓組織能強制執行限制,同時讓使用者在限制範圍內調整設定。產生的權限設定檔可由任務執行框架使用,也能直接套用至命令,接下來我們會進一步說明。

使用 codex sandbox 命令

Codex CLI 提供 sandbox 命令,方便你依照 Codex 設定中定義的權限設定檔,執行任意命令。這個命令常用來測試權限設定檔,確認沙箱確實能阻止應封鎖的行為。

例如,下列命令會嘗試讓 VS Code 在儲存檔案時執行惡意的自動格式化工具。假設 .vscode 已存在,上方定義的 dev 設定檔應會封鎖這次寫入,因為該目錄為唯讀(codex sandbox 預設將 cwd 視為工作區根目錄):

Bash

1
codex sandbox --permission-profile dev -- \
2
bash -c 'cat > .vscode/settings.json' <<'JSON'
3
{
4
"prettier.prettierPath": "./node_modules/evil-prettier",
5
"[typescript]": {
6
"editor.defaultFormatter": "esbenp.prettier-vscode",
7
"editor.formatOnSave": true
8
}
9
}
10
JSON

在 macOS 上,這項操作果然失敗,並顯示以下訊息:

純文字

1
bash: .vscode/settings.json: Operation not permitted

codex sandbox 命令讓你即使沒有啟動智慧體工作階段,也能使用 Codex 的沙箱機制。你可以使用相同的設定語言與各平台專屬的強制執行機制,限制由你自己的工具啟動的命令。

範例:將 MCP 伺服器置於沙箱中

如果在 config.toml 中設定使用標準輸入輸出 (stdio) 的 MCP 伺服器,Codex 任務執行框架不會自動在沙箱中執行伺服器的啟動命令。Codex 無法準確判斷伺服器需要哪些檔案或網路服務,套用預設沙箱設定檔可能讓原本可用的設定失效。

例如,設定 @modelcontextprotocol/server-memory⁠(在新視窗中開啟) MCP 伺服器供 Codex 使用的標準方式如下:

TOML

1
[mcp_servers.memory]
2
command = "npx"
3
args = [
4
"-y",
5
"@modelcontextprotocol/server-memory@1.0.0"
6
]
7

8
[mcp_servers.memory.env]
9
MEMORY_FILE_PATH = "~/mcp-data/memory.jsonl"

這個 npx 命令在沙箱外執行,寫入檔案和發出網路請求時,權限和執行 Codex 的使用者一樣,範圍過大。為了收緊權限,我們可以定義名為 memory-mcp 的權限設定檔,再用 codex sandbox --permission-profile memory-mcp 執行原本的 npx 命令,限制伺服器可寫入的位置,並封鎖伺服器的網路存取:

TOML

1
[permissions.memory-mcp.filesystem]
2
# Allow broad reads for Node.js/npm dependencies and configuration.
3
":root" = "read"
4
"~/.npm" = "write"
5
"~/mcp-data" = "write"
6

7
[permissions.memory-mcp.network]
8
enabled = false
9

10
[mcp_servers.memory]
11
command = "codex"
12
args = [
13
"sandbox",
14
"--permission-profile",
15
"memory-mcp",
16
"--",
17
"npx",
18
"--offline",
19
"@modelcontextprotocol/server-memory@1.0.0"
20
]
21

22
[mcp_servers.memory.env]
23
MEMORY_FILE_PATH = "~/mcp-data/memory.jsonl"

啟動伺服器前,先建立伺服器的資料目錄,並將指定版本的套件存入 npm 快取。這樣一來,npx --offline 就能在停用網路存取的設定檔下啟動伺服器:

Bash

1
# The sandbox can write to this folder, but it cannot create it.
2
mkdir -p ~/mcp-data
3

4
# Installing the MCP server requires network access.
5
npx -y --package=@modelcontextprotocol/server-memory@1.0.0 -c true

套件快取完成後,Codex 就能在不存取網路的情況下啟動記憶伺服器,且寫入範圍僅限於 npm 快取和伺服器的資料目錄。

Codex 沙箱的實作

沙箱實作會將權限設定檔轉換為由作業系統強制執行的限制。網路代理伺服器的核心請求處理與政策邏輯由三大作業系統共用,而代理伺服器的設定及其與沙箱的整合方式則依作業系統而異。我們會先探討共用的代理伺服器,再介紹 macOS、Linux 和 Windows 的實作。

網路代理伺服器

為了強制執行權限設定檔中的網路限制,任務執行框架會啟動網路代理伺服器,並設定沙箱允許連線至該代理伺服器,同時封鎖直接連線至外部主機。代理伺服器會依照設定檔的網域規則檢查每個請求,決定是否轉送。

在 Codex 程式碼庫中,實作網路代理伺服器的是 Rust 套件 codex-network-proxy⁠(在新視窗中開啟)。任務執行框架把這個套件當作程式庫使用。這個套件也能建置成獨立的 CLI⁠(在新視窗中開啟)。啟用後,codex-network-proxy 預設會同時啟動 HTTP 代理伺服器與 SOCKS5 代理伺服器。這些代理伺服器位址會透過環境變數傳給沙箱啟動的行程。除了注入 HTTP_PROXY、HTTPS_PROXY 和 ALL_PROXY 等標準環境變數,也會注入多個常見的應用程式專用環境變數⁠(在新視窗中開啟),例如 PIP_PROXY。不過,有些程式會忽略這些環境變數。如果程式嘗試直接連線至外部主機,作業系統的沙箱機制就會封鎖連線,詳見下方各平台專屬章節。

網路代理伺服器負責實施權限設定檔中定義的網路限制。例如,先前展示的 dev 設定檔允許送往 *.openai.com 的請求,並明確拒絕送往 evil.example 的請求。當請求的目標網域不符合任何允許或拒絕規則時,代理伺服器可以暫停請求,並交由任務執行框架決定是否核准。如同 shell 命令的範例,Codex 可能直接詢問使用者,也可能將請求交由自動審查⁠(在新視窗中開啟)處理。代理伺服器收到審查結果後,就會放行請求,或拒絕請求並傳回錯誤。

這裡的處理順序很重要,因為即使只是 DNS 查詢,也可能洩漏編碼在主機名稱中的資訊。因此,代理伺服器會先確認請求連往的主機名稱符合允許規則或已獲核准,才會解析該名稱。請注意,範圍過廣的萬用字元規則或 DNS 服務存取權,仍可能讓資料透過 DNS 外洩。

macOS

在 macOS 上,Codex 使用 Seatbelt⁠(在新視窗中開啟),這套沙箱機制由 Apple 提供,限制由作業系統核心強制執行。Seatbelt 政策以沙箱設定檔語言 (Sandbox Profile Language, SBPL) 撰寫。這是一種以 Scheme 為基礎、用來表達沙箱限制的語言。Codex 透過 macOS 的 /usr/bin/sandbox-exec 命令呼叫 Seatbelt。與 codex sandbox 一樣,呼叫時先指定沙箱選項,後面再接要執行的命令:

Bash

1
sandbox-exec -p PROFILE [-Dkey=value]* -- PROG ARGS...

PROFILE 是一段 SBPL 字串,包含用來設定沙箱的項目。例如,下列 SBPL 片段會讓沙箱政策允許讀寫 /dev/null 和 /dev/zero:

Scheme

1
(allow file-read* file-test-existence file-write-data
2
(literal "/dev/null")
3
(literal "/dev/zero"))

呼叫沙箱時若啟用了網路代理伺服器,設定檔就會加入類似下方範例的規則,只允許連線到指定的本機連接埠:

Scheme

1
; local HTTP proxy launched by Codex
2
(allow network-outbound (remote ip "localhost:3128"))
3

4
; local SOCKS proxy launched by Codex
5
(allow network-outbound (remote ip "localhost:8081"))


Codex 的基礎設定檔以
(deny default) 開頭,因此除非明確允許,否則對外連線都會被封鎖。

最後,SBPL 可以使用 (param) 加入預留位置:

Scheme

1
; Pass -DWRITABLE_ROOT_0=/path/to/dir to specify a folder that cannot be removed.
2
(deny file-write-unlink
3
(require-all
4
(literal (param "WRITABLE_ROOT_0"))
5
(vnode-type DIRECTORY)))

這些預留位置會由傳給 sandbox-exec 的 -Dkey=value 選項填入。

為了實作沙箱 API,Codex 先依據基礎政策⁠(在新視窗中開啟),為 sandbox-exec 組合引數清單⁠(在新視窗中開啟),再根據 permission_profile 和其他執行環境資訊調整清單,產生完整的 Seatbelt 設定檔。這份設定檔和對應的 -D 引數決定 Seatbelt 要強制執行哪些限制,其他網路規則則由網路代理伺服器執行。引數備齊後,就能直接呼叫 sandbox-exec。

要產生正確的 SBPL 並不容易,因為 Apple 並未向第三方提供這套語言的文件。man sandbox-exec 明確標示 The sandbox-exec command is DEPRECATED,也就是這個命令已棄用。使用 man 3 sandbox_init 查閱手冊,也能看到 sandbox_init() 程式庫函式已棄用的說明。儘管有棄用警告,macOS 仍在 /usr/share/sandbox 中隨附 Seatbelt 設定檔,包括 Google Chrome 和 Chromium 在內⁠(在新視窗中開啟)的第三方軟體也持續仰賴 Seatbelt。因此,我們計畫在可預見的未來繼續使用 Seatbelt。

Linux

為了在 Linux 上建立沙箱,Codex 結合使用 bubblewrap⁠(在新視窗中開啟) (bwrap) 與 seccomp-bpf⁠(在新視窗中開啟):前者是建構隔離環境的命令列工具,後者則是用來篩選系統呼叫的 Linux 核心機制。名為 codex-linux-sandbox 的內部輔助程式負責協調設定作業。與 macOS 上的 sandbox-exec 一樣,呼叫這個輔助程式時,先指定沙箱設定,後面再接要執行的命令:

Bash

1
codex-linux-sandbox SANDBOX_ARGS... -- PROG ARGS...

需要檔案系統隔離或代理路由時,codex-linux-sandbox 會呼叫 bwrap,建立初始沙箱環境。接著,bwrap 會在其中啟動 codex-linux-sandbox --apply-seccomp-then-exec。第二次呼叫時,會使用 seccomp-bpf,在執行使用者命令前套用額外限制。

為了建構初始沙箱環境,Codex 使用 bubblewrap,在獨立的掛載命名空間中建立檔案系統視圖,反映權限設定檔中的檔案系統規則。由於這是沙箱實作的基礎,Codex 隨附了一份 bwrap,即使使用者尚未安裝也能運作。如果 PATH 中有相容版本,Codex 就會優先使用系統上相容的 ⁠(在新視窗中開啟)bwrap⁠(在新視窗中開啟)。實務上,部分 Linux 發行版預設會停用使用者命名空間的存取⁠(在新視窗中開啟),但會對系統的 bwrap 開放例外權限。

與 sandbox-exec 一樣,bwrap 接受沙箱設定,後面再接要在沙箱內執行的命令。bwrap 不使用 SBPL 這類自訂設定語言,而是透過個別旗標進行設定。Codex 使用下列選項建立檔案系統視圖:

  • --bind:指定可寫入的檔案或目錄

  • --ro-bind:指定唯讀檔案或目錄

  • --perms 000 --tmpfs DIR --remount-ro DIR:拒絕存取 DIR

  • --perms 000 --ro-bind-data FD FILE:拒絕存取 FILE(其中 FD 是指向 /dev/null 的已開啟檔案描述元)

為了透過這些選項套用拒絕存取的 glob 模式,Codex 會在啟動每個命令前,將模式展開為具體路徑。之後新增且符合模式的路徑,不會自動加入該命令的沙箱限制。

Codex 也會指定 --unshare-ipc 和 --unshare-pid 等選項,防止沙箱存取主機上其他類型的資源,因此 bubblewrap 的作用不只是控制檔案的可見範圍。

使用 bubblewrap 時,只要網路已停用,或連線必須透過網路代理伺服器,Codex 就會傳入 --unshare-net,為沙箱建立新的網路命名空間。接著,我們會使用 seccomp-bpf,對命令可用的網路系統呼叫與通訊端家族施加額外限制。


具體而言,我們使用
seccompiler crate⁠(在新視窗中開啟),根據所需的篩選條件動態編譯 BPF 程式⁠(在新視窗中開啟),再把編譯好的程式套用到沙箱內的啟動器行程,讓整個行程樹都繼承這些限制。因此,bwrap 不會直接執行使用者的命令,而是執行 codex-linux-sandbox 啟動器,傳入啟動器本身的設定引數,後面再接使用者的命令:

Bash

1
bwrap BWRAP_ARGS... -- \
2
codex-linux-sandbox --apply-seccomp-then-exec CODEX_LINUX_SANDBOX_ARGS... -- \
3
PROG ARGS...

為了在不提升權限的情況下套用 seccomp 篩選器,啟動器會設定 Linux 的 no_new_privs 旗標⁠(在新視窗中開啟)。子行程會繼承此旗標,因此執行其他程式(例如 setuid 執行檔)時,也無法取得額外權限。

seccomp 篩選器會依網路設定而定。停用網路存取時,我們會封鎖多個網路相關系統呼叫,例如 connect(2) 和 bind(2)。不過,在沙箱中啟用網路代理伺服器時,我們會允許 IP 通訊端,以便連線到 codex-linux-sandbox 建立的 TCP 接聽器,但預設禁止建立獨立的 Unix 網域通訊端,以免意外存取主機資源。

連線至網路代理伺服器

當沙箱設定需要使用網路代理伺服器時,Codex 任務執行框架會建立一個代理伺服器執行個體,供同一個 Codex 對話串內的多次 codex-linux-sandbox 呼叫共用。每個沙箱都需要能從其隔離的網路命名空間連線到這個共用代理伺服器。Codex 會在該命名空間內提供回送 TCP 接聽器,並安排沙箱外的行程接受連線,再將連線轉送到代理伺服器。

下列圖表以一個代理端點說明這項配置,最後一張圖則顯示透過該端點建立的一個連線。啟動 bubblewrap 前,codex-linux-sandbox 會建立一對 Unix 通訊端作為控制通道,再建立子行程。子行程會執行 run_host_bridge(),並等候控制通道傳來接聽器的檔案描述元:

示意圖:Codex 任務執行框架啟動 codex-linux-sandbox,再由 codex-linux-sandbox 建立負責轉送的子行程。兩個行程透過 Unix 通訊端控制通道連線。

在此範例中,父行程使用 exec 將自己的程式映像替換為 bwrap,由 bwrap 建立沙箱,並在沙箱內啟動 codex-linux-sandbox --apply-seccomp-then-exec,同時傳入控制通道的檔案描述元 (FD):

示意圖:bwrap 建立沙箱網路命名空間,並在其中啟動 codex-linux-sandbox,透過 Unix 通訊端控制通道連接至沙箱外的轉送行程。

在沙箱的網路命名空間內,第二次呼叫的 codex-linux-sandbox 會建立回送 TCP 接聽器,並透過通訊端傳出接聽器的檔案描述元。接聽器仍屬於沙箱的網路命名空間,因此留在沙箱外的子行程可以接受來自沙箱內程式的連線,同時在主機的網路命名空間中建立上游連線。描述元傳遞完成後,兩個行程都會關閉各自的控制通道描述元,而沙箱內的行程也會關閉自己持有的接聽器副本。

TCP 接聽器就緒後,沙箱內的行程會設定 HTTP_PROXY⁠(在新視窗中開啟) 和相關環境變數的值,讓這些變數指向該接聽器。接著,行程會先套用 seccomp,再建立子行程來執行使用者的命令:

示意圖:沙箱內的程式連線至回送 TCP 接聽器,由沙箱外的 codex-linux-sandbox 轉送行程將流量轉送至 Codex 網路代理伺服器。

沙箱外的行程會保持接聽器開啟。每接受一條連線,就會連到指定的代理伺服器,在兩端之間轉送資料。

這套額外機制讓命令擁有自己的網路命名空間,包括獨立的回送介面。在 macOS 上,Seatbelt 允許命令直接連線到主機回送介面上的指定連接埠。在 Linux 上,命令則會連線到自己所屬的隔離命名空間內的接聽器,再由沙箱外的行程將這些連線轉送到設定的代理伺服器。傳遞檔案描述元後,命令就能建立連線,主機的網路命名空間也能維持隔離。

Windows

今年稍早,我們實作了 Windows 沙箱,並撰文介紹開發過程。之後,Microsoft 發布了名為 MXC 的程式庫,同時在 Windows 作業系統中推出新的行程隔離功能。我們正逐步改用以 MXC 程式庫為基礎的新沙箱。

什麼是 MXC?

MXC (Microsoft eXecution Container) 由 Microsoft 開發,是一套可在沙箱中執行程式碼的系統⁠(在新視窗中開啟),支援 Windows、Linux 和 macOS 上的多種隔離後端。Codex 在相容的 Windows 裝置上支援以 MXC 為基礎的沙箱,透過原生行程隔離,限制命令在使用者現有環境中能執行的操作。

我們正逐步改用 MXC,讓沙箱更安全、更容易使用,也解決現有 Windows 沙箱的幾項限制:

  • 設定沙箱需要較高的權限或系統管理員權限

  • 檢查和設定存取控制清單 (ACL) 既耗資源又費時

  • 設定沙箱後,主機上會留下下列項目:

    • ACL

    • 防火牆規則

    • 沙箱使用者

    • 控制平面檔案

MXC 提供 JSON 設定結構描述⁠(在新視窗中開啟)。Codex 使用 MXC SDK⁠(在新視窗中開啟) 建立符合該結構描述的執行請求,其中包含命令、工作目錄、環境與權限。這些權限涵蓋檔案系統與網路存取,以及桌面和剪貼簿等 Windows 資源。

如何依權限政策呼叫 MXC

Codex 對幾項功能採用固定設定,兼顧相容性與安全性。這些設定允許讀取 Windows 登錄,並保留 PowerShell 啟動時所需的 Win32k 與桌面存取權,但會停用剪貼簿存取、輸入注入,以及控制桌面和系統設定的功能。此外,即使原本的方式無法使用,MXC 也不能改動主機的檔案系統權限。

Codex 會將權限設定檔中的檔案系統與網路規則轉換為 MXC 設定。以先前的 dev 設定檔為例,假設條件如下:

  • C:\、D:\ 和 Z:\ 是這台電腦僅有的本機磁碟機。

  • 工作區根目錄與工作目錄均為 C:\work\demo。

  • 使用者的主目錄是 D:\Users\dev,因此 ~/build-cache 會解析為 D:\Users\dev\build-cache。

  • 拒絕存取的 glob 模式只會比對到 C:\work\demo\config\dev.env 和 C:\work\demo\config\prod.env。

對應的 MXC 設定會包括:

JSON

1
{
2
...
3
"filesystem": {
4
"readwritePaths": [
5
"C:\\work\\demo",
6
"D:\\Users\\dev\\build-cache",
7
...
8
],
9
"readonlyPaths": [
10
"C:\\",
11
"D:\\",
12
"Z:\\",
13
"C:\\work\\demo\\.agents",
14
"C:\\work\\demo\\.aws",
15
"C:\\work\\demo\\.codex",
16
"C:\\work\\demo\\.devcontainer",
17
"C:\\work\\demo\\.git",
18
"C:\\work\\demo\\.vscode",
19
...
20
],
21
"deniedPaths": [
22
"C:\\work\\demo\\config\\dev.env",
23
"C:\\work\\demo\\config\\prod.env",
24
"C:\\work\\demo\\secrets"
25
]
26
},
27
"network": {
28
"egress": {
29
"default": "deny",
30
"allow": [{
31
"to": [
32
{"cidr": "127.0.0.0/8"},
33
{"cidr": "::1/128"}
34
]
35
}]
36
},
37
"ingress": {
38
"default": "deny",
39
"hostLoopback": "allow"
40
}
41
},
42
...
43
}

磁碟機根目錄的存取權限

MXC 的檔案系統政策預設拒絕存取。為了讓命令能讀取設定檔允許的廣泛範圍,Codex 會授予本機各磁碟機根目錄的唯讀權限。這些權限會遞迴套用到下層目錄與檔案,但仍受使用者現有的作業系統權限限制。

磁碟機根目錄的寫入權限不會遞迴套用,因此 Codex 會把根目錄下一層現有的檔案與目錄也納入授權範圍。

授權衝突

較具體的路徑會覆寫上層路徑的授權,因此,即使 C:\ 為唯讀,其下的 C:\work\demo 仍可寫入,而 C:\work\demo\.git 則維持唯讀。

如果不同的路徑寫法、符號連結或接合點別名都指向同一路徑,MXC 會套用較嚴格的權限:拒絕存取優先於唯讀,而唯讀優先於讀寫。

拒絕存取的 glob 模式

MXC 只接受具體的拒絕存取路徑,因此 Codex 會在啟動前,將拒絕存取的 glob 模式展開為符合模式的檔案與目錄。命令執行期間,符合 glob 模式的新路徑不會自動加入拒絕存取清單。

網路存取

*.openai.com 等網域規則由前述共用的 Codex 網路代理伺服器強制執行。Codex 會在沙箱外執行該代理伺服器,並透過前述相同的標準 *_PROXY 環境變數,將代理伺服器的位址傳給命令。MXC 會封鎖直接對外連線,但沙箱內的命令仍可透過主機的回送介面連到代理伺服器,也能連到其他本機服務。

在 macOS、Linux 和 Windows 上,任務執行框架都使用相同的沙箱 API,依權限設定檔啟動命令。各平台專屬的實作會處理套用這些限制所需的設定作業。

將 Codex 沙箱用於更多工具

智慧體能自行撰寫和執行程式碼,因此也能靈活處理軟體開發以外的問題。Codex 沙箱讓智慧體能在使用者現有的環境中運用這項能力,同時對檔案系統與網路存取設下明確限制。沙箱是任務執行框架中可重複使用的基礎元件。透過 codex sandbox 命令,你也能在自己的工具中使用這套沙箱機制。

隨著智慧體能處理的任務愈來愈多,我們也希望更多工具和環境能用上沙箱。為此,我們會簡化權限設定,並在作業系統推出更完善的防護機制時加以採用。目標是讓智慧體能做更多事,同時讓使用者始終能決定智慧體可以存取哪些資源。

作者

OpenAI

致謝

特別感謝 David Wiesen、Charlie Weems、Viyat Bhalodia 和 Fotis Chantzis 對本文的貢獻。