Cấu hình nâng cao

Sử dụng các tùy chọn này khi bạn cần kiểm soát chi tiết hơn đối với nhà cung cấp, chính sách và tích hợp. Để bắt đầu nhanh, hãy xem Kiến thức cơ bản về cấu hình.

Để tìm hiểu thêm về hướng dẫn dự án, các khả năng có thể tái sử dụng, lệnh gạch chéo tùy chỉnh, quy trình làm việc với tác nhân phụ và các tích hợp, hãy xem Tùy chỉnh. Để biết các khóa cấu hình, hãy xem Tham chiếu cấu hình.

Hồ sơ

Hồ sơ cho phép bạn lưu các lớp cấu hình có tên và chuyển đổi giữa chúng từ CLI. Khi bạn truyền --profile profile-name, Codex sẽ tải ~/.codex/config.toml, sau đó phủ ~/.codex/profile-name.config.toml lên trên. Tên hồ sơ có thể chứa chữ cái, chữ số, dấu gạch nối và dấu gạch dưới.

Tạo một tệp TOML riêng cho từng hồ sơ. Sử dụng các khóa cấu hình cấp cao nhất trong tệp hồ sơ; không lồng chúng bên dưới [profiles.profile-name].

# ~/.codex/deep-review.config.toml
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"
model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"

codex --profile deep-review
codex exec --profile deep-review "review this change"

Vì tệp hồ sơ là một lớp nằm trên cấu hình người dùng cơ sở và dưới cấu hình dự án cùng CLI, tệp này chỉ cần chứa các giá trị khác với cấu hình cơ sở. Tệp hồ sơ cũng có thể ghi đè model_catalog_json; Codex sử dụng giá trị trong hồ sơ khi cả hai tệp đều thiết lập khóa này.

Trong Codex 0.134.0 trở lên, --profile không còn đọc [profiles.profile-name] từ config.toml và bộ chọn profile = "profile-name" cấp cao nhất cũng không còn được hỗ trợ. Hãy chuyển các thiết lập hồ sơ cũ sang ~/.codex/profile-name.config.toml, sau đó xóa bảng [profiles.profile-name] tương ứng và bộ chọn profile = "profile-name" khỏi config.toml.

Ghi đè một lần từ CLI

Ngoài việc chỉnh sửa ~/.codex/config.toml, bạn có thể ghi đè cấu hình cho một lần chạy duy nhất từ CLI:

• Ưu tiên các cờ chuyên dụng nếu có (ví dụ: --model).
• Sử dụng -c / --config khi cần ghi đè một khóa bất kỳ.

Ví dụ:

# Dedicated flag
codex --model gpt-5.6-terra

# Generic key/value override (value is TOML, not JSON)
codex --config model='"gpt-5.6-terra"'
codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

Lưu ý:

• Khóa có thể sử dụng ký hiệu dấu chấm để đặt các giá trị lồng nhau (ví dụ: mcp_servers.context7.enabled=false).
• Các giá trị --config được phân tích cú pháp dưới dạng TOML. Khi không chắc chắn, hãy đặt giá trị trong dấu ngoặc kép để shell không tách giá trị tại các dấu cách.
• Nếu không thể phân tích giá trị dưới dạng TOML, Codex sẽ coi đó là một chuỗi.

Vị trí cấu hình và trạng thái

Codex lưu trạng thái cục bộ trong CODEX_HOME (mặc định là ~/.codex).

Các tệp phổ biến bạn có thể thấy tại đó:

• config.toml (cấu hình cục bộ của bạn)
• auth.json (nếu bạn sử dụng phương thức lưu trữ thông tin xác thực dựa trên tệp) hoặc chuỗi khóa/kho khóa của hệ điều hành
• history.jsonl (nếu tính năng duy trì lịch sử được bật)
• Trạng thái khác theo từng người dùng, chẳng hạn như nhật ký và bộ nhớ đệm

Để biết chi tiết về xác thực (bao gồm các chế độ lưu trữ thông tin xác thực), hãy xem Xác thực. Để xem danh sách đầy đủ các khóa cấu hình, hãy xem Tham chiếu cấu hình.

Để tìm hiểu về các giá trị mặc định, quy tắc và kỹ năng dùng chung được đưa vào repo hoặc đường dẫn hệ thống, hãy xem Cấu hình nhóm.

Nếu bạn chỉ cần trỏ nhà cung cấp OpenAI tích hợp sẵn đến một proxy LLM, bộ định tuyến hoặc dự án đã bật lưu trú dữ liệu, hãy đặt openai_base_url trong config.toml thay vì định nghĩa nhà cung cấp mới. Thao tác này thay đổi URL cơ sở cho nhà cung cấp openai tích hợp sẵn mà không cần mục model_providers.<id> riêng.

