Quyề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 những gì lệnh có thể đọc hoặc ghi với các quy tắc mạng xác định những đích mà lệnh có thể truy cập.

Hãy dùng hồ sơ để cấp cho Codex đủ quyền truy cập cho cuộc trò chuyện hiện tại mà không cấp quyền truy cập rộng vào máy hoặc mạng của bạn. Ví dụ: một hồ sơ chỉ đọc có thể cho phép Codex kiểm tra dự án mà không chỉnh sửa, trong khi hồ sơ có quyền ghi có thể giới hạn các chỉnh sửa trong những 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 thiết lập 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-only duy trì việc thực thi lệnh cục bộ ở chế độ chỉ đọc.
• :workspace cho 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-access loại bỏ các hạn chế của hộp cát cục bộ và chỉ nên được sử 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 giá trị tích hợp sẵn.

Quản trị viên doanh nghiệp có thể định nghĩa hồ sơ và giới hạn 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ỏ sót sẽ bị từ chối, bao gồm cả hồ sơ tích hợp sẵn bị bỏ sót 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ý được khuyến nghị.

Hồ sơ tùy chỉnh sử dụng hai khái niệm liên quan:

• [permissions.<name>.workspace_roots] thêm các thư mục cụ thể cần được tính 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 lúc 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 trong 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ùng một hồ sơ một cách độc lập:

# /etc/codex/config.toml
[permissions.server.workspace_roots]
"~/code/server" = true

# ~/.codex/config.toml
[permissions.server.workspace_roots]
"~/code/mobile-app" = true

Khi 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"

