DEV Community

Cover image for Hồ sơ quyền Codex: Ví dụ config.toml cho các phiên chạy agent an toàn
Sebastian Petrus
Sebastian Petrus

Posted on Originally published at apidog.com

Hồ sơ quyền Codex: Ví dụ config.toml cho các phiên chạy agent an toàn

Hồ sơ quyền (permission profile) của Codex là những policy có tên trong config.toml, quyết định những gì các lệnh Codex chạy trên máy bạn được đọc, được ghi và được truy cập trên mạng. Bạn chọn một hồ sơ bằng default_permissions, khởi đầu từ một hồ sơ tích hợp (:read-only, :workspace hoặc :danger-full-access), rồi thêm các đường dẫn read, write và deny cùng danh sách domain được phép.

Dùng thử Apidog ngay hôm nay

Hướng dẫn này cung cấp các ví dụ config.toml sẵn sàng để copy cho những thiết lập phổ biến nhất, trong đó có một ví dụ cho công việc API, giúp coding agent của bạn chạy các bài test Apidog CLI trên chính các host API của bạn mà không cần mở internet.

Hồ sơ quyền của Codex là gì?

Hồ sơ quyền là một policy sandbox có thể tái sử dụng dành cho Codex. Nó kết hợp các quy tắc filesystem (lệnh được đọc, ghi hoặc không bao giờ được chạm vào những đường dẫn nào) với các quy tắc mạng (lệnh có được truy cập mạng hay không, và tới những domain nào). Codex thực thi hồ sơ bằng Seatbelt trên macOS, bubblewrap kèm seccomp trên Linux và WSL, và MXC trên Windows.

OpenAI đã giải thích thiết kế này trong bài Inside the Codex sandbox, xuất bản ngày 18 tháng 11 năm 2026. Thay vì chuyển công việc của bạn vào một container, Codex giới hạn các lệnh ngay trong môi trường hiện có của bạn, nhờ vậy các toolchain gốc vẫn chạy được.

Codex có sẵn ba hồ sơ tích hợp:

Hồ sơ Filesystem Mạng
:read-only Lệnh chỉ được đọc, không được ghi Tắt
:workspace Được ghi trong workspace root và thư mục tạm; .git, .agents, .codex, .aws vẫn chỉ đọc Tắt
:danger-full-access Không có giới hạn sandbox cục bộ Đầy đủ, trực tiếp

Tài liệu permissions vẫn gắn nhãn Beta cho tính năng này, nên hãy chuẩn bị tinh thần các key có thể thay đổi giữa các bản phát hành.

Bảng permissions nằm ở đâu trong config.toml

Các hồ sơ của bạn nằm trong ~/.codex/config.toml (hoặc ở lớp project hay lớp system). Có hai phần ở cấp cao nhất cần lưu ý:

  • default_permissions chỉ định hồ sơ mà Codex áp dụng mặc định. Nó phải khớp với một hồ sơ tích hợp hoặc một hồ sơ trong [permissions].
  • [permissions.<name>] định nghĩa một hồ sơ. Hãy đặt cho nó một description; mô tả này sẽ hiện trong picker /permissions.

Có một quy tắc khiến nhiều người vấp phải. Hồ sơ quyền không kết hợp được với các cài đặt sandbox cũ. Nếu sandbox_mode xuất hiện trong bất kỳ file config nào được nạp, hoặc bạn truyền --sandbox, Codex sẽ dùng cài đặt cũ và bỏ qua default_permissions. Hãy xóa sandbox_mode và [sandbox_workspace_write] trước khi chuyển sang.

Hồ sơ tuân theo mô hình thứ tự ưu tiên config thông thường. Các bảng được merge đệ quy, nên config của team có thể thêm một domain hay một đường dẫn vào hồ sơ của tổ chức mà không phải khai báo lại toàn bộ.

Quy tắc filesystem: read, write và deny

Mỗi mục filesystem ánh xạ một đường dẫn tới read, write hoặc deny. Đường dẫn cụ thể hơn sẽ thắng đường dẫn rộng hơn, và khi hai mục cùng nhắm vào một đường dẫn, deny thắng write, còn write thắng read.

Những dạng đường dẫn bạn sẽ dùng nhiều nhất:

  • :minimal: các đường dẫn nền tảng và runtime mà những công cụ phổ biến cần
  • :workspace_roots: các workspace root của phiên làm việc cùng bất kỳ root nào mà hồ sơ thêm vào
  • :root, :tmpdir, :slash_tmp, đường dẫn tuyệt đối và đường dẫn ~/