openai_base_url = "https://us.api.openai.com/v1"

Tệp cấu hình dự án (.codex/config.toml)

Ngoài cấu hình người dùng, Codex còn đọc các giá trị ghi đè theo phạm vi dự án từ những tệp .codex/config.toml trong repo. Codex duyệt từ thư mục gốc của dự án đến thư mục làm việc hiện tại và tải mọi tệp .codex/config.toml tìm thấy. Nếu nhiều tệp định nghĩa cùng một khóa, tệp gần thư mục làm việc của bạn nhất sẽ được ưu tiên.

Để bảo mật, Codex chỉ tải các tệp cấu hình theo phạm vi dự án khi dự án được tin cậy. Nếu dự án không được tin cậy, Codex sẽ bỏ qua các lớp .codex/ của dự án, bao gồm .codex/config.toml, hook cục bộ của dự án và quy tắc cục bộ của dự án. Các lớp người dùng và hệ thống vẫn độc lập và tiếp tục được tải.

Các đường dẫn tương đối trong cấu hình dự án (ví dụ: model_instructions_file) được phân giải tương đối theo thư mục .codex/ chứa config.toml.

Tệp cấu hình dự án không thể ghi đè các thiết lập chuyển hướng thông tin xác thực, thay đổi siêu dữ liệu yêu cầu của ứng dụng do máy chủ sở hữu, thay đổi xác thực nhà cung cấp, chọn hồ sơ cấu hình hoặc chạy các lệnh thông báo/đo từ xa cục bộ trên máy. Codex bỏ qua các khóa sau trong .codex/config.toml cục bộ của dự án và hiển thị cảnh báo khi khởi động nếu phát hiện chúng: openai_base_url, chatgpt_base_url, apps_mcp_product_sku, model_provider, model_providers, notify, profile, profiles, experimental_realtime_ws_base_url và otel. Hãy đặt các khóa nhà cung cấp, thông báo và đo từ xa trong ~/.codex/config.toml cấp người dùng; chọn hồ sơ cấu hình bằng --profile profile-name và ~/.codex/profile-name.config.toml.

Hook

Codex cũng có thể tải các hook vòng đời từ tệp hooks.json hoặc bảng [hooks] nội tuyến trong các tệp config.toml nằm cạnh những lớp cấu hình đang hoạt động.

Trong thực tế, bốn vị trí hữu ích nhất là:

• ~/.codex/hooks.json
• ~/.codex/config.toml
• <repo>/.codex/hooks.json
• <repo>/.codex/config.toml

Hook cục bộ của dự án chỉ được tải khi lớp .codex/ của dự án được tin cậy. Hook cấp người dùng không phụ thuộc vào trạng thái tin cậy của dự án.

Hook TOML nội tuyến sử dụng cùng cấu trúc sự kiện như hooks.json:

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

Nếu một lớp chứa cả hooks.json và [hooks] nội tuyến, Codex sẽ tải cả hai và hiển thị cảnh báo. Nên ưu tiên một cách biểu diễn cho mỗi lớp.

Để xem danh sách sự kiện hiện tại, các trường đầu vào, hành vi đầu ra và giới hạn, hãy xem Hook.

Vai trò agent ([agents] trong config.toml)

Để biết cách cấu hình vai trò tác nhân phụ ([agents] trong config.toml), hãy xem Tác nhân phụ.

Phát hiện thư mục gốc của dự án

Codex phát hiện cấu hình dự án (ví dụ: các lớp .codex/ và AGENTS.md) bằng cách duyệt ngược từ thư mục làm việc cho đến khi gặp thư mục gốc của dự án.

Theo mặc định, Codex coi thư mục chứa .git là thư mục gốc của dự án. Để tùy chỉnh hành vi này, hãy đặt project_root_markers trong config.toml:

# Treat a directory as the project root when it contains any of these markers.
project_root_markers = [".git", ".hg", ".sl"]

Đặt project_root_markers = [] để bỏ qua việc tìm kiếm trong các thư mục cha và coi thư mục làm việc hiện tại là thư mục gốc của dự án.

Nhà cung cấp mô hình tùy chỉnh

Nhà cung cấp mô hình xác định cách Codex kết nối với mô hình (URL cơ sở, API truyền dẫn, xác thực và các tiêu đề HTTP tùy chọn). Nhà cung cấp tùy chỉnh không thể sử dụng lại các ID nhà cung cấp tích hợp sẵn được dành riêng: openai, ollama và lmstudio.