[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 lúc chạy tối thiểu mà những công cụ phát triển phổ biế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 thiết lập liền kề IDE như .devcontainer/ ở chế độ chỉ đọc trong mỗi thư mục gốc.
• Từ chối các tệp môi trường khớp bằng 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 có phạm vi 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 như 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ụ, việc 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. Hãy đặ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"

[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 với :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

Quyền hệ thống tệp

Các mục hệ thống tệp sử dụng read, write hoặc deny:

Các mục cụ thể hơn ghi đè mục rộng hơn. Khi hai mục nhắm tới 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 tiếp tục 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 nhưng không thể ghi, còn các tệp môi trường khớp vẫn không khả dụng với lệnh trong hộp cát.

Một đường dẫn cụ thể hơn cũng có thể mở lại một cây con hẹp hơn bên trong vùng 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ợ:

Trên Windows gố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 trong :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 bên trong thư mục gốc không gian làm việc tương ứng. 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 những 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 glob nằm trong :workspace_roots, Codex diễn giải glob đó 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 từng thư mục gốc không gian làm việc lúc chạy hoặc do hồ sơ định nghĩa. Hãy dùng quy tắc này khi bạn muốn duy trì quyền ghi không gian làm việc thông thường nhưng không cho phép đọc tệp môi trường, bí mật được tạo hoặc các tệp tương tự có chứa thông tin xác thực.

Mẫu glob deny được hỗ trợ dưới dạng quy tắc từ chối đọc. Glob read hoặc write kém linh hoạt hơn trên hộp cát Linux, WSL và Windows gốc, vì vậy khi có thể, hãy ưu tiên đường dẫn chính xác hoặc quy tắc cây con như "docs/**" = "read".

Trên Linux, WSL và Windows gốc, 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 hộp cát khởi động. Đặt glob_scan_max_depth khi bạn sử dụng một 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 có giá trị ít nhất là 1. Giá trị cao hơn sẽ quét sâu hơn trước khi hộp cát khởi động, điều này có thể làm tăng công việc khởi động trên Linux, WSL và Windows gốc. Nếu không muốn dùng cách mở rộng hữu hạn, hãy liệt kê các độ sâu rõ ràng 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 quy tắc cho nhiều nơi 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" = true

Khi 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 lúc 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 có 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

Đặt enabled = true để cho phép truy cập mạng cho hồ sơ đã chọn:

[permissions.project-edit.network]
enabled = true

Khi quyền truy cập mạng được bật, Codex mặc định sử dụng đầy đủ chức năng mạng. Hầu hết hồ sơ cũng nên định nghĩa quy tắc miền:

[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 allow

Proxy hộp cát mạng mặc định liên kết với các trình lắng nghe cục bộ:

[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 = true

Hãy giữ các thiết lập trình lắng nghe này ở giá trị mặc định trừ khi bạn đang tích hợp với một môi trường lúc 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 dùng cho hoạt động phát triển cục bộ thông thường.

Mạng cục bộ và mạng riêng tư

Codex mặc định áp dụng cơ chế bảo vệ mạng cục bộ/riêng tư để chống lại hành vi tái liên kết DNS và việc vô tình truy cập 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 tên 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 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ông cụ như Docker. Hãy sử dụng hạn chế:

[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, bao gồm 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 socket Unix được bật, 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 thiết lập hộp cát 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ơ có thể tái sử dụng mô tả cả hành vi hệ thống tệp lẫn mạng. Chỉ dùng một trong hai hệ thống cho mỗi phiên, không dùng cả hai.

Các điểm khởi đầu được đề xuất:

• Đối với quy trình chỉ đọc, hãy dùng hồ sơ tích hợp sẵn :read-only hoặc định nghĩa một hồ sơ tùy chỉnh chỉ có quyền đọc tại những nơi cần thiết.
• Để chỉnh sửa không gian làm việc, hãy dùng hồ sơ tích hợp sẵn :workspace hoặc định nghĩa một hồ sơ tùy chỉnh ghi thông qua :workspace_roots và chỉ thêm những đường dẫn tạm hoặc bộ nhớ đệm bổ sung mà quy trình cần.
• Đối với thực thi cục bộ không hạn chế, chỉ dùng :danger-full-access khi 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 của một phiên. Các yêu cầu do tổ chức quản lý vẫn có thể bổ sung 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 ranh giới cho việc thực thi lệnh cục bộ trong hộp cát. Hãy sử dụng hồ sơ cùng với chính sách phê duyệt và các biện pháp kiểm soát riêng cho 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 hộp cát 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, thiết lập môi trường Codex cloud và các lần nâng quyền đã được phê duyệt sử dụng biện pháp kiểm soát riêng.
• Ghi hệ thống tệp: Hồ sơ có quyền ghi có thể tạo ra các thay đổi lâu dài. Hãy coi việc ghi vào tập lệnh, bước 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à hành động nhạy cảm vì các công cụ hoặc người dùng sau đó có thể thực thi những tệp này bên ngoài ngữ cảnh hộp cát ban đầu.
• Đích đi ra ngoài: Quy tắc miền mạng giới hạn những nơi lưu lượng lệnh trong hộp cát có thể đến thông qua proxy mạng. Các quy tắc này không xác định liệu đích được cho phép có đáng tin cậy hay không, và 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ộ: Đích mạng cục bộ và riêng tư mặc định bị chặn. Việc thêm localhost, IP riêng tư, socket Unix vào danh sách cho phép hoặc đặt allow_local_binding = true sẽ mở rõ ràng quyền truy cập vào dịch vụ cục bộ.

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

• Trên macOS, Codex sử dụng hồ sơ hộp cát Seatbelt. Nếu chính sách đã chọn không thể được hộp cát 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 ngoài hộp cát.
• Trên Linux và WSL, Codex sử dụng bubblewrap và seccomp, với Landlock khả dụng cho các đường dẫn dự phòng tương thích. Cơ chế thực thi mạnh nhất phụ thuộc vào không gian tên người dùng và khả năng hỗ trợ của kernel; máy chủ container bị hạn chế có thể buộc sử dụng đường dẫn tương thích, còn các chính sách phân tách không được hỗ trợ sẽ bị từ chối.
• Trên Windows gốc, hộp cát elevated mạnh nhất vì có thể sử dụng người dùng hộp cát 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. Hộp cát unelevated là 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 các 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 hộp cát Linux.

Hướng dẫn vận hành

Chọn hồ sơ có phạm vi hẹp nhất nhưng vẫn cho phép hoàn thành tác vụ, đặc biệt khi bạn cấp quyền ghi hoặc truy cập mạng đi ra ngoài. Hãy bảo đảm chính sách phê duyệt, cách xử lý bí mật và quy tắc cho phép phù hợp với cấp độ truy cập đó.

Các hồ sơ phổ biến

Chỉ đọc với danh sách mạng được phép

default_permissions = "readonly-net"

[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

Sau đây là ví dụ về một hồ sơ quyền cho phép Codex 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ệ hạn chế 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 nhưng 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 = false

Ghi vào không gian làm việc với quyền truy cập web công khai

default_permissions = "workspace-net"

[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. Quy tắc từ chối có thể thu hẹp một danh sách cho phép rộng.