Trang này được dịch từ tài liệu tiếng Anh. Lệnh, định danh và ví dụ giữ nguyên. Runtime 7.24.4 · SDK 2.6.7. Bản tiếng Anh

Chế độ Sandbox

Trạng thái: Đang hoạt động Phạm vi: trạng thái hiện tại Xem xét lần cuối: 2026-08-23 Chủ sở hữu: ax-code runtime

AX Code có một sandbox thực thi tích hợp, có thể hạn chế việc tác nhân AI làm trên hệ thống của bạn. Theo mặc định, AX Code khởi động ở truy cập đầy đủ với sandbox tắt, nên ghi hệ thống tệp và truy cập mạng không bị hạn chế. Hãy bật workspace-write hoặc read-only trước khi làm việc với kho không đáng tin hoặc chạy nhiệm vụ không giám sát.

Cảnh báo bảo mật: full-access không phải ranh giới bảo mật. Tác nhân có thể sửa tệp ngoài không gian làm việc, ghi .git/ và .ax-code/, chạy lệnh shell không hạn chế và truy cập mạng.

Bắt đầu nhanh

Bật tắt sandbox từ TUI:

• Gõ /sandbox trong lời nhắc, hoặc
• Nhấn Ctrl+P và tìm “sandbox”

Thanh trạng thái hiện trạng thái hiện tại:

• sandbox bật (xanh) — tác nhân bị giới hạn trong không gian làm việc
• sandbox tắt (đỏ) — không hạn chế

Thiết lập được giữ qua các phiên trong ax-code.json.

Những gì thay đổi

Cấu hình

Nguồn sự thật

Trang này tóm tắt hành vi hướng tới người dùng. Khi hành vi đổi, hãy đối chiếu tài liệu với:

• packages/ax-code/src/isolation/index.ts cho phân giải chế độ, đường dẫn được bảo vệ, kiểm tra mạng, kiểm tra ghi, kiểm tra bash và IsolationDeniedError.
• packages/ax-code/src/config/schema.ts cho dạng cấu hình, mặc định và mô tả.
• packages/ax-code/src/server/routes/isolation.ts cho hành vi bật tắt runtime và lưu bền.
• packages/ax-code/test/isolation/isolation.test.ts và packages/ax-code/test/tool/bash.test.ts cho hành vi thực thi kỳ vọng.

Hãy giữ các tuyên bố lặp trong README gốc ngắn và liên kết về đây để biết chi tiết.

Bật tắt từ TUI

Dùng /sandbox hoặc bảng lệnh (Ctrl+P → “Bật/tắt sandbox”). Thay đổi có hiệu lực ngay và được lưu vào ax-code.json của dự án bạn.

Cờ CLI

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

Biến môi trường

AX_CODE_ISOLATION_MODE=workspace-write ax-code

Tệp cấu hình

Trong ax-code.json:

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

Thứ tự ưu tiên

Cờ CLI > biến môi trường > tệp cấu hình > mặc định (full-access)

Khi một ghi đè CLI hoặc môi trường đang hoạt động, TUI báo chế độ đang có hiệu lực đó. Một lần bật tắt /sandbox có thể lưu tùy chọn dự án, nhưng ghi đè ưu tiên cao hơn vẫn hoạt động cho đến khi bị gỡ (thường là lúc khởi động lại).

Các chế độ cô lập

Đường dẫn được bảo vệ

Ở chế độ workspace-write, các đường dẫn này luôn được bảo vệ khỏi ghi:

• .git/ — ngăn hỏng trạng thái git do vô ý
• .ax-code/ — ngăn can thiệp cấu hình/plugin

Thêm đường dẫn được bảo vệ tùy chỉnh trong cấu hình:

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

Truy cập mạng

Mạng tắt theo mặc định ở các chế độ workspace-write và read-only. Các công cụ bị ảnh hưởng:

• webfetch — bị chặn
• websearch — bị chặn
• codesearch — bị chặn
• bash — các máy khách chỉ mạng (curl, wget, nc/ncat/netcat, telnet, ftp, tftp, scp, sftp, dig, nslookup, host) bị chặn

Giới hạn: Chặn mạng trong bash ở tầng ứng dụng và phủ các máy khách mạng chuyên dụng ở trên. Nó không chặn các công cụ lưỡng dụng cũng chạy được ngoại tuyến (git, npm/pnpm/yarn, pip, go, trình thông dịch ngôn ngữ như python/node), vì các lần gọi ngoại tuyến của chúng không phân biệt được tĩnh và chặn chúng sẽ làm gãy quy trình thường gặp. Cô lập mạng thật, triệt để cần điều khiển cấp hệ điều hành, mà sandbox này không cung cấp. Khi chạm một máy khách bị từ chối, tác nhân hỏi leo thang một lần.

Để cho phép mạng trong khi giữ hạn chế ghi:

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

Backend cô lập (ứng dụng so với hệ điều hành)

macOS: hồ sơ Seatbelt qua sandbox-exec (ghi giới hạn trong không gian làm việc/worktree, mạng bị từ chối khi network: false).
Linux: bubblewrap (bwrap) khi đã cài (--unshare-net khi mạng tắt, không gian làm việc được gắn bind ở chế độ RW).
Windows: hiện chỉ tầng ứng dụng.

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

Xem SECURITY.md để biết mô hình đe dọa.

Quyền và móc do kho kiểm soát

Tệp dự án không đáng tin theo mặc định. Quy tắc quyền trong ax-code.json, .ax-code/policy.json và định nghĩa tác nhân hoặc chế độ của dự án có thể siết truy cập bằng deny, nhưng các quyền allow/ask do kho kiểm soát bị bỏ qua. Lệnh dự án không thể bật mở rộng shell. .ax-code/hooks.json, .ax-code/plugin/ và plugin được cấu hình bởi dự án không được thực thi.

Cấu hình dự án không đáng tin cũng không thể chọn shell tùy chỉnh, LSP hoặc bộ định dạng thực thi được, gói nhà cung cấp hoặc điểm cuối API, biến môi trường thông tin xác thực nhà cung cấp, nguồn kỹ năng bên ngoài, hoặc đường dẫn chỉ dẫn ngoài worktree. Các đường dẫn chỉ dẫn tương đối an toàn và ghi đè tích hợp không thực thi được vẫn dùng được. Máy chủ MCP dùng một luồng phê duyệt có vân tay riêng, mô tả trong Tích hợp MCP.

Sau khi rà soát cấu hình do kho kiểm soát, người dùng có thể chọn tham gia bên ngoài kho cho tiến trình hiện tại:

AX_CODE_TRUST_PROJECT_CONFIG=1 ax-code

Công tắc chỉ-môi-trường ngăn một bản checkout tự tuyên bố mình đáng tin.

Cách thực thi hoạt động

Thực thi sandbox luôn ở tầng ứng dụng, được kiểm tra tại mỗi lần gọi công cụ. Khi backend là os hoặc auto và nền tảng hỗ trợ, bash còn được bọc thêm trong một sandbox nhân.

Khi một công cụ vi phạm cô lập, nó ném IsolationDeniedError kèm thông báo rõ giải thích phần nào bị chặn và vì sao.