Cấu hình chính sách sandbox

Việc một lượt chạy agent có được sandbox hay không được quyết định trên máy chủ, lúc khởi động (--sandbox). Nút gạt Bật sandboxing và hộp chọn Backend trong Cài đặt → Máy chủ → Chẩn đoán & quyền riêng tư là những tùy chọn lưu trên thiết bị của bạn. Phần dò host của thẻ Sandbox cho biết máy chủ có thể bọc được những gì.

Có hai điều khiển tác động tới một lượt chạy và hướng dẫn này bao quát cả hai: các quy tắc hành động trong Cài đặt → Không gian làm việc → Quyền của agent, vốn quyết định agent được push, mở hay truy cập những gì, và cờ --sandbox của chính máy chủ.

Điều gì ràng buộc một lượt chạy agent

Sáu thứ ràng buộc một agent. Thứ nhất là sandbox hệ điều hành và đây là thứ có điều kiện — năm thứ còn lại đúng trên mọi máy chủ.

Ranh giới	Nó làm gì
Sandbox hệ điều hành	Seatbelt trên macOS, bubblewrap trên Linux và WSL2. Bọc CLI Claude Code, các adapter ACP và công cụ `bash` của harness. Không có trên Windows và trên Linux thiếu `bwrap` và `socat`
Cây làm việc riêng của nó	Mỗi cuộc hội thoại nhận một bản checkout copy-on-write. Bản checkout gốc được đưa vào lượt chạy như một đường dẫn từ chối ghi và chính sandbox là thứ thực thi điều đó
Thông tin xác thực qua broker	Broker thông tin xác thực tạo mới một môi trường theo từng lượt chạy rồi thu hồi nó khi lượt chạy kết thúc. Token GitHub trong đó có thể đọc nhưng không thể push: một lần push đi qua Control Center, nơi hỏi quy tắc push trước
Rào chắn hành động	Mọi công cụ thay đổi trạng thái đều khai báo các lớp hiệu ứng của nó và bộ gác phân giải chúng trước khi lệnh gọi chạy. Một `prompt` không có người phê duyệt nào kết nối sẽ bị từ chối
Làm sạch môi trường	ACP và công cụ `bash` của harness nhận một môi trường đã lọc. Claude Code qua `NoSandboxAdapter` kế thừa môi trường của máy chủ
Bề mặt công cụ của chế độ	Chế độ chỉ đọc loại bỏ hẳn các công cụ thay đổi cây làm việc và ghim động từ đầu ra của chính chế độ để nó vẫn có thể bàn giao

Ba thứ vẫn yếu hơn vẻ ngoài của chúng:

Chỉ harness tích hợp mới thực thi cổng công cụ, các hợp đồng hoàn thành và những quy tắc cấu trúc của chế độ. Adapter Claude Code thì không. Riêng Claude Code được khởi chạy với --dangerously-skip-permissions, bởi một claude -p phi tương tác nếu không thì sẽ chặn mãi mãi ở prompt của chính nó — nên các lệnh gọi read, write và edit của Claude không được Control Center nhìn thấy cũng không bị đặt cổng, còn các lệnh bash của nó chỉ được một hook đọc dòng lệnh kiểm tra. Ở nơi sandbox bật, nó chính là ranh giới bao quanh những lệnh gọi đó.
Các công cụ tệp in-process của harness (read, write, edit, apply patch, search, find, search_files) chạy bên trong tiến trình máy chủ, nên không profile sandbox nào ràng buộc chúng. Chỉ công cụ bash đi qua bộ chạy lệnh đã được sandbox. Những công cụ đó bị ràng buộc bởi giới hạn đường dẫn của chính chúng cùng với rào chắn hành động.
Trên một máy chủ không có backend, hàng đầu tiên hoàn toàn không áp dụng. ACP và công cụ bash của harness quay về việc làm sạch môi trường cùng chính sách lệnh; Claude Code kế thừa môi trường của máy chủ qua NoSandboxAdapter. Máy chủ nói rõ điều đó trong log khởi động. Hãy kiểm tra máy của bạn ở bên dưới.

Quyết định agent được push những gì

Không có nút gạt theo từng agent cho git push, GitHub, phiếu hay mạng. Mỗi thứ là một quy tắc hành động:

Quy tắc	Mặc định tích hợp	Bao gồm những gì
Push lên remote	Hỏi trước	Mọi `git push` lên GitHub, bất kể adapter nào
Mở một pull request	Hỏi trước	`gh pr create` và các công cụ pull request
Xuất bản review hoặc merge	Hỏi trước	`gh pr merge`, `gh pr review`, `gh pr comment`, `gh pr close`
Ghi vào tracker bên ngoài	Hỏi trước	Việc ghi phiếu qua các công cụ của Control Center và `gh issue`
Truy cập mạng	Cho phép	Sandbox có mạng hay không, và các công cụ web của harness

