OpenAI Codex CLIをClash Vergeで使う接続設定ガイド入門

Codex CLIとClash Vergeの役割を分けて理解する

OpenAI Codex CLIをターミナルで利用する場合、Codex CLIは入力した指示を読み取り、AIサービスのAPIまたはログイン済みのサービスへHTTPS通信を送るプログラムです。一方、Clash Vergeは、その通信をローカルのプロキシポートで受け取り、ルールに従って直接接続またはプロキシ経由で転送するクライアントです。Codex CLI自体がClashの設定を変更するわけではなく、Clash VergeもAIサービスの認証情報を発行するものではありません。

この2つを組み合わせるときは、まず「Codex CLIの認証」と「ネットワーク経路」を別々に確認します。ログインが完了していても、APIエンドポイントへの接続がタイムアウトすればリクエストは送信できません。反対に、Clash Vergeでブラウザーが開けても、ターミナルのプロセスがプロキシ環境変数を参照していなければ、Codex CLIは別の経路から接続します。

確認対象	担当するもの	主な確認内容
認証	Codex CLIとOpenAI側のアカウント	ログイン状態、APIキー、利用権限、環境変数
経路	Clash Vergeとmihomoカーネル	プロキシポート、ルール、DNS、接続ログ
端末設定	シェルとOS	`HTTP_PROXY`、`HTTPS_PROXY`、`NO_PROXY`

Clash Vergeの基本プロキシを準備する

Clash Vergeでプロファイルを読み込んだら、まずプロファイルが正常に検証され、mihomoカーネルが起動していることを確認します。画面上でプロファイルが選択されていても、YAMLの解析エラー、ポートの競合、ノード情報の取得失敗があると、実際の通信は処理されません。ログ画面でカーネルの起動完了と、ローカルポートの待ち受けを確認してください。

一般的な設定では、HTTPとSOCKS5をまとめて扱える mixed-port を使います。例として 127.0.0.1:7890 は、同じ端末上のアプリだけが接続できるローカルポートです。ポート番号は環境によって異なるため、実際にはClash Vergeの設定画面または有効なYAMLを確認します。external-controller の 9090 などは管理API用であり、Codex CLIのプロキシ先には指定しないでください。

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

external-controller: 127.0.0.1:9090

rules:
  - MATCH,PROXY

上の例は構造を理解するための最小例です。実際の購読設定では、proxies、proxy-groups、dns、rule-providers などが含まれます。既存の購読設定全体を置き換えるのではなく、Clash Vergeのプロファイル編集やオーバーライド機能を使い、必要な項目だけを追加してください。特にルールの順番は重要で、先に広い範囲の DIRECT ルールを置くと、後ろに書いたプロキシルールへ到達しません。

プロファイルとカーネルの状態を確認する

プロファイルが現在選択され、YAMLの検証エラーが表示されていない。
mihomoカーネルが停止しておらず、混合ポートが他のアプリと競合していない。
プロキシグループに利用可能なノードがあり、遅延テストだけでなく実通信も成功している。
ルールモードが有効で、AIサービスのドメインが意図したポリシーへ送られている。

まずシステムプロキシを有効にしてブラウザーや一般的なHTTPSアプリで通信を確認する方法が簡単です。ただし、システムプロキシを有効にしただけで、すべてのターミナルプログラムが同じ設定を使うとは限りません。Codex CLIのプロセスには、シェルの環境変数を明示的に設定するほうが結果を再現しやすくなります。

Codex CLIへプロキシ環境変数を渡す

Codex CLIをClash Vergeのローカルポートへ接続する基本方法は、ターミナルにプロキシ環境変数を設定してからコマンドを実行することです。mixedポートがHTTP CONNECTとSOCKS5の両方を受け付ける構成なら、まずはHTTP形式のURLを指定すると、HTTPSリクエストをプロキシ経由で転送できます。

# macOS / Linux / zsh / bash
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export ALL_PROXY="http://127.0.0.1:7890"

codex

SOCKS5を使う場合は、Clash VergeのポートがSOCKS接続を受け付けることを確認し、次のように指定します。ツールや内部で使用するHTTPライブラリによって対応する変数が異なるため、最初から複数の形式を混在させるのではなく、HTTP形式で失敗した場合にSOCKS5形式を試すのが安全です。

export HTTP_PROXY="socks5://127.0.0.1:7890"
export HTTPS_PROXY="socks5://127.0.0.1:7890"
export ALL_PROXY="socks5://127.0.0.1:7890"

Windows PowerShellでは、現在のセッションだけに設定する場合、次の形式を使います。

$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:ALL_PROXY="http://127.0.0.1:7890"
codex

プロキシを使わないローカルアドレスを指定する必要がある場合は、NO_PROXY を追加します。ただし、AIサービスのドメインを誤って NO_PROXY に入れると、Clash Vergeを経由しなくなります。ログイン用のローカルコールバックが必要な構成では、localhost と 127.0.0.1 だけを除外対象にするなど、対象を限定してください。

export NO_PROXY="localhost,127.0.0.1,::1"

AIサービス向けルールを設計する

Codex CLIの通信を安定させるには、すべての通信を無条件に同じノードへ送るより、対象ドメインを明示したルールを作るほうが管理しやすくなります。OpenAI関連のホスト名はサービス構成やログイン方式によって変わる可能性があるため、固定の1ドメインだけを許可リストにするのではなく、実際の接続ログで確認したドメインを基準にします。公式ドキュメントで示された接続先と、Clash Vergeの日志に記録された実際の宛先が一致しているかを確認してください。

