Để chạy một Codex sandbox MCP server, hãy định nghĩa một permission profile trong ~/.codex/config.toml, sau đó trỏ command của server tới codex sandbox --permission-profile <name> -- theo sau là lệnh gốc. Codex không sandbox các stdio MCP server theo mặc định, nên nếu không có lớp bọc đó, một server chạy bằng npx sẽ chạy với toàn bộ quyền người dùng của bạn.
Bài viết kỹ thuật của OpenAI Inside the Codex sandbox, xuất bản ngày 18 tháng 11 năm 2026, nói rõ điều này: Codex không thể đoán chắc chắn một server cần những file hay dịch vụ mạng nào, nên nó để nguyên lệnh khởi chạy của server. Mọi MCP server bạn thêm bằng npx -y đều có thể đọc thư mục home của bạn, ghi ở bất cứ đâu bạn ghi được và gọi bất kỳ host nào trên internet.
Dưới đây bạn sẽ tạo một profile cho Apidog MCP Server, khóa nó vào một file OpenAPI cục bộ với mạng bị tắt, chứng minh profile hoạt động với codex sandbox, rồi giao phần việc thường nhật cho coding agent của bạn thông qua Apidog CLI.
Tại sao Codex để các stdio MCP server không được sandbox
Một stdio MCP server là một chương trình cục bộ mà Codex khởi chạy và giao tiếp qua standard input và output. Codex sandbox các lệnh shell mà model của nó chạy, nhưng không sandbox lệnh khởi chạy MCP server, bởi nó không thể biết server đó cần những file hay host nào. Server thừa hưởng toàn bộ quyền người dùng của bạn.
Các lệnh mà model chạy sẽ nhận profile mặc định :workspace: chỉ ghi trong workspace, .git và .codex là chỉ đọc, đọc rộng, không có mạng. Một MCP server trong [mcp_servers] không nhận được bất kỳ điều nào trong số đó.
Khoảng trống này quan trọng vì MCP server là mã bên thứ ba mà bạn tải về ngay lúc khởi chạy. Một cấu hình điển hình trông như sau:
[mcp_servers.memory]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-memory@1.0.0"]
npx -y tải package và chạy nó mà không hỏi gì. Nếu package đó bị xâm phạm, nó có thể đọc các file .env và SSH key của bạn rồi gửi chúng đi bất cứ đâu. Hướng dẫn của chúng tôi về MCP security policies đề cập tới mô hình mối đe dọa rộng hơn; bài này khắc phục đúng một lỗ hổng trong thiết lập Codex của bạn.
Cách một Codex permission profile hoạt động
Permission profile là một tập hợp các quy tắc hệ thống file và mạng có tên, nằm dưới [permissions] trong config.toml. Bài viết của OpenAI và tài liệu Codex permissions mô tả ba mức hệ thống file:
| Giá trị | Hiệu lực |
|---|---|
read |
Quyền chỉ đọc |
write |
Quyền đọc và ghi |
deny |
Không có quyền truy cập nào |
Ba khóa làm hầu hết công việc:
-
":root" = "read"cấp quyền đọc rộng, thứ mà Node.js và npm cần để nạp các file của chính chúng. - Một đường dẫn như
"~/.npm" = "write"chỉ cấp quyền ghi cho thư mục đó. - Một bảng
":workspace_roots"áp dụng các quy tắc tương đối với từng workspace root."**/*.env" = "deny"chặn mọi file.envbên dưới nó.
Mạng có ba chế độ: tắt, định tuyến qua proxy của Codex với danh sách domain được cho phép, hoặc truy cập đầy đủ.
Codex CLI mã nguồn mở thực thi các quy tắc này bằng chính hệ điều hành: Seatbelt trên macOS, bubblewrap kết hợp seccomp trên Linux và, trên các thiết bị Windows tương thích, MXC của Microsoft. Các tiến trình con thừa hưởng giới hạn, nên bất cứ thứ gì server sinh ra vẫn nằm gọn trong cùng chiếc hộp đó.
Bước 1: Chọn chế độ an toàn nhất cho Apidog MCP Server
Apidog MCP Server (apidog-mcp-server trên npm, phiên bản hiện tại là 0.0.18) chạy ở hai chế độ:
-
Chế độ Project, với
--project-id=<id>và mộtAPIDOG_ACCESS_TOKEN, kéo tài liệu API của bạn từ một dự án Apidog qua mạng. -
Chế độ OAS, với
--oas=<url-or-path>, đọc trực tiếp một file Swagger hoặc OpenAPI.
Chế độ OAS với một file cục bộ không cần mạng chút nào. Đó là profile mạnh nhất bạn có thể viết, nên nó là ví dụ chính ở đây. Apidog CLI giữ spec luôn mới từ bên ngoài sandbox (Bước 5).
Chúng tôi đã đọc package 0.0.18 để tìm hiểu server ghi những gì: nó lưu cache dữ liệu trong ~/.apidog-mcp-server (hoặc thư mục trong APIDOG_DATA_LOCATION), và ở chế độ project nó gọi https://api.apidog.com trừ khi bạn truyền --apidog-api-base-url.
Bước 2: Định nghĩa permission profile
Thêm đoạn này vào ~/.codex/config.toml:
[permissions.apidog-mcp.filesystem]
# Broad reads so Node.js and npm can load their own files.
":root" = "read"
"~/.npm" = "write"
"~/.apidog-mcp-server" = "write"
[permissions.apidog-mcp.filesystem.":workspace_roots"]
"**/*.env" = "deny"
[permissions.apidog-mcp.network]
enabled = false
Server có thể đọc spec và ghi vào hai thư mục cache. Nó không thể mở bất kỳ file .env nào trong workspace, và nó không có mạng.
Bước 3: Bọc lệnh khởi chạy server trong codex sandbox
Giờ hãy thay lệnh khởi chạy npx đơn thuần bằng codex sandbox. Cờ -C đặt thư mục làm việc, đây cũng chính là workspace root mà quy tắc .env áp dụng:
[mcp_servers.pets-api-docs]
command = "codex"
args = [
"sandbox",
"--permission-profile", "apidog-mcp",
"-C", "/Users/you/code/pets-api",
"--",
"npx", "--offline",
"apidog-mcp-server@0.0.18",
"--oas=/Users/you/code/pets-api/openapi.json"
]
Có ba chi tiết quan trọng:
-
Ghim phiên bản.
@0.0.18nghĩa là một bản phát hành mới không thể tráo mã dưới chân bạn. -
Dùng
npx --offline. Khi mạng đã tắt,npxphải tìm thấy package trong cache. -
Dùng đường dẫn tuyệt đối. Codex truyền
argsthẳng qua không qua shell, nên~sẽ không được mở rộng.
README của Apidog gợi ý đặt tên server theo API mà nó tài liệu hóa, ví dụ “Pets API Documentation”, để model biết khi nào nên dùng nó.
Bước 4: Nạp trước package vào cache và chứng minh profile hoạt động
Sandbox có thể ghi vào thư mục cache nhưng không thể tạo nó, và nó không thể tải bất cứ thứ gì xuống. Hãy chạy những lệnh này một lần, bên ngoài sandbox:
mkdir -p ~/.apidog-mcp-server
npx -y --package=apidog-mcp-server@0.0.18 -c true
Sau đó kiểm tra profile trước khi bạn tin tưởng nó. codex sandbox chạy bất kỳ lệnh nào dưới một profile, điều này khiến nó trở thành một công cụ kiểm thử nhanh gọn:
cd /Users/you/code/pets-api
# 1. A .env file in the workspace is unreadable
codex sandbox --permission-profile apidog-mcp -- cat .env
# cat: .env: Operation not permitted
# 2. Writes outside the allowed folders fail
codex sandbox --permission-profile apidog-mcp -- bash -c 'echo x > /tmp/probe.txt'
# bash: /tmp/probe.txt: Operation not permitted
# 3. The allowed cache folder is writable
codex sandbox --permission-profile apidog-mcp -- touch ~/.apidog-mcp-server/probe
# (no output, exit 0)
# 4. No network
codex sandbox --permission-profile apidog-mcp -- curl -sS https://api.apidog.com/
# curl: (6) Could not resolve host: api.apidog.com
Đó là những kết quả chúng tôi thu được trên macOS. Sau đó hãy kiểm tra rằng server vẫn hoạt động bằng cách gửi cho nó một MCP handshake:
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
| codex sandbox --permission-profile apidog-mcp -- \
npx --offline apidog-mcp-server@0.0.18 --oas=$PWD/openapi.json
Với mạng đã tắt, server trả lời bằng ba công cụ: một công cụ đọc spec OpenAPI, một công cụ đọc các file được tham chiếu bởi $ref, và một công cụ làm mới spec. Đó là tất cả những gì Codex cần để viết mã dựa trên API của bạn.
Trên macOS, hãy thêm --log-denials vào bất kỳ lệnh codex sandbox nào để in ra các lần Seatbelt từ chối sau khi lệnh thoát. Đó là cách nhanh nhất để tìm ra một thư mục mà server thực sự cần.
Bước 5: Để Codex giữ spec luôn mới với Apidog CLI
Một server offline chỉ đọc file, nên phải có thứ gì đó cập nhật file đó. Hãy giao việc này cho coding agent của bạn bằng Apidog CLI. Nó chạy bên ngoài MCP sandbox, dưới các quy tắc lệnh thông thường của Codex, và MCP server không bao giờ cần token.
Thiết lập (một lần):
npm install -g apidog-cli
apidog auth login --with-token <your-access-token>
Nếu bạn chưa kết nối CLI vào Codex, hãy xem How to Use the Apidog CLI in Codex.
Gửi prompt cho agent của bạn:
Export the OpenAPI 3.1 spec for Apidog project 1234567 to ./openapi.json,
then run test scenario 637132 in environment 358171 against it and give me
a CLI summary. Don't touch any .env file.
Các lệnh mà agent chạy (cờ lấy từ apidog export --help và apidog run --help, CLI 2.2.12):
apidog export --project 1234567 --format openapi --oas-version 3.1 --output ./openapi.json
apidog run -t 637132 -e 358171 -r cli,junit --out-dir ./apidog-reports
export ghi đè lên file mà server trong sandbox đọc, nên lần gọi MCP tiếp theo sẽ thấy các endpoint mới. run thực thi kịch bản test của bạn và ghi một báo cáo JUnit cho CI. Thêm --upload-report nếu bạn muốn xem lại lượt chạy trong ứng dụng Apidog. Gói Free của Apidog hỗ trợ tối đa 4 người dùng.
Khi server cần mạng: danh sách domain được cho phép
Chế độ Project cần truy cập api.apidog.com. Câu trả lời của Codex là network proxy: đặt enabled = true, liệt kê các domain được cho phép và bật tính năng network_proxy. Đây là hình dạng được tài liệu hóa trong bài của OpenAI, được điều chỉnh cho Apidog:
[permissions.apidog-mcp-live.filesystem]
":root" = "read"
"~/.npm" = "write"
"~/.apidog-mcp-server" = "write"
[permissions.apidog-mcp-live.filesystem.":workspace_roots"]
"**/*.env" = "deny"
[permissions.apidog-mcp-live.network]
enabled = true
[permissions.apidog-mcp-live.network.domains]
"api.apidog.com" = "allow"
[features]
network_proxy = true
Một deny tường minh thắng allow, và proxy chỉ phân giải một hostname sau khi một quy tắc cho phép nó, vì ngay cả một lần tra cứu DNS cũng có thể rò rỉ dữ liệu. OpenAI cảnh báo rằng các wildcard rộng vẫn có thể cho phép đánh cắp dữ liệu dựa trên DNS, nên hãy liệt kê chính xác các host.
Một lưu ý từ chính thử nghiệm của chúng tôi. Trên máy Mac của chúng tôi, proxy khởi động và tiêm HTTP_PROXY cùng các biến tương tự vào sandbox, nhưng nó trả về 403 với x-proxy-error: blocked-by-allowlist cho mọi host, kể cả những host được cho phép. Máy của chúng tôi định tuyến DNS qua một ứng dụng proxy cục bộ, có thể đó là nguyên nhân. Hãy chạy codex sandbox --permission-profile apidog-mcp-live -- curl -sS https://api.apidog.com/ trên máy của chính bạn trước khi bạn phụ thuộc vào profile này. Nếu host được cho phép vẫn thất bại, hãy quay về chế độ OAS ở Bước 1.
Bạn nên dùng profile nào?
| Loại server | Mạng | Quyền ghi hệ thống file | Ví dụ |
|---|---|---|---|
| Chỉ đọc file cục bộ | enabled = false |
Cache npm + thư mục dữ liệu riêng | Apidog MCP Server với --oas
|
| Gọi một API đã biết | Proxy + domain chính xác | Cache npm + thư mục dữ liệu riêng | Apidog MCP Server với --project-id
|
| Cần internet mở | Tránh, hoặc cô lập trong một VM | Càng hẹp càng tốt | Các server duyệt web |
Nếu bạn chạy Codex trong một nhóm, quản trị viên có thể dùng allowed_permission_profiles trong requirements.toml để giới hạn những profile mà người dùng được phép chọn. Và nếu bạn đang bị cám dỗ tắt hẳn sandbox, hãy đọc lý do tại sao việc bỏ qua Codex sandbox đánh đổi đúng lớp bảo vệ này.
Câu hỏi thường gặp
Codex có sandbox các MCP server theo mặc định không? Không. OpenAI nói rõ rằng Codex không sandbox lệnh khởi chạy một stdio MCP server được cấu hình trong config.toml. Bạn tự thêm sandbox bằng cách khởi chạy server qua codex sandbox --permission-profile <name> --.
Tại sao dùng npx --offline thay vì npx -y? Với network.enabled = false, npx không thể tải bất cứ thứ gì. --offline bảo nó dùng bản sao bạn đã lưu trong cache bằng npx -y --package=<pkg>@<version> -c true, và việc ghim phiên bản ngăn một bản phát hành mới thay thế mã.
Sandbox có bảo vệ các API key của tôi không? Nó chặn những gì bạn từ chối. Profile :workspace cho phép đọc rộng, nên hãy thêm quy tắc deny cho các file .env và các thư mục bí mật. Khi mạng đã tắt, server cũng không thể gửi đi bất cứ thứ gì nó đọc được.
Cách này có hoạt động trên Linux và Windows không? Có. Cùng một profile áp dụng ở mọi nơi; Codex thực thi nó bằng bubblewrap và seccomp trên Linux và bằng một sandbox dựa trên MXC trên các thiết bị Windows tương thích. Hãy kiểm tra từng máy với codex sandbox, vì đường dẫn và thiết lập DNS khác nhau.
Tôi có thể sandbox các MCP server khác theo cách tương tự không? Có. Bất kỳ stdio server nào cũng làm được: tìm các thư mục nó ghi và các host nó gọi, cấp cho nó một profile, bọc lệnh lại, nạp trước package vào cache và kiểm tra. Ví dụ của chính OpenAI sandbox @modelcontextprotocol/server-memory với quyền ghi giới hạn ở ~/.npm và ~/mcp-data.


Top comments (0)