【Codex】【備忘録】Ubuntu VPS上でCodex CLI使用時の不具合対応例:2026/7/18

Codex CLI

/var/lib/snapd/voidに飛ばされるSnap版Codexの問題を解決する

WindowsのVS CodeからRemote-SSHでUbuntu VPSへ接続し、VPS上のプロジェクトをCodex CLIで編集できるようにした。

今回もっとも重要だったポイントは、VPSに入っていたCodexがOpenAI公式の配布経路ではなく、第三者が公開したSnap版だったことである。Snapのサンドボックス制限により、/srv配下のプロジェクトを正しく参照できず、Codexの作業ディレクトリが/var/lib/snapd/voidとして見えていた。

最終的にはSnap版を削除し、OpenAI公式のCodex CLIへ入れ替えることで解決した。

OpenAIはCodex CLIを、ターミナル上でリポジトリの調査、ファイル編集、コマンド実行に使用できるツールとして提供している。公式配布ではインストーラーのほか、@openai/codex npmパッケージも案内されている。

1. 今回の環境

構成は次のとおり。

Windows PC
 └─ Visual Studio Code
     └─ Remote-SSH
         └─ Ubuntu VPS
             └─ /srv/ono-piano.com/OnoPiano.Com2026
                 ├─ AGENTS.md
                 ├─ app.py
                 ├─ tests
                 └─ その他のプロジェクトファイル

VPSのログインユーザーはadminで、対象プロジェクトは次の場所にある。

/srv/ono-piano.com/OnoPiano.Com2026

2. 発生した症状

CodexにAGENTS.mdを更新させようとしたところ、次のようなログが出た。

Ran pwd
└ /var/lib/snapd/void

さらに、Codexは次のように判断していた。

この作業は /var/lib/snapd/void 配下の読み取り権限が必要ですが、
現状のサンドボックスでは AGENTS.md を開けません。

Gitの状態確認も失敗した。

git -C /var/lib/snapd/void status --short

fatal: not a git repository
(or any parent up to mount point /var/lib)

一見すると、AGENTS.mdやプロジェクトディレクトリのLinuxパーミッションが原因に見える。

しかし、今回の本当の原因は、通常のchmodやchownで直すファイル権限ではなかった。

3. /var/lib/snapd/voidとは何だったのか

本来、Codexを次のディレクトリから起動していた。

cd /srv/ono-piano.com/OnoPiano.Com2026
codex

それにもかかわらず、Codex側から見た作業場所は次になっていた。

/var/lib/snapd/void

今回の環境では、Snap版Codexのサンドボックスからアクセスできない場所が、実際の/srvディレクトリではなく、Snap内部のダミー領域として見えていた。

その結果、次の問題が連鎖的に発生した。

/srvのプロジェクトが見えない
        ↓
AGENTS.mdが見つからない
        ↓
Gitリポジトリも見つからない
        ↓
読み取り権限がないように見える
        ↓
Codexがファイル編集を実行できない

ただし、/var/lib/snapd/voidと表示されたことだけでSnapが原因だと断定せず、次のコマンドで実体を確認する必要がある。

4. インストール済みCodexの確認

VPSのターミナルで次を実行した。

which codex
snap list | grep -i codex

結果は次のとおりだった。

/snap/bin/codex

Snapの一覧にもCodexが表示された。

codex  0.114.0  34  latest/stable  jcat-nysasounds  -

これにより、現在実行されているCodexがSnap版であることが確認できた。

さらに、PublisherがOpenAIではなく、第三者の名前になっていた。少なくとも、OpenAIが公式ドキュメントで案内しているインストーラーまたは@openai/codex npmパッケージとは異なる配布経路である。

より詳しく確認する場合は、次も実行できる。

type -a codex
command -v codex
readlink -f "$(command -v codex)"

コマンドは改行して実行する

今回、コピー時にコマンドが連結され、次のようになった場面があった。

snap list | grep -i codexwhich codex

この場合、grepがcodexwhichなどをファイル名として扱い、次のようなエラーが出ることがある。

grep: codex: No such file or directory

正しくは、別々の行で実行する。

which codex
snap list | grep -i codex

5. Snap版Codexを削除する

Snap版を削除した。

sudo snap remove codex

削除後、シェルが以前のコマンド位置を記憶している可能性があるため、キャッシュを更新する。

hash -r

Codexが見つからなくなったことを確認する。

command -v codex

何も表示されなければ、Snap版はPATHから消えている。

念のため確認する。

snap list | grep -i codex

Codexが表示されなければ削除完了である。

6. Node.jsとnpmの確認

npm版を使う場合は、Node.jsとnpmが必要になる。

node -v
npm -v

例えば次のようにバージョン番号が表示されればよい。

vXX.XX.X
XX.XX.X