Hãy dùng extends để kế thừa các biện pháp bảo vệ tích hợp thay vì dựng lại chúng. Đây là một hồ sơ giữ nguyên các mặc định của :workspace và khóa chặt các secret:

default_permissions = "dev"

[permissions.dev]
description = "Workspace edits, secrets denied, no network."
extends = ":workspace"

[permissions.dev.filesystem]
"~/build-cache" = "write"

[permissions.dev.filesystem.":workspace_roots"]
".vscode" = "read"
"**/*.env" = "deny"
"secrets" = "deny"
Enter fullscreen mode Exit fullscreen mode

Các quy tắc trong :workspace_roots áp dụng cho mọi root, nên secrets nghĩa là thư mục secrets trong từng project root. Một hồ sơ có thể extend :read-only, :workspace hoặc một hồ sơ có tên khác. Nó không thể extend :danger-full-access.

Trên Linux, WSL và Windows gốc, một glob deny ** không giới hạn có thể cần glob_scan_max_depth (ít nhất là 1) trong [permissions.<name>.filesystem] để Codex có thể mở rộng nó trước khi sandbox khởi động.

Sơ đồ cách hồ sơ quyền của Codex lọc các đường dẫn filesystem và yêu cầu mạng trước khi một lệnh chạy

Quy tắc mạng: tắt, mở hoặc trong danh sách cho phép

Mạng có ba trạng thái, và hai cài đặt điều khiển chúng:

  1. Mạng tắt (enabled = false, mặc định của :workspace): lệnh không thể truy cập mạng.
  2. Mạng bật, proxy tắt: lệnh được truy cập trực tiếp, không giới hạn. Các quy tắc domain của bạn bị bỏ qua.
  3. Mạng bật, proxy bật: lưu lượng đi qua proxy mạng của Codex, proxy này thực thi các quy tắc domain của hồ sơ.

Trạng thái thứ hai chính là cái bẫy. Đặt permissions.<name>.network.enabled = true không khởi động proxy. Bạn còn cần thêm dòng này ở cấp cao nhất:

[features]
network_proxy = true
Enter fullscreen mode Exit fullscreen mode

Các pattern domain hỗ trợ host chính xác (api.example.com), *.example.com chỉ cho subdomain, **.example.com cho cả apex lẫn subdomain, và * là wildcard toàn cục chỉ dùng cho allow. Các mục deny ghi đè mục allow, và một proxy đang hoạt động mà không có mục allow nào sẽ chặn mọi thứ bên ngoài.

Khi proxy hoạt động, nó cũng chặn các đích mạng cục bộ và riêng tư theo mặc định. Để truy cập một service cục bộ, hãy thêm chính xác host đó vào danh sách cho phép, ví dụ "localhost" = "allow" hoặc "127.0.0.1" = "allow".

Một hồ sơ quyền Codex cho công việc API

Đây là hồ sơ chúng tôi đã thử nghiệm cho phát triển API. Nó chỉnh sửa code trong workspace, không bao giờ đọc file .env hay thư mục secrets, và chỉ có thể truy cập host API của bạn cùng Apidog:

default_permissions = "api-work"

[features]
network_proxy = true

[permissions.api-work]
description = "Workspace edits, no secrets, API hosts only."
extends = ":workspace"

[permissions.api-work.filesystem.":workspace_roots"]
"**/*.env" = "deny"
"secrets" = "deny"

[permissions.api-work.network]
enabled = true

[permissions.api-work.network.domains]
"api.your-company.com" = "allow"      # API đang được test
"staging-api.your-company.com" = "allow"
"**.apidog.com" = "allow"             # Apidog CLI và API của nó
Enter fullscreen mode Exit fullscreen mode

Hãy thay hai host đó bằng những host mà test của bạn gọi tới. Apidog CLI gửi các yêu cầu test từ máy bạn tới API đang được test, nên host đó phải nằm trong danh sách cho phép, chứ không chỉ host của Apidog. Nếu bạn test một server cục bộ, hãy thêm "localhost" = "allow".

Hãy cài package trước phiên làm việc, chứ không phải trong phiên. Lệnh npm install -g apidog-cli@latest cần registry.npmjs.org, domain mà hồ sơ này cố ý chặn.

