NixOS Codexの導入とCLI設定・安全な動作確認の実践手順

NixOSでCodexを使う前に知るべき位置づけ

Codexは、ターミナルからプロジェクトのファイルを読み、変更案を作り、必要なコマンドや確認を進めるAIコーディングエージェントです。NixOSとの組み合わせでは、Codexが扱うプロジェクトの状態と、Nixが提供する実行環境の状態を分けて見ることが大切です。ファイルを置いた場所、利用できるコマンド、動的ローダー、sandbox用の道具が同時に関係するため、どこで問題が起きているかを一つずつ切り分けます。

NixOSは、必要なパッケージや設定を宣言して環境を再現しやすい一方、一般的なLinux向けバイナリをそのまま置いて起動するだけでは足りない場合があります。これはCodexに固有の問題ではありません。Nixの管理下にない実行ファイルが、通常のLinuxで前提にするローダーやライブラリを見つけられないことがあるためです。最初から深い設定へ進まず、公式CLIの導入、コマンドの検出、sandboxの起動という順に確認します。

Linux向け公式CLIをNixOSで使う考え方

OpenAIの公式CLIドキュメントは、Codexをターミナルで使い、プロジェクトの内容を調べ、変更し、結果を確認する入口として説明しています。NixOSでは、導入方法をNixOSのパッケージとして扱うか、公式インストーラーでユーザー環境へ入れるかを選べます。公式パッケージが現在のチャンネルで提供されているかは、先にNixOSのパッケージ検索で確認し、見つからなければLinux向け公式インストーラーを使う判断が現実的です。

この二つは優劣ではなく、管理の単位が違います。Nixの設定で管理すれば世代の切り替えや再現がしやすくなり、公式インストーラーを使えばCodexの公開版に追随しやすくなります。ただし、公式インストーラーで導入したものをNixOSのシステム設定に書いたことにすることはできません。どこへ入れたか、どのユーザーが使うか、更新時に何を戻せるかを記録しておきます。

先行版と日常利用を分ける

今回確認できる0.155.0-alpha.16は、GitHub公式リリースで先行版と表示されています。新しい番号は不具合修正や改善を含む可能性がありますが、安定版と同じ意味ではありません。NixOSの強みである世代管理を生かし、普段のプロジェクトと確認用の小さなプロジェクトを分け、起動、ファイル読み取り、限定した変更、結果の確認までを一通り試してから常用するか決めます。

先行版を試した結果を評価するときは、「起動した」だけで合格にしないことが重要です。NixOSのシェルへ入ったときに同じPATHが見えるか、Codexがプロジェクトを読み取れるか、sandboxが意図した範囲に収まるか、変更後にテストや差分を読めるかまで確認します。これらを記録しておけば、次の版で何が変わったのかを比べやすくなります。

導入前にNixOSの状態を確認する

Codexを入れる前に、OSの版、CPUアーキテクチャ、シェル、ネットワーク、主要コマンドの場所を確認します。問題が起きた後にまとめて調べると、Codexの導入失敗なのか、NixOSの環境差なのかが分かりにくくなります。確認結果はターミナルの出力を保存するだけでもよく、個人情報や不要なパスを公開記事へ貼り付けないよう注意します。作業後に同じ状態を再現できるよう、確認した版とコマンドの場所も控えておきます。

Step 1: NixOSの版とCPUを確認する

まず、どの世代のNixOSで作業しているかと、実行するバイナリの形式に合うCPUかを調べます。Codexの公開物が想定するLinux環境と、自分のマシンの構成が違う場合、導入手順が同じでも結果が変わります。次の確認は読み取りだけで、システム設定を変更しません。

nixos-version
uname -m
echo "$SHELL"

nixos-versionではチャンネルやリビジョンを含む版情報を確認し、uname -mではx86_64やaarch64などを確認します。あとで問題を報告する場合も、この二つがあると再現条件を説明しやすくなります。シェルがbash以外でも、公式インストーラーが想定するコマンドを実行できるかを次の手順で確認します。