コマンドが見つからない場合は、利用しているUbuntu環境の方針に従って、サポート中のNode.jsをインストールする。

Pythonの仮想環境である.venvは、Codex CLIのインストールには直接関係しない。

(.venv) admin@server:...

と表示されていても、Codex CLIはNode.js/npmで動くため、Pythonパッケージとしてインストールするわけではない。

7. OpenAI公式のCodex CLIをインストールする

方法A：npmでシステム全体にインストール

今回使用した方法はこちら。

sudo npm install -g @openai/codex

短縮形でも同じである。

sudo npm i -g @openai/codex

OpenAIの公式案内にも@openai/codexのグローバルインストール方法が掲載されている。

インストール後に確認する。

which codex
codex --version

例えば次のように、/snap/bin以外が表示されればよい。

/usr/local/bin/codex

環境によっては次のような場所になる。

/usr/bin/codex
/home/admin/.local/bin/codex

重要なのは、次になっていないことである。

/snap/bin/codex

方法B：sudoを使わずユーザー領域へインストール

VPSのシステム領域を変更したくない場合は、npmのグローバル領域をユーザーのホームに設定できる。

mkdir -p "$HOME/.local"

npm config set prefix "$HOME/.local"

grep -qxF 'export PATH="$HOME/.local/bin:$PATH"' ~/.bashrc \
  || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

export PATH="$HOME/.local/bin:$PATH"

npm install -g @openai/codex

確認する。

which codex
codex --version

この場合は、通常次のようになる。

/home/admin/.local/bin/codex

現在の公式インストーラーを使う方法

OpenAIの現行ドキュメントでは、macOS/Linux向けのスタンドアロンインストーラーも案内されている。新規環境では、公式ドキュメントを確認した上でこちらを使用してもよい。

curl -fsSL https://chatgpt.com/codex/install.sh | sh

今回の備忘録では、問題のあったSnap版をnpm版へ置換した実績を重視し、npm方式を使用した。

8. VPS上でCodexへログインする

インストール後、VPS上で認証する。

codex login

Codexは、ChatGPTアカウントによるサインインと、OpenAI APIキーによるサインインに対応している。ChatGPTでログインした場合はChatGPT側の利用権限、APIキーを使用した場合はAPI側の従量課金が適用される。

VPSではlocalhost認証に失敗することがある

通常のブラウザ認証では、認証後に次のようなURLへ戻ろうとする。

http://localhost:1455/...

しかし、ブラウザはWindows PC上で開いており、Codex CLIはVPS上で動いている。

そのため、ブラウザのlocalhostはVPSではなくWindows PC自身を指し、次のエラーになることがある。

このサイトにアクセスできません
localhostで接続が拒否されました
ERR_CONNECTION_REFUSED

これはChatGPTへのログインそのものに失敗したとは限らない。認証結果をVPS上のCodexへ戻せていない状態である。

9. Device Codeでログインする

VPSやヘッドレス環境ではDevice Code認証を使用する。

codex login --device-auth

表示されたURLをWindows側のブラウザで開き、ターミナルに表示された一時コードを入力する。

対話形式のログイン画面が表示されている場合は、Escキーを押し、次を選択してもよい。

Sign in with Device Code

OpenAIも、リモート環境やlocalhostコールバックが使用できない環境では、Device Code認証を推奨している。

Device Codeの選択肢が使えない場合は、ChatGPTのセキュリティ設定またはワークスペース設定でDevice Code Loginが許可されているか確認する。

10. ログイン状態を確認する

認証後、次を実行する。

codex login status

成功していれば、例えば次のように表示される。

Logged in using ChatGPT

ログアウトする場合は次を使用する。

codex logout

OpenAI公式ドキュメントでも、ログイン状態の確認にはcodex login statusを使用するとされている。

Codex CLIとIDE拡張は、同一環境で動作している場合、キャッシュされた認証情報を共有する。認証情報は環境によって~/.codex/auth.jsonまたはOSの資格情報ストアに保存される。

ただし、

Windowsローカル環境

と、

SSH接続先のUbuntu VPS

は別の実行環境である。

そのため、Windows側でログイン済みでも、VPS側のadminユーザーで再認証が必要になる場合がある。

11. 正しいプロジェクトディレクトリからCodexを起動する

Codexを起動する前に、必ず対象プロジェクトへ移動する。

cd /srv/ono-piano.com/OnoPiano.Com2026

現在位置を確認する。

pwd

結果が次であることを確認する。

/srv/ono-piano.com/OnoPiano.Com2026

Gitリポジトリであることも確認する。

git status

その後、Codexを起動する。

codex

Codexの起動画面で、作業ディレクトリが正しく表示されているか確認する。

directory: /srv/ono-piano.com/OnoPiano.Com2026

/var/lib/snapd/voidではなく、実際のプロジェクトパスが表示されれば解決である。