Một điểm cần lưu ý từ lần chạy thử của chúng tôi: trên một máy Mac đang chạy ứng dụng proxy hoặc VPN ở chế độ DNS fake-IP, mọi host được cho phép đều phân giải thành địa chỉ 198.18.x.x. Cơ chế chặn local/private coi đó là địa chỉ riêng tư và chặn lại, Codex báo lỗi "local/private network addresses are blocked by the sandbox policy." Thêm allow_local_binding = true vào [permissions.api-work.network] đã khắc phục được, nhưng nó cũng mở ra các hostname trong danh sách cho phép vốn phân giải thành địa chỉ riêng tư, nên chỉ đặt khi bạn thực sự cần.

Kiểm tra hồ sơ với codex sandbox

Đừng tin một hồ sơ cho đến khi bạn tận mắt thấy nó chặn được thứ gì đó. Lệnh codex sandbox chạy bất kỳ lệnh nào dưới một hồ sơ có tên và coi thư mục hiện tại là một workspace root:

codex sandbox --permission-profile api-work -- cat README.md .env
Enter fullscreen mode Exit fullscreen mode

Với hồ sơ ở trên, lần chạy của chúng tôi in ra README rồi tới:

cat: .env: Operation not permitted
Enter fullscreen mode Exit fullscreen mode

Một lần ghi ra ngoài workspace cũng thất bại tương tự (Operation not permitted), trong khi một file mới bên trong workspace thì được tạo. Về mạng, hãy kiểm tra rằng proxy chặn một host mà bạn không liệt kê:

codex sandbox -P api-work -- curl -sI https://example.org
Enter fullscreen mode Exit fullscreen mode

Proxy trả về 403 Forbidden với x-proxy-error: blocked-by-allowlist, trong khi apidog.com trả về 200. Trên macOS, thêm --log-denials để in ra các lần Seatbelt từ chối sau khi lệnh kết thúc.

Bạn cũng có thể dùng codex sandbox để bọc các tiến trình mà Codex không tự sandbox. Bài viết của OpenAI lưu ý rằng các stdio MCP server trong config.toml chạy không có sandbox, và đưa ra ví dụ một hồ sơ memory-mcp với "~/mcp-data" = "write" và network.enabled = false bọc lệnh npx của server.

Chuyển hồ sơ giữa phiên với /permissions

Trong Codex CLI, gõ /permissions để mở picker. Khi đã có các hồ sơ có tên, nó sẽ liệt kê chúng kèm mô tả. Để chọn trực tiếp một hồ sơ:

/permissions api-work --approval-policy=on-request --reviewer=user
Enter fullscreen mode Exit fullscreen mode

Lệnh đó đặt hồ sơ cho phiên hiện tại và gửi các yêu cầu phê duyệt tới bạn. Hồ sơ và phê duyệt là hai cơ chế điều khiển tách biệt: hồ sơ quyết định một lệnh trong sandbox được chạm vào những gì, còn chính sách phê duyệt quyết định khi nào Codex hỏi trước khi bước ra ngoài phạm vi đó. Tài liệu tham khảo lệnh CLI liệt kê các lệnh phiên khác.

Để Codex test API của bạn với Apidog CLI

Khi api-work đang bật, Codex có thể chạy các bài test API thực sự mà không cần mở internet. Apidog CLI cung cấp cho agent của bạn các lệnh cho endpoint, test case và lượt chạy, với đầu ra JSON mà nó có thể đọc. Bạn thiết lập một lần ở ngoài sandbox:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install
Enter fullscreen mode Exit fullscreen mode

Sau đó đưa cho Codex một prompt:

Using Apidog CLI, create a test case in project <projectId> for
GET /orders/{id} on endpoint <endpointId> that asserts a 200 status and
a non-empty "items" array. Run it against environment <envId> and
summarize any failures.
Enter fullscreen mode Exit fullscreen mode

Codex đọc schema của payload, validate JSON và chạy test case:

apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog test-case run --project <projectId> --endpoint <endpointId> -e <envId> -r cli,json
Enter fullscreen mode Exit fullscreen mode

Trong lần test của chúng tôi, cả apidog auth status và apidog project list đều chạy bên trong sandbox api-work với chỉ **.apidog.com được cho phép. Token của bạn nằm trong ~/.apidog, hồ sơ này đọc được nhưng không sửa được. Để xem hướng dẫn đầy đủ, hãy đọc cách dùng Apidog CLI trong Codex, và đổi -r cli,json thành -r junit khi cùng lượt chạy đó chuyển vào một pipeline CI. Gói Free của Apidog hỗ trợ tối đa 4 người dùng.