Vào Cài đặt → Không gian làm việc → Quyền của agent
Chọn phạm vi — Không gian làm việc, Agent hoặc Space — rồi trên hàng của quy tắc, chọn Cho phép, Hỏi trước hoặc Từ chối

Các quy tắc push giới hạn theo nhánh, như một quy tắc từ chối push lên main, cũng được áp dụng: xem Rào chắn.

Điểm kiểm tra: yêu cầu agent push một nhánh. Với Hỏi trước bạn nhận được một yêu cầu phê duyệt nêu kho mã và các ref; với Từ chối, git in ra ! [remote rejected] <ref> (Control Center policy: …).

Mỗi quy tắc tác động tới lượt chạy thế nào:

Push được thực thi bằng thứ lượt chạy nắm giữ. Token GitHub của nó là một token cài đặt GitHub App chỉ đọc, có thể đọc nội dung và làm việc với pull request. Cấu hình git của nó gửi mọi lần push lên GitHub tới một cổng loopback trên cc_server, nơi hỏi quy tắc và chỉ khi đó mới chuyển tiếp lần push bằng một token ghi mà agent không bao giờ thấy. Cổng chỉ chuyển tiếp tới kho mã của chính worktree hoặc tới một kho mã GitHub được liên kết với không gian làm việc. Điều này đúng với mọi adapter.
Pull request và issue từ shell được nhận ra qua dòng lệnh, trong công cụ bash của harness và, qua một hook, trong công cụ Bash của Claude Code. Một agent che giấu lệnh (một script, eval, một lời gọi API trực tiếp) sẽ lọt qua bước kiểm tra này, nhưng không lọt qua cổng push.
Khóa phiếu không bao giờ được đặt vào sandbox. Agent ghi phiếu qua các công cụ MCP của Control Center, vốn hỏi quy tắc.
Mạng được phân giải một lần, khi lượt chạy bắt đầu. Từ chối tắt mạng của sandbox; Cho phép và Hỏi trước giữ nó bật, và với Hỏi trước các công cụ web_fetch và web_search của harness vẫn hỏi ở mỗi lệnh gọi. Khi mạng bật, GitHub luôn nằm trong danh sách cho phép egress.

Khi chưa cấu hình GitHub App, lượt chạy nhận personal access token dự phòng, thứ không thể thu hẹp thành chỉ đọc. git push vẫn đi qua cổng và quy tắc, nhưng mã dùng trực tiếp token có thể push vòng qua nó. Hãy cấu hình GitHub App để quy tắc có hiệu lực ràng buộc.

Thông tin xác thực GitHub của lượt chạy luôn chỉ thuộc về broker — một token cài đặt GitHub App giới hạn theo kho mã, hoặc PAT dự phòng — chứ không bao giờ là token đã lưu của chính thành viên yêu cầu. PAT của máy chủ bị giữ lại khỏi một lượt chạy hành động thay một thành viên không phải chủ sở hữu và chưa kết nối GitHub.

Kiểm tra xem các lượt chạy agent của bạn có được sandbox không

Hai thứ quyết định điều đó, cả hai đều trên máy chủ: máy chủ có cung cấp backend hay không và --sandbox có bật hay không. Hãy kiểm tra theo đúng thứ tự đó.

Vào Cài đặt → Máy chủ → Chẩn đoán & quyền riêng tư
Đọc thẻ Sandbox. Mục Host là cỗ máy mà cc_server chạy trên đó, không phải cỗ máy bạn đang nhìn. Trường Backend liệt kê Sandbox gốc (Seatbelt trên macOS, bubblewrap trên Linux và WSL2) hoặc Không cô lập. Mục Đang áp dụng là tùy chọn của thiết bị này, không phải lớp bọc mà máy chủ thực sự dùng.
Đọc log khởi động của máy chủ. Nó in đúng một trong ba dòng:
- agent sandbox ON cùng ghi chú backend — các lượt chạy được bọc
- no OS-native agent sandbox on this host cùng một gợi ý cài đặt nếu có — các lượt chạy không được bọc
- agent sandbox DISABLED by --sandbox off — một sự chọn không dùng có chủ đích

GET /healthz không báo cáo trạng thái sandbox, nên log khởi động chính là cách kiểm tra.

Để tắt sandbox một cách có chủ đích — một máy chủ nơi profile hành xử sai chính là lý do tính năng này tồn tại — hãy khởi động máy chủ với --sandbox off, hoặc đặt CC_SERVER_SANDBOX=off. Mặc định là on và on nghĩa là “dùng backend nếu máy chủ có một cái”, chứ không bao giờ là “bắt buộc phải có một cái”.

Hai tình huống không bao giờ được bọc bằng sandbox gốc. Trên Windows, phép dò native luôn báo không khả dụng và không có gì để cài — việc điều phối agent dùng none. Backend microvm là riêng biệt (terminal tương tác và rig) và được đặt cổng dò theo runtime của chính nó. Trên Linux và WSL2, cả bwrap và socat đều phải có trên PATH; thiếu chúng thì phép dò báo không khả dụng và nêu tên các gói còn thiếu.

