Codexの設定 - 環境変数

提供: MochiuWiki : SUSE, EC, PCB

概要

OpenAI Codex CLIは、認証・エンドポイント・プロキシ・デバッグ・MCP連携等、動作の細部を環境変数によって制御できる。
CLIフラグ、環境変数、config.toml、ビルトインデフォルトの優先順位に従って設定が解決される。

主要カテゴリは以下の通りである。

Codexの環境変数
カテゴリ 説明
認証関連 APIキー、Azureキー
エンドポイント関連 カスタムLLMエンドポイント、プロキシ・ゲートウェイ
ファイルシステム関連 ホームディレクトリのパス指定
プロキシ関連 HTTP / HTTPS / SOCKSプロキシ
ロギング・デバッグ Rustログレベル、ログファイル
シェル環境変数フォワード シェルから引き継ぐ変数の制御
MCP関連 bearer_token_env_varによるトークン参照


設定優先度は以下の通りである。

  1. CLIフラグ (最高優先度)
  2. 環境変数
  3. config.toml (プロジェクトレベル)
  4. config.toml (ユーザレベル)
  5. ビルトインデフォルト (最低優先度)



認証関連

OPENAI_API_KEY

OPENAI_API_KEY は、OpenAI APIへの認証に使用する必須の環境変数である。