Định nghĩa các nhà cung cấp bổ sung và trỏ model_provider đến chúng:

model = "gpt-5.6-terra"
model_provider = "proxy"

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"

[model_providers.local_ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"

[model_providers.mistral]
name = "Mistral"
base_url = "https://api.mistral.ai/v1"
env_key = "MISTRAL_API_KEY"

Nếu một nhà cung cấp tùy chỉnh hỗ trợ điểm cuối tìm kiếm trên web độc lập, hãy khai báo khả năng đó trong cấu hình nhà cung cấp:

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "https://proxy.example.com/v1"
env_key = "OPENAI_API_KEY"
supports_standalone_web_search = true

Thiết lập này mặc định là false đối với nhà cung cấp tùy chỉnh. Tính năng tìm kiếm web độc lập đang được phát triển và bị tắt theo mặc định. Việc đặt khả năng của nhà cung cấp thành true không tự động bật tính năng này: nhà cung cấp phải hỗ trợ một điểm cuối tương thích, và mô hình cùng môi trường chạy được chọn phải hỗ trợ tìm kiếm độc lập. Chế độ web_search đã cấu hình và các hạn chế tìm kiếm được quản lý vẫn được áp dụng.

Thêm tiêu đề yêu cầu khi cần:

[model_providers.example]
http_headers = { "X-Example-Header" = "example-value" }
env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }

Sử dụng xác thực dựa trên lệnh khi nhà cung cấp cần Codex lấy bearer token từ một trình trợ giúp thông tin xác thực bên ngoài:

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "https://proxy.example.com/v1"
wire_api = "responses"