Step 2: curlとNixの実行場所を確認する

OpenAIの公式CLIドキュメントにあるLinux向け手順を使うには、ダウンロードに使うcurlと、NixOSの環境へ入るためのnix-shellまたはnix developが利用できる必要があります。ここで大切なのは、コマンドが存在することだけでなく、Nixシェルへ入った後も同じコマンドが見えることです。

command -v curl
command -v nix-shell
command -v nix

いずれかが見つからない場合は、Codexの導入を続ける前にNixOS側のパッケージ設定を見直します。NixOS公式Wikiの開発環境とnix-shellの説明にも、プロジェクトごとに必要な道具をシェルへ用意する考え方がまとめられています。システム全体へ追加するか、プロジェクトだけに用意するかを先に決めてください。

Step 3: sandbox用のbwrapを確認する

OpenAIのsandbox説明では、Linuxでbwrapとseccompを使ってコマンドの実行範囲を制限します。NixOSでは、bwrapがPATHにない、または必要な設定がシステムに反映されていないと、Codex本体が起動しても作業開始時に止まる可能性があります。次の確認で見つからなくても、ただちにCodexの故障とは決めつけません。

command -v bwrap
bwrap --version

bwrapが見つからない場合は、NixOSのパッケージ検索で現在のチャンネルにあるbubblewrapを確認します。パッケージ名と実行ファイル名が異なることがあるため、検索結果の説明とインストール後のPATHを両方見ます。NixOS公式のパッケージ検索を起点に、利用中のチャンネルを合わせて確認するのが安全です。

公式CLIをNixOSへ入れる二つの方法

NixOSでの導入は、Codexをユーザー環境へ入れて更新を追いやすくする方法と、Nixシェルで必要な道具をそろえてプロジェクト単位で使う方法に分けられます。どちらを選んでも、Codex公式の配布元と、実際に起動したコマンドの場所を記録してください。NixOSの設定へ追加するパッケージと、Codex本体の入手元を混ぜないことがポイントです。最初は一つの方法に絞り、版、PATH、sandboxの結果を残すと後から比較しやすくなります。

Step 1: 公式のLinux向けインストーラーを使う

OpenAI公式ドキュメントで案内されているLinux向けインストーラーを使う場合は、NixOS上のbashから次のコマンドを実行します。表示される内容を読み、配布元がchatgpt.comであることを確認してから実行してください。管理下の端末で外部スクリプトの実行が制限されている場合は、組織のルールに従い、先に内容を保存して確認します。

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

インストールが終わったら、インストーラーが表示した案内に従ってPATHを読み直し、次を確認します。

command -v codex
codex --version

command -vの結果が空なら、導入に失敗したと即断せず、ユーザーのプロファイルに追加されたパスが現在のシェルへ反映されているかを見ます。NixOS公式Wikiの環境変数の説明を参照し、ログインシェルと一時的なNixシェルでPATHがどう違うかを確認してください。

Step 2: Nixシェルで依存する道具をそろえる

公式インストーラーを実行する前に、curlとbubblewrapをプロジェクト用のNixシェルへそろえる方法もあります。たとえば、プロジェクト直下のshell.nixを次のように用意し、必要な道具だけを一時的にPATHへ加えます。Codex本体をこの例に書いていないのは、公式配布物とNixpkgsの提供状況を混同しないためです。

{ pkgs ? import <nixpkgs> {} }:

pkgs.mkShell {
  packages = with pkgs; [
    curl
    bubblewrap
  ];
}

その後、プロジェクトのルートで次を実行します。

nix-shell
command -v curl
command -v bwrap
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex --version

この方法は、プロジェクトごとに必要な道具を整理しやすい反面、シェルを出るとPATHの見え方が変わります。導入後に別のターミナルでcodexが見つからない場合は、Nixシェル内でだけ使う設計にしたのか、ユーザー環境へ入れたのかを確認します。