Sơ đồ luồng Codex chạy Apidog CLI trong hồ sơ api-work, với proxy mạng cho phép host API và Apidog đồng thời chặn các domain khác

Những giới hạn cần biết trước khi tin tưởng một hồ sơ

Hồ sơ quyền thu hẹp phạm vi ảnh hưởng. Chúng không tự làm cho agent trở nên an toàn. Tài liệu và bài viết của OpenAI liệt kê những giới hạn sau:

  • Quyền đọc rộng vẫn bật với :workspace. Trình biên dịch cần SDK và config nằm ngoài repo, nên một file config ở nơi khác chứa API key có thể vẫn đọc được. Hãy deny rõ ràng ~/.ssh và các đường dẫn tương tự, hoặc dùng ":root" = "deny" cùng ":minimal" = "read".
  • Glob deny chỉ là một ảnh chụp. Trên Linux, WSL và Windows, các kết quả khớp được mở rộng khi mỗi tiến trình trong sandbox khởi động. Một file .env được tạo sau đó vẫn có thể bị một shell hay dev server chạy lâu đọc được.
  • Wildcard vẫn có thể rò rỉ qua DNS. Proxy chỉ phân giải một hostname sau khi nó được cho phép, nhưng các quy tắc wildcard quá rộng hoặc quyền truy cập các dịch vụ DNS vẫn có thể cho phép tuồn dữ liệu qua DNS.
  • Proxy chỉ bao phủ các lệnh trong sandbox. Web search, connector, MCP server, trình duyệt và lưu lượng tới model của chính Codex dùng các cơ chế điều khiển riêng.
  • Các thao tác ghi có thể tồn tại lâu hơn phiên. Ví dụ của OpenAI là một node_modules/prettier bị sửa đổi mà sau đó editor của bạn chạy khi lưu file, ở ngoài sandbox.

Nếu bạn từng dùng các cách vòng để vượt qua Codex sandbox, một hồ sơ tùy chỉnh hẹp thường là giải pháp gọn gàng hơn. Các team cần policy xuyên nhiều máy nên đọc Codex security cookbook và phần allowed_permission_profiles được quản lý.

Câu hỏi thường gặp

Hồ sơ quyền mặc định của Codex là gì?

Không có hồ sơ mặc định nào mà bạn nên dựa vào. Tài liệu khuyến nghị đặt default_permissions một cách rõ ràng để hành vi có thể đoán trước. Với hầu hết công việc coding, :workspace là nền tảng hợp lý: ghi được trong workspace root và thư mục tạm, mạng tắt.

Tại sao các quy tắc domain của tôi bị bỏ qua?

Thường là do thiếu features.network_proxy. Với network.enabled = true mà không có proxy, lệnh được truy cập mạng trực tiếp và không giới hạn. Cũng nên kiểm tra rằng không có config nào được nạp đặt sandbox_mode, vì nó vô hiệu hóa hồ sơ hoàn toàn.

Làm sao để Codex không đọc file .env?

Thêm "**/*.env" = "deny" vào [permissions.<name>.filesystem.":workspace_roots"]. Trên Linux, WSL và Windows, hãy đặt glob_scan_max_depth cho các pattern ** không giới hạn, và nhớ rằng các kết quả khớp mới không được thêm vào những tiến trình đang chạy.

Tôi có thể cho phép localhost trong hồ sơ quyền Codex không?

Được. Hãy thêm chính xác host đó vào danh sách cho phép, ví dụ "localhost" = "allow" hoặc "127.0.0.1" = "allow". Chỉ đặt allow_local_binding = true khi một hostname trong danh sách cho phép phân giải thành địa chỉ cục bộ hoặc riêng tư.

Hồ sơ quyền có sandbox MCP server không?

Không. Các stdio MCP server trong config.toml khởi động không có sandbox. Hãy bọc lệnh của server bằng codex sandbox --permission-profile <name> -- với một hồ sơ riêng.

Tôi có thể dùng hồ sơ cùng cờ --sandbox không?

Không. Truyền --sandbox hoặc đặt sandbox_mode khiến Codex dùng các cài đặt sandbox cũ thay vì default_permissions. Hãy chọn một hệ thống cho mỗi phiên.

Top comments (0)