Quyền
Quyền
Cấu hình các hồ sơ quyền Codex beta để truy cập hệ thống tệp và mạng
allowed_permission_profiles được quản lý là ngoại lệ: cài đặt này khiến Codex sử dụng
hồ sơ quyền. Hãy xóa các cài đặt cũ như
sandbox_mode và [sandbox_workspace_write] trước khi triển khai danh sách cho phép của
hồ sơ được quản lý. Khi triển khai cho doanh nghiệp có nhiều phiên bản, bạn có thể giữ yêu cầu
allowed_sandbox_modes được quản lý làm ràng buộc tương thích tạm thời
cho đến khi mọi máy khách đều chạy Codex 0.138.0 trở lên.
Hồ sơ quyền cho phép bạn áp dụng các ranh giới đặc quyền tối thiểu cho những lệnh cục bộ mà Codex chạy thay mặt bạn. Hồ sơ là một chính sách có tên, kết hợp các quy tắc hệ thống tệp (xác định lệnh có thể đọc hoặc ghi nội dung nào) với các quy tắc mạng (xác định lệnh có thể truy cập những đích nào).
Hãy dùng hồ sơ để cấp cho Codex vừa đủ quyền truy cập cho cuộc trò chuyện hiện tại mà không cấp quyền rộng đối với máy hoặc mạng của bạn. Ví dụ: hồ sơ chỉ đọc có thể cho phép Codex kiểm tra một dự án mà không chỉnh sửa, còn hồ sơ có quyền ghi có thể giới hạn việc chỉnh sửa trong các thư mục gốc không gian làm việc đã chọn.
Hồ sơ quyền cục bộ được hỗ trợ trên macOS, Linux, WSL và Windows gốc. Xem Phạm vi và cơ chế thực thi để biết chi tiết và lưu ý riêng cho từng nền tảng.
Đối với cài đặt mạng của Codex cloud, hãy xem Truy cập Internet.
Định nghĩa và chọn hồ sơ
Codex cung cấp ba hồ sơ quyền tích hợp sẵn:
:read-onlygiữ cho việc thực thi lệnh cục bộ ở chế độ chỉ đọc.:workspacecho phép ghi bên trong các thư mục gốc không gian làm việc đang hoạt động và thư mục tạm của hệ thống.:danger-full-accessloại bỏ các hạn chế sandbox cục bộ và chỉ nên được dùng khi bạn chủ ý cấp quyền truy cập rộng như vậy.
Tạo một hồ sơ có tên trong [permissions.<name>], sau đó đặt khóa cấp cao nhất
default_permissions thành tên hồ sơ đó hoặc một trong các hồ sơ tích hợp sẵn ở trên.
Trong ví dụ này, project-edit là tên hồ sơ do người dùng định nghĩa, không phải một giá trị
tích hợp sẵn.
Quản trị viên doanh nghiệp có thể định nghĩa hồ sơ và hạn chế những hồ sơ
mà người dùng được phép chọn thông qua requirements.toml được quản lý. Khi
allowed_permission_profiles xuất hiện, các hồ sơ bị bỏ qua sẽ bị từ chối,
bao gồm cả hồ sơ tích hợp sẵn bị bỏ qua và hồ sơ được thêm trong các phiên bản Codex tương lai. Xem
Kiểm soát các hồ sơ quyền khả dụng
để biết cấu hình được quản lý nên dùng.
Hồ sơ tùy chỉnh sử dụng hai khái niệm có liên quan:
[permissions.<name>.workspace_roots]thêm các thư mục cụ thể cần được xem là thư mục gốc không gian làm việc cho hồ sơ đó.[permissions.<name>.filesystem.":workspace_roots"]định nghĩa các quy tắc hệ thống tệp mà Codex áp dụng bên trong mọi thư mục gốc không gian làm việc có hiệu lực: các thư mục gốc không gian làm việc khi chạy của phiên hiện tại cộng với các thư mục gốc do hồ sơ định nghĩa ở trên.
Hồ sơ cũng sử dụng mô hình lớp cấu hình thông thường. Các lớp có độ ưu tiên cao hơn có thể thêm hoặc thay thế mục dưới cùng một tên hồ sơ mà không cần khai báo lại toàn bộ hồ sơ.
Ví dụ: cấu hình cấp tổ chức và cấu hình cấp người dùng có thể mở rộng độc lập cùng một hồ sơ:
# /etc/codex/config.toml
[permissions.server.workspace_roots]
"~/code/server" = true# ~/.codex/config.toml
[permissions.server.workspace_roots]
"~/code/mobile-app" = trueKhi server đang hoạt động, cả hai thư mục gốc không gian làm việc đều tham gia vào hồ sơ
có hiệu lực.
default_permissions = "project-edit"
[features]
network_proxy = true
[permissions.project-edit.workspace_roots]
"~/code/app" = true
"~/code/shared-lib" = true
[permissions.project-edit.filesystem]
":minimal" = "read"
[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
".devcontainer" = "read"
"**/*.env" = "deny"
[permissions.project-edit.network]
enabled = true
[permissions.project-edit.network.domains]
"api.openai.com" = "allow"
"objects.githubusercontent.com" = "allow"
"*.github.com" = "allow"
"tracking.example.com" = "deny"Hồ sơ này:
- Đọc các đường dẫn khi chạy tối thiểu mà những công cụ phổ biến dành cho nhà phát triển cần.
- Áp dụng cùng các quy tắc thư mục gốc không gian làm việc cho phiên hiện tại và các thư mục gốc do hồ sơ định nghĩa.
- Giữ các cài đặt liền kề IDE như
.devcontainer/ở chế độ chỉ đọc trong từng thư mục gốc. - Từ chối các tệp môi trường khớp với quy tắc glob.
- Chỉ cho phép truy cập mạng thông qua chính sách miền đã cấu hình.
Trong một hồ sơ đang hoạt động, các quy tắc từ chối hẹp hơn vẫn có hiệu lực ngay cả khi một
đường dẫn rộng hơn có thể đọc hoặc ghi. Ví dụ: hồ sơ có thể cho phép ghi vào các thư mục gốc không gian làm việc
nhưng vẫn đặt một đường dẫn .env khớp thành deny.
Mở rộng hồ sơ
Dùng extends khi một hồ sơ gần giống với hồ sơ tích hợp sẵn hoặc một hồ sơ có tên khác.
Nên mở rộng một hồ sơ tích hợp sẵn thay vì bắt đầu từ đầu để
các biện pháp bảo vệ cơ sở được kế thừa. Ví dụ: mở rộng :workspace sẽ giữ
thư mục .codex của thư mục gốc không gian làm việc ở chế độ chỉ đọc, trừ khi bạn ghi đè
rõ ràng. Chỉ đặt hồ sơ cha một lần, sau đó chỉ thêm hoặc ghi đè những quy tắc
khác biệt.
default_permissions = "project-edit"
[features]
network_proxy = true
[permissions.project-edit]
description = "Project editing with OpenAI API access."
extends = ":workspace"
[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"
[permissions.project-edit.network]
enabled = true
[permissions.project-edit.network.domains]
"api.openai.com" = "allow"Hồ sơ này bắt đầu từ :workspace, tiếp tục từ chối các tệp .env khớp và
cho phép yêu cầu đến api.openai.com. Một hồ sơ có thể mở rộng :read-only,
:workspace hoặc một hồ sơ có tên khác. Hồ sơ không thể mở rộng
:danger-full-access; Codex cũng từ chối hồ sơ cha không xác định và chu trình
kế thừa.
Đặc tả cấu hình
| Mục | Kiểu / giá trị | Mặc định | Chi tiết |
|---|---|---|---|
default_permissions |
Tên hồ sơ dạng chuỗi | Không có | Đặt tên cho hồ sơ quyền mà Codex áp dụng theo mặc định. Tên phải khớp với một hồ sơ trong [permissions] hoặc một hồ sơ tích hợp sẵn như :workspace. Hãy đặt rõ ràng để có hành vi có thể dự đoán; các yêu cầu được quản lý chỉ có thể bỏ qua mục này khi cả :workspace và :read-only đều được cho phép rõ ràng. Codex dùng các cài đặt sandbox cũ trừ khi allowed_permission_profiles được quản lý yêu cầu dùng hồ sơ quyền trong thiết lập này. |
[permissions.<name>] |
Bảng | Không có | Định nghĩa một hồ sơ có tên. default_permissions chọn một hồ sơ làm mặc định; các cài đặt hồ sơ quyền khác cũng sử dụng tên hồ sơ. |
permissions.<name>.description |
Chuỗi | Không có | Cung cấp mô tả dễ đọc cho hồ sơ. Hồ sơ không kế thừa mô tả của hồ sơ cha thông qua extends. |
permissions.<name>.extends |
Tên hồ sơ dạng chuỗi | Không có | Khởi tạo hồ sơ này từ một hồ sơ có tên khác hoặc hồ sơ tích hợp sẵn :read-only hay :workspace. Codex từ chối :danger-full-access, hồ sơ cha không xác định và chu trình kế thừa. |
[permissions.<name>.workspace_roots] |
Bảng | Không có | Thêm các thư mục gốc không gian làm việc do hồ sơ định nghĩa, nhận các quy tắc hệ thống tệp :workspace_roots cùng với các thư mục gốc không gian làm việc khi chạy của phiên hiện tại. |
permissions.<name>.workspace_roots."<path>" |
Boolean | false |
Thêm đường dẫn vào tập hợp thư mục gốc không gian làm việc của hồ sơ khi là true. Các mục được đặt thành false vẫn không hoạt động. |
[permissions.<name>.filesystem] |
Bảng | Không có | Ánh xạ đường dẫn hệ thống tệp sang giá trị truy cập hoặc bản đồ đường dẫn con có phạm vi. Bảng hệ thống tệp bị thiếu hoặc trống sẽ tiếp tục hạn chế quyền truy cập hệ thống tệp và phát cảnh báo khi khởi động. |
permissions.<name>.filesystem.glob_scan_max_depth |
Số | Không có | Giới hạn việc mở rộng glob từ chối đọc trên Linux, WSL và Windows gốc khi Codex chụp nhanh các kết quả khớp trước lúc khởi động sandbox. Giá trị lớn hơn có thể làm tăng khối lượng quét khi khởi động. Dùng giá trị ít nhất là 1 khi mẫu ** không giới hạn cần được mở rộng trước trong phạm vi hữu hạn. |
[permissions.<name>.filesystem]."<path>" |
read, write hoặc deny |
Không có | Cấp quyền truy cập trực tiếp cho một đường dẫn được hỗ trợ. deny từ chối quyền truy cập và được ưu tiên hơn các mục write hoặc read có cùng độ cụ thể. Codex từ chối các quy tắc ghi trực tiếp mà môi trường chạy hiện tại không thể thực thi. |
[permissions.<name>.filesystem."<path>"]."<subpath>" |
read, write hoặc deny |
Không có | Cấp quyền truy cập vào một đường dẫn con của <path>. Dùng . cho đường dẫn cơ sở. Các đường dẫn con khác phải là đường dẫn con tương đối và không được chứa thành phần . hoặc ... |
[permissions.<name>.network] |
Bảng | Không có | Cấu hình quyền truy cập mạng của lệnh và chính sách mà proxy mạng đang hoạt động sẽ thực thi. Bật features.network_proxy trừ khi các yêu cầu mạng do quản trị viên quản lý đã khởi động proxy. |
permissions.<name>.network.enabled |
Boolean | false |
Cho phép các lệnh trong hồ sơ truy cập mạng. Cài đặt này không khởi động proxy mạng; nếu không có proxy đang hoạt động, lệnh có thể kết nối trực tiếp mà không bị hạn chế theo miền. |
[permissions.<name>.network.domains] |
Bảng | Không có | Ánh xạ các mẫu máy chủ sang allow hoặc deny. Quy tắc chỉ áp dụng khi proxy mạng đang hoạt động. Proxy đang hoạt động sẽ chặn yêu cầu miền nếu không có mục allow, và mục từ chối được ưu tiên hơn mục cho phép. |
permissions.<name>.network.domains."<pattern>" |
allow hoặc deny |
Không có | Hỗ trợ máy chủ chính xác, *.example.com cho miền con, **.example.com cho miền gốc cùng các miền con và * làm ký tự đại diện toàn cục chỉ cho phép. Mẫu máy chủ được chuẩn hóa bằng cách xóa khoảng trắng đầu cuối, chuyển thành chữ thường, bỏ dấu chấm ở cuối và loại bỏ cổng hoặc dấu ngoặc đơn giản. |
[permissions.<name>.network.unix_sockets] |
Bảng | Không có | Ánh xạ các giá trị ghi đè danh sách cho phép socket Unix. Chỉ dùng cho các tích hợp cục bộ như Docker. |
permissions.<name>.network.unix_sockets."<path>" |
allow hoặc deny |
Không có | Thêm đường dẫn socket Unix tuyệt đối vào danh sách cho phép có hiệu lực bằng allow, hoặc từ chối bằng deny. Các mục bị từ chối sẽ bị loại khỏi danh sách cho phép có hiệu lực. |
permissions.<name>.network.proxy_url |
Chuỗi URL | http://127.0.0.1:3128 |
Trình lắng nghe proxy HTTP được dùng cho HTTP_PROXY, HTTPS_PROXY, các biến proxy websocket và các biến môi trường proxy công cụ liên quan. |
permissions.<name>.network.enable_socks5 |
Boolean | true |
Bật trình lắng nghe SOCKS5 được dùng cho ALL_PROXY và các biến proxy FTP. |
permissions.<name>.network.socks_url |
Chuỗi URL | http://127.0.0.1:8081 |
Địa chỉ trình lắng nghe SOCKS5. |
permissions.<name>.network.enable_socks5_udp |
Boolean | true |
Bật hỗ trợ UDP qua SOCKS5 khi trình lắng nghe SOCKS5 được bật. |
permissions.<name>.network.allow_upstream_proxy |
Boolean | true |
Cho phép proxy sandbox mạng tuân theo các cài đặt HTTP(S)_PROXY và ALL_PROXY thượng nguồn cho các yêu cầu gửi đi. |
permissions.<name>.network.allow_local_binding |
Boolean | false |
Vô hiệu hóa cơ chế bảo vệ mạng cục bộ/riêng tư khi là true. Khi là false, các giá trị cục bộ chính xác như localhost hoặc 127.0.0.1 phải được thêm rõ ràng vào danh sách cho phép, còn tên máy chủ phân giải thành IP cục bộ hoặc riêng tư vẫn bị chặn. |
permissions.<name>.network.dangerously_allow_non_loopback_proxy |
Boolean | false |
Cho phép trình lắng nghe proxy liên kết với các địa chỉ không phải loopback. Không đặt mục này cho hoạt động phát triển cục bộ thông thường. |
permissions.<name>.network.dangerously_allow_all_unix_sockets |
Boolean | false |
Bỏ qua danh sách cho phép socket Unix ở nơi hỗ trợ proxy socket Unix. Đây là một lối thoát cục bộ có phạm vi rộng. |
Quyền hệ thống tệp
Các mục hệ thống tệp sử dụng read, write hoặc deny:
| Quyền truy cập | Ý nghĩa |
|---|---|
read |
Cho phép lệnh đọc tệp và liệt kê thư mục bên dưới đường dẫn. Lệnh không thể tạo, sửa đổi, đổi tên hoặc xóa tệp tại đó. |
write |
Cho phép lệnh đọc và sửa đổi tệp bên dưới đường dẫn, bao gồm tạo, đổi tên và xóa tệp khi hệ điều hành cho phép. |
deny |
Từ chối cả quyền đọc lẫn ghi bên dưới đường dẫn. Dùng mục này để tách một đường dẫn con bị từ chối khỏi quyền cấp read hoặc write rộng hơn. |
Mục cụ thể hơn sẽ ghi đè mục rộng hơn. Khi hai mục nhắm đến cùng một
đường dẫn, deny được ưu tiên hơn write và write được ưu tiên
hơn read.
Thứ tự ưu tiên này cho phép hồ sơ mô tả một khu vực làm việc rộng trước, rồi tách các tệp hoặc thư mục cần giữ ở trạng thái không thể đọc:
[permissions.project-edit.filesystem]
":minimal" = "read"
[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
".devcontainer" = "read"
"**/*.env" = "deny"Trong ví dụ này, thư mục gốc không gian làm việc vẫn có thể ghi, .devcontainer/ vẫn
có thể đọc mà không trở thành có thể ghi, còn các tệp môi trường khớp vẫn
không khả dụng đối với những lệnh trong sandbox.
Một đường dẫn cụ thể hơn cũng có thể mở lại cây con hẹp hơn bên trong một quy tắc từ chối rộng hơn:
[permissions.project-edit.filesystem]
"~/Documents" = "deny"
"~/Documents/codex" = "write"Các dạng đường dẫn được hỗ trợ:
| Đường dẫn | Ý nghĩa | Đường dẫn con có phạm vi |
|---|---|---|
:root |
Thư mục gốc của hệ thống tệp | Chỉ . |
:minimal |
Các đường dẫn nền tảng và môi trường chạy mà những công cụ phổ biến cần | Chỉ . |
:workspace_roots |
Các thư mục gốc không gian làm việc của phiên hiện tại cùng mọi thư mục gốc do hồ sơ định nghĩa đã bật | Có |
:tmpdir |
Vị trí $TMPDIR, khi khả dụng |
Chỉ . |
:slash_tmp |
Thư mục /tmp, nếu tồn tại |
Chỉ . |
/absolute/path |
Một đường dẫn tuyệt đối của nền tảng, chẳng hạn /path trên macOS/Linux/WSL hoặc C:\path trên Windows gốc |
Có |
~/path |
Một đường dẫn bên dưới thư mục chính của người dùng hiện tại | Có |
Trên Windows gốc, các đường dẫn tương đối với thư mục chính cũng có thể dùng dấu gạch chéo ngược, chẳng hạn
~\work.
Chỉ dùng :root khi hồ sơ chủ ý cần phạm vi đọc rộng:
[permissions.audit.filesystem]
":root" = "read"Dùng các mục lồng nhau dưới :workspace_roots để giới hạn quyền truy cập vào các đường dẫn con
tương đối với thư mục gốc không gian làm việc:
[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write" # each workspace root
"docs" = "read" # each workspace-root docs directory
"generated" = "deny" # each workspace-root generated directoryĐường dẫn con lồng nhau phải nằm trong thư mục gốc không gian làm việc. Phép duyệt lên thư mục cha như
../other-repo sẽ bị từ chối.
Từ chối đọc bằng đường dẫn chính xác hoặc glob
Dùng deny cho các tệp hoặc cây con mà Codex không được đọc, ngay cả khi một quy tắc
hồ sơ rộng hơn cấp quyền truy cập ở gần đó. Đường dẫn chính xác phù hợp với các vị trí ổn định
như ~/.ssh. Mẫu glob phù hợp hơn khi hồ sơ cần bao phủ một
nhóm tệp nhạy cảm có vị trí chính xác khác nhau giữa các kho lưu trữ.
Khi một glob nằm dưới :workspace_roots, Codex diễn giải nó tương đối với từng
thư mục gốc không gian làm việc có hiệu lực. Ví dụ:
[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"Quy tắc này từ chối đọc các tệp .env khớp được tìm thấy bên dưới mỗi thư mục gốc không gian làm việc
khi chạy hoặc do hồ sơ định nghĩa. Hãy dùng quy tắc này khi bạn muốn giữ nguyên quyền ghi
thông thường trong không gian làm việc, đồng thời khiến tệp môi trường, bí mật được tạo hoặc các tệp tương tự
chứa thông tin xác thực không thể đọc được.
Mẫu glob deny được hỗ trợ làm quy tắc từ chối đọc. Các glob read hoặc write
kém khả chuyển hơn trên sandbox Linux, WSL và Windows gốc, vì vậy hãy ưu tiên đường dẫn
chính xác hoặc quy tắc cây con như "docs/**" = "read" khi có thể.
Trên Linux, WSL và Windows gốc, một mẫu từ chối đọc ** không giới hạn có thể cần
được mở rộng trước trong phạm vi hữu hạn trước khi sandbox khởi động. Hãy đặt glob_scan_max_depth khi
bạn dùng mẫu không giới hạn như "**/*.env" = "deny":
[permissions.project-edit.filesystem]
glob_scan_max_depth = 3
[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"glob_scan_max_depth phải ít nhất là 1. Giá trị cao hơn sẽ quét sâu hơn trước khi
sandbox khởi động, điều này có thể làm tăng công việc khi khởi động trên Linux, WSL và Windows gốc.
Nếu không muốn dùng mở rộng hữu hạn, hãy liệt kê rõ các độ sâu như
*.env, */*.env và */*/*.env.
Thêm các thư mục gốc không gian làm việc có thể tái sử dụng vào hồ sơ khi cần áp dụng cùng các quy tắc cho nhiều thư mục hơn thư mục gốc của phiên hiện tại:
[permissions.project-edit.workspace_roots]
"~/code/app" = true
"~/code/shared-lib" = trueKhi hồ sơ này hoạt động, Codex áp dụng các quy tắc :workspace_roots cho các
thư mục gốc không gian làm việc khi chạy của phiên hiện tại và từng thư mục gốc không gian làm việc
do hồ sơ định nghĩa đã bật.
Trên Windows gốc, đường dẫn ký tự ổ đĩa như D:\work và đường dẫn UNC như
\\server\share được hỗ trợ dưới dạng đường dẫn tuyệt đối.
Quyền mạng
Quyền truy cập mạng và lọc mạng là hai cài đặt riêng biệt. Đặt
permissions.<name>.network.enabled = true để cho phép lệnh truy cập mạng
và bật features.network_proxy để thực thi các quy tắc miền của hồ sơ:
[features]
network_proxy = true
[permissions.project-edit.network]
enabled = true
[permissions.project-edit.network.domains]
"example.com" = "allow" # exact host
"*.example.com" = "allow" # subdomains only
"**.example.com" = "allow" # apex and subdomains
"ads.example.com" = "deny" # deny wins over allowHành vi thu được phụ thuộc vào cả hai cài đặt:
- Tắt mạng: Lệnh không thể truy cập mạng, bất kể tính năng proxy có được bật hay không.
- Bật mạng, tắt proxy: Lệnh có quyền truy cập mạng trực tiếp, không hạn chế. Các quy tắc miền trong hồ sơ quyền không được thực thi.
- Bật mạng, bật proxy: Lệnh sử dụng proxy, nơi thực thi các quy tắc miền của hồ sơ. Nếu proxy đang hoạt động không có miền nào được phép, proxy sẽ chặn các đích bên ngoài.
Việc thêm [permissions.<name>.network.domains] hoặc đặt
permissions.<name>.network.enabled = true không bật
features.network_proxy. Thay vào đó, quản trị viên có thể bật
proxy bằng [experimental_network] trong requirements.toml. Xem
Cấu hình được quản lý.
Khi hoạt động, proxy sandbox mạng liên kết với các trình lắng nghe cục bộ theo mặc định:
[permissions.project-edit.network]
enabled = true
proxy_url = "http://127.0.0.1:3128"
enable_socks5 = true
socks_url = "http://127.0.0.1:8081"
enable_socks5_udp = trueGiữ nguyên giá trị mặc định của các cài đặt trình lắng nghe này, trừ khi bạn đang tích hợp với
một môi trường chạy cụ thể. Các khóa mạng dangerously_* là lối thoát dành cho
môi trường chuyên biệt và không nên được dùng cho hoạt động phát triển cục bộ thông thường.
Mạng cục bộ và riêng tư
Khi proxy mạng hoạt động, Codex áp dụng cơ chế bảo vệ mạng cục bộ/riêng tư theo mặc định để phòng chống liên kết lại DNS và việc vô tình truy cập các dịch vụ cục bộ. Để chủ ý cho phép một đích cục bộ dạng giá trị trực tiếp, hãy thêm chính xác máy chủ hoặc địa chỉ IP đó vào danh sách cho phép:
[permissions.project-edit.network.domains]
"localhost" = "allow"
"127.0.0.1" = "allow"Chỉ đặt allow_local_binding = true khi hồ sơ phải truy cập các
tên máy chủ trong danh sách cho phép nhưng được phân giải thành địa chỉ cục bộ hoặc riêng tư:
[permissions.project-edit.network]
enabled = true
allow_local_binding = true
[permissions.project-edit.network.domains]
"localhost" = "allow"Socket Unix
Proxy socket Unix là một lối thoát cục bộ dành cho các công cụ như Docker. Chỉ nên dùng khi thật sự cần thiết:
[permissions.project-edit.network.unix_sockets]
"/var/run/docker.sock" = "allow"
"/tmp/old.sock" = "deny"Dùng deny để từ chối một đường dẫn socket, kể cả mục cho phép được kế thừa. Các đường dẫn
socket bị từ chối sẽ bị loại khỏi danh sách cho phép có hiệu lực.
Khi bật socket Unix, hãy giữ các trình lắng nghe proxy liên kết với địa chỉ loopback.
Di chuyển từ các cài đặt sandbox cũ
Hồ sơ quyền thay thế tổ hợp cũ gồm sandbox_mode và
sandbox_workspace_write khi bạn muốn một hồ sơ tái sử dụng được mô tả cả hành vi
hệ thống tệp lẫn mạng. Hãy dùng hệ thống này hoặc hệ thống kia cho một phiên, không dùng
cả hai.
Các điểm khởi đầu nên dùng:
- Đối với quy trình chỉ đọc, hãy dùng hồ sơ
:read-onlytích hợp sẵn hoặc định nghĩa một hồ sơ tùy chỉnh chỉ có quyền đọc ở nơi cần thiết. - Để chỉnh sửa không gian làm việc, hãy dùng hồ sơ
:workspacetích hợp sẵn hoặc định nghĩa một hồ sơ tùy chỉnh ghi thông qua:workspace_rootsvà chỉ thêm các đường dẫn tạm hoặc bộ nhớ đệm bổ sung mà quy trình cần. - Để thực thi cục bộ không hạn chế, chỉ dùng
:danger-full-accesskhi bạn chủ ý muốn mô hình truy cập cục bộ rộng nhất.
Hồ sơ mô tả trạng thái cục bộ mặc định cho một phiên. Các yêu cầu do tổ chức quản lý vẫn có thể thêm những hạn chế mà cấu hình người dùng không được phép mở rộng. Xem Cấu hình được quản lý để biết các ràng buộc hệ thống tệp và mạng do quản trị viên thực thi.
Phạm vi và cơ chế thực thi
Hồ sơ quyền định nghĩa các ranh giới cho việc thực thi lệnh cục bộ trong sandbox. Hãy dùng chúng cùng chính sách phê duyệt và các cơ chế kiểm soát riêng cho tìm kiếm web, trình kết nối, máy chủ MCP, trình duyệt tích hợp, Computer Use và Codex cloud.
Những gì hồ sơ kiểm soát
- Thực thi lệnh cục bộ: Hồ sơ quyền chi phối các lệnh trong sandbox chạy trên máy của bạn. Trình kết nối, máy chủ MCP, bề mặt trình duyệt hoặc computer-use, cài đặt môi trường Codex cloud và các lần nâng quyền đã phê duyệt sử dụng cơ chế kiểm soát riêng.
- Ghi vào hệ thống tệp: Hồ sơ có quyền ghi có thể tạo ra thay đổi lâu dài. Hãy coi thao tác ghi vào tập lệnh, bước xây dựng, hook của trình quản lý gói, tệp khởi động shell và thư mục dùng chung là nhạy cảm, vì công cụ hoặc người dùng sau đó có thể thực thi các tệp đó bên ngoài ngữ cảnh sandbox ban đầu.
- Đích gửi đi: Các quy tắc miền mạng chỉ giới hạn lưu lượng lệnh trong sandbox có thể đi đến đâu khi proxy mạng đang hoạt động. Chúng không xác định một đích được phép có đáng tin cậy hay không, và các quy tắc cho phép bằng ký tự đại diện vẫn có phạm vi rộng.
- Dịch vụ cục bộ: Proxy mạng đang hoạt động mặc định chặn các đích mạng
cục bộ và riêng tư. Việc thêm
localhost, IP riêng tư hoặc socket Unix vào danh sách cho phép hay đặtallow_local_binding = truesẽ mở rõ ràng quyền truy cập vào các dịch vụ cục bộ.
Những gì proxy mạng không kiểm soát
Proxy mạng chỉ lọc lưu lượng từ các lệnh cục bộ chạy bên trong sandbox. Proxy không áp dụng danh sách cho phép miền của hồ sơ cho:
- Tìm kiếm web: Công cụ tìm kiếm được lưu trữ sử dụng cài đặt truy cập riêng. Dùng
web_searchvà, đối với máy khách được quản lý,allowed_web_search_modesđể kiểm soát công cụ này.tools.web_search.allowed_domainslọc kết quả tìm kiếm, không lọc quyền truy cập mạng của lệnh. - Ứng dụng và trình kết nối: Các công cụ dựa trên trình kết nối sử dụng kết nối phía dịch vụ, quyền không gian làm việc và cài đặt ứng dụng hoặc công cụ riêng.
- Máy chủ MCP: Máy chủ MCP cục bộ và từ xa sử dụng tiến trình hoặc
phương thức truyền tải riêng. Kiểm soát chúng bằng cấu hình
mcp_serversvà danh sách cho phép máy chủ được quản lý. - Trình duyệt và Computer Use: Hoạt động điều hướng trình duyệt và computer-use sử dụng cơ chế kiểm soát tính năng và phê duyệt riêng.
- Lưu lượng dịch vụ Codex: Các yêu cầu mô hình, xác thực và dịch vụ máy khách khác sử dụng cài đặt HTTP và proxy hệ thống riêng của máy khách.
- Codex cloud: Những tác vụ này sử dụng cài đặt truy cập Internet riêng của môi trường.
Để giới hạn các bề mặt này, hãy cấu hình trực tiếp từng khả năng. Danh sách cho phép mạng của lệnh không phải chính sách mạng toàn cục cho mọi hành động mà Codex có thể thực hiện.
Cách cơ chế thực thi hoạt động
- Trên macOS, Codex sử dụng hồ sơ sandbox Seatbelt. Nếu chính sách đã chọn không thể được sandbox của nền tảng thực thi, Codex sẽ từ chối chạy lệnh thay vì âm thầm chạy lệnh bên ngoài sandbox.
- Trên Linux và WSL, Codex sử dụng bubblewrap và seccomp, đồng thời có Landlock cho các đường dẫn dự phòng tương thích. Đường dẫn thực thi mạnh nhất phụ thuộc vào namespace người dùng và khả năng hỗ trợ của kernel; máy chủ vùng chứa bị hạn chế có thể buộc dùng các đường dẫn tương thích và những chính sách phân tách không được hỗ trợ sẽ bị từ chối.
- Trên Windows gốc, sandbox
elevatedmạnh nhất vì có thể dùng người dùng sandbox chuyên biệt với đặc quyền thấp hơn, ranh giới quyền hệ thống tệp và quy tắc tường lửa. Sandboxunelevatedlà phương án dự phòng có khả năng cô lập mạng yếu hơn và không thể thực thi mọi phần tách quyền đọc/ghi, vì vậy chính sách không được hỗ trợ sẽ bị từ chối. Hãy dùng WSL khi bạn cần mô hình sandbox của Linux.
Hướng dẫn vận hành
Chọn hồ sơ hẹp nhất vẫn cho phép tác vụ hoàn tất, đặc biệt khi bạn cấp quyền ghi hoặc quyền truy cập mạng gửi đi. Hãy căn chỉnh chính sách phê duyệt, cách xử lý bí mật và các quy tắc cho phép với mức truy cập đó.
Hồ sơ thông dụng
Chỉ đọc với danh sách cho phép mạng
default_permissions = "readonly-net"
[features]
network_proxy = true
[permissions.readonly-net.filesystem]
":minimal" = "read"
[permissions.readonly-net.filesystem.":workspace_roots"]
"." = "read"
[permissions.readonly-net.network]
enabled = true
[permissions.readonly-net.network.domains]
"api.openai.com" = "allow"Chỉ cho phép truy cập tệp trong không gian làm việc
Dưới đây là ví dụ về hồ sơ quyền giúp Codex có thể ghi vào các thư mục không gian làm việc của bạn, đồng thời từ chối đọc phần còn lại của hệ thống tệp (với một số ngoại lệ có giới hạn, do :minimal xác định).
default_permissions = "workspace-only"
[permissions.workspace-only]
# By extending the :workspace profile, you get Codex's safeguards to ensure
# subfolders such as .codex/ and .git/ within a workspace root are read-only
# while the rest of the folder is writable.
extends = ":workspace"
[permissions.workspace-only.filesystem]
# By default, deny read access to all files on disk.
":root" = "deny"
# Though in practice, a software agent needs to be able to read folders that
# contain common tools, such as `/usr/bin`, to get work done, so grant access
# to a "minimal" set of files and folders, as determined by Codex.
":minimal" = "read"
# By extending the :workspace profile, :tmpdir and :slash_tmp are "write" by
# default, though you can deny access to them altogether, if desired.
":tmpdir" = "deny"
":slash_tmp" = "deny"Ghi vào không gian làm việc mà không có mạng
default_permissions = "project-edit"
[permissions.project-edit.filesystem]
":minimal" = "read"
[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
[permissions.project-edit.network]
enabled = falseGhi vào không gian làm việc với quyền truy cập web công khai
default_permissions = "workspace-net"
[features]
network_proxy = true
[permissions.workspace-net.filesystem]
":minimal" = "read"
[permissions.workspace-net.filesystem.":workspace_roots"]
"." = "write"
[permissions.workspace-net.network]
enabled = true
[permissions.workspace-net.network.domains]
"*" = "allow"Chỉ dùng quy tắc cho phép toàn cục "*" khi bạn chủ ý cho phép truy cập
mạng công khai. Các quy tắc từ chối có thể thu hẹp một danh sách cho phép rộng.