Konfigurasi Lanjutan

Gunakan opsi berikut saat Anda memerlukan kontrol lebih besar atas penyedia, kebijakan, dan integrasi. Untuk memulai dengan cepat, lihat Dasar-dasar konfigurasi.

Untuk informasi latar belakang tentang panduan proyek, kemampuan yang dapat digunakan kembali, perintah garis miring khusus, alur kerja subagen, dan integrasi, lihat Penyesuaian. Untuk kunci konfigurasi, lihat Referensi Konfigurasi.

Profil

Profil memungkinkan Anda menyimpan lapisan konfigurasi bernama dan beralih di antaranya dari CLI. Saat Anda meneruskan --profile profile-name, Codex memuat ~/.codex/config.toml, lalu menimpanya dengan ~/.codex/profile-name.config.toml. Nama profil dapat berisi huruf, angka, tanda hubung, dan garis bawah.

Buat file TOML terpisah untuk setiap profil. Gunakan kunci konfigurasi tingkat atas dalam file profil; jangan menempatkannya di bawah [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"

Karena file profil merupakan lapisan di atas konfigurasi pengguna dasar dan di bawah konfigurasi proyek serta CLI, file tersebut hanya perlu berisi nilai yang berbeda dari konfigurasi dasar Anda. File profil juga dapat menimpa model_catalog_json; Codex menggunakan nilai profil ketika kedua file menetapkannya.

Di Codex 0.134.0 dan yang lebih baru, --profile tidak lagi membaca [profiles.profile-name] dari config.toml, dan pemilih tingkat atas profile = "profile-name" tidak lagi didukung. Pindahkan pengaturan profil lama ke ~/.codex/profile-name.config.toml, lalu hapus tabel [profiles.profile-name] yang sesuai dan pemilih profile = "profile-name" dari config.toml.

Penimpaan satu kali dari CLI

Selain mengedit ~/.codex/config.toml, Anda dapat menimpa konfigurasi untuk satu kali eksekusi dari CLI:

• Utamakan flag khusus jika tersedia (misalnya, --model).
• Gunakan -c / --config saat Anda perlu menimpa kunci apa pun.

Contoh:

# 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"]'

Catatan:

• Kunci dapat menggunakan notasi titik untuk menetapkan nilai bertingkat (misalnya, mcp_servers.context7.enabled=false).
• Nilai --config diurai sebagai TOML. Jika ragu, beri tanda kutip pada nilai agar shell tidak memecahnya pada spasi.
• Jika nilai tidak dapat diurai sebagai TOML, Codex memperlakukannya sebagai string.

Lokasi konfigurasi dan status

Codex menyimpan status lokalnya di bawah CODEX_HOME (default-nya ~/.codex).

File umum yang mungkin Anda temukan di sana:

• config.toml (konfigurasi lokal Anda)
• auth.json (jika Anda menggunakan penyimpanan kredensial berbasis file) atau rantai kunci/keyring OS Anda
• history.jsonl (jika persistensi riwayat diaktifkan)
• Status per pengguna lainnya, seperti log dan cache

Untuk detail autentikasi (termasuk mode penyimpanan kredensial), lihat Autentikasi. Untuk daftar lengkap kunci konfigurasi, lihat Referensi Konfigurasi.

Untuk default, aturan, dan keterampilan bersama yang disimpan dalam repo atau jalur sistem, lihat Konfigurasi Tim.

Jika Anda hanya perlu mengarahkan penyedia bawaan OpenAI ke proksi LLM, router, atau proyek dengan residensi data yang diaktifkan, tetapkan openai_base_url dalam config.toml alih-alih mendefinisikan penyedia baru. Tindakan ini mengubah URL dasar untuk penyedia bawaan openai tanpa memerlukan entri model_providers.<id> terpisah.

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

File konfigurasi proyek (.codex/config.toml)

Selain konfigurasi pengguna, Codex membaca penimpaan dalam cakupan proyek dari file .codex/config.toml di dalam repo Anda. Codex menelusuri dari akar proyek hingga direktori kerja saat ini dan memuat setiap .codex/config.toml yang ditemukan. Jika beberapa file mendefinisikan kunci yang sama, file yang paling dekat dengan direktori kerja Anda akan berlaku.

Demi keamanan, Codex hanya memuat file konfigurasi dalam cakupan proyek ketika proyek dipercaya. Jika proyek tidak dipercaya, Codex mengabaikan lapisan .codex/ proyek, termasuk .codex/config.toml, hook lokal proyek, dan aturan lokal proyek. Lapisan pengguna dan sistem tetap terpisah dan tetap dimuat.

Jalur relatif di dalam konfigurasi proyek (misalnya, model_instructions_file) diselesaikan relatif terhadap folder .codex/ yang berisi config.toml.

File konfigurasi proyek tidak dapat menimpa pengaturan yang mengalihkan kredensial, mengubah metadata permintaan aplikasi milik host, mengubah autentikasi penyedia, memilih profil konfigurasi, atau menjalankan perintah notifikasi/telemetri lokal mesin. Codex mengabaikan kunci berikut dalam .codex/config.toml lokal proyek dan menampilkan peringatan saat startup ketika menemukannya: openai_base_url, chatgpt_base_url, apps_mcp_product_sku, model_provider, model_providers, notify, profile, profiles, experimental_realtime_ws_base_url, dan otel. Tetapkan kunci penyedia, notifikasi, dan telemetri dalam ~/.codex/config.toml tingkat pengguna Anda; pilih profil konfigurasi dengan --profile profile-name dan ~/.codex/profile-name.config.toml.

Hook

Codex juga dapat memuat hook siklus hidup dari file hooks.json atau tabel [hooks] sebaris dalam file config.toml yang berada di samping lapisan konfigurasi aktif.

Dalam praktiknya, empat lokasi yang paling berguna adalah:

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

Hook lokal proyek hanya dimuat ketika lapisan .codex/ proyek dipercaya. Hook tingkat pengguna tetap independen dari kepercayaan proyek.

Hook TOML sebaris menggunakan struktur peristiwa yang sama seperti 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"

Jika satu lapisan berisi hooks.json dan [hooks] sebaris, Codex memuat keduanya dan menampilkan peringatan. Utamakan satu representasi per lapisan.

Untuk daftar peristiwa, bidang input, perilaku output, dan batasan saat ini, lihat Hook.

Peran agen ([agents] dalam config.toml)

Untuk konfigurasi peran subagen ([agents] dalam config.toml), lihat Subagen.

Deteksi akar proyek

Codex menemukan konfigurasi proyek (misalnya, lapisan .codex/ dan AGENTS.md) dengan menelusuri ke atas dari direktori kerja hingga mencapai akar proyek.

Secara default, Codex memperlakukan direktori yang berisi .git sebagai akar proyek. Untuk menyesuaikan perilaku ini, tetapkan project_root_markers dalam config.toml:

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

Tetapkan project_root_markers = [] untuk melewati pencarian direktori induk dan memperlakukan direktori kerja saat ini sebagai akar proyek.

Penyedia model khusus

Penyedia model menentukan cara Codex terhubung ke model (URL dasar, API wire, autentikasi, dan header HTTP opsional). Penyedia khusus tidak dapat menggunakan kembali ID penyedia bawaan yang dicadangkan: openai, ollama, dan lmstudio.

Tentukan penyedia tambahan dan arahkan model_provider kepadanya:

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"

Jika penyedia khusus mendukung endpoint pencarian web mandiri, nyatakan kemampuan tersebut dalam konfigurasi penyedianya:

[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

Pengaturan ini secara default bernilai false untuk penyedia khusus. Pencarian web mandiri masih dalam pengembangan dan dinonaktifkan secara default. Menetapkan kemampuan penyedia ke true tidak mengaktifkannya: penyedia harus mendukung endpoint yang kompatibel, dan model serta runtime yang dipilih harus mendukung pencarian mandiri. Mode web_search yang dikonfigurasi dan pembatasan pencarian terkelola tetap berlaku.

Tambahkan header permintaan bila diperlukan:

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

Gunakan autentikasi berbasis perintah ketika penyedia memerlukan Codex untuk mengambil token bearer dari pembantu kredensial eksternal:

[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

Perintah autentikasi tidak menerima stdin dan harus mencetak token ke stdout. Codex memangkas spasi kosong di sekelilingnya, memperlakukan token kosong sebagai kesalahan, dan menyegarkannya secara proaktif pada refresh_interval_ms; tetapkan refresh_interval_ms = 0 untuk menyegarkan hanya setelah autentikasi dicoba ulang. Jangan gabungkan [model_providers.<id>.auth] dengan env_key, experimental_bearer_token, atau requires_openai_auth.

Penyedia Amazon Bedrock

Codex menyertakan penyedia model bawaan amazon-bedrock. Tetapkan langsung sebagai model_provider; tidak seperti penyedia khusus, penyedia bawaan ini hanya mendukung penimpaan profil dan wilayah AWS bertingkat.

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

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

Jika Anda menghilangkan profile, Codex menggunakan rantai kredensial AWS standar. Tetapkan region ke wilayah Bedrock yang didukung dan harus menangani permintaan.

Untuk alur penyiapan lengkap, opsi autentikasi, model yang didukung, dan ketersediaan fitur, lihat Menggunakan ChatGPT Work dan Codex dengan Amazon Bedrock.

Mode OSS (penyedia lokal)

Codex dapat berjalan dengan penyedia "sumber terbuka" lokal seperti Ollama atau LM Studio saat Anda meneruskan --oss. Pilih salah satunya untuk satu kali eksekusi dengan --local-provider, atau tetapkan oss_provider sebagai default. Jika tidak ada yang ditetapkan, CLI interaktif meminta Anda memilih; codex exec keluar dengan kesalahan.

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

Penyedia Azure dan penyesuaian per penyedia

[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

Untuk mengubah URL dasar penyedia bawaan OpenAI, gunakan openai_base_url; jangan buat [model_providers.openai] karena Anda tidak dapat menimpa ID penyedia bawaan.

Pelanggan ChatGPT yang menggunakan residensi data

Proyek yang dibuat dengan residensi data diaktifkan dapat membuat penyedia model untuk memperbarui base_url dengan prefiks yang benar.

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

Penalaran model, tingkat detail, dan batas

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 hanya berlaku untuk penyedia yang menggunakan Responses API. Penyedia Chat Completions akan mengabaikan pengaturan tersebut.

Kebijakan persetujuan dan mode sandbox

Pilih tingkat keketatan persetujuan (memengaruhi kapan Codex dijeda) dan tingkat sandbox (memengaruhi akses file/jaringan).

Untuk detail operasional yang perlu diperhatikan saat mengedit config.toml, lihat Kombinasi umum sandbox dan persetujuan, Jalur yang dilindungi dalam akar yang dapat ditulisi, dan Akses jaringan.

Untuk profil izin beta yang mengonfigurasi akses sistem file dan jaringan secara bersamaan, lihat Izin.

Anda juga dapat menggunakan kebijakan persetujuan terperinci (approval_policy = { granular = { ... } }) untuk mengizinkan atau menolak otomatis setiap kategori perintah. Ini berguna jika Anda menginginkan persetujuan interaktif normal untuk beberapa kasus, tetapi menginginkan kasus lainnya, seperti request_permissions atau perintah skrip keterampilan, ditolak otomatis secara aman.

Tetapkan approvals_reviewer = "auto_review" untuk mengarahkan permintaan persetujuan interaktif yang memenuhi syarat melalui peninjauan otomatis. Ini mengubah peninjau, bukan batas sandbox.

Gunakan [auto_review].policy untuk instruksi kebijakan peninjau lokal. guardian_policy_config terkelola lebih diprioritaskan.

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

Profil izin bernama

Untuk profil bawaan, sintaks profil khusus, dan model konfigurasi sistem file serta jaringan lengkap, lihat Izin.

Untuk daftar kunci lengkap dan batasan persyaratan, lihat Referensi Konfigurasi dan Konfigurasi terkelola.

Nonaktifkan sandbox sepenuhnya (gunakan hanya jika lingkungan Anda sudah mengisolasi proses):

sandbox_mode = "danger-full-access"

Kebijakan lingkungan shell

shell_environment_policy mengontrol variabel lingkungan mana yang diteruskan Codex ke perintah yang dijalankan. Mulai dengan lingkungan kosong menggunakan inherit = "none", atau warisi kumpulan yang telah dipangkas menggunakan inherit = "core". Tambahkan nilai eksplisit dan filter berkunci untuk menghindari penerusan rahasia yang tidak diperlukan ke perintah yang dijalankan.

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

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

Pola filter tidak peka huruf besar-kecil dan mendukung * serta ?. Gunakan "exclude" untuk menghapus variabel yang cocok. Jika pola apa pun menggunakan "include", Codex hanya mempertahankan variabel yang cocok dengan pola penyertaan. Penyertaan tidak memulihkan variabel yang sudah dikecualikan. Kunci filter digabungkan tanpa membedakan huruf besar-kecil di seluruh lapisan konfigurasi.

ignore_default_excludes secara default bernilai true, sehingga Codex tidak secara otomatis menghapus nama variabel yang berisi KEY, SECRET, atau TOKEN. Tetapkan ke false untuk menerapkan pengecualian otomatis tersebut sebelum filter eksplisit Anda dijalankan.

Codex menerapkan pengecualian otomatis terlebih dahulu, lalu pengecualian khusus, nilai dari set, dan terakhir daftar izin pola penyertaan. Karena set dijalankan setelah pengecualian, ini dapat memulihkan variabel yang dikecualikan. Daftar izin pola penyertaan tetap dapat menghapus nilai yang dipulihkan tersebut.

Array lama exclude dan include_only tetap didukung untuk konfigurasi yang sudah ada. Jangan gabungkan salah satu array dengan [shell_environment_policy.filters] dalam lapisan konfigurasi yang sama; Codex menolak kombinasi tersebut.

Server MCP

Lihat dokumentasi MCP khusus untuk detail konfigurasi.

Observabilitas dan telemetri

Aktifkan ekspor log OpenTelemetry (OTel) untuk melacak eksekusi Codex (permintaan API, SSE/peristiwa, perintah, persetujuan/hasil alat). Dinonaktifkan secara default; aktifkan secara eksplisit melalui [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

Pilih pengekspor:

[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" }
}}

Jika exporter = "none", Codex merekam peristiwa tetapi tidak mengirim apa pun. Pengekspor mengelompokkan data secara asinkron dan mengirimkan sisanya saat dimatikan. Metadata peristiwa mencakup nama layanan, versi CLI, tag lingkungan, id percakapan, model, pengaturan sandbox/persetujuan, dan bidang per peristiwa (lihat Referensi Konfigurasi).

Data yang dipancarkan

Codex memancarkan peristiwa log terstruktur untuk eksekusi dan penggunaan alat. Jenis peristiwa yang mewakili meliputi:

• codex.conversation_starts (model, pengaturan penalaran, kebijakan sandbox/persetujuan)
• codex.api_request (percobaan, status/keberhasilan, durasi, dan detail kesalahan)
• codex.sse_event (jenis peristiwa aliran, keberhasilan/kegagalan, durasi, serta jumlah token pada response.completed)
• codex.websocket_request dan codex.websocket_event (durasi permintaan serta jenis/keberhasilan/kesalahan per pesan)
• codex.user_prompt (panjang; konten disamarkan kecuali diaktifkan secara eksplisit)
• codex.tool_decision (disetujui/ditolak dan apakah keputusan berasal dari konfigurasi atau pengguna)
• codex.tool_result (durasi, keberhasilan, cuplikan output)

Metrik OTel yang dipancarkan

Ketika pipeline metrik OTel diaktifkan, Codex memancarkan penghitung dan histogram durasi untuk aktivitas API, aliran, dan alat.

Setiap metrik di bawah juga menyertakan tag metadata default: auth_mode, originator, session_source, model, dan app.version.

Untuk panduan keamanan dan privasi lebih lanjut terkait telemetri, lihat Keamanan.

Metrik

Secara default, Codex secara berkala mengirimkan sejumlah kecil data penggunaan dan kesehatan anonim kembali ke OpenAI. Hal ini membantu mendeteksi saat Codex tidak berfungsi dengan benar dan menunjukkan fitur serta opsi konfigurasi yang digunakan, sehingga tim Codex dapat berfokus pada hal yang paling penting. Metrik ini tidak berisi informasi pengenal pribadi (PII). Pengumpulan metrik tidak bergantung pada ekspor log/jejak OTel.

Jika Anda ingin menonaktifkan pengumpulan metrik sepenuhnya pada aplikasi desktop ChatGPT, Codex CLI, dan ekstensi IDE di suatu mesin, tetapkan flag analitik dalam konfigurasi Anda:

[analytics]
enabled = false

Setiap metrik mencakup bidangnya sendiri beserta bidang konteks default di bawah ini.

Bidang konteks default (berlaku untuk setiap peristiwa/metrik)

• auth_mode: swic | api | unknown.
• model: nama model yang digunakan.
• app.version: versi Codex.

Katalog metrik

Setiap metrik mencakup bidang wajib beserta bidang konteks default di atas. Nama metrik di bawah menghilangkan prefiks codex.. Sebagian besar nama metrik dipusatkan dalam codex-rs/otel/src/metrics/names.rs; metrik khusus fitur yang dipancarkan di luar file tersebut juga disertakan di sini. Jika suatu metrik menyertakan bidang tool, bidang tersebut mencerminkan alat internal yang digunakan (misalnya, apply_patch atau shell) dan tidak berisi perintah shell atau patch sebenarnya yang hendak diterapkan oleh codex.

Runtime dan transportasi model

Metrik cloud_requirements.fetch_attempt menyertakan bidang trigger, attempt, outcome, dan status_code. Metrik cloud_requirements.fetch_final menyertakan bidang trigger, outcome, reason, attempt_count, dan status_code.

Aktivitas giliran dan alat

Metrik mcp.call dan mcp.call.duration_ms menyertakan status; emisi pemanggilan alat normal juga menyertakan tool, serta connector_id dan connector_name jika tersedia. Pemanggilan MCP Codex Apps yang diblokir dapat memancarkan mcp.call hanya dengan status.

Utas, tugas, dan fitur

Metrik shell_snapshot menyertakan success dan, jika gagal, failure_reason.

Memori dan status lokal

Metrik external_agent_config.detect dan external_agent_config.import menyertakan migration_type; migrasi keterampilan juga menyertakan skills_count.

Sandbox Windows

Metrik kegagalan penyiapan dengan hak akses yang ditingkatkan mencakup code dan message ketika detail kegagalan penyiapan Windows tersedia, dan dapat mencakup originator ketika dipancarkan dari jalur penyiapan bersama. Metrik windows_sandbox.legacy_setup_preflight_failed mencakup originator ketika dipancarkan dari jalur penyiapan bersama, tetapi kegagalan pemeriksaan awal untuk prompt cadangan mungkin tidak menyertakan bidang apa pun.

Kontrol umpan balik

Secara default, klien lokal memungkinkan pengguna mengirimkan umpan balik dari /feedback. Untuk menonaktifkan pengumpulan umpan balik di aplikasi desktop ChatGPT, Codex CLI, dan ekstensi IDE pada suatu mesin, perbarui konfigurasi Anda:

[feedback]
enabled = false

Jika dinonaktifkan, /feedback menampilkan pesan bahwa fitur dinonaktifkan dan Codex menolak pengiriman umpan balik.

Menyembunyikan atau menampilkan peristiwa penalaran

Jika Anda ingin mengurangi keluaran "penalaran" yang mengganggu (misalnya dalam log CI), Anda dapat menyembunyikannya:

hide_agent_reasoning = true

Jika Anda ingin menampilkan konten penalaran mentah saat model menghasilkannya:

show_raw_agent_reasoning = true

Aktifkan penalaran mentah hanya jika hal tersebut dapat diterima dalam alur kerja Anda. Beberapa model/penyedia (seperti gpt-oss) tidak menghasilkan penalaran mentah; dalam hal ini, pengaturan tersebut tidak menimbulkan efek yang terlihat.

Notifikasi

Gunakan notify untuk memicu program eksternal setiap kali Codex memancarkan peristiwa yang didukung (saat ini hanya agent-turn-complete). Fitur ini berguna untuk notifikasi pop-up desktop, webhook obrolan, pembaruan CI, atau pemberitahuan melalui saluran lain yang tidak dicakup oleh notifikasi bawaan TUI.

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

Contoh notify.py (dipotong) yang bereaksi terhadap 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())

Skrip menerima satu argumen JSON. Bidang yang umum mencakup:

• type (saat ini agent-turn-complete)
• thread-id (pengidentifikasi sesi)
• turn-id (pengidentifikasi giliran)
• cwd (direktori kerja)
• input-messages (pesan pengguna yang memicu giliran tersebut)
• last-assistant-message (teks pesan terakhir asisten)

Tempatkan skrip di lokasi tertentu pada disk dan arahkan notify ke lokasi tersebut.

notify dibandingkan dengan tui.notifications

• notify menjalankan program eksternal (cocok untuk webhook, pemberi notifikasi desktop, dan hook CI).
• tui.notifications merupakan fitur bawaan TUI dan secara opsional dapat memfilter berdasarkan jenis peristiwa (misalnya, agent-turn-complete dan approval-requested).
• tui.notification_method mengontrol cara TUI memancarkan notifikasi terminal (auto, osc9, atau bel).
• tui.notification_condition mengontrol apakah notifikasi TUI hanya dipicu ketika terminal berada dalam kondisi unfocused atau always.

Dalam mode auto, Codex mengutamakan notifikasi OSC 9 (urutan escape terminal yang ditafsirkan oleh beberapa terminal sebagai notifikasi desktop) dan menggunakan BEL (\x07) sebagai cadangan jika tidak tersedia.

Lihat Referensi Konfigurasi untuk mengetahui kunci yang tepat.

Persistensi riwayat

Secara default, Codex menyimpan transkrip sesi lokal di CODEX_HOME (misalnya, ~/.codex/history.jsonl). Untuk menonaktifkan persistensi riwayat lokal:

[history]
persistence = "none"

Untuk membatasi ukuran file riwayat, tetapkan history.max_bytes. Ketika ukuran file melampaui batas, Codex menghapus entri paling lama dan memadatkan file sambil mempertahankan catatan terbaru.

[history]
max_bytes = 104857600 # 100 MiB

Sitasi yang dapat diklik

Jika Anda menggunakan integrasi terminal/editor yang mendukungnya, Codex dapat merender sitasi file sebagai tautan yang dapat diklik. Konfigurasikan file_opener untuk memilih skema URI yang digunakan Codex:

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

Contoh: sitasi seperti /home/user/project/main.py:42 dapat ditulis ulang menjadi tautan vscode://file/...:42 yang dapat diklik.

Penemuan instruksi proyek

Codex membaca AGENTS.md (dan file terkait) serta menyertakan panduan proyek dalam jumlah terbatas pada giliran pertama suatu sesi. Dua opsi mengontrol cara kerjanya:

• project_doc_max_bytes: jumlah yang dibaca dari setiap file AGENTS.md
• project_doc_fallback_filenames: nama file tambahan yang akan dicoba ketika AGENTS.md tidak ditemukan pada suatu tingkat direktori

Untuk panduan terperinci, lihat Instruksi khusus dengan AGENTS.md.

Desktop

Opsi di bagian ini hanya berlaku untuk aplikasi desktop ChatGPT.

Menambahkan penangan file khusus

Dalam ~/.codex/config.toml tingkat pengguna Anda, tambahkan entri di bawah desktop.custom_file_handlers untuk membuka file di editor atau peluncur internal yang secara default tidak didukung oleh aplikasi desktop ChatGPT. Setiap entri menambahkan target editor ke menu Buka di pada aplikasi. Aplikasi menampilkan target ketika command merupakan jalur absolut yang ada atau dapat ditemukan dari PATH milik aplikasi.

Contoh berikut menunjukkan tiga cara meneruskan file ke penangan:

# 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"

Simpan config.toml, lalu mulai ulang aplikasi desktop ChatGPT.

ID penangan adalah segmen terakhir dari header tabel TOML. ID harus berisi 1–64 karakter, diawali huruf atau angka ASCII, dan karakter lainnya hanya boleh berupa huruf ASCII, angka, titik, garis bawah, atau tanda hubung. Aplikasi mengekspos ID dengan awalan custom:; misalnya, company_editor menjadi custom:company_editor. Apit ID yang mengandung titik dengan tanda kutip agar TOML tidak menafsirkannya sebagai tabel bertingkat. Contoh:

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

Setiap penangan mendukung bidang berikut:

Nilai input mengontrol apa yang mengikuti args:

• path menambahkan jalur sebagai argumen perintah terakhir.
• json_argument menambahkan objek JSON dengan target, path, appPath, dan location. Nilai location adalah objek dengan nilai line dan column yang berbasis 1, atau null.
• json_stdin menulis objek JSON ke masukan standar alih-alih menambahkannya sebagai argumen. Objek ini juga menyertakan hostConfig, remoteWorkspaceRoot, dan remotePath; bidang-bidang ini bernilai null ketika tidak berlaku.

Misalnya, company_editor dapat menerima argumen ini ketika pengguna membuka lokasi sumber tertentu:

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

Memilih penangan khusus sebagai editor pilihan akan menyimpan pilihan dengan cara yang sama seperti memilih editor bawaan, termasuk preferensi per proyek.

Opsi TUI

Menjalankan codex tanpa subperintah akan meluncurkan antarmuka pengguna terminal (TUI) interaktif. Codex menyediakan sejumlah konfigurasi khusus TUI di bawah [tui], termasuk:

• tui.notifications: mengaktifkan/menonaktifkan notifikasi (atau membatasinya pada jenis tertentu)
• tui.notification_method: memilih auto, osc9, atau bel untuk notifikasi terminal
• tui.notification_condition: memilih unfocused atau always untuk menentukan kapan notifikasi dipicu
• tui.animations: mengaktifkan/menonaktifkan animasi ASCII dan efek kilau
• tui.alternate_screen: mengontrol penggunaan layar alternatif (tetapkan ke never untuk mempertahankan riwayat gulir terminal)
• tui.show_tooltips: menampilkan atau menyembunyikan tooltip orientasi pada layar selamat datang

Nilai default tui.notification_method adalah auto. Dalam mode auto, Codex mengutamakan notifikasi OSC 9 (urutan escape terminal yang ditafsirkan oleh beberapa terminal sebagai notifikasi desktop) ketika terminal tampaknya mendukungnya, dan menggunakan BEL (\x07) sebagai cadangan jika tidak tersedia.

Lihat Referensi Konfigurasi untuk daftar lengkap kunci.