本頁譯自英文文件。指令、識別名稱與範例保持原樣。執行環境 7.24.4 · SDK 2.6.7。 英文原文

沙盒模式

狀態：有效 範圍：目前狀態 上次審閱：2026-08-23 負責人：ax-code runtime

AX Code 內建執行沙盒，可以限制 AI agent 在你系統上的行為。預設情況下，AX Code 以完整存取啟動且沙盒關閉，因此檔案系統寫入與網路存取不受限。在處理不受信任的儲存庫或執行無人值守工作之前，請啟用 workspace-write 或 read-only。

安全性警告：full-access 不是安全邊界。agent 可以修改工作區以外的檔案、寫入 .git/ 與 .ax-code/、執行不受限的 shell 指令，以及存取網路。

快速開始

從 TUI 切換沙盒：

• 在提示中輸入 /sandbox，或
• 按 Ctrl+P 並搜尋「sandbox」

狀態列顯示目前狀態：

• 沙盒開啟（綠色）— agent 限制在工作區內
• 沙盒關閉（紅色）— 沒有限制

此設定會跨工作階段保存在 ax-code.json。

有什麼改變

設定

權威來源

本頁摘要面向使用者的行為。行為改變時，請對照下列來源核對文件：

• packages/ax-code/src/isolation/index.ts：模式解析、受保護路徑、網路檢查、寫入檢查、bash 檢查，以及 IsolationDeniedError。
• packages/ax-code/src/config/schema.ts：設定形狀、預設值與說明。
• packages/ax-code/src/server/routes/isolation.ts：執行環境切換行為與持久性。
• packages/ax-code/test/isolation/isolation.test.ts 與 packages/ax-code/test/tool/bash.test.ts：預期的強制執行行為。

根目錄 README 中的重複宣稱保持簡短，並連回此處查看細節。

從 TUI 切換

使用 /sandbox 或命令選擇區（Ctrl+P →「開啟或關閉沙盒」）。變更立即生效，並儲存到專案的 ax-code.json。

CLI 旗標

ax-code --sandbox workspace-write   # sandbox on
ax-code --sandbox full-access       # sandbox off
ax-code --sandbox read-only         # strictest: blocks all mutations

環境變數

AX_CODE_ISOLATION_MODE=workspace-write ax-code

設定檔

在 ax-code.json 中：

{
  "isolation": {
    "mode": "workspace-write",
    "network": false
  }
}

優先順序

CLI 旗標 > 環境變數 > 設定檔 > 預設（full-access）

當 CLI 或環境覆寫作用中時，TUI 會回報該有效模式。/sandbox 切換可以儲存專案偏好，但較高優先的覆寫會一直作用，直到移除為止（通常在重新啟動時）。

隔離模式

受保護路徑

在 workspace-write 模式中，這些路徑一律受寫入保護：

• .git/ — 防止意外損毀 git 狀態
• .ax-code/ — 防止竄改設定或外掛

在設定中加入自訂受保護路徑：

{
  "isolation": {
    "mode": "workspace-write",
    "protected": ["secrets", "credentials"]
  }
}

網路存取

在 workspace-write 與 read-only 模式中，網路預設停用。受影響的工具：

• webfetch — 已阻擋
• websearch — 已阻擋
• codesearch — 已阻擋
• bash — 僅網路的用戶端（curl、wget、nc/ncat/netcat、telnet、ftp、tftp、scp、sftp、dig、nslookup、host）已阻擋

限制：bash 中的網路阻擋屬於應用程式層，涵蓋上方的專用網路用戶端。它不會攔截也能離線運作的兩用工具（git、npm/pnpm/yarn、pip、go，以及 python/node 這類語言解譯器），因為無法以靜態方式區分它們的離線呼叫，阻擋它們會破壞常見工作流程。真正、徹底的網路隔離需要作業系統層控制，而此沙盒並不提供。碰到被拒絕的用戶端時，agent 會提示一次升級。

若要在保留寫入限制的同時允許網路：

{
  "isolation": {
    "mode": "workspace-write",
    "network": true
  }
}

隔離後端（應用程式對作業系統）

**macOS：**透過 sandbox-exec 使用 Seatbelt 設定檔（寫入限於工作區／worktree，當 network: false 時拒絕網路）。
**Linux：**已安裝時使用 bubblewrap（bwrap）（網路停用時為 --unshare-net，工作區以讀寫繫結掛載）。
**Windows：**目前只有應用程式層。

{
  "isolation": {
    "mode": "workspace-write",
    "network": false,
    "backend": "auto"
  }
}

威脅模型見 SECURITY.md。

儲存庫控制的權限與 hooks

專案檔預設不受信任。ax-code.json、.ax-code/policy.json 以及專案 agent 或模式定義中的權限規則，可以用 deny 收緊存取，但儲存庫控制的 allow/ask 授予會被忽略。專案指令不能啟用 shell 展開。.ax-code/hooks.json、.ax-code/plugin/ 以及專案設定的外掛不會被執行。

不受信任的專案設定也不能選擇自訂 shell、可執行的 LSP 或格式化工具、供應商套件或 API 端點、供應商憑證環境變數、外部技能來源，或 worktree 以外的指示路徑。安全的相對指示路徑與不可執行的內建覆寫仍然可用。MCP 伺服器使用另一套指紋核准流程，說明見 MCP 整合。

檢閱儲存庫控制的設定之後，使用者可以在儲存庫之外、針對目前行程選擇加入：

AX_CODE_TRUST_PROJECT_CONFIG=1 ax-code

僅環境的開關可防止某個檢出把自己宣告為受信任。

強制執行方式

沙盒強制執行始終在應用程式層，於每次工具呼叫時檢查。當 backend 為 os 或 auto 且平台支援時，bash 會額外包在核心沙盒中。

工具違反隔離時，會擲出 IsolationDeniedError，並以清楚訊息說明阻擋了什麼以及原因。