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 nhiều hơn đối với nhà cung cấp, chính sách và các tích hợp. Để bắt đầu nhanh, hãy xem Cấu hình cơ bản.

Để tìm hiểu thông tin nền tảng 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. Để xem 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.6-sol"
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à bên dưới cấu hình dự án và CLI, tệp này chỉ cần chứa những 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 giá trị 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 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 khi có sẵn (ví dụ: --model).
• Sử dụng -c / --config khi bạn 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 để thiết lập các giá trị lồng nhau (ví dụ: mcp_servers.context7.enabled=false).
• 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 nháy để shell không tách giá trị tại các khoảng trắng.
• 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 thường gặp 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 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 bật tính năng lưu giữ lịch sử)
• 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 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 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 khả năng lưu trú dữ liệu, hãy thiết lập 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ở của 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 bên 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 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 tách biệt và tiếp tục được tải.

Các đường dẫn tương đối bên 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 cách 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à in 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 thiết lập 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 hook vòng đời từ các tệp hooks.json hoặc các bảng [hooks] nội tuyến trong những tệp config.toml nằm cạnh các 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 vẫn độc lập với mức độ 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à đưa ra 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ò tác nhân ([agents] trong config.toml)

Để tìm hiểu 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 lên từ thư mục làm việc cho đến khi đến 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 thiết lập 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"]

Thiết lập 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ột mô hình (URL cơ sở, API truyền tải, 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 dành riêng cho nhà cung cấp tích hợp sẵn: openai, ollama và lmstudio.

Định nghĩa thêm nhà cung cấp 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 mặc định là false đối với nhà cung cấp tùy chỉnh. Tính năng tìm kiếm trên web độc lập đang được phát triển và mặc định bị tắt. Việc đặt khả năng của nhà cung cấp thành true khô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 rỗng là lỗi và chủ động làm mới tại refresh_interval_ms; hãy thiết lập 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 tích hợp sẵn nhà cung cấp mô hình amazon-bedrock. Hãy đặt trực tiếp nhà cung cấp này làm model_provider; không giống nhà cung cấp tùy chỉnh, nhà cung cấp tích hợp sẵn này chỉ hỗ trợ các giá trị ghi đè lồng nhau cho hồ sơ và khu vực AWS.

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. Hãy đặt region thành khu vực Bedrock được hỗ trợ sẽ xử lý 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à phạm vi tính năng khả dụ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 thiết lập mục nào, CLI tương tác sẽ yêu cầu bạn chọn; codex exec thoát với 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ở của 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.

Tổ chức API sử dụng khả năng lưu trú dữ liệu

Các dự án được tạo với khả 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. Đối với không gian làm việc ChatGPT có khả năng lưu trú dữ liệu, bạn không cần nhà cung cấp tùy chỉnh; Codex tuân thủ thiết lập lưu trú của không gian làm việc khi bạn đăng nhập bằng ChatGPT.

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

Khả năng 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. Nhà cung cấp Chat Completions sẽ bỏ qua thiết lập này.

Chính sách phê duyệt và chế độ môi trường cô lập

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 độ môi trường cô lập (ả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 môi trường cô lập và phê duyệt thường dùng, Đường dẫn được bảo vệ trong thư mục gốc có thể ghi và Quyền truy cập mạng.

Codex và ChatGPT Work không còn hỗ trợ approval_policy = "untrusted". Xem Chuyển đổi từ chính sách phê duyệt untrusted đã ngừng hỗ trợ để tìm hiểu các thiết lập được hỗ trợ và cơ chế phê duyệt chặt chẽ hơn dựa trên dự án.

Để tìm hiểu các hồ sơ quyền beta 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 giữ phê duyệt tương tác thông thường cho một số trường hợp nhưng muốn các 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 bị từ chối theo hướng an toàn.

Thiết lập approvals_reviewer = "auto_review" để chuyển các yêu cầu phê duyệt tương tác đủ điều kiện qua quy trình đánh giá tự động. Thao tác này thay đổi người đánh giá chứ không thay đổi ranh giới môi trường cô lập.

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

approval_policy = "on-request"  # Other options: 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 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 đầy đủ cho hệ thống tệp và mạng, 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 môi trường cô lập (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 hợp đã được rút 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ẫu bao gồm. Mẫu bao gồm không khôi phục các biến đã bị loại trừ. Các khóa bộ lọc được hợp nhất mà không phân biệt chữ hoa chữ thường giữa các lớp cấu hình.

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

Codex áp dụng các loại trừ tự động trước, sau đó là cá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 bước loại trừ, 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 các cấu hình hiện có. Không kết hợp bất kỳ mảng nào trong số này 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

Hãy 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 mặc định bị tắt; 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 sự kiện nhưng không gửi dữ liệu nào. Các 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 trò chuyện, mô hình, thiết lập môi trường cô lập/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 các sự kiện nhật ký có cấu trúc cho các 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 môi trường cô lập/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/bị 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)

Số liệu OTel được phát ra

Khi quy trình số liệu OTel được bật, Codex phát 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 số liệu 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.

Số liệu

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 đến OpenAI. Việc này giúp phát hiện khi Codex hoạt động không chính xác 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 số liệu 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 số liệu độc lập với hoạt động 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 số liệu 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 thiết lập cờ phân tích trong cấu hình:

[analytics]
enabled = false

Mỗi số liệu bao gồm các trường riêng cùng các 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/số liệu)

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