Step 3: システム設定へ追加する範囲を決める

複数のユーザーや複数のプロジェクトで同じ道具を使うなら、configuration.nixのenvironment.systemPackagesへcurlやbubblewrapを追加し、nixos-rebuildで世代を更新する方法があります。ただし、Codex本体を同じ設定で管理できるかは、利用中のNixpkgsチャンネルに対応パッケージがあるかで変わります。見つからないものを無理に属性名で決め打ちせず、NixOSのパッケージ検索で確認してください。

システム設定へ追加する場合は、変更前の世代を確認し、更新後にcommand -v bwrapとcodex --versionを再確認します。うまくいかなかったときに前の世代へ戻せるよう、設定ファイルの差分と実行したコマンドを残しておくことが重要です。NixOSの世代管理は、導入を試すときの戻しやすさを高めますが、ユーザー環境へ個別に入れたCodexのファイルまで消してくれるわけではありません。

NixOSでつまずきやすい実行ファイルと共有ライブラリ

NixOSで外部配布の実行ファイルを使うとき、よくある問題は「ファイルはあるのに起動できない」という状態です。これは実行ファイルが参照する動的ローダーや共有ライブラリが、NixOSの標準的な配置と一致しない場合に起こります。Codexのコマンドが見つかるかと、Codexが実際に起動して作業を始められるかは別の確認です。エラーの文面と発生した段階を分けて記録すれば、必要な修正だけを選びやすくなります。

bwrapが見つからない場合

bwrap: command not foundのような表示が出た場合は、まずbubblewrapがNixOSのシステム設定かNixシェルへ入っているかを見ます。パッケージ名はbubblewrap、実行ファイル名はbwrapです。この違いを把握していないと、パッケージを入れたのにコマンドがないという誤解が起きます。

一時的に試すだけなら、利用中のNixOSで許可されている方法に応じて、nix-shell -p bubblewrapでシェルへ入る方法があります。継続して使うなら、プロジェクトのshell.nixまたはシステム設定へ明記し、誰がどの環境で使うかをそろえます。確認するコマンドは次の二つです。

command -v bwrap
bwrap --version

バージョンが出ても、sandboxの起動に必要な権限やカーネル機能が利用できるとは限りません。Codexを実際に小さなプロジェクトで起動し、読み取りだけの依頼を試して、エラーの全文を確認します。

実行時にローダーやライブラリが足りない場合

No such file or directoryが実行ファイルに対して出るとき、対象ファイルが本当にないとは限りません。動的ローダーのパスが合わず、Linuxが実行開始前に止まっていることがあります。NixOS公式Wikiのnix-ldの説明では、Nixでパッチされていないバイナリを動かすための選択肢としてnix-ldが紹介されています。

ただし、nix-ldを有効にすればすべての外部バイナリが動くと考えるのは危険です。必要なライブラリを絞り、まずエラーに出た名前を調べ、NixOSのパッケージとして用意できるかを確認します。個別のプロジェクト用シェルで試してから、システム全体へ広げる順序にすると、他の環境へ意図しない影響を与えにくくなります。

PATHとログインシェルを確認する

NixOSでは、通常のターミナル、nix-shell、nix develop、エディタから開いたターミナルでPATHが変わることがあります。command -v codexが場所を返すか、codex --versionが同じ版を返すかを、利用する入口ごとに確認します。コマンド名だけを見ていると、古い版と新しい版を取り違える可能性があります。

printf '%s\n' "$PATH"
command -v codex
codex --version

シェルの初期化ファイルを変更した場合は、新しいターミナルを開いてから再確認します。NixOS公式Wikiでは環境変数をシステム設定やセッションへ渡す方法が説明されていますが、設定の書き方は利用中の構成によって違います。変更したファイル、反映した世代、確認した版を記録しておくと、問題の範囲を狭めやすくなります。

CodexのsandboxとNixOSを安全に合わせる