ルールの追加位置は、既存の広告ブロック、地域分岐、プロセス分流などのルールとの関係を見て決めます。たとえば、AIサービスのドメインより前に GEOIP,CN,DIRECT のような広いルールがあると、ドメインの解決結果によっては意図せず直接接続される場合があります。反対に、対象ドメインをプロキシへ送るルールを上部へ置けば、後続の広いルールに先に一致することを防げます。

rules:
  - DOMAIN-SUFFIX,openai.com,AI
  - DOMAIN-SUFFIX,oaistatic.com,AI
  - DOMAIN-SUFFIX,auth.openai.com,AI
  - MATCH,DIRECT

これは説明用の例であり、利用中のサービスが実際に使うホスト名をすべて網羅するものではありません。AI は既存のプロキシグループ名に置き換えます。グループ名に日本語や記号が含まれている場合、YAMLの記法や引用符が必要になることがあります。設定を保存した後は、Clash Vergeのプロファイル検証を実行し、ルールの構文エラーがないことを確認してください。

DNSと直接接続を確認する

ドメインルールが機能しない原因として、DNS解決の結果、IPv6経路、またはアプリケーション側の名前解決方法が考えられます。Clash VergeでDNSを有効にしていても、Codex CLIが独自のDNS処理やOSの名前解決を使う場合、画面で想定した経路と実際の経路が異なることがあります。まずはTUNを有効にせず、プロキシ環境変数だけで動作を確認すると、DNSとルーティングの問題を分離できます。

Clash Vergeの接続ログで、対象ホスト名のルール結果が AI になっているか確認する。
同じホストへの通信が一部だけ DIRECT になっていないか確認する。
IPv4では成功し、IPv6で失敗する場合は一時的にIPv6の経路を切り分ける。
DNSエラーとTLS証明書エラーを、認証失敗と混同しない。

接続できないときの診断手順

Codex CLIが起動しない、ログイン画面が完了しない、リクエストがタイムアウトする、といった症状は原因が異なります。最初にエラーメッセージを省略せず保存し、Clash Vergeのログで同じ時刻の接続を探します。ログに対象ホストがまったく表示されない場合は、Codex CLIが環境変数を受け取っていない、または別のエンドポイントへ接続している可能性があります。

症状	考えられる原因	次の確認
接続タイムアウト	プロキシ未設定、ノード停止、ルールの直接接続	環境変数、接続ログ、プロキシグループを確認
connection refused	7890番などのポートが待ち受けていない	Clash Vergeのカーネル状態と実際のポート番号を確認
TLSまたは証明書エラー	時刻ずれ、HTTPS検査、経路上の切断	OSの日時、企業ネットワーク、Clashのログを確認
401または403	認証情報、アカウント権限、サービス側の拒否	プロキシを変える前に認証状態と利用条件を確認
CLIだけ失敗する	シェルがプロキシ変数を引き継いでいない	`env` やPowerShellの環境変数を確認

ローカルポートの疎通だけを調べる場合は、機密情報を含まない公開URLや、利用が許可されたテスト先を使います。次のコマンドは、Clash Vergeのプロキシポートを通してHTTPSリクエストを送る例です。レスポンス本文に認証トークンを含むURLを使わないでください。

curl -v \
  --proxy http://127.0.0.1:7890 \
  --connect-timeout 10 \
  --max-time 30 \
  https://example.com/

このコマンドで Connection refused が出るなら、Codex CLI以前にローカルポートの問題があります。接続が確立してからTLSエラーになる場合は、プロキシポート、ノード、DNS、証明書経路の順に調べます。curlが成功してもCodex CLIが失敗する場合は、Codex CLIが参照する認証方式、プロキシ変数名、独自の設定ファイルを確認してください。

TUNモードを使う場合の注意点

コマンドラインツールの中には、HTTPプロキシ環境変数を無視したり、子プロセスへ環境変数を渡さなかったりするものがあります。そのような場合は、Clash VergeのTUNモードでシステム全体のIP通信を取り込む方法を検討できます。ただし、TUNは管理者権限、仮想ネットワークインターフェース、DNSの引き受け、ルーティング変更に関係するため、最初から有効にする必要はありません。

まずシステムプロキシまたは環境変数でCodex CLIが動くことを確認し、それでも対象プロセスだけが経路から外れる場合にTUNへ進みます。TUNを有効にした後は、同じ通信を二重にプロキシしないよう、HTTP環境変数、システムプロキシ、TUNのルールを整理してください。二重経路になると、遅延の増加、TLS接続の再試行、ログの見分けにくさが発生します。

TUNを有効にする前に、現在のシステムプロキシ状態を記録する。
管理者権限やネットワーク拡張の許可を、OSの正式な設定画面で確認する。
DNS hijackやstrict-routeは、環境に必要な場合だけ有効にする。
企業VPN、Docker、WSL、別の仮想ネットワークアダプターとの競合を確認する。
通信が直った後も、Clash Vergeのログで対象ドメインと実際の策略を確認する。

最終的には、Codex CLIの認証が有効で、Clash Vergeのログに対象通信が現れ、意図したプロキシグループで接続できる状態を目標にします。プロキシポートを変更した場合は、シェルの環境変数も同じ番号へ更新してください。接続トラブルのたびにノード、DNS、TUN、認証を一度に変更するのではなく、ローカルポート、単純なHTTPS疎通、ドメインルール、Codex CLIの順に確認すると、原因を短時間で絞り込めます。