Konfigurasi Lanjutan

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

Untuk mengetahui latar belakang tentang panduan proyek, kemampuan yang dapat digunakan kembali, perintah garis miring kustom, 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 teratas dalam file profil; jangan menempatkannya di bawah [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"

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

Di Codex 0.134.0 dan versi lebih baru, --profile tidak lagi membaca [profiles.profile-name] dari config.toml, dan pemilih profile = "profile-name" tingkat teratas 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 sekali pakai dari CLI

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

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

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, apit nilai dengan tanda kutip agar shell Anda tidak memisahkannya 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 (nilai default-nya adalah ~/.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 nilai default, aturan, dan keterampilan bersama yang disimpan ke dalam repo atau jalur sistem, lihat Konfigurasi Tim.

Jika Anda hanya perlu mengarahkan penyedia OpenAI bawaan ke proksi LLM, router, atau proyek yang mengaktifkan residensi data, tetapkan openai_base_url di config.toml alih-alih menentukan penyedia baru. Tindakan ini mengubah URL dasar untuk penyedia openai bawaan 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 Anda, Codex membaca penimpaan khusus proyek dari file .codex/config.toml di dalam repo Anda. Codex menelusuri dari root proyek hingga direktori kerja Anda saat ini dan memuat setiap .codex/config.toml yang ditemukannya. Jika beberapa file menentukan kunci yang sama, file yang paling dekat dengan direktori kerja Anda akan berlaku.

Demi keamanan, Codex hanya memuat file konfigurasi khusus proyek saat 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 dimulai 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] inline 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 saat lapisan .codex/ proyek dipercaya. Hook tingkat pengguna tetap tidak bergantung pada kepercayaan proyek.

Hook TOML inline 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 sekaligus [hooks] inline, Codex memuat keduanya dan menampilkan peringatan. Utamakan satu representasi per lapisan.

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

Peran agen ([agents] dalam config.toml)

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

Deteksi root proyek

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

Secara default, Codex menganggap direktori yang berisi .git sebagai root 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 root proyek.

Penyedia model kustom

Penyedia model menentukan cara Codex terhubung ke model (URL dasar, API protokol, autentikasi, dan header HTTP opsional). Penyedia kustom 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 kustom 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 kustom. 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 saat penyedia memerlukan Codex 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 sekitarnya, memperlakukan token kosong sebagai kesalahan, dan menyegarkan secara proaktif pada refresh_interval_ms; tetapkan refresh_interval_ms = 0 agar penyegaran hanya dilakukan setelah percobaan ulang autentikasi. Jangan gabungkan [model_providers.<id>.auth] dengan env_key, experimental_bearer_token, atau requires_openai_auth.

Penyedia Amazon Bedrock

Codex menyertakan penyedia model amazon-bedrock bawaan. Tetapkan langsung sebagai model_provider; tidak seperti penyedia kustom, 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 proses dengan --local-provider, atau tetapkan oss_provider sebagai default. Jika keduanya tidak ditetapkan, CLI interaktif meminta Anda memilih; codex exec akan keluar dengan kesalahan.

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

Penyedia Azure dan penyetelan 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 bagi penyedia OpenAI bawaan, gunakan openai_base_url; jangan membuat [model_providers.openai] karena Anda tidak dapat menimpa ID penyedia bawaan.

Organisasi API yang menggunakan residensi data

Proyek yang dibuat dengan residensi data aktif dapat membuat penyedia model untuk memperbarui base_url dengan prefiks yang tepat. Untuk ruang kerja ChatGPT dengan residensi data, penyedia kustom tidak diperlukan; Codex mematuhi pengaturan residensi ruang kerja saat Anda masuk dengan ChatGPT.

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, verbositas, 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 root yang dapat ditulis, dan Akses jaringan.

Codex dan ChatGPT Work tidak lagi mendukung approval_policy = "untrusted". Lihat Bermigrasi dari kebijakan persetujuan untrusted yang telah dihentikan untuk pengaturan yang didukung dan persetujuan yang lebih ketat berdasarkan proyek.

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 prompt. Ini berguna saat Anda menginginkan persetujuan interaktif normal untuk beberapa kasus, tetapi menginginkan kasus lainnya, seperti prompt request_permissions atau skrip keterampilan, gagal secara tertutup dan otomatis.

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 yang dikelola memiliki prioritas.

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

Profil izin bernama

Untuk profil bawaan, sintaks profil kustom, serta model konfigurasi sistem file dan 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 telah mengisolasi proses):

sandbox_mode = "danger-full-access"

Kebijakan lingkungan shell

shell_environment_policy mengontrol variabel lingkungan yang diteruskan Codex ke perintah yang dijalankan. Mulailah dengan lingkungan kosong menggunakan inherit = "none", atau warisi kumpulan yang telah dipangkas menggunakan inherit = "core". Tambahkan nilai eksplisit dan filter berdasarkan kunci agar rahasia yang tidak diperlukan tidak diteruskan 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 suatu pola menggunakan "include", Codex hanya mempertahankan variabel yang cocok dengan pola penyertaan. Penyertaan tidak memulihkan variabel yang telah dikecualikan. Kunci filter digabungkan tanpa membedakan huruf besar-kecil di seluruh lapisan konfigurasi.