Codexの便利さは、コードを読んで終わるのではなく、必要なコマンドを使って結果を確認できる点にあります。その一方で、どのフォルダーへ書き込めるか、ネットワークへ接続できるか、確認なしに実行できる操作は何かを把握しないまま進めると、意図しない変更が起こります。NixOSのシステム設定とCodexのsandbox設定は別の層なので、両方を確認します。

OpenAIの公式説明では、Linuxでbwrapとseccompを使い、選択したsandboxの範囲に応じてコマンドを実行します。NixOSでこの機能を使うときは、bwrapの存在だけでなく、作業フォルダーをどこに置くか、Nixストアやホームディレクトリをどう扱うかも確認します。まず読み取り中心で起動し、動作が分かってから書き込み範囲を広げるのが分かりやすい進め方です。

read-onlyから試す

最初の起動では、プロジェクトの構造を説明させるだけにし、ファイル変更を求めない方法が向いています。NixOSの構成ファイルや、失敗すると起動できなくなる重要な場所を対象に含めず、複製した小さなリポジトリを使います。Codexが参照したファイル、実行した確認、分からない点を説明させれば、sandboxの範囲とプロジェクトの読み取り方を同時に確認できます。

読み取りだけの確認でエラーが出た場合は、変更を許す前に原因を調べます。bwrapの不足、ライブラリの不足、作業場所の権限、NixOSのカーネル設定など、候補を一つずつ見ます。読み取りが安定してから、限定したファイルだけを変更する段階へ移ります。

workspace-writeで対象を限定する

変更を試すときは、プロジェクトのルートなど、目的に必要な場所だけを対象にします。Codexへ「このフォルダー内のこのファイルだけを変更し、設定ファイルと履歴用のディレクトリは触らない」と伝え、作業後に差分を読みます。NixOSの/etc/nixosのような重要な場所で直接試すのではなく、最初はテスト用のプロジェクトを用意してください。

書き込みができることと、変更を採用してよいことは別です。差分が依頼した範囲に収まっているか、Nix式の構文が壊れていないか、再構築前に内容を読めるかを確認します。変更を広げる必要が出たら、対象と理由を改めて依頼文へ追加し、どの範囲が変わるかを先に説明させます。

許可を広げる前に見る項目

Codexが何かの操作を止めて確認を求めた場合は、すぐに許可するのではなく、操作の目的、対象パス、変更内容、外部へ送られる情報があるかを確認します。NixOSでは、システム設定の再構築や大きなパッケージ取得が、プロジェクトの小さな修正より広い影響を持つことがあります。必要な操作だけを一つずつ許可し、不要なら読み取りへ戻します。

特に、ホーム全体、/etc/nixos、Nixストア、実際の利用者データを同時に対象にしないことが大切です。確認画面が出たから安全と考えず、作業後の差分とコマンド結果を人が読みます。Codexのsandbox、NixOSの権限、プロジェクト自身のテストを三つの確認点として扱うと、原因と影響範囲を分けて考えられます。

初回起動から最初の依頼までの手順

導入が終わったら、大きな機能追加をすぐに頼むのではなく、読み取り、限定した変更、結果確認の順に進めます。次の手順は、NixOS上でCodexが使えることを確認しながら、プロジェクトの状態を壊さずに最初の依頼まで進めるためのものです。作業前に保存してある差分がある場合は、その内容を先に自分で把握してください。

1. 作業用プロジェクトを選ぶ。 重要なNixOS設定や本番に近いデータではなく、複製した小さなリポジトリを用意します。ルートの場所、使う言語、確認に使えるテストをメモします。
2. Codexの版を確認する。 command -v codexとcodex --versionを実行し、公式リリース欄で安定版か先行版かを照らし合わせます。今回の0.155.0-alpha.16を試すなら、常用環境と分けた場所で行います。
3. 読み取り依頼を出す。 「このプロジェクトの構成、起動方法、関連する確認方法を説明し、まだファイルは変更しない」と伝えます。参照したファイルと、判断できない前提を列挙させます。
4. 小さな変更を頼む。 対象ファイル、変えてはいけないもの、完了条件を指定します。たとえば一つの関数のエラーメッセージを変え、関連する確認だけを実行するよう依頼します。
5. 差分と確認結果を読む。 git diff、テスト結果、Codexの説明を照合し、意図しないファイルが変わっていないかを見ます。問題があれば、許可を広げる前に原因を一つに絞ります。