OpenAI公式のCLI手順でも、プロジェクトディレクトリを開いてからcodexを実行する流れが案内されている。

12. ワンライナーで確実に起動する

毎回cdを忘れないように、次のように起動してもよい。

cd /srv/ono-piano.com/OnoPiano.Com2026 && codex

エイリアスを設定することもできる。

echo "alias codex-ono='cd /srv/ono-piano.com/OnoPiano.Com2026 && codex'" \
  >> ~/.bashrc

source ~/.bashrc

以後は次だけで起動できる。

codex-ono

複数プロジェクトがある場合は、それぞれ別のエイリアスを作成すると分かりやすい。

13. VS Code Remote-SSHで使う場合の確認

Codex CLIだけを使うなら、VS CodeのCodex拡張は必須ではない。

ただし、VS Code右側のCodexパネルをRemote-SSH先で使用する場合は、Codex拡張をWindowsローカルだけでなく、SSH接続先にもインストールする必要がある。

VS Codeの拡張機能画面で、次のセクションを確認する。

SSH: ONOPIANO-VPS - INSTALLED

その中に、OpenAI公式の次の拡張が表示されている必要がある。

Codex – OpenAI's coding agent

拡張の詳細画面では、次のような表示になる。

Extension is enabled on 'SSH: onopiano-vps'

ローカル側のLOCAL - INSTALLEDにだけ表示されている場合、リモートVPS側にはインストールされていない。

Remote-SSH接続の確認

VS Code左下に次が表示されていることを確認する。

SSH: onopiano-vps

ターミナルでも確認する。

hostname
whoami
pwd

例えば次のようになれば、VPS側のターミナルである。

x220-158-17-145
admin
/srv/ono-piano.com/OnoPiano.Com2026

次のようなWindowsパスが表示される場合は、ローカルターミナルである。

D:\usr8_work\...

Codex IDE拡張は、エディタで開いているファイルや選択範囲をコンテキストとして利用し、変更内容をVS Code内でレビューするための機能を提供している。

14. Codexパネルがロゴのまま止まる場合

CLIは正常に動いているのに、VS Code右側のCodexパネルがロゴ表示のまま止まる場合がある。

まず次を確認する。

1. Remote-SSH先にCodex拡張がインストールされているか
2. VPS側でcodex login statusが成功するか
3. VPS側のwhich codexが/snap/bin/codexになっていないか
4. VS Codeのウィンドウを再読み込みしたか

コマンドパレットを開く。

Ctrl + Shift + P

次を実行する。

Developer: Reload Window

それでも直らない場合は、CLIを直接使用すればVPS上の開発作業は継続できる。

cd /srv/ono-piano.com/OnoPiano.Com2026
codex

VS Code拡張のGUIとCodex CLIは別の操作画面なので、GUIが表示されない場合でも、CLIが正常ならプロジェクトの調査、編集、テスト実行は可能である。

15. AGENTS.mdを用意する

Codexでは、プロジェクト固有の継続的な指示をAGENTS.mdに記述する。

/srv/ono-piano.com/OnoPiano.Com2026/AGENTS.md

Codex CLI内で次を実行すると、初期ファイルを作成できる。

/init

OpenAI公式ドキュメントでも、AGENTS.mdはCodexが自動的に読み込むプロジェクト指示ファイルであり、ビルド方法、テスト方法、リポジトリ構成、禁止事項、完了条件などを記載する場所とされている。

例：

# AGENTS.md

## Project root

The project root is:

`/srv/ono-piano.com/OnoPiano.Com2026`

Do not work outside this directory unless explicitly instructed.

## Source of Truth

The authoritative specification files are stored under:

- `docs/spec/`
- `docs/architecture.md`

Read the applicable specification before changing code.

## Development rules

- Make the minimum necessary change.
- Do not modify production configuration without approval.
- Do not delete existing files without approval.
- Do not expose secrets or environment variables.
- Check `git diff` before completing a task.

## Verification

Run the appropriate checks before reporting completion:

```bash
git diff --check
python -m unittest -v

Definition of Done

A task is complete only when:

  1. The requested change is implemented.
  2. Relevant tests pass.
  3. git diff --check succeeds.
  4. Modified files are summarized.
  5. Unresolved risks are reported.

---

## 16. Codexが`AGENTS.md`を読んでいるか確認する

Codexを必ずプロジェクト直下から起動する。

```bash
cd /srv/ono-piano.com/OnoPiano.Com2026
codex

Codex内で次のように指示する。

現在の作業ディレクトリを確認してください。
読み込んだAGENTS.mdの場所と、重要な指示を要約してください。
ファイル変更は行わないでください。

Codexが次のように認識すればよい。

Working directory:
/srv/ono-piano.com/OnoPiano.Com2026

