Codex Windows のインストールとトラブルシューティング: ネイティブ PowerShell、WSL、サンドボックスの権限とパスの問題

Windows 上の Codex に関する最も一般的な問題は、多くの場合モデルの機能ではなく、実行環境です。つまり、コマンドが Windows と WSL のどちらにインストールされているか、リポジトリパスがどのファイルシステムに属しているか、Git がどの認証情報のセットを使用しているか、どの環境変数が端末によって継承されているか、サンドボックスで書き込みが許可されているかどうかなどです。ネイティブ PowerShell と WSL はどちらもエントリポイントとして使用できますが、同じタスク内で 2 つのノード、Git、Python、パスのセットを混合しないでください。この記事は、最初にルートを選択するのに役立ち、次にインストール、ログイン、リポジトリの検証、および障害の場所を完了するのに役立ちます。 Codex のインストール方法、モデル、および特定の承認インターフェイスは引き続き更新される可能性があります。この記事の診断原則は長期間再利用でき、インストールコマンドは OpenAI Codex 公式ドキュメントの現在のページで確認する必要があります。

最初にネイティブ Windows または WSL を選択します。

ネイティブ PowerShell の方が適しています。

プロジェクトは元々、C:\Work などの Windows ディレクトリにあります。
Visual Studio、MSBuild、PowerShell、または Windows SDK によって異なります。
テストでは Windows プログラムを呼び出す必要があります。
チームコマンドと展開スクリプトは主に PowerShell です。 WSL は次の場合に適しています。
プロジェクトの運用環境が Linux である。
Bash、GNU ツール、Docker Linux ワークフローに依存する。
大文字と小文字、パーミッションビット、またはシンボリックリンクを区別するコードが含まれる。
チーム README 主に Linux コマンドを提供します。選択の原則はシンプルです。Codex をプロジェクトのメインツールチェーンと同じ環境に維持します。特定のコマンドが WSL で短いからといって、Windows リポジトリ、Windows ノード、および WSL Git を 1 つのタスクに混在させないでください。

コンピューター上の 2 つの既存の環境のインベントリ

PowerShell でチェックイン:

1
2
3
4
5
6


Get-Command codex -ErrorAction SilentlyContinue
Get-Command node -ErrorAction SilentlyContinue
Get-Command git -ErrorAction SilentlyContinue
codex --version
node --version
git --version

WSL を入力:

1
2
3


wsl --status
wsl --list --verbose
wsl

WSL 内で実行:

1
2
3
4
5
6


command -v codex
command -v node
command -v git
codex --version
node --version
git --version

両側の出力が異なっていてもエラーではなく、これらは本質的に独立した環境です。問題は、ユーザーは一方がアップグレードされていると思っていても、もう一方は実際には実行されているということです。

ネイティブ PowerShell インストール前の準備

まず、64 ビット PowerShell と Node が利用可能であることを確認します。

1
2
3
4


$PSVersionTable
[Environment]::Is64BitProcess
node --version
npm --version

npm を使用して Codex をインストールする場合は、公式の現在のインストールコマンドを実行します。一般的な形式は次のとおりです。

1

npm install -g @openai/codex

インストール後:

1
2
3


Get-Command codex
codex --version
codex --help

公式 Windows インストーラーまたはその他の推奨方法が提供されている場合は、最新の公式手順が最初に使用されます。 npm、スタンドアロンバイナリ、および複数のパッケージマネージャーを使用して、Codex の 3 つのコピーを同時にインストールしないでください。コマンドによって解決された実際のパスを表示します:

1
2


(Get-Command codex).Source
npm config get prefix

ネイティブログインと認証情報

ログインの開始:

1

codex login

ブラウザのログインが完了したら、同じ Windows ユーザーの端末検証に戻ります。管理者 PowerShell でログインし、通常のユーザーとして実行しないでください。ユーザーディレクトリと資格情報は異なる場合があります。 API Keyを使用する場合は、公式サポートの方法に従って設定してください。一時環境変数は、現在のプロセスとそのサブプロセスでのみ有効です。

1
2


$env:OPENAI_API_KEY = '<temporary-key>'
codex

