高度な設定

プロバイダー、ポリシー、外部連携を細かく制御したい場合は、以下のオプションを使います。初めて設定する場合は、設定の基本を参照してください。

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

Work クラウドからローカルコンピューターにアクセスする場合の設定例の適用

以下は Codex の設定例です。Work クラウドからローカルコンピューターにアクセスする際に応用する場合は、事前に設定リファレンスを確認してください。

• ポリシーの適用範囲： ローカルアクセスを使用する Work と dot では、管理ポリシーを有効にすると、サポート対象のグローバルポリシーが共有クラウドオーケストレーターに適用されます。接続先のコンピューターには、該当するローカル実行要件が適用されます。Work のクラウドコンテナには、引き続き既存の Work クラウドポリシーが適用されます。
• ローカル実行： MDM と従来の管理対象デバイスの要件は、エージェントセキュリティよりも優先されます。デバイスのシステム要件ファイルは、エージェントセキュリティよりも優先度が低くなります。
• Enterprise 向けフック： ワークスペースでこの機能が有効になっている場合、サポート対象のライフサイクルイベントとツールイベントに対して、管理者が定義した MCP フックをクラウドコーディネーター（オーケストレーター）で実行できます。クラウドオーケストレーションでは、ツールをローカルで実行する場合でも、コマンドフックや、ローカル設定またはプラグインで定義したフックは使用できません。
• 監査： これらのフックを運用に組み込む前に、コールバックの接続をテストし、受信するイベントと、失敗時のタスクへの影響を確認してください。MCP フックだけでは、Compliance API の完全な監査証跡は得られません。
• その他の設定： 管理設定を通じて、カスタムモデルプロバイダーやホスト上のローカルパスをこの機能に引き継ぐことはできません。ネットワーク制限とフィールドごとのマージルールは、管理設定で確認してください。

サポート範囲と設定手順については、フックを参照してください。

プロファイル

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

プロファイルごとに別々の TOML ファイルを作成してください。プロファイルファイルでは、設定キーをトップレベルに記述し、[profiles.profile-name] の下には配置しないでください。

この例では GPT-6.1 Sol を使用します。サインイン中のアカウントまたはワークスペースに、このモデルのアクセス権が必要です。アクセス権がない場合は、利用できるモデルを選んでください。

1
2
3
4
5# ~/.codex/deep-review.config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
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 は [profiles.profile-name] を config.toml から読み込みません。トップレベルの profile = "profile-name" による選択もサポートされなくなりました。従来のプロファイル設定を ~/.codex/profile-name.config.toml に移し、対応する [profiles.profile-name] テーブルと profile = "profile-name" セレクターを config.toml から削除してください。

CLI からの一時的な上書き

~/.codex/config.toml を編集するほか、CLI から今回の実行に限って設定を上書きできます。

• 専用フラグがある場合は、そのフラグを優先してください（例：--model）。
• 任意のキーを上書きするには、-c または --config を使用してください。

以下のモデルの上書き例にも、GPT-6.1 Sol のアクセス権が必要です。アクセス権がない場合は、利用できるモデルに置き換えてください。

1
2
3
4
5
6# Dedicated flag
codex --model gpt-6.1-sol
# Generic key/value override (value is TOML, not JSON)
codex --config model='"gpt-6.1-sol"'
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 プロキシ、ルーター、またはデータレジデンシーを有効にしたプロジェクトに変更するだけなら、新しいプロバイダーを定義する代わりに openai_base_url を config.toml に設定してください。これで組み込みの openai プロバイダーのベース URL が変わり、別途 model_providers.<id> エントリを作成する必要はありません。

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

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

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

セキュリティ上の理由から、Codex は信頼済みのプロジェクトでのみプロジェクト設定ファイルを読み込みます。信頼されていないプロジェクトでは、プロジェクトの .codex/ レイヤーを無視します。これには .codex/config.toml、プロジェクト内のフック、プロジェクト内のルールが含まれます。ユーザーレイヤーとシステムレイヤーはこれとは独立しており、引き続き読み込まれます。

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

プロジェクト設定ファイルでは、認証情報の送信先を変える設定、ホストが管理するアプリリクエストのメタデータを変更する設定、プロバイダーの認証を変更する設定、設定プロファイルを選択する設定、マシン上で通知やテレメトリのコマンドを実行する設定は上書きできません。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 ファイル、またはインラインの [hooks] テーブルを含む config.toml ファイルから、ライフサイクルフックを読み込むこともできます。

よく使う配置場所は次の 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 は両方を読み込み、警告を表示します。レイヤーごとにどちらか一方を使用してください。

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

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

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

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

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

デフォルトでは、Codex は .git を含むディレクトリをプロジェクトルートとして扱います。この動作を変更するには、project_root_markers を config.toml に設定してください。

# 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 を選んでください。Codex では、openai、ollama、lmstudio、amazon-bedrock、amazon-bedrock-runtime、gcp は組み込みプロバイダー用に予約されています。

プロバイダーを追加で定義し、model_provider で使用するプロバイダーを指定します。

1
2
3
4
5
6
7
8
9
10
11
12
13model = "gpt-6.1-sol"
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" }

組織の ID プロバイダーを通じてブラウザからサインインするには、ゲートウェイのネイティブ OAuth を使用してください。[model_providers.<id>.gateway_oauth] に認可 URL、トークン URL、パブリッククライアントの ID、トークンの送信方法を設定します。requires_openai_auth = false で利用でき、ChatGPT へのサインイン、PowerShell、Azure CLI、外部の認証情報ヘルパーは不要です。ゲートウェイ側で、設定した Cookie またはカスタムヘッダーから OAuth トークンを受け取れる必要があります。