設定していない場合、Codex CLIは起動時にエラーを返す。

  • 注意事項 (Issue #3286)
    ChatGPT Plusサブスクリプションのログイン認証とAPIキー認証は、別の課金体系である。
    ChatGPTにブラウザでログインしていても、OPENAI_API_KEY が設定されていなければAPIは使用できない。
    APIキーは platform.openai.com/api-keys で発行する。


 export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxx"


CODEX_API_KEY

CODEX_API_KEY は、OPENAI_API_KEY のエイリアスである。

両方が設定されている場合、OPENAI_API_KEY が優先される。
OPENAI_API_KEY という名前を環境に露出させたくない場合の代替として使用できる。

 export CODEX_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxx"


AZURE_OPENAI_API_KEY

AZURE_OPENAI_API_KEY は、Azure OpenAI Serviceへの接続に使用する認証キーである。
OPENAI_BASE_URL にAzureエンドポイントを指定した場合に合わせて設定する。

  • 注意事項
    Azure AD (Entra ID) / Managed Identity によるOAuth認証は現時点で未対応である。
    サービスプリンシパルやワークロードアイデンティティを使用する場合は、キーを手動で取得して設定する必要がある。


 export AZURE_OPENAI_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
 export OPENAI_BASE_URL="https://my-resource.openai.azure.com/openai/deployments/gpt-4o"



エンドポイント関連

OPENAI_BASE_URL

OPENAI_BASE_URL は、OpenAI互換のカスタムLLMエンドポイントを指定する環境変数である。
デフォルト値は、https://api.openai.com/v1 である。

以下に示すような用途で使用する。


 # LiteLLMプロキシを使用する例
 export OPENAI_BASE_URL="https://litellm.example.com/v1"
 export OPENAI_API_KEY="sk-xxxx"
 
 # ローカルOllamaを使用する例
 export OPENAI_BASE_URL="http://localhost:11434/v1"
 export OPENAI_API_KEY="ollama"



ファイルシステム関連

CODEX_HOME

CODEX_HOME は、Codex CLIが使用するホームディレクトリのパスを指定する環境変数である。
デフォルト値は ~/.codex である。

CODEX_HOME 以下に作成される主なファイル、ディレクトリは以下の通りである。

CODEX_HOMEディレクトリの構成要素一覧
ファイル / ディレクトリ 説明
config.toml ユーザ全体の設定ファイル
auth.json 認証情報 (APIキーキャッシュ等)
機密ファイルであるため、バージョン管理対象から除外すること。
log/codex-tui.log TUI (インタラクティブモード) のログファイル
log/codex-cli.log CLI (非インタラクティブモード) のログファイル 


 # CODEX_HOMEを変更する例 (複数ユーザ環境や共有ストレージを使用する場合)
 export CODEX_HOME="/opt/codex-config"
 
 # プロジェクトごとに分離する例
 export CODEX_HOME="$(pwd)/.codex-local"



プロキシ関連

HTTP_PROXY

HTTP_PROXY は、HTTPリクエストのプロキシサーバを指定する環境変数である。

企業ネットワーク等でHTTP通信をプロキシ経由にする場合に設定する。

 export HTTP_PROXY="http://proxy.example.com:8080"


HTTPS_PROXY

HTTPS_PROXY は、HTTPS通信のプロキシサーバを指定する環境変数である。

OpenAI APIへのリクエストはHTTPSで行われるため、企業プロキシ環境ではこの変数の設定が必要になる場合が多い。

 export HTTPS_PROXY="http://proxy.example.com:8080"


ALL_PROXY

ALL_PROXY は、全プロトコルのプロキシを一括指定する環境変数である。

SOCKSプロキシを使用する場合はこの変数に設定する。

  • 注意事項 (Issue #16360)
    ALL_PROXY にSOCKSプロキシのみを設定した場合、MCPサーバのブートストラップ (初期接続) が失敗することがある。
    MCP利用時は HTTPS_PROXY を併用するか、MCPエンドポイントを NO_PROXY に追加することで回避できる。


 export ALL_PROXY="socks5://proxy.example.com:1080"


NO_PROXY

NO_PROXY は、プロキシを経由しないホストやドメインを指定する環境変数である。

カンマ区切りで複数のホスト、ドメイン、CIDRを指定できるが、ワイルドカードや接頭辞マッチングは部分的にしか対応していない。

  • 部分対応の制限事項
    サブドメインのワイルドカード (*.example.com 形式) は一部の実装で動作しない場合がある。
    接頭辞マッチング (.example.com 形式) はホストリゾルバに依存する。


 export NO_PROXY="localhost,127.0.0.1,::1,.internal.example.com,mcp-server.local"



ロギング・デバッグ

RUST_LOG

RUST_LOG は、Codex CLIのログ出力レベルを制御する環境変数である。

Codex CLIはRustで実装されており、Rustの標準ロギングフレームワーク (env_logger / tracing) を使用している。

デフォルト値は codex_core=info である。

詳細なログを取得する場合の設定例を以下に示す。

 # デフォルト設定
 export RUST_LOG="codex_core=info"
 
 # 詳細デバッグ出力 (問題調査時に使用)
 export RUST_LOG="codex_core=debug,codex_tui=debug,codex_rmcp_client=debug"
 
 # 全モジュールのデバッグログ
 export RUST_LOG="debug"
 
 # MCPクライアントのデバッグのみ
 export RUST_LOG="codex_rmcp_client=debug"


ログは、以下に示すファイルに記録される。

  • $CODEX_HOME/log/codex-tui.log
    TUIモード (インタラクティブ起動) 時のログ
  • $CODEX_HOME/log/codex-cli.log
    CLIモード (非インタラクティブ起動) 時のログ



シェル環境変数フォワード

shell_environment_policy

shell_environment_policy は、Codex CLIがシェルから引き継ぐ環境変数の範囲を制御する設定である。

環境変数として直接指定するのではなく、config.toml の設定項目として記述する。

設定可能な値は以下の通りである。

シェル環境変数の引き継ぎポリシー一覧
ポリシー 説明
inherit シェルの全環境変数をCodex CLIに引き継ぐ。(デフォルト)
exclude 指定した変数を除外して引き継ぐ。
include_only 指定した変数のみを引き継ぐ。
セキュリティ上の理由から許可リスト方式を推奨する。


config.toml での設定例を以下に示す。

 # 全変数を引き継ぐ (デフォルト)
 [shell_environment_policy]
 inherit = "all"
 
 # 特定の変数のみを引き継ぐ (推奨: 許可リスト方式)
 [shell_environment_policy]
 inherit = "none"
 include_only = ["PATH", "HOME", "LANG", "TZ", "TERM", "OPENAI_API_KEY"]
 
 # 特定の変数を除外して引き継ぐ
 [shell_environment_policy]
 inherit = "all"
 exclude = ["AWS_SECRET_ACCESS_KEY", "GITHUB_TOKEN"]


shell_snapshot

shell_snapshot は、セッション再開時のシェル環境を復元する機能に関連する設定である。

  • PR #17271 での修正について
    スナップショット復元時にプロキシ関連の環境変数 (HTTP_PROXY、HTTPS_PROXY、NO_PROXY 等) が正規化されない問題が修正された。
    このPR以前のバージョンでは、プロキシ設定がスナップショット経由で引き継がれない場合があった。



MCP関連環境変数

bearer_token_env_var で参照

MCPサーバの認証トークンは、config.toml 内の bearer_token_env_var フィールドを通じて環境変数から参照する。

トークンの値を config.toml に直接記述せず、環境変数名を文字列で指定する方式である。

 [[mcp_servers]]
 name = "github"
 transport = "http"
 url = "https://api.githubcopilot.com/mcp/"
 
 [mcp_servers.auth]
 type = "bearer"
 # 環境変数名を指定する (値ではなく変数名を記述)
 bearer_token_env_var = "GITHUB_TOKEN"
 
 [[mcp_servers]]
 name = "slack"
 transport = "http"
 url = "https://mcp.slack.com/sse"
 
 [mcp_servers.auth]
 type = "bearer"
 bearer_token_env_var = "SLACK_BOT_TOKEN"


一般的なMCPトークン例

MCPサーバに対してよく使用される環境変数を以下に示す。

MCPサーバ連携で使用する主要な環境変数 (認証トークン)
環境変数 説明
GITHUB_TOKEN GitHub MCPサーバへの認証トークン
GitHub Personal Access Token または GitHub Appsのトークン
SLACK_BOT_TOKEN Slack MCPサーバへの認証トークン
Slack Bot Token (xoxb- 形式)
ANTHROPIC_API_KEY Anthropic APIへの認証キー
Claude等のAnthropicモデルをMCP経由で使用する場合に設定する。
SENTRY_AUTH_TOKEN Sentry MCPサーバへの認証トークン
エラー追跡・監視サービスのSentryと連携する場合に設定する。



環境変数一覧

下表に、Codex CLIの主要な環境変数を示す。

Codex CLI 環境変数一覧
環境変数 用途 デフォルト 説明
OPENAI_API_KEY 認証 なし OpenAI APIの認証キー (必須)
CODEX_API_KEY 認証 なし OPENAI_API_KEYのエイリアス
AZURE_OPENAI_API_KEY 認証 なし Azure OpenAI Serviceの認証キー
OPENAI_BASE_URL エンドポイント https://api.openai.com/v1 カスタムLLMエンドポイントURL
CODEX_HOME ファイルシステム ~/.codex Codex CLIのホームディレクトリ
HTTP_PROXY プロキシ なし HTTPプロキシサーバのURL
HTTPS_PROXY プロキシ なし HTTPSプロキシサーバのURL
ALL_PROXY プロキシ なし 全プロトコル共通プロキシ (SOCKS対応)
NO_PROXY プロキシ なし プロキシ除外ホスト一覧 (部分対応)
RUST_LOG ロギング codex_core=info Rustログレベルの指定
GITHUB_TOKEN MCP認証 なし GitHub MCPサーバのトークン
SLACK_BOT_TOKEN MCP認証 なし Slack MCPサーバのトークン
ANTHROPIC_API_KEY MCP認証 なし Anthropic API / Claude MCPトークン
SENTRY_AUTH_TOKEN MCP認証 なし Sentry MCPサーバのトークン



設定優先度

Codex CLIの設定は、以下に示す優先度で解決される。

上位の設定が下位の設定を上書きする。

設定優先度
優先度 設定方法 説明
1 (最高) CLIフラグ コマンド実行時に直接指定するオプション
2 環境変数 シェルに設定された環境変数
3 config.toml (プロジェクト) カレントディレクトリ以下の .codex/config.toml
4 config.toml (ユーザ) ~/.codex/config.toml (CODEX_HOME以下)
5 (最低) ビルトインデフォルト Codex CLIのコンパイル時デフォルト値



シェル設定例

Bash

Bashで環境変数を永続設定する場合は、~/.profile または ~/.bashrc に追記する。

 # Codex CLI 環境変数設定
 export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxx"
 
 # カスタムエンドポイント (オプション)
 # export OPENAI_BASE_URL="https://litellm.example.com/v1"
 
 # プロキシ設定 (オプション)
 # export HTTPS_PROXY="http://proxy.example.com:8080"
 # export HTTP_PROXY="http://proxy.example.com:8080"
 # export NO_PROXY="localhost,127.0.0.1"
 
 # CODEX_HOMEのカスタマイズ (オプション)
 # export CODEX_HOME="${XDG_CONFIG_HOME:-$HOME/.config}/codex"


Zsh

Zshで環境変数を永続設定する場合は、~/.zprofile または ~/.zshrc に追記する。

 # Codex CLI 環境変数設定
 export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxx"
 
 # カスタムエンドポイント (オプション)
 # export OPENAI_BASE_URL="https://litellm.example.com/v1"
 
 # プロキシ設定 (オプション)
 # export HTTPS_PROXY="http://proxy.example.com:8080"
 # export HTTP_PROXY="http://proxy.example.com:8080"
 # export NO_PROXY="localhost,127.0.0.1"


Fish

Fishシェルで環境変数を永続設定する場合は、~/.config/fish/conf.d/codex.fish を新規作成して設定を記述する。

 # Codex CLI環境変数設定
 set -x OPENAI_API_KEY "sk-proj-xxxxxxxxxxxxxxxxxxxx"
 
 # カスタムエンドポイント (オプション)
 # set -x OPENAI_BASE_URL "https://litellm.example.com/v1"

 # プロキシ設定 (オプション)
 # set -x HTTPS_PROXY "http://proxy.example.com:8080"
 # set -x HTTP_PROXY "http://proxy.example.com:8080"
 # set -x NO_PROXY "localhost,127.0.0.1"


Fishシェルでユニバーサル変数 (全セッションで永続) として設定する場合は、以下に示すコマンドを使用する。

 set -Ux OPENAI_API_KEY "sk-proj-xxxxxxxxxxxxxxxxxxxx"



config.toml での環境変数参照

config.toml では、環境変数の値を直接記述するのではなく、環境変数名を参照する形式で設定できる。

これにより、機密情報を設定ファイルに含めずに済む。

 # MCPサーバのトークンを環境変数から参照する
 [[mcp_servers]]
 name = "github"
 transport = "http"
 url = "https://api.githubcopilot.com/mcp/"
 
 [mcp_servers.auth]
 type = "bearer"
 bearer_token_env_var = "GITHUB_TOKEN"
 
 # シェル環境変数の引き継ぎポリシーを設定する
 [shell_environment_policy]
 inherit = "none"
 include_only = [
    "PATH",
    "HOME",
    "LANG",
    "TZ",
    "TERM",
    "OPENAI_API_KEY",
    "OPENAI_BASE_URL",
    "HTTPS_PROXY",
    "NO_PROXY"
 ]



実用例

基本的なAPI認証

Codex CLIを使用するための最小構成の設定例を以下に示す。

 # OpenAI APIキーを設定する
 export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxx"
 
 # 動作確認
 codex "Hello, Codex!"


カスタムエンドポイント

OpenAI互換のカスタムエンドポイントに接続する場合の設定例を以下に示す。

 # LiteLLMプロキシ経由でAnthropicのClaudeを使用する例
 export OPENAI_BASE_URL="https://litellm.example.com/v1"
 export OPENAI_API_KEY="sk-xxxx"  # LiteLLMのマスターキー
 
 codex --model "claude-opus-4-5" "コードのレビューをしてください"


企業プロキシ環境

企業ネットワークでプロキシサーバを経由する場合の設定例を以下に示す。

 # 企業プロキシの設定
 export HTTPS_PROXY="http://proxy.corporate.com:8080"
 export HTTP_PROXY="http://proxy.corporate.com:8080"
 export NO_PROXY="localhost,127.0.0.1,.internal.corporate.com"
 
 # APIキーの設定
 export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxx"
 
 # Codex CLIを起動する
 codex


デバッグログ有効化

問題が発生した際の詳細ログを取得する設定例を以下に示す。

 # 全コンポーネントの詳細デバッグログを有効化する
 export RUST_LOG="codex_core=debug,codex_tui=debug,codex_rmcp_client=debug"
 
 # Codex CLIを起動する
 codex
 
 # ログファイルを確認する
 tail -f ~/.codex/log/codex-tui.log



注意事項

  • ChatGPTログインとAPIキーの混同 (Issue #3286)
    ChatGPT PlusやProのサブスクリプションでウェブサービスにログインしていても、Codex CLIのAPI認証とは別である。
    Codex CLIを使用するには、OPENAI_API_KEY に有効なAPIキーを設定し、APIの従量課金が発生することを確認する。

  • プロキシ正規化の修正 (PR #17271)
    セッションスナップショット復元時にプロキシ設定が失われる問題は、PR #17271 で修正された。
    古いバージョンのCodex CLIを使用している場合は、最新版にアップデートすることを推奨する。

  • Azure OAuth未対応
    Azure AD (Entra ID) / Managed Identity によるOAuth認証は現時点でサポートされていない。
    Azureを使用する場合は、AZURE_OPENAI_API_KEY にAPIキーを設定する必要がある。

  • NO_PROXY の部分対応
    NO_PROXY のワイルドカードやサブドメインマッチングは実装に依存し、完全に動作しない場合がある。
    除外したいホストは明示的に列挙することを推奨する。

  • auth.json の機密性
    $CODEX_HOME/auth.json にはAPIキーキャッシュが保存される。
    このファイルはパーミッションを制限し (600推奨)、バージョン管理対象から除外すること。

  • shell_environment_policy で許可リスト推奨
    デフォルトの inherit = "all" では、全シェル環境変数がCodexのサブプロセスに引き継がれる。
    セキュリティ上の観点から、include_only で必要な変数のみを許可リスト方式で指定することを推奨する。



不明な環境変数

以下の環境変数は、コミュニティで言及されているが、現時点で公式ドキュメントには記載されていない。
実際の動作は未確認であり、将来のバージョンで変更または削除される可能性がある。

  • CODEX_LOG
    RUST_LOG と同様の用途と推測されるが、公式ドキュメント未記載
  • CODEX_DISABLE_*
    各種機能の無効化フラグと推測されるが、公式ドキュメント未記載
  • OPENAI_ORG_ID
    OpenAIの組織IDを指定する変数と推測されるが、Codex CLIでの動作は未確認
  • OPENAI_PROJECT_ID
    OpenAIのプロジェクトIDを指定する変数と推測されるが、Codex CLIでの動作は未確認



関連ページ



「https://mochiu.net/index.php?title=Codexの設定_-_環境変数&oldid=14697」から取得