実際のキーを PowerShell プロファイル、リポジトリスクリプト、またはコマンド履歴に書き込まないでください。テストが完了したら、ターミナルを閉じ、必要に応じてキーを取り消します。ログインに失敗した場合は、まずシステム時刻、ブラウザのコールバック、ファイアウォール、プロキシを確認し、構成ディレクトリ全体を繰り返し削除しないでください。

ネイティブ Windows でリポジトリを開きます。

絶対パスを使用します:

1
2
3
4


Set-Location -LiteralPath 'C:\Work\my-project'
git rev-parse --show-toplevel
git status --short
codex

パスにスペースが含まれている場合、-LiteralPath は手動エスケープよりも信頼性が高くなります。開始後、Codex に読み取り専用チェックを実行させます。

1

报告当前工作目录、Git 分支和未提交文件，不要修改文件。

報告されるパスは git rev-parse --show-toplevel と一致している必要があります。エラーが発生した場合は、セッションを終了し、正しいディレクトリで再起動します。

WSL インストールの正しい場所

指定されたディストリビューションを PowerShell に入力します。

1

wsl -d Ubuntu

WSL にノードとコーデックスをインストールします。 Linux のインストールを完了したふりをして /mnt/c/Program Files/nodejs/npm.cmd を呼び出さないでください。すべてのコマンドが Linux パスからのものであることを確認します。

1
2
3
4


which node
which npm
which codex
file "$(which codex)"

公式のインストールコマンドを実行してログインします。

1
2


npm install -g @openai/codex
codex login

WSL のログイン状態は、通常、Windows のネイティブ状態とは別のものです。同じブラウザアカウントで認証が完了した場合でも、対象環境で別途認証が必要となります。

WSL リポジトリが /home と /mnt/c のどちらに配置されるか

Linux ツールチェーンプロジェクトは、WSL 独自のファイルシステムで優先されます。たとえば、

1
2
3
4
5


mkdir -p ~/src
cd ~/src
git clone https://github.com/example/project.git
cd project
codex

/mnt/c/Work/project は Windows プログラムから直接アクセスするのに便利ですが、多数の小さなファイル、パーミッションビット、シンボリックリンク、ファイルリスニング、およびケースの動作が必要になります。異なる場合があります。プロジェクトを Visual Studio と WSL の両方で使用する必要がある場合は、Windows ディスク上に残しておくこともできますが、次のことをテストする必要があります。

npm/pnpm のインストール速度、
Git ファイルのアクセス許可の変更、
Watcher のイベントのリーク、
シンボリックリンクが正常に作成されました。
ケースに依存するかどうかをテストします。
Docker バインドマウントのパフォーマンス。 Windows と WSL から 2 つのフォーマッタを同時に実行して、同じ作業ツリーを変更しないでください。

Windows パスと WSL パスの交換

PowerShell パス:

1

C:\Work\my-project

通常は WSL に対応します:

1

/mnt/c/Work/my-project

wslpath を使用する変換は文字列置換よりも信頼性が高くなります:

1
2


wslpath 'C:\Work\my-project'
wslpath -w /home/user/src/project

Pass を入れないでください。 C:\... パスを Linux ネイティブコマンドに直接指定します。 /home/... を通常の Windows プログラムに渡して、自動的に認識されることを期待しないでください。 Codex ツール呼び出しのパスは、それが起動される環境に属している必要があります。

一方の側では Git 認証情報を取得できるのに、もう一方の側では取得できないのはなぜですか?

PowerShell の Git は Git Credential Manager を使用する場合があります。 WSL Git は SSH エージェント、Linux 資格情報ストアを使用するか、ヘルパーが構成されていない可能性があります。 Windows チェック:

1
2


git config --show-origin --get-all credential.helper
git remote -v

WSL チェック:

1
2
3


git config --show-origin --get-all credential.helper
git remote -v
ssh -T [email protected]

WSL プルの失敗を修正するために、リモート URL にパーソナルアクセストークンを書き込まないでください。これは、.git/config、ログ、およびプロセスパラメーターに表示されます。より安全な方法は、選択した環境で GitHub CLI、SSH キー、またはサポートされている認証情報ヘルパーを構成することです。

CRLF と「すべてのファイルが変更されました」

CRLF は Windows で一般的に使用され、LF は Linux で一般的に使用されます。 .gitattributes が不明瞭な場合、環境を切り替えると、Git は多数のファイルが変更されたと認識する可能性があります。最初に見てください:

1
2
3


git status --short
git diff --numstat
git config --show-origin --get core.autocrlf

リポジトリは、.gitattributes を通じてポリシーを宣言する必要があります。例:

1
2
3


* text=auto
*.sh text eol=lf
*.ps1 text eol=crlf

実際のルールはチームと一致している必要があります。ユーザーが変更をコミットしていない場合は、一括再正規化コマンドを実行しないでください。 Codex を開始するとすぐに何百もの変更が見られる場合は、エージェントに「修復」を続行させるのではなく、まず書き込みを停止し、それが改行、パーミッションビット、または生成されたファイルであるかどうかを確認してください。

PowerShell の引用符は Bash の引用符とは異なります。

PowerShell の一重引用符は変数を展開しませんが、二重引用符は変数を展開します。

1
2
3


$name = 'demo'
Write-Output '$name'
Write-Output "$name"

Bash のルールは似ていますが、同一ではなく、パイプラインオブジェクトモデルは異なります。エラーが発生しやすいコンテンツには、

JSON の二重引用符、
正規表現の $、
Git コミットメッセージのバックティック、
スペースを含むパス、
PowerShell パラメータにバインドされたネイティブコマンドパラメータ。
curl は、古い PowerShell のエイリアスである可能性があります。単に「Windows コマンド」と言うのではなく、「PowerShell 7 で実行する」などのコマンドを作成するときに、Codex にターゲットシェルを指定させます。

サンドボックスと承認は Windows UAC ではありません。

Codex のサンドボックスは、エージェントが今回何を読み取り、書き込み、実行できるかを決定します。 Windows UAC および NTFS ACL は、オペレーティングシステムレベルのアクセス許可を決定します。両者はレベルが異なります。プログラムが管理者として実行されている場合でも、Codex はサンドボックスポリシーにより特定の書き込みを拒否する場合があります。逆に、サンドボックスでは、NTFS アクセス許可を侵害できないコマンドの実行が許可されます。タスクを開始する前に確認してください:

ワークスペースのルートディレクトリが正しいかどうか、
リポジトリへの書き込みのみが許可されているかどうか、
ネットワークアクセスが必要かどうか、
コマンドの実行に承認が必要かどうか、
ユーザー設定ディレクトリは範囲外です。
他のマウントディスクにアクセスするかどうか。プロンプトを避けるためだけに最高特権モードを永続的に使用しないでください。高い権限には、明確なタスクと検証可能な目標が対応している必要があります。

「アクセスが拒否されました」の階層化されたトラブルシューティング

最後の文を読むだけではなく、最初に完全なエラーパスを取得します。ファイル属性と ACL を確認します:

1
2


Get-Item -LiteralPath '.\target-file'
Get-Acl -LiteralPath '.\target-file' | Format-List

他のプロセスによって占有されているかどうかを確認します:

1

Get-Process | Where-Object { $_.ProcessName -match 'node|python|dotnet|code' }

次に判断します:

Codex サンドボックスの範囲、
Windows ファイルのアクセス許可、
ファイル読み取り専用属性;
ウイルス対策ソフトウェアのインターセプト;
ファイルロック;
パスが長すぎるか文字の問題;
WSL マウント権限マッピング。 Defender を直接オフにしたり、全員にディスク全体に対するフルコントロールを与えたりしないでください。

ノード、Python、およびパッケージマネージャーの競合

Windows には、winget Node、nvm-windows、Volta、およびプロジェクト内ツールが同時に存在する可能性があります。 WSL には、nvm またはシステムノードのセットもあります。実際の解析パスを記録します:

1

Get-Command node,pnpm,python,pip | Select-Object Name,Source

WSL:

1

type -a node pnpm python3 pip3

Codex に依存関係をインストールさせる前に、packageManager、ロックファイル、.nvmrc、.python-version、またはリポジトリのツール設定を読んでください。 package-lock.json、pnpm-lock.yaml、および yarn.lock が同時に表示される場合は、エージェントにパッケージマネージャーを推測させないでください。まずプロジェクトのドキュメントと Git 履歴を確認する必要があります。

Docker Desktop と WSL

ネイティブ PowerShell と WSL はどちらも Docker Desktop を呼び出すことができますが、コンテキストとパスのマウント方法が異なります。確認:

1
2
3


docker context show
docker version
docker compose version

WSL で同じコマンドを実行して、予想されるエンジンへの接続を確認します。 Compose ファイル内の Windows パス、WSL パス、名前付きボリュームは交換できません。権限の問題が発生した場合は、まず docker compose config を実行して解析結果を表示します。信頼できないコンテナやエージェントに Docker Socket を公開しないでください。 Docker デーモンにアクセスできるということは、通常、ホストマシン上で高い権限を取得することを意味します。

プロキシと TLS エラー

企業ネットワークでは、ブラウザがログインできるからといって、npm、Git、Codex CLI が外部ネットワークにアクセスできるわけではありません。 PowerShell View エージェント変数:

1

Get-ChildItem Env:HTTP_PROXY,Env:HTTPS_PROXY,Env:NO_PROXY -ErrorAction SilentlyContinue

Git View エージェント:

1

git config --show-origin --get-regexp 'http\..*proxy'

WSL 環境変数は Windows と自動的に同期されません。それらを個別に構成し、実際に直接接続が必要なローカルアドレスを NO_PROXY に含めます。長期的な解決策として TLS 検証をオフにしないでください。エンタープライズ CA をインストールするか、ネットワーク管理者が正しいプロキシ構成を提供する必要があります。

タスクを開始する前にベースラインを保存します。

使用する環境に関係なく、最初に実行します。

1
2
3


git status --short
git branch --show-current
git rev-parse --show-toplevel

どの変更がユーザーに属するか、どのファイルを変更できるか、どのテストを実行する必要があるかを Codex に伝えます。完了後に少なくとも次のことを確認してください。

1
2
3


git status --short
git diff --stat
git diff --check

リスクの高いタスクでは、プロジェクトのテストとビルドも実行する必要があります。 Git の差分やテスト結果の代わりに「Codex は完了したと言っています」を使用しないでください。

一般的な症状のクイックチェック

PowerShell がコーデックスを見つけられない

端末を再起動し、npm config get prefix と Get-Command codex をチェックして、WSL のみにインストールされていないことを確認します。

WSL のコーデックスは .cmd を指します

説明 PATH が Windows npm グローバルディレクトリに混在しています。 PATH をクリアし、WSL 内に Linux バージョンをインストールします。

ログイン成功後も認証されていない旨のメッセージが表示される

実行中のユーザーや環境がログイン時と同じであることを確認してください。管理者端末、一般端末、Windows、WSLはそれぞれ独立した構成となっている場合があります。

Git はすべての権限ビットの変更を表示します

core.fileMode、リポジトリの場所、および WSL マウント動作を確認します。まず変更を理解してください。直接コミットしないでください。

PowerShell ではテストが失敗するが、WSL では成功する

シェルスクリプト、パス区切り記号、環境変数の構文、依存バイナリを確認してください。時々利用できる 2 つのプロセスセットを維持するのではなく、運用目標に基づいてプライマリ環境を選択します。

Codex がワークスペース外のディレクトリへのアクセスを要求します。

ディレクトリが実際にビルドキャッシュまたは SDK であるかどうかを確認します。タスクで必要でない場合は、タスクを拒否し、代わりにリポジトリ内の一時ディレクトリを使用させます。

推奨される安定した組み合わせ

Windows/.NET/PowerShell プロジェクト: コードはネイティブ Codex、Windows Git、PowerShell 7 を使用して NTFS に配置されます。 Linux サービス/ノード/Python プロジェクト: コードは WSL Codex、Linux Git および PowerShell 7 を使用して WSL ~/src に配置されます。バッシュ。両側のプロジェクトにまたがる必要があります。一意の Git 作成環境を指定し、もう一方の側では特定のツールのみを実行し、.gitattributes で改行戦略を修正します。最も重要なことは、どのルートが「より高度」であるかではなく、コマンド、ファイルシステム、認証情報、テストが同じ解釈可能な環境にあるかどうかです。環境が安定すると、Codex のトラブルシューティングコストは大幅に削減されます。

Windows と WSL の参考資料

OpenAI Codex 公式ドキュメント
Microsoft WSL ファイルシステムの説明
[Git プロパティ]ドキュメント](https://git-scm.com/docs/gitattributes)