プロバイダーの要件として、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 からの入力は渡されません。トークンは標準出力に書き出してください。Codex は前後の空白を取り除き、空のトークンをエラーとして扱います。通常は refresh_interval_ms で指定した間隔で事前にトークンを更新します。認証の再試行後にのみ更新するには、refresh_interval_ms = 0 に設定してください。[model_providers.<id>.auth] と env_key、experimental_bearer_token、requires_openai_auth は併用しないでください。

Amazon Bedrock プロバイダー

model_provider には、Bedrock Mantle エンドポイントを使用する場合は amazon-bedrock、Runtime エンドポイントを使用する場合は amazon-bedrock-runtime を指定してください。Mantle で使用する AWS 認証情報とリージョンは、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 の利用を参照してください。

Google Cloud Vertex AI プロバイダー

プロジェクトからアクセスできる Vertex AI のモデルを使用するには、config.toml で組み込みプロバイダーを指定してください。

model_provider = "gcp"

[model_providers.gcp]
project_id = "my-project"
location = "global"

project_id または location を省略すると、Codex はそれぞれ GOOGLE_CLOUD_PROJECT または GOOGLE_CLOUD_LOCATION から値を読み取ります。ロケーションのデフォルトは global です。

デフォルトの認証を使用するには、Codex を実行するマシンに Google Cloud CLI をインストールしてください。ローカルでサインインするには、gcloud auth application-default login を実行します。Codex は gcloud auth application-default print-access-token を実行してアクセストークンを取得します。

特定の ADC ファイルを使用するには、その絶対パスを credential_file に指定します。このキーは [model_providers.gcp] に記述してください。Codex は認証コマンドの実行時に GOOGLE_APPLICATION_CREDENTIALS にそのパスを設定します。

デプロイ環境で別のエンドポイント、トークン取得コマンド、または固定ヘッダーを使用する場合は、それぞれ base_url、auth、http_headers を [model_providers.gcp] に設定してください。

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

--oss を指定すると、Codex は Ollama や LM Studio などのローカルの「オープンソース」プロバイダーに接続して実行できます。今回の実行に使うプロバイダーは --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_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" に設定すると、対象となる対話型の承認リクエストが自動レビューに送られます。ルールを追加する方法や、レビュー担当が使用するポリシーを置き換える方法については、自動レビューの設定を参照してください。

approval_policy = "on-request"  # Other options: never or { granular = { ... } }
approvals_reviewer = "user"     # Or "auto_review" for Auto-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

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

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

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

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

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

管理者は、使用するエクスポーターと個々のログ設定を requirements.toml で指定し、適用を強制できます。

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

[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.agent_response（otel.log_agent_responses = true の場合に記録される、メインエージェントと起動されたサブエージェントの最終回答）
• codex.guardian_assessment（otel.log_guardian_assessments = true の場合に記録される、承認リクエストの自動レビューの完了結果）
• codex.tool_decision（承認または拒否、判断元が設定かユーザーか）
• codex.tool_result（所要時間、成否、出力の抜粋）

出力される OTel メトリクス

OTel メトリクスパイプラインが有効な場合、Codex は API、ストリーム、ツールの動作について、カウンターと所要時間のヒストグラムを出力します。

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

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

メトリクス

デフォルトでは、Codex は使用状況と動作状態に関する少量の匿名データを定期的に OpenAI に送信します。このデータを使って、Codex が正常に動作していない状況や、利用されている機能と設定オプションを把握し、Codex チームが優先して取り組む課題を判断します。これらのメトリクスに個人を特定できる情報（PII）は含まれません。メトリクスの収集は、OTel のログやトレースのエクスポートとは独立しています。

分析機能と組み込みの statsig メトリクスエクスポーターを無効にするには、設定ファイルで分析フラグを次のように指定します。

[analytics]
enabled = false

カスタムの OTLP メトリクスエクスポーターも無効にするには、otel.metrics_exporter = "none" に設定してください。

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

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

• 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 呼び出しがブロックされた場合は、mcp.call に status だけが含まれることがあります。

スレッド、タスク、機能

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

以下は notify.py の例（抜粋）です。agent-turn-complete に反応して通知を表示します。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35#!/usr/bin/env python3
import argparse
import json
import subprocess
import sys


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Show a Codex turn-completion notification on macOS."
    )
    parser.add_argument("notification", type=json.loads, help="Codex notification JSON")
    notification = parser.parse_args().notification
    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 を 1 つの引数として受け取ります。主なフィールドは次のとおりです。

• 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 は、ターミナルにフォーカスがない場合にのみ通知するか（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 はファイルの引用元をクリック可能なリンクとして表示できます。file_opener で、Codex が使用する URI スキームを指定してください。

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 デスクトップアプリが標準で対応していないエディターや社内ランチャーでファイルを開けます。エントリごとに、アプリのファイルを開くアプリの選択メニューにエディターが 1 つ追加されます。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 の英字、数字、ピリオド、アンダースコア、ハイフンのみを使用できます。アプリは ID に custom: プレフィックスを付けて公開します。たとえば、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 モードでは、Codex はターミナルが対応していると判断した場合に OSC 9 通知（一部のターミナルがデスクトップ通知として扱うエスケープシーケンス）を優先し、それ以外の場合は BEL（\x07）にフォールバックします。

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