[model_providers.proxy.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000
refresh_interval_ms = 300000

Lệnh xác thực không nhận stdin và phải in token ra stdout. Codex loại bỏ khoảng trắng bao quanh, coi token trống là lỗi và chủ động làm mới tại refresh_interval_ms; đặt refresh_interval_ms = 0 để chỉ làm mới sau khi thử lại xác thực. Không kết hợp [model_providers.<id>.auth] với env_key, experimental_bearer_token hoặc requires_openai_auth.

Nhà cung cấp Amazon Bedrock

Codex bao gồm nhà cung cấp mô hình amazon-bedrock tích hợp sẵn. Hãy đặt trực tiếp nhà cung cấp này làm model_provider; khác với nhà cung cấp tùy chỉnh, nhà cung cấp tích hợp sẵn này chỉ hỗ trợ ghi đè hồ sơ và khu vực AWS lồng nhau.

model_provider = "amazon-bedrock"
model = "<bedrock-model-id>"

[model_providers.amazon-bedrock.aws]
profile = "default"
region = "eu-central-1"

Nếu bạn bỏ qua profile, Codex sẽ sử dụng chuỗi thông tin xác thực AWS tiêu chuẩn. Đặt region thành khu vực Bedrock được hỗ trợ sẽ xử lý các yêu cầu.

Để xem toàn bộ quy trình thiết lập, các tùy chọn xác thực, mô hình được hỗ trợ và tính khả dụng của tính năng, hãy xem Sử dụng ChatGPT Work và Codex với Amazon Bedrock.

Chế độ OSS (nhà cung cấp cục bộ)

Codex có thể chạy với một nhà cung cấp "mã nguồn mở" cục bộ như Ollama hoặc LM Studio khi bạn truyền --oss. Chọn một nhà cung cấp cho một lần chạy bằng --local-provider hoặc đặt oss_provider làm mặc định. Nếu không đặt tùy chọn nào, CLI tương tác sẽ nhắc bạn chọn; codex exec sẽ thoát và báo lỗi.

# Default local provider used with `--oss`
oss_provider = "ollama" # or "lmstudio"

Nhà cung cấp Azure và tinh chỉnh theo từng nhà cung cấp

[model_providers.azure]
name = "Azure"
base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
query_params = { api-version = "2025-04-01-preview" }
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 10
stream_idle_timeout_ms = 300000

Để thay đổi URL cơ sở cho nhà cung cấp OpenAI tích hợp sẵn, hãy sử dụng openai_base_url; không tạo [model_providers.openai] vì bạn không thể ghi đè ID của nhà cung cấp tích hợp sẵn.

Khách hàng ChatGPT sử dụng lưu trú dữ liệu

Các dự án được tạo với tính năng lưu trú dữ liệu đã bật có thể tạo một nhà cung cấp mô hình để cập nhật base_url bằng tiền tố chính xác.

model_provider = "openaidr"
[model_providers.openaidr]
name = "OpenAI Data Residency"
base_url = "https://us.api.openai.com/v1" # Replace 'us' with domain prefix

Suy luận, độ chi tiết và giới hạn của mô hình

model_reasoning_summary = "none"          # Disable summaries
model_verbosity = "low"                   # Shorten responses
model_supports_reasoning_summaries = true # Force reasoning
model_context_window = 128000             # Context window size

model_verbosity chỉ áp dụng cho các nhà cung cấp sử dụng Responses API. Các nhà cung cấp Chat Completions sẽ bỏ qua thiết lập này.

Chính sách phê duyệt và chế độ sandbox

Chọn mức độ nghiêm ngặt của phê duyệt (ảnh hưởng đến thời điểm Codex tạm dừng) và cấp độ sandbox (ảnh hưởng đến quyền truy cập tệp/mạng).

Để biết các chi tiết vận hành cần lưu ý khi chỉnh sửa config.toml, hãy xem Các tổ hợp sandbox và phê duyệt phổ biến, Đường dẫn được bảo vệ trong thư mục gốc có thể ghi và Truy cập mạng.

Để tìm hiểu về hồ sơ quyền đang ở giai đoạn beta dùng để cấu hình đồng thời quyền truy cập hệ thống tệp và mạng, hãy xem Quyền.

Bạn cũng có thể sử dụng chính sách phê duyệt chi tiết (approval_policy = { granular = { ... } }) để cho phép hoặc tự động từ chối từng loại lời nhắc. Điều này hữu ích khi bạn muốn phê duyệt tương tác thông thường cho một số trường hợp nhưng muốn những trường hợp khác, chẳng hạn như request_permissions hoặc lời nhắc từ tập lệnh kỹ năng, tự động thất bại theo hướng an toàn.

Đặt approvals_reviewer = "auto_review" để chuyển các yêu cầu phê duyệt tương tác đủ điều kiện qua quá trình đánh giá tự động. Thao tác này thay đổi bên đánh giá, không thay đổi ranh giới sandbox.

Sử dụng [auto_review].policy cho các chỉ dẫn chính sách của trình đánh giá cục bộ. guardian_policy_config được quản lý được ưu tiên hơn.

approval_policy = "untrusted"   # Other options: on-request, never, or { granular = { ... } }
approvals_reviewer = "user"     # Or "auto_review" for automatic review
sandbox_mode = "workspace-write"
allow_login_shell = false       # Optional hardening: disallow login shells for shell tools

# Example granular approval policy:
# approval_policy = { granular = {
#   sandbox_approval = true,
#   rules = true,
#   mcp_elicitations = true,
#   request_permissions = false,
#   skill_approval = false
# } }

[sandbox_workspace_write]
exclude_tmpdir_env_var = false  # Allow $TMPDIR
exclude_slash_tmp = false       # Allow /tmp
writable_roots = ["/Users/YOU/.pyenv/shims"]
network_access = false          # Opt in to outbound network

[auto_review]
policy = """
Use your organization's automatic review policy.
"""

Hồ sơ quyền có tên

Để tìm hiểu về các hồ sơ tích hợp sẵn, cú pháp hồ sơ tùy chỉnh và mô hình cấu hình hệ thống tệp cùng mạng đầy đủ, hãy xem Quyền.

Để xem danh sách khóa đầy đủ và các ràng buộc về yêu cầu, hãy xem Tham chiếu cấu hình và Cấu hình được quản lý.

Tắt hoàn toàn sandbox (chỉ sử dụng nếu môi trường của bạn đã cô lập các tiến trình):

sandbox_mode = "danger-full-access"

Chính sách môi trường shell

shell_environment_policy kiểm soát các biến môi trường mà Codex truyền cho các lệnh được khởi chạy. Bắt đầu với môi trường trống bằng inherit = "none" hoặc kế thừa một tập đã tinh gọn bằng inherit = "core". Thêm các giá trị tường minh và bộ lọc theo khóa để tránh truyền những bí mật không cần thiết cho các lệnh được khởi chạy.

[shell_environment_policy]
inherit = "core"
set = { MY_FLAG = "1" }
ignore_default_excludes = false

[shell_environment_policy.filters]
"AWS_*" = "exclude"
"AZURE_*" = "exclude"

Mẫu bộ lọc không phân biệt chữ hoa chữ thường và hỗ trợ * cùng ?. Sử dụng "exclude" để loại bỏ các biến khớp mẫu. Khi bất kỳ mẫu nào sử dụng "include", Codex chỉ giữ các biến khớp với một mẫu bao gồm. Các mẫu bao gồm không khôi phục những biến đã bị loại trừ. Khóa bộ lọc được hợp nhất giữa các lớp cấu hình mà không phân biệt chữ hoa chữ thường.

ignore_default_excludes mặc định là true, vì vậy Codex không tự động loại bỏ các tên biến chứa KEY, SECRET hoặc TOKEN. Đặt thành false để áp dụng các quy tắc loại trừ tự động đó trước khi chạy các bộ lọc tường minh của bạn.

Codex áp dụng các quy tắc loại trừ tự động trước, sau đó đến quy tắc loại trừ tùy chỉnh, các giá trị từ set và cuối cùng là danh sách cho phép theo mẫu bao gồm. Vì set chạy sau các quy tắc loại trừ nên nó có thể khôi phục một biến đã bị loại trừ. Danh sách cho phép theo mẫu bao gồm vẫn có thể loại bỏ giá trị đã được khôi phục đó.

Các mảng exclude và include_only cũ vẫn được hỗ trợ cho những cấu hình hiện có. Không kết hợp bất kỳ mảng nào trong số đó với [shell_environment_policy.filters] trong cùng một lớp cấu hình; Codex sẽ từ chối tổ hợp đó.

Máy chủ MCP

Xem tài liệu MCP chuyên biệt để biết chi tiết cấu hình.

Khả năng quan sát và đo từ xa

Bật tính năng xuất nhật ký OpenTelemetry (OTel) để theo dõi các lần chạy Codex (yêu cầu API, SSE/sự kiện, lời nhắc, phê duyệt/kết quả công cụ). Tính năng này bị tắt theo mặc định; hãy chủ động bật qua [otel]:

[otel]
environment = "staging"   # defaults to "dev"
exporter = "none"         # set to otlp-http or otlp-grpc to send events
log_user_prompt = false   # redact user prompts unless explicitly enabled

Chọn một trình xuất:

[otel]
exporter = { otlp-http = {
  endpoint = "https://otel.example.com/v1/logs",
  protocol = "binary",
  headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
}}

[otel]
exporter = { otlp-grpc = {
  endpoint = "https://otel.example.com:4317",
  headers = { "x-otlp-meta" = "abc123" }
}}

Nếu exporter = "none", Codex ghi lại các sự kiện nhưng không gửi gì. Trình xuất xử lý theo lô bất đồng bộ và đẩy hết dữ liệu khi tắt. Siêu dữ liệu sự kiện bao gồm tên dịch vụ, phiên bản CLI, thẻ môi trường, ID cuộc hội thoại, mô hình, thiết lập sandbox/phê duyệt và các trường theo từng sự kiện (xem Tham chiếu cấu hình).

Dữ liệu được phát ra

Codex phát ra các sự kiện nhật ký có cấu trúc cho lần chạy và hoạt động sử dụng công cụ. Các loại sự kiện tiêu biểu bao gồm:

• codex.conversation_starts (mô hình, thiết lập suy luận, chính sách sandbox/phê duyệt)
• codex.api_request (lần thử, trạng thái/thành công, thời lượng và chi tiết lỗi)
• codex.sse_event (loại sự kiện luồng, thành công/thất bại, thời lượng cùng số lượng token trên response.completed)
• codex.websocket_request và codex.websocket_event (thời lượng yêu cầu cùng loại/trạng thái thành công/lỗi của từng thông điệp)
• codex.user_prompt (độ dài; nội dung được che trừ khi được bật rõ ràng)
• codex.tool_decision (được phê duyệt/từ chối và quyết định đến từ cấu hình hay người dùng)
• codex.tool_result (thời lượng, trạng thái thành công, đoạn trích đầu ra)

Chỉ số OTel được phát ra

Khi quy trình chỉ số OTel được bật, Codex phát ra các bộ đếm và biểu đồ tần suất thời lượng cho hoạt động API, luồng và công cụ.

Mỗi chỉ số bên dưới cũng bao gồm các thẻ siêu dữ liệu mặc định: auth_mode, originator, session_source, model và app.version.

Để biết thêm hướng dẫn về bảo mật và quyền riêng tư liên quan đến đo từ xa, hãy xem Bảo mật.

Chỉ số

Theo mặc định, Codex định kỳ gửi một lượng nhỏ dữ liệu ẩn danh về mức sử dụng và tình trạng hoạt động cho OpenAI. Điều này giúp phát hiện khi Codex hoạt động không đúng và cho biết những tính năng cùng tùy chọn cấu hình nào đang được sử dụng, để nhóm Codex có thể tập trung vào những điều quan trọng nhất. Các chỉ số này không chứa bất kỳ thông tin nhận dạng cá nhân (PII) nào. Việc thu thập chỉ số độc lập với quá trình xuất nhật ký/dấu vết OTel.

Nếu muốn tắt hoàn toàn việc thu thập chỉ số trên ứng dụng ChatGPT dành cho máy tính, Codex CLI và tiện ích IDE của một máy, hãy đặt cờ phân tích trong cấu hình:

[analytics]
enabled = false

Mỗi chỉ số bao gồm các trường riêng cùng những trường ngữ cảnh mặc định bên dưới.

Trường ngữ cảnh mặc định (áp dụng cho mọi sự kiện/chỉ số)

• auth_mode: swic | api | unknown.
• model: tên mô hình được sử dụng.
• app.version: phiên bản Codex.

Danh mục chỉ số

Mỗi chỉ số bao gồm các trường bắt buộc cùng các trường ngữ cảnh mặc định ở trên. Tên chỉ số bên dưới lược bỏ tiền tố codex.. Hầu hết tên chỉ số được tập trung trong codex-rs/otel/src/metrics/names.rs; các chỉ số dành riêng cho tính năng được phát ra bên ngoài tệp đó cũng được liệt kê tại đây. Nếu một chỉ số bao gồm trường tool, trường này phản ánh công cụ nội bộ được sử dụng (ví dụ: apply_patch hoặc shell) và không chứa lệnh shell thực tế hay bản vá mà codex đang cố áp dụng.

Môi trường chạy và truyền tải mô hình

Chỉ số cloud_requirements.fetch_attempt bao gồm các trường trigger, attempt, outcome và status_code. Chỉ số cloud_requirements.fetch_final bao gồm các trường trigger, outcome, reason, attempt_count và status_code.

Hoạt động của lượt và công cụ

Các chỉ số mcp.call và mcp.call.duration_ms bao gồm status; dữ liệu phát ra từ lệnh gọi công cụ thông thường cũng bao gồm tool, cùng connector_id và connector_name khi có. Các lệnh gọi MCP của Codex Apps bị chặn có thể phát ra mcp.call chỉ với status.

Luồng, tác vụ và tính năng

Chỉ số shell_snapshot bao gồm success và failure_reason khi xảy ra lỗi.

Bộ nhớ và trạng thái cục bộ

Các chỉ số external_agent_config.detect và external_agent_config.import bao gồm migration_type; quá trình di chuyển kỹ năng cũng bao gồm skills_count.

Sandbox Windows

Các chỉ số lỗi thiết lập nâng cao bao gồm code và message khi có thông tin chi tiết về lỗi thiết lập Windows, đồng thời có thể bao gồm originator khi được phát ra từ quy trình thiết lập dùng chung. Chỉ số windows_sandbox.legacy_setup_preflight_failed bao gồm originator khi được phát ra từ quy trình thiết lập dùng chung, nhưng lỗi kiểm tra trước của lời nhắc dự phòng có thể không bao gồm trường nào.

Các tùy chọn kiểm soát phản hồi

Theo mặc định, các ứng dụng khách cục bộ cho phép người dùng gửi phản hồi từ /feedback. Để tắt tính năng thu thập phản hồi trên ứng dụng ChatGPT dành cho máy tính, Codex CLI và tiện ích mở rộng IDE của một máy, hãy cập nhật cấu hình:

[feedback]
enabled = false

Khi bị tắt, /feedback hiển thị thông báo cho biết tính năng đã bị tắt và Codex từ chối các nội dung phản hồi được gửi.

Ẩn hoặc hiển thị các sự kiện suy luận

Nếu muốn giảm nội dung đầu ra "suy luận" gây nhiễu (ví dụ: trong nhật ký CI), bạn có thể ẩn nội dung đó:

hide_agent_reasoning = true

Nếu muốn hiển thị nội dung suy luận thô khi một mô hình phát ra nội dung đó:

show_raw_agent_reasoning = true

Chỉ bật nội dung suy luận thô nếu điều này phù hợp với quy trình làm việc của bạn. Một số mô hình/nhà cung cấp (như gpt-oss) không phát ra nội dung suy luận thô; trong trường hợp đó, cài đặt này không tạo ra hiệu ứng hiển thị nào.

Thông báo

Dùng notify để kích hoạt một chương trình bên ngoài mỗi khi Codex phát ra các sự kiện được hỗ trợ (hiện chỉ có agent-turn-complete). Tính năng này hữu ích cho thông báo bật lên trên máy tính, webhook trò chuyện, bản cập nhật CI hoặc bất kỳ cảnh báo qua kênh phụ nào mà thông báo TUI tích hợp sẵn không hỗ trợ.

notify = ["python3", "/path/to/notify.py"]

Ví dụ về notify.py (đã rút gọn) phản ứng với agent-turn-complete:

#!/usr/bin/env python3
import json, subprocess, sys

def main() -> int:
    notification = json.loads(sys.argv[1])
    if notification.get("type") != "agent-turn-complete":
        return 0
    title = f"Codex: {notification.get('last-assistant-message', 'Turn Complete!')}"
    message = " ".join(notification.get("input-messages", []))
    subprocess.check_output([
        "terminal-notifier",
        "-title", title,
        "-message", message,
        "-group", "codex-" + notification.get("thread-id", ""),
        "-activate", "com.googlecode.iterm2",
    ])
    return 0

if __name__ == "__main__":
    sys.exit(main())

Tập lệnh nhận một đối số JSON duy nhất. Các trường phổ biến bao gồm:

• type (hiện là agent-turn-complete)
• thread-id (mã định danh phiên)
• turn-id (mã định danh lượt)
• cwd (thư mục làm việc)
• input-messages (các tin nhắn của người dùng dẫn đến lượt này)
• last-assistant-message (văn bản trong tin nhắn gần nhất của trợ lý)

Đặt tập lệnh ở một vị trí trên đĩa và trỏ notify đến tập lệnh đó.

notify so với tui.notifications

• notify chạy một chương trình bên ngoài (phù hợp với webhook, trình thông báo trên máy tính và hook CI).
• tui.notifications được tích hợp sẵn trong TUI và có thể tùy chọn lọc theo loại sự kiện (ví dụ: agent-turn-complete và approval-requested).
• tui.notification_method kiểm soát cách TUI phát thông báo đầu cuối (auto, osc9 hoặc bel).
• tui.notification_condition kiểm soát việc thông báo TUI chỉ được kích hoạt khi đầu cuối ở trạng thái unfocused hay always.

Ở chế độ auto, Codex ưu tiên thông báo OSC 9 (một chuỗi thoát đầu cuối được một số đầu cuối diễn giải thành thông báo trên máy tính) và chuyển sang dùng BEL (\x07) nếu không thể sử dụng OSC 9.

Xem Tham chiếu cấu hình để biết chính xác các khóa.

Lưu giữ lịch sử

Theo mặc định, Codex lưu bản ghi các phiên cục bộ trong CODEX_HOME (ví dụ: ~/.codex/history.jsonl). Để tắt tính năng lưu giữ lịch sử cục bộ:

[history]
persistence = "none"

Để giới hạn kích thước tệp lịch sử, hãy đặt history.max_bytes. Khi tệp vượt quá giới hạn, Codex loại bỏ các mục cũ nhất và thu gọn tệp trong khi vẫn giữ lại các bản ghi mới nhất.

[history]
max_bytes = 104857600 # 100 MiB

Trích dẫn có thể nhấp

Nếu bạn sử dụng tiện ích tích hợp đầu cuối/trình soạn thảo có hỗ trợ tính năng này, Codex có thể hiển thị trích dẫn tệp dưới dạng liên kết có thể nhấp. Hãy cấu hình file_opener để chọn lược đồ URI mà Codex sử dụng:

file_opener = "vscode" # or cursor, windsurf, vscode-insiders, none

Ví dụ: một trích dẫn như /home/user/project/main.py:42 có thể được viết lại thành liên kết vscode://file/...:42 có thể nhấp.

Khám phá hướng dẫn của dự án

Codex đọc AGENTS.md (và các tệp liên quan), sau đó đưa một lượng giới hạn hướng dẫn của dự án vào lượt đầu tiên của phiên. Hai tùy chọn kiểm soát cách hoạt động của tính năng này:

• project_doc_max_bytes: lượng nội dung cần đọc từ mỗi tệp AGENTS.md
• project_doc_fallback_filenames: các tên tệp bổ sung cần thử khi thiếu AGENTS.md ở một cấp thư mục

Để xem hướng dẫn chi tiết, hãy đọc Hướng dẫn tùy chỉnh bằng AGENTS.md.

Máy tính

Các tùy chọn trong phần này chỉ áp dụng cho ứng dụng ChatGPT dành cho máy tính.

Thêm trình xử lý tệp tùy chỉnh

Trong ~/.codex/config.toml ở cấp người dùng, hãy thêm các mục bên dưới desktop.custom_file_handlers để mở tệp trong các trình soạn thảo hoặc trình khởi chạy nội bộ mà ứng dụng ChatGPT dành cho máy tính không hỗ trợ theo mặc định. Mỗi mục sẽ thêm một trình soạn thảo đích vào các menu Mở bằng của ứng dụng. Ứng dụng liệt kê đích khi command là một đường dẫn tuyệt đối hiện có hoặc có thể được phân giải từ PATH của ứng dụng.

Ví dụ sau minh họa ba cách truyền tệp cho một trình xử lý:

# Append the opened path directly after the command.
[desktop.custom_file_handlers.vscodium]
label = "VSCodium"
icon = "/Users/you/.codex/icons/vscodium.png"
command = "codium"

# Place fixed arguments before the opened path.
[desktop.custom_file_handlers.textedit]
label = "TextEdit"
icon = "/Users/you/.codex/icons/textedit.png"
command = "/usr/bin/open"
args = ["-a", "TextEdit"]

# Append one JSON argument with the path and editor context.
[desktop.custom_file_handlers.company_editor]
label = "Company Editor"
icon = "/opt/company/editor/icon.png"
command = "/opt/company/bin/editor"
input = "json_argument"

Lưu config.toml, sau đó khởi động lại ứng dụng ChatGPT dành cho máy tính.

ID của trình xử lý là phân đoạn cuối cùng trong tiêu đề bảng TOML. ID phải chứa 1–64 ký tự, bắt đầu bằng một chữ cái hoặc chữ số ASCII và các ký tự còn lại chỉ được là chữ cái ASCII, chữ số, dấu chấm, dấu gạch dưới hoặc dấu gạch nối. Ứng dụng hiển thị ID với tiền tố custom:; ví dụ: company_editor trở thành custom:company_editor. Hãy đặt ID chứa dấu chấm trong dấu ngoặc kép để TOML không diễn giải ID đó là một bảng lồng nhau. Ví dụ:

[desktop.custom_file_handlers."company.editor"]
label = "Company Editor"
icon = "/opt/company/editor/icon.png"
command = "/opt/company/bin/editor"

Mỗi trình xử lý hỗ trợ các trường sau:

Giá trị input kiểm soát nội dung theo sau args:

• path nối thêm đường dẫn làm đối số cuối cùng của lệnh.
• json_argument nối thêm một đối tượng JSON với target, path, appPath và location. Giá trị location là một đối tượng có các giá trị line và column bắt đầu từ 1, hoặc là null.
• json_stdin ghi đối tượng JSON vào đầu vào chuẩn thay vì thêm một đối số. Đối tượng cũng bao gồm hostConfig, remoteWorkspaceRoot và remotePath; các trường này là null khi không áp dụng.

Ví dụ: company_editor có thể nhận đối số này khi người dùng mở một vị trí mã nguồn cụ thể:

{
  "target": "custom:company_editor",
  "path": "/repo/src/index.ts",
  "appPath": null,
  "location": { "line": 12, "column": 3 }
}

Việc chọn một trình xử lý tùy chỉnh làm trình soạn thảo ưu tiên sẽ lưu lựa chọn theo cùng cách như khi chọn trình soạn thảo tích hợp sẵn, bao gồm cả tùy chọn riêng cho từng dự án.

Tùy chọn TUI

Chạy codex mà không có lệnh con sẽ khởi chạy giao diện đầu cuối tương tác (TUI). Codex cung cấp một số cấu hình dành riêng cho TUI bên dưới [tui], bao gồm:

• tui.notifications: bật/tắt thông báo (hoặc giới hạn ở các loại cụ thể)
• tui.notification_method: chọn auto, osc9 hoặc bel cho thông báo đầu cuối
• tui.notification_condition: chọn unfocused hoặc always để xác định thời điểm kích hoạt thông báo
• tui.animations: bật/tắt hiệu ứng hoạt ảnh ASCII và hiệu ứng ánh sáng lướt
• tui.alternate_screen: kiểm soát việc sử dụng màn hình thay thế (đặt thành never để giữ lại lịch sử cuộn của đầu cuối)
• tui.show_tooltips: hiển thị hoặc ẩn chú giải hướng dẫn ban đầu trên màn hình chào mừng

tui.notification_method mặc định là auto. Ở chế độ auto, Codex ưu tiên thông báo OSC 9 (một chuỗi thoát đầu cuối được một số đầu cuối diễn giải thành thông báo trên máy tính) khi đầu cuối có vẻ hỗ trợ loại thông báo này, và chuyển sang dùng BEL (\x07) nếu không.

Xem Tham chiếu cấu hình để biết danh sách khóa đầy đủ.