Cách sandbox MCP Server với codex sandbox

Codex không chạy các máy chủ MCP stdio trong sandbox, nên các máy chủ npx sẽ chạy với đầy đủ quyền của bạn. Hãy tạo một permission profile, bọc máy chủ bằng codex sandbox rồi kiểm thử.

INEZA Felin-Michel

INEZA Felin-Michel

20 tháng 11 2026

Cách sandbox MCP Server với codex sandbox

Apidog cho doanh nghiệp

Triển khai tại chỗ

SSO & RBAC

Tuân thủ SOC 2

Khám phá Apidog Enterprise

Để 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:

  1. ":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.
  2. Một đường dẫn như "~/.npm" = "write" chỉ cấp quyền ghi cho thư mục đó.
  3. 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 .env bê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 đủ.

Ba chế độ mạng cho một Codex permission profile: network.enabled = false để không có mạng, một proxy với danh sách domain được cho phép như api.apidog.com, và truy cập mạng đầy đủ cần tránh đối với MCP server

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ế độ 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:

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ó.

Sơ đồ: Codex khởi chạy codex sandbox với profile apidog-mcp, profile này chạy npx --offline apidog-mcp-server với một file OpenAPI; bên trong sandbox nó có thể đọc openapi.json và ghi vào ~/.npm và ~/.apidog-mcp-server, trong khi các file .env, internet và các thư mục khác bị chặ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.

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API