Danh mục số liệu

Mỗi số liệu 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 số liệu bên dưới lược bỏ tiền tố codex.. Phần lớn tên số liệu được tập trung trong codex-rs/otel/src/metrics/names.rs; các số liệu dành riêng cho tính năng được phát ra bên ngoài tệp đó cũng được đưa vào đây. Nếu một số liệu 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ế hoặc bản vá mà codex đang cố áp dụng.

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

Số liệu cloud_requirements.fetch_attempt bao gồm các trường trigger, attempt, outcome và status_code. Số liệu 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 số liệu mcp.call và mcp.call.duration_ms bao gồm status; các lần phát sự kiện 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 mcp.call chỉ với status.

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

Số liệu shell_snapshot bao gồm success và, khi xảy ra lỗi, failure_reason.

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

Các số liệu external_agent_config.detect và external_agent_config.import bao gồm migration_type; hoạt động di chuyển kỹ năng cũng bao gồm skills_count.

Môi trường cô lập 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 các lỗi kiểm tra sơ bộ 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 sẽ hiển thị thông báo cho biết tính năng đã bị tắt và Codex sẽ 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 đầu ra "suy luận" gây nhiễu (ví dụ: trong nhật ký CI), bạn có thể ẩn đầu ra đó:

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 này:

show_raw_agent_reasoning = true

Chỉ bật nội dung suy luận thô nếu nội dung đó 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 (chẳng hạn 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 thay đổi nào có thể thấy được.

Thông báo

Sử dụng notify để kích hoạt một chương trình bên ngoài mỗi khi Codex phát ra 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, 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 tích hợp của TUI 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 thường gặp 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 rồi trỏ notify đến đó.

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 vào TUI và có thể 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 trong terminal (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 terminal ở trạng thái unfocused hay always.

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

Xem Tài liệu tham khảo về 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 chép lại 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 sẽ loại bỏ các mục cũ nhất và thu gọn tệp trong khi vẫn giữ lại những bản ghi mới nhất.

[history]
max_bytes = 104857600 # 100 MiB

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

Nếu sử dụng một tích hợp terminal/trình soạn thảo có hỗ trợ tính năng này, Codex có thể hiển thị các 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) rồi đư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 sau 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 không tìm thấy 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 những 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 sẽ 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 một tệp cho 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 có 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 đường dẫn vào làm đối số cuối cùng của lệnh.
• json_argument nối thêm một đối tượng JSON có target, path, appPath và location. Giá trị location là một đối tượng có các giá trị line và column được đánh số 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 này 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í cụ thể trong mã nguồn:

{
  "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, bao gồm cả tùy chọn riêng cho từng dự án.

Các tùy chọn TUI

Chạy codex mà không có lệnh con sẽ khởi chạy giao diện người dùng terminal tương tác (TUI). Codex cung cấp một số cấu hình dành riêng cho TUI trong [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 terminal
• 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 hoạt ảnh ASCII và hiệu ứng lấp lánh
• 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 terminal)
• tui.show_tooltips: hiển thị hoặc ẩn chú giải công cụ hướng dẫn trên màn hình chào mừng

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

Xem Tài liệu tham khảo về cấu hình để biết danh sách khóa đầy đủ.