この手順の目的は、Codexへ多くを任せることではなく、NixOS側の環境とプロジェクト側の条件を分けて確認することです。最初の読み取りでbwrapやPATHの問題が見つかれば、変更へ進まず環境を直します。逆に、導入から差分確認まで問題がなければ、作業の大きさを少しずつ広げられます。OpenAIのCodex CLI公式ドキュメントでも、プロジェクトを開き、依頼を説明し、結果を確認する基本の流れが案内されています。

NixOSでのトラブル切り分け

導入後に問題が出たときは、エラーメッセージを短く言い換えて終わらせず、どの段階で止まったかを記録します。コマンドが見つからない、Codexは起動するがsandboxが始まらない、ファイルを読めるが書き込めない、変更後の確認が失敗する、という四つは原因が異なります。NixOSではシステムの世代、Nixシェル、ユーザー環境の三つを同時に変えないことが切り分けの基本です。変更は一つずつ適用し、同じ確認を繰り返せる状態を保ちます。

codexコマンドが見つからない

この場合は、インストーラーが完了したか、実行ファイルを置いたディレクトリがPATHに含まれるか、現在のターミナルがNixシェルの内側かを確認します。command -v codexが空でも、インストール先が失われたとは限りません。インストーラーの最後の表示、ユーザーのプロファイル、別の新しいターミナルでの結果を順に比べます。

NixOSのシステム設定へパスを追加する前に、まず一時的に正しいPATHを指定して起動できるかを試します。起動できるなら、恒久的な設定の問題です。起動できないなら、ファイルの権限や動的ローダーへ調査を戻します。複数の版が見つかる場合は、どの版を使うかを決めてから古いパスを整理します。

起動時にライブラリのエラーが出る

No such file or directory、cannot open shared object file、ローダーに関する表示があるときは、動的依存を疑います。NixOS公式のnix-ld説明を参照し、エラーに出たライブラリがNixpkgsにあるか、個別のNixシェルで用意できるかを調べます。いきなり広いライブラリ集合を入れるのではなく、必要なものを確認してから設定します。

エラーを再現する最小のコマンドを作るのも有効です。Codexの起動、bwrapの起動、対象プロジェクトの確認を別々に実行し、どのコマンドで止まるかを記録します。問題の切り分けができたら、NixOSの世代を一つ進める変更と、ユーザー環境へ入れる変更を分けて適用します。

sandboxの開始で止まる

Codex本体は起動するのに、依頼を始めた段階でsandbox関連のエラーが出る場合は、bwrap --version、実行ユーザー、対象パス、利用しているsandboxモードを確認します。OpenAI公式のsandbox説明にあるLinux側の前提と、NixOSで有効になっている機能が一致しているかを見ます。bwrapの存在だけでなく、必要な権限とカーネル側の条件が関係することがあります。

試験用の小さなプロジェクトで読み取りだけを行い、同じエラーが出るかを確認します。小さな場所では動くのに大きなリポジトリで止まるなら、パスの長さ、シンボリックリンク、アクセス権、作業場所の違いを比べます。エラーを隠すためにsandboxを広げるのではなく、原因が分かる最小の設定へ戻してから調整してください。

読み取りはできるが書き込めない

まず、Codexの書き込み範囲と、NixOS側のファイル所有者・権限を別々に確認します。プロジェクトが読み取り専用の場所、別ユーザーのホーム、マウントされた外部ディスクにある場合、sandboxを変更しても書き込めないことがあります。ls -ldやstatで対象ディレクトリを読み、必要な範囲だけ自分のユーザーが書ける場所へ複製します。