Instructions:
/srv/ono-piano.com/OnoPiano.Com2026/AGENTS.md

Codexが誤った指示を読み込む場合は、上位ディレクトリにあるAGENTS.override.mdや、別のAGENTS.mdを確認する。

公式ドキュメントでは、Codexは現在の作業ディレクトリまで指示ファイルを探索し、より作業場所に近い指示を優先する。起動ディレクトリが違うと、期待したAGENTS.mdが読み込まれない。

17. 最終確認用コマンド

以下を上から実行すれば、基本的な設定状態を確認できる。

echo "===== User and host ====="
hostname
whoami

echo "===== Current directory ====="
pwd

echo "===== Codex executable ====="
which codex
readlink -f "$(command -v codex)"

echo "===== Codex version ====="
codex --version

echo "===== Login status ====="
codex login status

echo "===== Git repository ====="
git status --short

echo "===== AGENTS.md ====="
ls -la AGENTS.md

期待する状態は次のとおり。

whoami
→ admin

pwd
→ /srv/ono-piano.com/OnoPiano.Com2026

which codex
→ /usr/local/bin/codex
  または /home/admin/.local/bin/codex

codex login status
→ Logged in using ChatGPT

git status
→ 正常にGit状態が表示される

ls -la AGENTS.md
→ ファイルが存在する

次の状態は問題が残っている。

which codex
→ /snap/bin/codex

pwd
→ /var/lib/snapd/void

git status
→ not a git repository

18. トラブル別の切り分け

codex: command not found

PATHが反映されていない可能性がある。

source ~/.bashrc
hash -r
which codex

ユーザー領域へインストールした場合は確認する。

echo "$PATH"
ls -la ~/.local/bin/codex

localhostで接続が拒否されました

VPS上のCodexへブラウザ認証結果を戻せていない。

codex login --device-auth

を使用する。

Logged in using ChatGPTだがCodexが動かない

現在のディレクトリを確認する。

pwd
git status

正しいディレクトリへ移動して再起動する。

cd /srv/ono-piano.com/OnoPiano.Com2026
codex

AGENTS.mdを開けません

ファイル権限だけでなく、Codexの実行ファイルと現在位置を確認する。

which codex
pwd
ls -la AGENTS.md

which codexが/snap/bin/codexなら、今回と同じSnap版問題の可能性がある。

fatal: not a git repository

CodexがGitリポジトリ外で起動している。

cd /srv/ono-piano.com/OnoPiano.Com2026
git status
codex

VS CodeのCodexパネルだけ表示されない

CLIが使えるか確認する。

codex login status
codex --version
codex

CLIが使えるなら、VPS側の開発自体は可能である。

次に、VS Codeの次を確認する。

SSH: ONOPIANO-VPS - INSTALLED

ここにCodex拡張があることを確認し、次を実行する。

Developer: Reload Window

必要に応じて、VS CodeのOUTPUTパネルからCodexログを確認する。

19. 認証情報の注意点

Codexの認証情報が~/.codex/auth.jsonに保存されている場合、このファイルにはアクセストークンが含まれる。

そのため、次の操作は禁止する。

Gitへコミットする
ブログへ内容を掲載する
チャットへ本文を貼り付ける
他人へ送付する

.gitignoreにも追加しておくと安全である。

.codex/
**/.codex/auth.json

ただし、通常の認証ファイルはプロジェクト直下ではなく、ユーザーのホームにある。

/home/admin/.codex/auth.json

OpenAIも、auth.jsonをパスワードと同様に扱い、共有やコミットを行わないよう案内している。

20. 今回の結論

今回の問題は、単純なLinuxのファイルパーミッションではなかった。

原因と解決の流れは次のとおり。

Codexが/srvのプロジェクトを読めない
        ↓
pwdが/var/lib/snapd/voidになる
        ↓
AGENTS.mdとGitリポジトリを認識できない
        ↓
which codexで/snap/bin/codexを確認
        ↓
第三者配布のSnap版Codexを削除
        ↓
OpenAI公式のCodex CLIをインストール
        ↓
Device CodeでVPS側を認証
        ↓
正しいプロジェクトへcdして起動
        ↓
/srv配下のファイルを正常に編集可能

最終的な基本コマンドは次の4行である。

cd /srv/ono-piano.com/OnoPiano.Com2026
which codex
codex login status
codex

VPSでCodex CLIを使う場合は、次の3点を最初に確認するのが重要である。

1. Codexがどこからインストールされているか
2. どのLinuxユーザーで認証されているか
3. どの作業ディレクトリから起動しているか

特に、chmodやsudoを繰り返す前に、

which codex
pwd
git status

を確認することで、今回のようなSnapサンドボックス問題と、通常のファイル権限問題を早く切り分けられる。

コメント

タイトルとURLをコピーしました