透過為每個代理提供範圍限定的工作區、明確的檔案權限、受控制的 Shell 執行、網路與套件政策、清晰的機密邊界、持久化的日誌、捕獲的成品，以及在合併或發佈變更前的人員審查，在沙盒中執行 Claude Code 風格或受管編碼代理。代理仍然可以讀取程式碼、編輯檔案、安裝依賴項、執行測試並產生修補程式，但周圍的環境會決定它能觸及什麼、能擷取什麼、能看到哪些憑證，以及何時需要人員核准後續步驟。
需要隔離的項目
編碼代理不僅僅是一個附加在儲存庫上的聊天機器人。一旦它能編輯檔案並執行命令，它就開始像一個具有語言模型推理能力的初級建置工作人員。該工作人員可能會執行 npm test、檢查產生的檔案、啟動開發伺服器，或因為錯誤訊息提示而嘗試安裝套件。如果工作區是你的筆記型電腦、共用的 CI 執行器或長期運作的類似生產環境的虛擬機器，那麼爆炸半徑就太廣了。
隔離的目標是整個代理工作循環：
- 代理可讀取或修改的儲存庫簽出與分支。
- 代理可寫入的檔案系統路徑。
- 代理可自動執行的命令。
- 需要核准的命令。
- 代理可觸及的套件註冊表、網域與 API。
- 暴露給工作階段的憑證。
- 為審查而保留的日誌、差異、測試輸出、螢幕截圖與成品。
- 成功、失敗或逾時後的清除行為。
Claude Code 與其他受管編碼代理產品可能包含它們自己的權限系統。例如，Anthropic 的 Claude Code 文件描述了允許與禁止工具、核准行為以及在地端使用的沙盒指南的權限設定。將這些控制視為一層，而非整個邊界。更穩固的設計是將代理也放置於隔離的執行環境中，然後在該執行環境內套用工具權限。
參考架構
一個實用的沙盒代理工作流程包含四個層級：
| 層級 | 用途 | 典型控制 |
|---|---|---|
| 代理控制器 | 決定任務計劃與工具呼叫 | 模型/工具權限、核准模式、任務提示 |
| 沙盒執行環境 | 托管命令執行的工作區 | 隔離的檔案系統、程序限制、生命週期控制 |
| 政策閘道 | 決定允許哪些操作 | 命令規則、網路出口規則、套件政策、機密範圍 |
| 審查介面 | 讓人類檢查結果 | 差異、日誌、測試結果、成品、拉取請求 |
保持這些層級獨立。如果代理控制器因提示注入而受損，沙盒執行環境與政策閘道仍應限制後果。如果套件安裝拉入了非預期的程式碼，網路與成品日誌應使其可見。如果代理產生看似合理的修補程式，審查介面仍應確切顯示哪些內容被更改以及哪些測試被執行。
概念性的政策物件可能如下所示：
workspace:
mode: ephemeral
repo_ref: pull-request-branch
writable_paths:
- /workspace/project
readonly_paths:
- /workspace/reference
commands:
auto_allow:
- git status
- npm test
- npm run lint
- pytest
require_approval:
- npm install
- pip install
- docker build
- git push
deny:
- rm -rf /
- curl ... | sh
network:
default: deny
allow:
- registry.npmjs.org
- pypi.org
- files.pythonhosted.org
secrets:
expose:
- READ_ONLY_PACKAGE_TOKEN
deny:
- PRODUCTION_DATABASE_URL
- CLOUD_ADMIN_TOKEN
artifacts:
capture:
- git diff
- test-results/
- screenshots/
- command-log.jsonl
這故意不是 SDK 範例。確切的政策格式取決於你的代理框架與沙盒提供者。重點是權限應在模型的自由形式推理之外表達，然後由執行環境或協調層強制執行。
工作區與儲存庫設定
從乾淨的工作區開始每個代理執行。受管代理不應繼承開發者的 Shell 歷史、SSH 代理、dotfiles、雲端 CLI 登入或未追蹤的本地檔案，除非有刻意的理由。
對於儲存庫工作，使用專用的簽出：
- 僅複製或掛載任務所需的儲存庫。
- 簽出一個新的任務分支，而不是編輯預設分支。
- 鎖定基底提交，以便審查可以重現起始點。
- 將依賴項快取與可寫入的原始碼路徑分開。
- 將產生的成品儲存在原始碼樹之外，除非它們是預期差異的一部分。
分支隔離很重要，因為編碼代理經常在確定一個方案之前嘗試多種方法。一個乾淨的任務分支為審查者提供正常的拉取請求差異，而不是包含臨時實驗的混合工作區。如果代理需要與參考實作進行比較，請以唯讀方式掛載該參考。
對於長期執行的受管代理，決定沙盒是暫時性的、暫停的還是快照的。暫時性工作區更容易推理。快照與暫停/恢復對於長時間工作、瀏覽器工作階段與昂貴的設定步驟很有用，但它們仍應保留清晰的稽核軌跡：快照何時建立、哪些檔案存在、以及哪些憑證可用。
檔案系統權限
檔案系統範圍應比「代理可以讀取整台機器」更窄。大多數編碼任務需要：
- 對儲存庫工作區的讀寫存取。
- 對選定任務上下文、fixtures 或文件的唯讀存取。
- 用於建置輸出與暫存檔案的臨時目錄。
- 無法存取主機家目錄、無關的儲存庫、雲端憑證、瀏覽器設定檔或生產資料轉儲。
寫入權限需要特別注意。能夠編輯儲存庫的編碼代理也可以編輯腳本、測試、鎖定檔案、CI 配置與部署檔案。這可能正是任務所需，但應在審查中可見。對於敏感路徑，例如 .github/workflows/、部署清單或套件發佈配置，需要更強的核准步驟或由人類擁有的最終審查。
當任務範圍狹窄時，使用檔案允許清單。例如，文件代理可能只需要 docs/ 和一個產生的預覽目錄。依賴項升級代理可能需要 package.json、鎖定檔案和測試快照。廣泛的重構需要更寬的存取權限，但審查應預期更大的差異和更完整的測試。
Shell 執行政策
Shell 存取是編碼代理既實用又危險的地方。它們需要執行命令來執行測試、格式化程式碼、檢查建置錯誤以及驗證修復。它們不需要不受限制的權限來無暫停地執行每個命令。
一個好的 Shell 政策有三個類別：
| 類別 | 範例 | 為何重要 |
|---|---|---|
| 自動允許 | git status、npm test、pytest、go test ./...、npm run lint |
保持常規編輯-測試循環快速 |
| 需核准 | 套件安裝、遷移、長時間運行的服務、外部 CLI、git push |
在狀態、成本或網路風險改變時增加阻力 |
| 禁止 | 破壞性的主機命令、憑證傾印、不安全的 Shell 管道、寫入工作區之外 | 阻止不應委派的操作 |
不要僅依賴命令文字比對。代理可以透過腳本、套件管理器鉤子或巢狀 Shell 執行命令。對於高風險環境，將命令政策與執行環境層級的檔案系統邊界、資源限制和網路控制結合。
長時間運行的命令需要逾時行為。測試伺服器、瀏覽器自動化執行或建置監控程式可能在代理執行下一個步驟後仍然存活。捕獲程序 ID、標準輸出、標準錯誤、退出狀態、執行時間與終止原因。如果命令開啟了預覽埠，記錄埠映射並在清除時關閉它。
套件安裝與網路出口
套件安裝是代理工作區最有用的功能之一，也是最容易引入風險的地方之一。編碼代理可能因為 Stack Overflow 回答、README 或模型生成的計劃建議而安裝套件。這可能改變依賴關係圖、執行安裝腳本並觸及外部註冊表。
對於實作指南與生產工作流程，從預設拒絕的網路狀態開始，然後允許任務所需的內容：
- 套件註冊表，例如 npm 或 PyPI，最好透過註冊表鏡像或快取。
- 儲存庫及子模組所需的來源主機。
- 任務所需的文件網域。
- 僅當沙盒具有正確的資料分類時才允許內部 API。
避免預設給每個代理廣泛的網際網路出口。如果因研究或瀏覽器自動化而需要廣泛存取，請將該執行與修改程式碼的執行分開，並相應地標記成品。
對於套件安裝，記錄：
- 套件管理器命令。
- 註冊表主機。
- 鎖定檔案變更。
- 下載的套件名稱與版本（如有）。
- 任何執行的安裝腳本。
- 是否有人類核准了安裝。
這並不會使任意套件變得安全。它使變更可審查。
機密邊界
機密應限於任務所需、短暫存在，且預設情況下不存在。最安全的沙盒不是承諾模型絕不會洩露機密的沙盒，而是除非任務確實需要否則機密不存在的沙盒。
使用這些預設值：
- 代理工作區中沒有生產資料庫憑證。
- 沒有雲端管理員令牌。
- 沒有個人 SSH 金鑰或開發者機器憑證。
- 盡可能使用唯讀憑證。
- 為套件讀取、測試 fixtures 或僅限暫存 API 使用單獨的令牌。
- 在成品分享之前，在日誌中進行遮罩處理。
如果代理必須呼叫外部服務，提供一個狹隘的令牌，並記錄哪個工具或命令使用了它。避免將廣泛的憑證放在代理可編輯的檔案中。環境變數很方便，但它們仍然可以被命令列印、包含在日誌中或複製到產生的檔案中。將它們視為已暴露給代理程序。
日誌、成品與稽核軌跡
只有當審查者能夠看到發生了什麼時，人類審查才有用。沙盒化編碼代理的執行應保留比最終修補程式更多的內容。
至少捕獲：
- 任務提示或說明摘要。
- 基底提交與分支。
- 當你的工具能記錄時，記錄讀取和寫入的檔案。
- 執行的命令，包含時間戳記、工作目錄、退出狀態、標準輸出與標準錯誤。
- 套件安裝與網路存取摘要。
- 測試與建置結果。
- 產生的檔案、螢幕截圖、報告或預覽連結。
- 最終差異。
將日誌儲存在比沙盒壽命更長的審查介面中。如果沙盒在執行後立即被銷毀，證據仍應在拉取請求、CI 成品存儲或代理平台記錄中可用。
對於使用受管代理的團隊，此稽核軌跡也有助於比較代理效能。你可以看到失敗是由於缺少依賴項、被拒絕的命令、不明確的提示、不穩定的測試還是真正的程式碼問題。
清除與重置
沙盒清除是安全性與成本控制，而不僅僅是整理。在執行結束時：
- 停止背景程序。
- 關閉開放的埠。
- 撤銷任務範圍的令牌。
- 匯出所需的成品。
- 刪除不屬於審查一部分的臨時檔案。
- 根據執行類型銷毀、暫停或快照沙盒。
對於不受信任或探索性工作，暫時性重置是最乾淨的預設值。對於長期運行的代理，僅在已知良好的設定步驟之後進行快照，而不是在任意代理活動之後。如果失敗的執行需要調查，請保留沙盒或快照，並附上明確的到期時間。
Novita Agent Sandbox 的定位
Novita Agent Sandbox 專為 AI 代理執行工作流程而設計，其中程式碼在隔離的雲端工作區內執行，而不是在開發者筆記型電腦或共享主機上。Novita 的沙盒文件描述了對應於本指南中模式的核心原始功能：沙盒生命週期管理、檔案系統操作、命令執行、模板以及代理工作負載的執行環境管理。
這使得 Novita 適合正在建立編碼代理、數據分析、瀏覽器代理、評估或長期運作代理工作流程的團隊，這些工作流程需要一個執行環境以及模型 API。但請保持邊界清晰：本文是針對 Claude Code 風格與受管編碼代理的通用實作模式。它並未聲稱與 Claude Code 有正式整合、合作關係，或與每個受管代理產品都普遍相容。
如果你正在設計基於 Novita 的工作流程，請使用產品文件了解確切的已發布 API 表面，並保持你的政策層明確。沙盒可以提供隔離的執行工作區；你的應用程式仍應決定命令核准、網路政策、機密範圍、成品保留與人類審查閘道。
安全審查清單
在允許編碼代理在玩具儲存庫之外運行之前，請使用此清單：
| 問題 | 應檢查的內容 |
|---|---|
| 隔離邊界是什麼？ | 專用工作區、程序限制、檔案系統隔離以及明確的提供者文件 |
| 代理可以讀取什麼？ | 預設僅限儲存庫存取，無主機家目錄，無關儲存庫 |
| 代理可以寫入什麼？ | 可寫入的來源路徑是明確的；敏感配置路徑需要額外審查 |
| 哪些命令自動執行？ | 允許測試和格式化命令；狀態變更命令需要核准 |
| 存在什麼網路存取？ | 預設拒絕或範圍限定出口；套件註冊表和文件網域是刻意的 |
| 套件安裝如何處理？ | 記錄鎖定檔案變更、註冊表主機和安裝腳本 |
| 存在哪些機密？ | 僅限任務範圍、短暫存在、最小權限憑證 |
| 日誌會怎樣？ | 命令、輸出、差異和成品在沙盒清除後仍然存在 |
| 清除如何執行？ | 背景程序、埠、令牌和臨時檔案已關閉或撤銷 |
| 誰批准合併或發佈？ | 人類審查者檢查程式碼、測試、安全敏感檔案與產生的成品 |
最重要的規則很簡單：不要將「代理請求了權限」與「系統執行了邊界」混為一談。模型可以幫助解釋它想做什麼。執行環境與政策層應決定它被允許做什麼。
常見問題
可以在沙盒中執行 Claude Code 嗎？
可以，只要你的設定將 Claude Code 風格的代理放在範圍限定的工作區內，並在其周圍執行檔案系統、Shell、網路、機密、日誌記錄與審查政策。不要認為僅靠本地權限提示就足以應對生產環境或敏感儲存庫。
容器是否足以實現編碼代理的隔離？
有時可以，但答案取決於你的威脅模型。容器對於可重複的建置與依賴項分離很有用，但安全敏感的工作負載應在將容器視為完整沙盒邊界之前，評估核心邊界、主機掛載、網路預設值、執行環境權限與提供者文件。
應該允許代理安裝套件嗎？
可以允許，但套件安裝應作為受控的供應鏈事件來處理。偏好使用註冊表允許清單或鏡像、鎖定檔案審查、安裝腳本記錄，以及對新依賴項或擷取並執行遠端程式碼的命令進行核准。
人類審查者在合併前應檢查什麼？
檢查最終差異、執行的命令、執行的測試、套件與鎖定檔案變更、觸及的 CI/部署檔案、產生的成品，以及任何被拒絕或需要核准的操作。對於安全敏感的儲存庫，將沙盒政策本身作為變更的一部分進行審查。
Novita Agent Sandbox 是否與 Claude Code 正式整合？
本文並未做出此聲明。Novita Agent Sandbox 為代理工作流程提供隔離的執行原始功能，而 Claude Code 與受管代理產品則有各自產品特定的介面與權限模型。在發佈可執行命令之前，請根據當前產品文件驗證確切的整合路徑。