ignore_default_excludes secara default bernilai true, sehingga Codex tidak 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 kustom, nilai dari set, dan terakhir daftar izin pola penyertaan. Karena set dijalankan setelah pengecualian, pengaturan ini dapat memulihkan variabel yang dikecualikan. Daftar izin pola penyertaan tetap dapat menghapus nilai yang dipulihkan tersebut.

Array exclude dan include_only yang lebih lama 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 proses Codex (permintaan API, SSE/peristiwa, prompt, 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 eksportir:

[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 mencatat peristiwa tetapi tidak mengirim apa pun. Eksportir memproses batch secara asinkron dan melakukan flush 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 proses dan penggunaan alat. Jenis peristiwa yang mewakili antara lain:

• codex.conversation_starts (model, pengaturan penalaran, kebijakan sandbox/persetujuan)
• codex.api_request (percobaan, status/keberhasilan, durasi, dan detail kesalahan)
• codex.sse_event (jenis peristiwa stream, 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

Saat alur metrik OTel diaktifkan, Codex memancarkan penghitung dan histogram durasi untuk aktivitas API, stream, dan alat.

Setiap metrik di bawah juga mencakup 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 mengirim sedikit data penggunaan dan kesehatan anonim kembali ke OpenAI. Data 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 identitas 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 di codex-rs/otel/src/metrics/names.rs; metrik khusus fitur yang dipancarkan di luar file tersebut juga disertakan di sini. Jika suatu metrik mencakup bidang tool, bidang tersebut mencerminkan alat internal yang digunakan (misalnya, apply_patch atau shell) dan tidak berisi perintah shell atau patch aktual yang coba diterapkan oleh codex.

Runtime dan transportasi model

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

Aktivitas giliran dan alat

Metrik mcp.call dan mcp.call.duration_ms mencakup status; emisi panggilan alat normal juga mencakup tool, beserta connector_id dan connector_name jika tersedia. Panggilan MCP Codex Apps yang diblokir dapat memancarkan mcp.call hanya dengan status.

Utas, tugas, dan fitur

Metrik shell_snapshot mencakup success dan, jika gagal, failure_reason.

Memori dan status lokal

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

Sandbox Windows

Metrik kegagalan penyiapan dengan hak istimewa yang ditingkatkan mencakup code dan message ketika detail kegagalan penyiapan Windows tersedia, dan dapat mencakup originator ketika dihasilkan dari jalur penyiapan bersama. Metrik windows_sandbox.legacy_setup_preflight_failed mencakup originator ketika dihasilkan dari jalur penyiapan bersama, tetapi kegagalan pemeriksaan awal perintah fallback 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 komputer, perbarui konfigurasi Anda:

[feedback]
enabled = false

Saat 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 untuk alur kerja Anda. Beberapa model/penyedia (seperti gpt-oss) tidak menghasilkan penalaran mentah; dalam hal ini, pengaturan tersebut tidak memiliki efek yang terlihat.

Notifikasi

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

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

Contoh notify.py (dipotong) yang merespons 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 meliputi:

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

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

notify dibandingkan dengan tui.notifications

• notify menjalankan program eksternal (cocok untuk webhook, pemberi notifikasi desktop, dan kait CI).
• tui.notifications merupakan fitur bawaan TUI dan dapat memfilter berdasarkan jenis peristiwa secara opsional (misalnya, agent-turn-complete dan approval-requested).
• tui.notification_method mengontrol cara TUI menghasilkan notifikasi terminal (auto, osc9, atau bel).
• tui.notification_condition mengontrol apakah notifikasi TUI hanya dipicu ketika terminal berada dalam keadaan 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 fallback jika tidak tersedia.

Lihat Referensi Konfigurasi untuk mengetahui kunci yang tepat.

Persistensi riwayat

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

[history]
persistence = "none"

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

[history]
max_bytes = 104857600 # 100 MiB

Kutipan yang dapat diklik

Jika Anda menggunakan integrasi terminal/editor yang mendukungnya, Codex dapat merender kutipan 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: kutipan 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 pengaturan mengontrol cara kerjanya:

• project_doc_max_bytes: jumlah konten 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 milik aplikasi. Aplikasi menampilkan target ketika command merupakan jalur absolut yang ada atau dapat ditemukan dari PATH aplikasi.

Contoh berikut menunjukkan tiga cara untuk 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 tersebut 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 berisi 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 merupakan objek dengan nilai line dan column berbasis 1, atau null.
• json_stdin menulis objek JSON ke masukan standar alih-alih menambahkan argumen. Objek tersebut juga menyertakan hostConfig, remoteWorkspaceRoot, dan remotePath; bidang-bidang ini bernilai null jika 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 mempertahankan pilihan tersebut dengan cara yang sama seperti ketika memilih editor bawaan, termasuk preferensi per proyek.

Opsi TUI

Menjalankan codex tanpa subperintah akan meluncurkan antarmuka pengguna terminal (TUI) interaktif. Codex menyediakan beberapa 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 (atur ke never untuk mempertahankan riwayat gulir terminal)
• tui.show_tooltips: menampilkan atau menyembunyikan keterangan alat pengenalan 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 tampak mendukungnya, dan menggunakan BEL (\x07) sebagai fallback jika tidak tersedia.

Lihat Referensi Konfigurasi untuk daftar lengkap kunci.