高度な設定

プロバイダー、ポリシー、連携をより細かく制御するには、これらのオプションを使用します。すぐに始めるには、設定の基本を参照してください。

プロジェクトのガイダンス、再利用可能な機能、カスタムスラッシュコマンド、サブエージェントのワークフロー、連携について詳しくは、カスタマイズを参照してください。設定キーについては、設定リファレンスを参照してください。

プロファイル

プロファイルを使うと、名前を付けた設定レイヤーを保存し、CLI から切り替えられます。 --profile profile-name を指定すると、Codex は ~/.codex/config.toml を読み込み、 その上に ~/.codex/profile-name.config.toml を適用します。 プロファイル名には、英字、数字、ハイフン、アンダースコアを使用できます。

プロファイルごとに個別の TOML ファイルを作成します。 プロファイルのファイルではトップレベルの設定キーを使用し、[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"

プロファイルのファイルは、ユーザーの基本設定より優先順位が高く、プロジェクト設定や CLI 設定より低いレイヤーです。 そのため、基本設定と異なる値だけを指定すれば十分です。 プロファイルのファイルでは model_catalog_json もオーバーライドできます。 両方のファイルに設定されている場合、Codex はプロファイル側の値を使用します。

Codex 0.134.0 以降では、--profile は config.toml から [profiles.profile-name] を読み込まなくなりました。 トップレベルの profile = "profile-name" セレクターもサポートされなくなりました。 従来のプロファイル設定を ~/.codex/profile-name.config.toml に移行してください。 その後、config.toml から、 対応する [profiles.profile-name] テーブルと profile = "profile-name" セレクターを削除してください。

CLI からの 1 回限りのオーバーライド

~/.codex/config.toml を編集する方法のほか、CLI から 1 回の実行に限って設定をオーバーライドすることもできます：

• 専用フラグがある場合は、そちらを優先してください（例：--model）。
• 任意のキーをオーバーライドする必要がある場合は、-c / --config を使用します。

例：

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

注意事項：

• キーにドット記法を使用すると、ネストされた値を設定できます（例：mcp_servers.context7.enabled=false）。
• --config の値は TOML として解析されます。迷った場合は、シェルが値を空白で分割しないように、値を引用符で囲んでください。
• 値を TOML として解析できない場合、Codex は文字列として扱います。

設定と状態の保存場所

Codex はローカルの状態を CODEX_HOME 配下に保存します（デフォルトは ~/.codex）。

ここに保存される主なファイルなどは、次のとおりです：

• config.toml（ローカル設定）
• auth.json（ファイルベースで認証情報を保存する場合）、または OS のキーチェーン／キーリング
• history.jsonl（履歴の永続化が有効な場合）
• ログやキャッシュなど、その他のユーザーごとの状態

認証情報の保存モードを含む認証の詳細については、認証を参照してください。設定キーの一覧については、設定リファレンスを参照してください。

リポジトリにチェックインするかシステムパスに配置する、共有のデフォルト設定、ルール、スキルについては、チーム設定を参照してください。

組み込みの OpenAI プロバイダーを LLM プロキシ、ルーター、またはデータレジデンシーが有効なプロジェクトに接続するだけなら、新しいプロバイダーを定義する代わりに、config.toml で openai_base_url を設定します。これにより、別途 model_providers.<id> エントリを作成することなく、組み込みの openai プロバイダーのベース URL を変更できます。

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

プロジェクト設定ファイル（.codex/config.toml）

ユーザー設定に加えて、Codex はリポジトリ内の .codex/config.toml ファイルから、プロジェクト単位のオーバーライドを読み込みます。Codex はプロジェクトルートから現在の作業ディレクトリまでたどり、見つかったすべての .codex/config.toml を読み込みます。複数のファイルで同じキーが定義されている場合は、作業ディレクトリに最も近いファイルが優先されます。

セキュリティ上、Codex がプロジェクト単位の設定ファイルを読み込むのは、プロジェクトが信頼されている場合に限られます。プロジェクトが信頼されていない場合、Codex はプロジェクトの .codex/ レイヤーを無視します。これには .codex/config.toml、プロジェクトローカルのフック、プロジェクトローカルのルールが含まれます。ユーザー用とシステム用のレイヤーは別に扱われ、引き続き読み込まれます。

プロジェクト設定内の相対パス（例：model_instructions_file）は、config.toml を含む .codex/ フォルダーを基準に解決されます。

プロジェクト設定ファイルでは、認証情報の送信先の変更、 ホストが管理するアプリリクエストのメタデータ変更、プロバイダー認証の変更、設定プロファイルの選択、 マシン上での通知／テレメトリコマンドの実行に関する設定をオーバーライドできません。 Codex は、プロジェクトローカルの .codex/config.toml に次のキーがある場合はそれらを無視し、 起動時に警告を表示します：openai_base_url、chatgpt_base_url、 apps_mcp_product_sku、model_provider、model_providers、notify、 profile、profiles、experimental_realtime_ws_base_url、otel。 プロバイダー、通知、テレメトリのキーは、ユーザーレベルの ~/.codex/config.toml に設定してください。 設定プロファイルは --profile profile-name と ~/.codex/profile-name.config.toml を使用して 選択します。

フック

Codex は、アクティブな設定レイヤーと同じ場所にある hooks.json ファイル、 または config.toml ファイル内のインライン [hooks] テーブルからも、ライフサイクルフックを読み込めます。

実際に特に役立つのは、次の 4 か所です：

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

プロジェクトローカルのフックは、プロジェクトの .codex/ レイヤーが信頼されている場合にのみ読み込まれます。 ユーザーレベルのフックは、プロジェクトの信頼状態に左右されません。

インライン TOML フックは、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"

同じレイヤーに hooks.json とインライン [hooks] の両方が含まれる場合、Codex は両方を読み込み、警告を表示します。 レイヤーごとにどちらか一方の形式を使用することをおすすめします。

現在のイベント一覧、入力フィールド、出力時の動作、制限事項については、 フックを参照してください。

エージェントのロール（config.toml 内の [agents]）

サブエージェントのロール設定（config.toml 内の [agents]）については、サブエージェントを参照してください。

プロジェクトルートの検出

Codex は、作業ディレクトリからプロジェクトルートまで上位ディレクトリをたどり、プロジェクト設定（.codex/ レイヤーや AGENTS.md など）を検出します。

デフォルトでは、Codex は .git を含むディレクトリをプロジェクトルートとして扱います。この動作をカスタマイズするには、config.toml で project_root_markers を設定します：

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

project_root_markers = [] を設定すると、親ディレクトリの検索を省略し、現在の作業ディレクトリをプロジェクトルートとして扱います。

カスタムモデルプロバイダー

モデルプロバイダーは、Codex がモデルに接続する方法（ベース URL、通信 API、認証、任意の HTTP ヘッダー）を定義します。カスタムプロバイダーでは、予約済みの組み込みプロバイダー ID である openai、ollama、lmstudio を再利用できません。

追加のプロバイダーを定義し、model_provider で指定します：

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"

カスタムプロバイダーがスタンドアロンのウェブ検索エンドポイントに対応している場合は、 プロバイダーの設定でその機能への対応を宣言します：

[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

カスタムプロバイダーでは、この設定のデフォルト値は false です。 スタンドアロンのウェブ検索は開発中で、デフォルトでは無効です。プロバイダーの機能への対応を true に設定しても、有効にはなりません。 プロバイダーが互換性のあるエンドポイントに対応し、 選択したモデルとランタイムもスタンドアロン検索に対応している必要があります。 設定済みの web_search モードと、 管理設定による検索制限も引き続き適用されます。

必要に応じてリクエストヘッダーを追加します：

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

プロバイダーの認証のために、Codex が外部の認証情報ヘルパーからベアラートークンを取得する必要がある場合は、コマンドベースの認証を使用します：

[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

認証コマンドには stdin からの入力はなく、トークンを stdout に出力する必要があります。Codex は前後の空白を削除し、空のトークンをエラーとして扱います。また、refresh_interval_ms で指定した間隔でトークンを事前に更新します。認証を再試行した後にのみ更新するには、refresh_interval_ms = 0 を設定します。[model_providers.<id>.auth] を env_key、experimental_bearer_token、requires_openai_auth と併用しないでください。

Amazon Bedrock プロバイダー

Codex には amazon-bedrock モデルプロバイダーが組み込まれています。 これを model_provider に直接設定します。カスタムプロバイダーとは異なり、 この組み込みプロバイダーでサポートされるのは、ネストされた AWS プロファイルとリージョンのオーバーライドのみです。

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

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

profile を省略すると、Codex は標準の AWS 認証情報チェーンを使用します。 region には、リクエストを処理するサポート対象の Bedrock リージョンを設定します。

セットアップの全手順、認証オプション、対応モデル、機能の提供状況については、 Amazon Bedrock での ChatGPT Work と Codex の利用 を参照してください。

OSS モード（ローカルプロバイダー）

--oss を指定すると、Codex は Ollama や LM Studio などのローカルの「オープンソース」プロバイダーに接続して実行できます。 1 回の実行で使用するプロバイダーを --local-provider で選択するか、 oss_provider でデフォルトを設定します。どちらも設定されていない場合は、 対話型 CLI では選択を求められ、codex exec はエラーで終了します。

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

Azure プロバイダーとプロバイダーごとの調整

[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

組み込みの OpenAI プロバイダーのベース URL を変更するには、openai_base_url を使用してください。組み込みプロバイダー ID はオーバーライドできないため、[model_providers.openai] は作成しないでください。

データレジデンシーを利用する API 組織

データレジデンシーを有効にして作成したプロジェクトでは、モデルプロバイダーを作成し、正しいプレフィックスを使用するように base_url を更新できます。データレジデンシーを利用する ChatGPT ワークスペースでは、カスタムプロバイダーは不要です。ChatGPT でサインインすると、Codex はワークスペースのデータレジデンシー設定に従います。

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

モデルの推論、詳細度、制限

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 は Responses API を使用するプロバイダーにのみ適用されます。Chat Completions プロバイダーでは、この設定は無視されます。

承認ポリシーとサンドボックスモード

承認の厳格さ（Codex が一時停止するタイミングに影響）とサンドボックスレベル（ファイルやネットワークへのアクセスに影響）を選択します。

config.toml の編集時に留意すべき動作の詳細については、サンドボックスと承認の一般的な組み合わせ、書き込み可能なルート内の保護されたパス、ネットワークアクセスを参照してください。

Codex と ChatGPT Work は、approval_policy = "untrusted" をサポートしなくなりました。 サポートされる設定と、プロジェクト設定に由来するより厳格な承認ルールについては、 廃止された untrusted 承認ポリシーからの移行を参照してください。

ファイルシステムとネットワークへのアクセスをまとめて設定できるベータ版の権限プロファイルについては、権限を参照してください。

詳細な承認ポリシー（approval_policy = { granular = { ... } }）を使用すると、承認プロンプトのカテゴリーごとに、表示を許可するか自動的に拒否するかを指定できます。一部のケースでは通常の対話的な承認を使用しつつ、request_permissions やスキルスクリプトの承認プロンプトなど、その他のケースでは自動的に拒否して安全側に倒したい場合に便利です。

approvals_reviewer = "auto_review" を設定すると、対象となる対話的な承認リクエストが 自動レビューに送られます。変更されるのはレビュー担当であり、 サンドボックスの境界は変わりません。

レビュー担当へのローカルのポリシー指示には [auto_review].policy を使用します。 管理対象の guardian_policy_config が優先されます。

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

名前付き権限プロファイル

組み込みプロファイル、カスタムプロファイルの構文、ファイルシステムとネットワークの設定モデル全体については、 権限を参照してください。

キーの全一覧と要件による制約については、 設定リファレンスと 管理対象の設定を参照してください。

サンドボックスを完全に無効にするには、次のように設定します（環境側ですでにプロセスが隔離されている場合にのみ使用してください）。

sandbox_mode = "danger-full-access"

シェル環境ポリシー

shell_environment_policy は、Codex が起動するコマンドに渡す環境変数を制御します。 inherit = "none" で空の環境から開始するか、 inherit = "core" で必要なものに絞って継承します。 起動するコマンドに不要なシークレットを渡さないよう、値を明示的に指定し、キーを指定したフィルターを追加してください。

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

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

フィルターパターンは大文字と小文字を区別せず、* と ? を使用できます。 一致する変数を除外するには "exclude" を使用します。いずれかのパターンで "include" を使用すると、Codex は包含パターンに一致する変数だけを残します。 包含パターンを指定しても、すでに除外された変数は復元されません。 フィルターのキーは、設定レイヤー間で 大文字と小文字を区別せずにマージされます。

ignore_default_excludes のデフォルトは true なので、 Codex は名前に KEY、SECRET、TOKEN を含む変数を自動的には除外しません。 明示的に指定したフィルターの適用前にこれらの自動除外を適用するには、false に設定してください。

Codex は、自動除外、カスタム除外、 set による値の設定、包含パターンの許可リストの順に適用します。 set は除外処理の後に実行されるため、除外された変数を復元できます。 ただし、復元された値も、包含パターンの許可リストによって除外される場合があります。

既存の設定では、従来の exclude 配列と include_only 配列も引き続きサポートされます。 どちらの配列も、同じ設定レイヤー内で [shell_environment_policy.filters] と併用しないでください。 Codex はこの組み合わせを拒否します。

MCP サーバー

設定の詳細については、専用の MCP ドキュメントを参照してください。

オブザーバビリティとテレメトリ

OpenTelemetry（OTel）のログエクスポートを有効にすると、Codex の実行状況（API リクエスト、SSE／イベント、プロンプト、ツールの承認／結果）を追跡できます。デフォルトでは無効です。有効にするには、[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

エクスポーターを選択します。

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

exporter = "none" の場合、Codex はイベントを記録しますが、何も送信しません。エクスポーターは非同期でバッチ処理し、シャットダウン時に残りのデータを送信します。イベントのメタデータには、サービス名、CLI バージョン、環境タグ、会話 ID、モデル、サンドボックス／承認の設定、イベントごとのフィールドが含まれます（設定リファレンスを参照）。

出力される内容

Codex は、実行状況やツールの使用状況に関する構造化ログイベントを出力します。代表的なイベントタイプは次のとおりです。

• codex.conversation_starts（モデル、推論設定、サンドボックス／承認ポリシー）
• codex.api_request（試行、ステータス／成功、所要時間、エラーの詳細）
• codex.sse_event（ストリームイベントの種類、成功／失敗、所要時間、および response.completed 時のトークン数）
• codex.websocket_request と codex.websocket_event（リクエストの所要時間、およびメッセージごとの種類／成功／エラー）
• codex.user_prompt（長さ。内容は明示的に有効にしない限り伏せられます）
• codex.tool_decision（承認／拒否、および判断が設定に基づくものかユーザーによるものか）
• codex.tool_result（所要時間、成功、出力の抜粋）

出力される OTel メトリクス

OTel メトリクスパイプラインを有効にすると、Codex は API、ストリーム、ツールの処理に関するカウンターと所要時間のヒストグラムを出力します。

以下の各メトリクスには、デフォルトのメタデータタグとして auth_mode、originator、session_source、model、app.version も含まれます。

テレメトリに関するセキュリティとプライバシーの詳しいガイダンスは、セキュリティを参照してください。

メトリクス

デフォルトでは、Codex は匿名の使用状況データと稼働状況データを少量、定期的に OpenAI に送信します。これにより、Codex の不具合を検出し、利用されている機能や構成オプションを把握できるため、Codex チームは最も重要な課題に注力できます。これらのメトリクスには、個人を特定できる情報（PII）は含まれません。メトリクスの収集は、OTel のログ／トレースのエクスポートとは独立しています。

マシン上の ChatGPT デスクトップアプリ、Codex CLI、IDE 拡張機能のすべてでメトリクスの収集を完全に無効にするには、構成で分析用フラグを次のように設定します。

[analytics]
enabled = false

各メトリクスには、固有のフィールドに加え、以下のデフォルトのコンテキストフィールドが含まれます。

デフォルトのコンテキストフィールド（すべてのイベント／メトリクスに適用）

• auth_mode: swic | api | unknown
• model: 使用したモデルの名前
• app.version: Codex のバージョン

メトリクス一覧

各メトリクスには、必須フィールドに加え、上記のデフォルトのコンテキストフィールドが含まれます。以下のメトリクス名では、接頭辞 codex. を省略しています。 ほとんどのメトリクス名は codex-rs/otel/src/metrics/names.rs で一元管理されています。このファイル以外で出力される機能固有のメトリクスも、ここに掲載しています。 メトリクスに tool フィールドが含まれる場合、その値は内部で使用されたツール（たとえば apply_patch や shell）を表します。実際のシェルコマンドや、codex が適用しようとしているパッチの内容は含まれません。

ランタイムとモデル通信

cloud_requirements.fetch_attempt メトリクスには、trigger、attempt、outcome、status_code の各フィールドが含まれます。cloud_requirements.fetch_final メトリクスには、trigger、outcome、reason、attempt_count、status_code の各フィールドが含まれます。

ターンとツールのアクティビティ

mcp.call と mcp.call.duration_ms のメトリクスには status が含まれます。通常のツール呼び出しで出力されるメトリクスには tool も含まれ、取得できる場合は connector_id と connector_name も含まれます。ブロックされた Codex アプリの MCP 呼び出しでは、status のみを含む mcp.call が出力される場合があります。

スレッド、タスク、機能

shell_snapshot メトリクスには success が含まれ、失敗時には failure_reason も含まれます。

メモリとローカル状態

external_agent_config.detect と external_agent_config.import のメトリクスには migration_type が含まれます。スキルの移行では skills_count も含まれます。

Windows サンドボックス

管理者権限によるセットアップの失敗メトリクスには、Windows セットアップの失敗の詳細が取得できる場合に code と message が含まれます。また、共通のセットアップ処理経路から出力される場合は、originator が含まれることがあります。windows_sandbox.legacy_setup_preflight_failed メトリクスには、共通のセットアップ処理経路から出力される場合に originator が含まれます。ただし、フォールバックの確認プロンプトでの事前チェックの失敗には、フィールドが一切含まれない場合があります。

フィードバックの制御

デフォルトでは、ローカルクライアントのユーザーは /feedback からフィードバックを送信できます。同じマシン上の ChatGPT デスクトップアプリ、Codex CLI、IDE 拡張機能でフィードバックの収集を無効にするには、次のように構成を更新します。

[feedback]
enabled = false

無効にすると、/feedback に無効であることを示すメッセージが表示され、Codex はフィードバックの送信を拒否します。

推論イベントの非表示と表示

CI ログなどで「推論」の出力が多すぎる場合は、次のように出力を抑制できます。

hide_agent_reasoning = true

モデルが出力する生の推論内容を表示するには、次のように設定します。

show_raw_agent_reasoning = true

生の推論内容の表示は、ワークフロー上問題がない場合にのみ有効にしてください。gpt-oss など、一部のモデルやプロバイダーは生の推論内容を出力しません。その場合、この設定による表示の変化はありません。

通知

notify を使用すると、Codex がサポート対象のイベント（現在は agent-turn-complete のみ）を出力するたびに、外部プログラムを起動できます。デスクトップのトースト通知、チャットの Webhook、CI の更新通知など、組み込みの TUI 通知では対応できない別経路での通知に便利です。

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

agent-turn-complete に反応する notify.py の例（一部省略）を示します。

#!/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())

スクリプトは、単一の JSON 引数を受け取ります。主なフィールドは次のとおりです。

• type（現在は agent-turn-complete）
• thread-id（セッション識別子）
• turn-id（ターン識別子）
• cwd（作業ディレクトリ）
• input-messages（そのターンのきっかけとなったユーザーメッセージ）
• last-assistant-message（最後のアシスタントメッセージのテキスト）

スクリプトをディスク上の任意の場所に配置し、notify にその場所を指定します。

notify と tui.notifications の違い

• notify は外部プログラムを実行します（Webhook、デスクトップ通知ツール、CI フックに適しています）。
• tui.notifications は TUI に組み込まれており、必要に応じてイベントの種類（agent-turn-complete や approval-requested など）でフィルタリングできます。
• tui.notification_method は、TUI がターミナル通知を出力する方法（auto、osc9、bel）を制御します。
• tui.notification_condition は、TUI 通知をターミナルにフォーカスがないときだけ送るか（unfocused）、 常に送るか（always）を制御します。

auto モードでは、Codex は OSC 9 通知（一部のターミナルがデスクトップ通知として解釈するターミナルエスケープシーケンス）を優先し、使用できない場合は BEL（\x07）にフォールバックします。

正確なキーについては、構成リファレンスを参照してください。

履歴の永続化

デフォルトでは、Codex はローカルセッションの会話記録を CODEX_HOME 配下（~/.codex/history.jsonl など）に保存します。ローカル履歴の永続化を無効にするには、次のように設定します。

[history]
persistence = "none"

履歴ファイルのサイズに上限を設けるには、history.max_bytes を設定します。ファイルが上限を超えると、Codex は古いエントリから削除し、最新の記録を残してファイルのサイズを縮小します。

[history]
max_bytes = 104857600 # 100 MiB

クリック可能な引用

対応するターミナルやエディターとの連携を使用している場合、Codex はファイルの引用をクリック可能なリンクとして表示できます。Codex が使用する URI スキームは、file_opener で指定します。

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

たとえば、/home/user/project/main.py:42 のような引用を、クリック可能な vscode://file/...:42 リンクに書き換えることができます。

プロジェクト指示の検出

Codex は AGENTS.md（および関連ファイル）を読み取り、セッションの最初のターンに、上限の範囲内でプロジェクトのガイダンスを含めます。この動作は、次の 2 つの設定で制御します。

• project_doc_max_bytes：各 AGENTS.md ファイルから読み取る量
• project_doc_fallback_filenames：ディレクトリに AGENTS.md がない場合に、追加で確認するファイル名

詳しい手順については、AGENTS.md によるカスタム指示を参照してください。

デスクトップ

このセクションのオプションは、ChatGPT デスクトップアプリにのみ適用されます。

カスタムファイルハンドラーの追加

ユーザーレベルの ~/.codex/config.toml で、 desktop.custom_file_handlers の下にエントリを追加すると、ChatGPT デスクトップアプリがデフォルトでは対応していないエディターや内部ランチャーで ファイルを開けます。各エントリは、アプリの 次で開く メニューに エディターの選択肢を追加します。command が既存の絶対パスであるか、 アプリの PATH から解決できる場合、その選択肢が表示されます。

次の例は、ハンドラーにファイルを渡す 3 つの方法を示しています。

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

config.toml を保存し、ChatGPT デスクトップアプリを再起動します。

ハンドラー ID は、TOML テーブルヘッダーの最後のセグメントです。 長さは 1～64 文字で、先頭は ASCII の英字または数字である必要があります。残りの文字には、 ASCII の英字、数字、ピリオド、アンダースコア、ハイフンのみを使用できます。アプリは、 custom: プレフィックスを付けた ID を公開します。たとえば、company_editor は custom:company_editor になります。ピリオドを含む ID は、TOML がネストされたテーブルとして 解釈しないように引用符で囲んでください。次に例を示します。

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

各ハンドラーは、次のフィールドに対応しています。

input の値によって、args の後に続く内容が決まります。

• path は、コマンドの最後の引数としてパスを追加します。
• json_argument は、target、path、appPath、 location を含む JSON オブジェクトを追加します。location の値は、1 から始まる line と column の値を持つオブジェクト、または null です。
• json_stdin は引数を追加せず、 JSON オブジェクトを標準入力に書き込みます。このオブジェクトには hostConfig、remoteWorkspaceRoot、 remotePath も含まれます。これらのフィールドは、該当しない場合は null になります。

たとえば、ユーザーがソース内の特定の位置を開くとき、 company_editor は次の引数を受け取ることができます。

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

カスタムハンドラーを優先エディターとして選択すると、組み込みエディターを選択した場合と同じように、プロジェクトごとの設定も含めて選択内容が保存されます。

TUI オプション

サブコマンドを指定せずに codex を実行すると、対話型ターミナル UI（TUI）が起動します。Codex では、[tui] に以下のような TUI 固有の設定を指定できます。

• tui.notifications：通知の有効化・無効化（または特定の種類への制限）
• tui.notification_method：ターミナル通知の方式を auto、osc9、bel から選択
• tui.notification_condition：通知を出す条件を unfocused または always から選択
• tui.animations：ASCII アニメーションときらめき効果の有効化・無効化
• tui.alternate_screen：代替画面の使用を制御（ターミナルのスクロールバックを保持するには never に設定）
• tui.show_tooltips：ウェルカム画面の初回利用ガイド用ツールチップの表示・非表示

tui.notification_method のデフォルトは auto です。auto モードでは、ターミナルが OSC 9 通知に対応していると判断される場合、Codex はこの方式を優先します。OSC 9 は、一部のターミナルがデスクトップ通知として解釈するターミナルエスケープシーケンスです。対応していないと判断される場合は、BEL（\x07）にフォールバックします。

キーの全一覧は、構成リファレンスを参照してください。