書き込みが可能になった後も、変更をすぐ採用せず差分を読みます。Nix式は一文字の違いで評価結果が変わるため、変更後にnix-instantiate --evalなどの確認方法が使えるかをプロジェクトの説明に合わせて選びます。Codexには確認結果と未確認の点を分けて報告させ、失敗した確認を成功したように扱わないことが重要です。

アップデートとロールバックの考え方

Codexの版を更新すると、機能だけでなく、sandbox、利用できるモデル、ログイン画面、実行ファイルの配置が変わる可能性があります。特に0.155.0-alpha.16のような先行版は、公開日が新しいことだけを理由に常用へ切り替えず、公式リリースの表示、変更内容、手元の確認結果を合わせて判断します。NixOSの世代管理はOS側の設定を戻す助けになりますが、Codexのユーザー環境やプロジェクトの変更を自動で戻す仕組みではありません。

先行版を常用環境へ入れる前に

更新前にcodex --versionの出力、NixOSの版、bwrapの版、利用しているプロジェクトを記録します。次に公式のCodexリリース一覧で、対象の版が安定版か先行版か、公開日と変更内容を確認します。公式ページで分からない点は、推測で補わず、実際の小さなプロジェクトで再現するかを確かめます。

先行版を試すときは、現在使っている版をすぐ消さず、別の導入先や別のNixシェルから起動できる形を残します。更新後は、起動、読み取り、限定した書き込み、テスト、差分表示の順で確認します。どこか一つでも以前と違う場合は、変更点を記録してから採用の判断をします。

NixOS側の変更を戻せるようにする

configuration.nixやflakeを変更する前に、現在の設定とNixOSの世代を確認します。再構築後にbwrapが見えなくなった、PATHが変わった、別のパッケージが評価できなくなったという場合は、NixOS側の変更を前の世代へ戻して原因を分離できます。ユーザー環境へ公式インストーラーで入れたCodexは別管理なので、必要ならその版も個別に戻します。

ロールバックの確認では、Codexだけでなく、Nixシェル、command -v bwrap、プロジェクトの読み取りを順に試します。OSを戻しただけで依頼途中のファイル差分が消えるとは限らないため、プロジェクトは別途バックアップやバージョン管理で守ります。NixOSの世代とプロジェクトの履歴を分けて管理することで、何を戻したのかを説明できます。

まとめ

NixOSでCodexを使うときの要点は、Codex本体、Nixのパッケージ環境、Linuxのsandboxを一つの問題として扱わないことです。まずnixos-version、CPU、curl、Nixシェル、bwrapを確認し、次にOpenAI公式のLinux向けインストーラーかプロジェクト用のNixシェルを選びます。導入後はcommand -v codexとcodex --versionで実行場所と版を確かめ、読み取りだけの小さな依頼から始めてください。

9月17日に公開された0.155.0-alpha.16は、NixOS上で新しいCodexを試すきっかけになりますが、先行版である点を忘れず、安定版と試験用環境を分けます。bwrapや共有ライブラリのエラーが出たら、NixOS公式Wikiのnix-ld、nix-shell、環境変数の説明を参照し、コマンドが見つからない問題と起動後のsandbox問題を別々に調べます。

最初の依頼では、対象プロジェクト、変更してよい範囲、完了条件、確認方法を明示します。差分、テスト、Codexの説明を人が読み、NixOSの世代とプロジェクトの履歴を別々に残せば、導入に失敗しても戻しやすくなります。最新の版を追うことより、環境の境界と確認の順序を整えることが、NixOSでCodexを長く使うための基礎になります。

出典: OpenAI Codex CLI、OpenAI sandbox、openai/codex Releases、NixOS Wiki: Nix-ld、NixOS Wiki: nix-shell開発環境。