Trên Linux/WSL2 có cài bubblewrap, các mẫu glob tệp bí mật của chính sách chuẩn không thể được thực thi với những tệp mà agent tạo về sau. Một lượt chạy native như vậy giờ thất bại thay vì âm thầm bỏ qua các quy tắc. Vì vậy một phép dò khởi động thành công không bảo đảm rằng một lần điều phối trên Linux có thể bắt đầu. --sandbox off là một sự chọn không dùng không-giới-hạn có chủ đích, không phải một ranh giới bảo mật thay thế.

Biết điều một chế độ vốn đã cấm

Chế độ được lưu theo từng space và được đưa vào bộ giải quyết rào chắn với vai trò lớp preset chế độ. Ba trong bốn chế độ là chỉ đọc và một chế độ chỉ đọc từ chối thẳng mười một lớp hiệu ứng:

Chế độ	Cây làm việc	Bị preset từ chối
Agent (`chat`)	Có thể ghi	Không gì cả — các mặc định tích hợp được áp dụng
Kế hoạch	Chỉ đọc	Xóa một tệp, ghi bên ngoài cây làm việc, tạo commit, push, mở một PR, xuất bản hoặc merge, ghi vào tracker bên ngoài, cài một gói, chạy một tiến trình, thay đổi cấu trúc không gian làm việc, khởi động hoặc điều khiển một enclosure
Rà soát	Chỉ đọc	Cùng mười một lớp đó. Người dùng không thể tự chọn — trình soạn chỉ đưa ra Agent, Kế hoạch và Điều phối
Điều phối	Chỉ đọc	Cùng mười một lớp đó

Truy cập mạng và truy cập secret cố tình không bị một chế độ chỉ đọc từ chối: nghiên cứu chính là ý nghĩa của một chế độ như vậy.

Yêu cầu phê duyệt trước khi một hành động chạy

Phê duyệt là một quyết định của rào chắn, không phải một cài đặt sandbox.

Vào Cài đặt → Không gian làm việc → Quyền của agent
Đặt lớp hành động thành Hỏi trước ở phạm vi không gian làm việc, agent hoặc space

Một quyết định Hỏi trước ngắt lượt chạy và hỏi bạn. Khi không có người phê duyệt nào kết nối, nó đóng khi lỗi và hành động bị từ chối. Xem Cấu hình rào chắn để biết đầy đủ thứ tự phân giải.

Xử lý sự cố

Một agent không thể push mà tôi chưa từng từ chối

Hãy đọc những gì git in ra. Control Center policy: … nghĩa là một quy tắc đã từ chối lần push hoặc một Hỏi trước không được trả lời. … is not linked to this workspace nghĩa là lần push nhắm tới một kho mã không phải của chính worktree và cũng không được liên kết với không gian làm việc. Control Center has no GitHub credential that can push … nghĩa là GitHub App chưa được cài trên kho mã đó và không có thông tin xác thực dự phòng nào push được: hãy cài App lên kho mã đó hoặc kết nối GitHub.

Thẻ Sandbox báo không có sandbox gốc

Thì các lượt chạy agent trên máy chủ đó không được Seatbelt hay bubblewrap bọc, và những ranh giới còn lại là tất cả những gì bạn có. Trên Linux và WSL2, hãy cài cả hai công cụ còn thiếu — sudo apt-get install bubblewrap socat — rồi khởi động lại máy chủ; log khởi động sau đó phải cho biết sandbox đang bật. Trên Windows không có backend gốc nào để cài, nên thay vào đó hãy siết chặt rào chắn: xem Cấu hình rào chắn.

Một agent với tới được một tệp bên ngoài cây làm việc của nó

Công cụ nào với tới nó sẽ quyết định liệu điều này có nằm trong dự kiến hay không.

Các công cụ tệp in-process của harness (read, write, edit, apply patch, search, find, search_files) chạy trong tiến trình máy chủ, nên không profile sandbox nào áp dụng cho chúng — ràng buộc của chúng là giới hạn đường dẫn của chính chúng cùng với rào chắn. Một lệnh bash hoặc CLI Claude Code thì có được bọc ở nơi tồn tại backend, và các bản checkout đã đăng ký của bạn nằm trong nhóm từ chối ghi bên trong lớp bọc đó ở mọi chế độ, kể cả những cách viết đã phân giải symlink của chúng (trên macOS, một đường dẫn đi qua /tmp hoặc /var/folders được phân giải dưới /private và cả hai cách viết giờ đều bị từ chối). Trên một máy chủ không có backend thì không điều nào trong số đó áp dụng. Dù thế nào, rào chắn vẫn có thể từ chối thẳng Ghi bên ngoài cây làm việc.