Codex CLIを使い始めたけれど、サブコマンドやオプション名を毎回思い出せない。
そんな方に向けて、この記事では codex completion zshによるTab入力補完 だけを扱います。macOSまたはLinuxでZ shellを使っている方が、いきなり設定ファイルを変えず、まず現在のターミナルだけで試せる手順です。
今日のゴールは理解した気になることではありません。codexの後でTabキーを押し、候補を呼び出せる状態にすることです。AIへのログインやモデルの回答を待たなくても、10分ほどで確認できます。
この記事は2026年9月2日に公式ドキュメントを確認し、Codex CLI 0.150.1でコマンド生成と読み込みを検証しています。
この記事で扱うこと
扱う機能は1つです。
codex completion zsh
このコマンドが作る補完用スクリプトをZ shellへ読み込みます。テーマ変更、プロンプト編集、BashやFishの設定は扱いません。
対象は次の方です。
- macOSまたはLinuxを使っている
- Z shellを使っている、または自分のシェルを確認できる
- Codex CLIをこれから使う、もしくは使い始めたばかり
- 長いオプション名の入力ミスを減らしたい
Windows PowerShellやBashを使っている方は、考え方は同じでも設定コマンドが異なります。今回は再現手順を一本にするため、Z shellだけに絞ります。
そもそもCodex CLIとは
Codexは、コードやファイルを読み、依頼に応じて作業できる AIエージェント です。AIエージェントとは、質問に文章で答えるだけでなく、許可された範囲でファイル確認やコマンド実行まで進められる仕組み、と考えると分かりやすいです。
CLIは「Command Line Interface」の略で、画面上のボタンではなく、ターミナルへ文字を打って操作する方式です。ターミナルは、コマンドという短い指示文を入力するアプリです。macOSなら「ターミナル」アプリを使えます。
今回の入力補完は、AIの回答内容を変える機能ではありません。Codex CLIそのものを、少し入力しやすくする機能です。
codex completion zshは何をするのか
入力補完は、コマンドの途中でTabキーを押したとき、続きの候補を表示したり入力を補ったりする仕組みです。
たとえば、毎回このようにhelpを開いて探す代わりに、
codex --help
codexと半角スペースまで入力してTabを押し、候補から次の操作を探せます。
ここで出てくる シェル は、ターミナルに入力された文字を受け取り、コマンドを実行するプログラムです。Z shell（zsh） はシェルの1つで、近年のmacOSでは標準的に使われています。
codex completion zshは、Z shell向けの補完スクリプトを標準出力へ生成します。ただ実行しただけでは、現在のZ shellにまだ読み込まれません。生成結果を読み込むところまでが今回の手順です。
なぜ便利なのか
僕もCLIでは、コマンドそのものより「ハイフンは1つやったか2つやったか」で止まることがあります。情報を覚えることと、仕事を進めることは別物なんですよね。
補完を使う価値は、暗記量を増やすことではありません。
- オプション名のタイプミスを減らせる
- 今使える候補をターミナル上で探せる
- helpを開いて戻る小さな往復を減らせる
- 一度設定すれば、次の作業でも使える
一回で省ける時間は小さいです。でも、毎日使うCLIほど、この小ささが効いてきます。
前提を確認する
ここからのコマンドはすべて、Codexの会話画面ではなく 通常のターミナル に入力します。
1. Codex CLIが入っているか確認する
codex --version
次のように版番号が出れば、インストール済みです。数字は環境や更新時期で異なって大丈夫です。
codex-cli 0.150.1
command not found: codexと出る場合は、公式READMEにあるmacOS/Linux向けインストールを実行します。
curl -fsSL https://chatgpt.com/codex/install.sh | sh
このコマンドはインターネット上の公式インストールスクリプトを取得して実行します。組織のPCではソフトウェア導入ルールがある場合があるので、先に管理者の方針を確認してください。終わったらターミナルを開き直し、もう一度codex --versionを確認します。
今回の補完生成は、AIモデルへ質問する操作ではありません。そのため、補完の確認だけならCodexへのサインインは不要です。
2. 今のシェルを確認する
echo "$SHELL"
末尾が/zshなら今回の対象です。
/bin/zsh
/bin/bashなど別の値が出た場合は、この記事の設定をそのまま保存しないでください。公式機能は複数のシェルに対応していますが、読み込み方が異なります。
最初の一歩: 現在のターミナルだけで試す
いきなり.zshrcを書き換えなくて大丈夫です。
.zshrcは、Z shellを起動するたびに読み込まれる設定ファイルです。まずは保存せず、今開いているターミナルだけに補完を読み込みます。合わなければ、そのターミナルを閉じるだけで元に戻ります。
次の2行を順番に実行してください。
autoload -Uz compinit && compinit
eval "$(codex completion zsh)"
1行目は、Z shellの補完システムを初期化します。2行目は、codex completion zshが生成したスクリプトを、現在のZ shellへ読み込みます。
evalは受け取った文字列をシェルの命令として評価するコマンドです。ここでは、インストール済みのCodex CLIがその場で生成した補完スクリプトだけを読み込んでいます。出所の分からない文字列へ置き換えて実行しない、という点は覚えておくと安心です。
正常なら、何も表示されないことがあります。何も出ないから失敗、ではありません。
成功を確認する
表示の違いに左右されにくい確認と、実際の操作確認を両方行います。
確認1: 補完関数が読み込まれたか
whence -w _codex
次のように出れば、Codex用の補完関数が現在のZ shellにあります。
_codex: function
手元のCodex CLI 0.150.1では、この結果まで確認できました。
確認2: Tabを押す
ターミナルに次を入力します。ただし、まだEnterは押しません。
codex
codexの後ろには半角スペースがあります。この状態でTabキーを押します。候補が表示される、候補一覧へ移る、もう一度Tabを求められるなど、見え方は端末設定によって異なります。
ここまで動けば、今日のゴール達成です。AIに何かを変更させていないので、練習用リポジトリもAPI利用も必要ありません。
次回からも使えるようにする
一時読み込みで問題なかった方だけ、Z shell起動時に自動で読み込む設定へ進みます。
まず.zshrcがある場合に備えてバックアップします。
cp ~/.zshrc ~/.zshrc.codex-completion-backup 2>/dev/null || true
次に、同じ設定を過去に書いていないか確認します。
grep -n "codex completion zsh" ~/.zshrc 2>/dev/null
何も出なければ、次の2行を追記します。
printf '%s\n' 'autoload -Uz compinit && compinit' 'eval "$(codex completion zsh)"' >> ~/.zshrc
新しいZ shellが.zshrcを読み込んだ状態で確認します。
zsh -lic 'whence -w _codex'
_codex: functionと表示されたら、次回以降も読み込まれる状態です。新しいターミナルを開き、codex、半角スペース、Tabの順で試してください。
つまずきポイント
1. command not found: codexと出る
Codex CLIが未インストールか、実行ファイルの場所がPATHへ反映されていません。PATHは、コマンドを探すフォルダ一覧です。公式手順でインストール後、ターミナルを開き直してcodex --versionから確認します。
2. command not found: compdefと出る
Z shellの補完システムが初期化されていない可能性があります。公式ドキュメントどおり、先に次を実行します。
autoload -Uz compinit && compinit
eval "$(codex completion zsh)"
3. Tabを押しても何も見えない
まず関数の読み込みを機械的に確認します。
whence -w _codex
_codex: functionが出るなら、読み込み自体はできています。codexの後ろに半角スペースがあるか確認し、Tabを2回押してみてください。端末やZ shellの設定により、候補の見え方は変わります。
4. echo "$SHELL"がzshではない
この記事の永続化手順は使わないでください。codex completion --helpを実行すると、手元の版が対応するシェル候補を確認できます。BashやFishでは読み込み先や設定方法が異なります。
5. 新しいターミナルで補完が消えた
一時読み込みだけを実行した状態です。まず一時読み込みで動作を確認できていれば問題ありません。継続利用する場合は.zshrcへ追記し、新しいターミナルを開いて確認します。
6. ターミナル起動時に同じ処理が何度も走る
.zshrcへ同じ行を複数回追加した可能性があります。
grep -n "codex completion zsh" ~/.zshrc
複数行あれば、使い慣れたテキストエディタで重複だけを削除します。編集前の状態は~/.zshrc.codex-completion-backupへ戻せます。
7. 公式例と候補が違う
Codex CLIの版が異なると、利用できるコマンドや候補も変わり得ます。まず版と現在のhelpを確認します。
codex --version
codex completion --help
記事の版番号へ無理に合わせるより、自分の環境が生成した補完を使う方が自然です。
よくある質問
補完を使うとCodexへ情報が送信されますか
今回確認したcodex completion zshは、ローカルで補完スクリプトを生成する操作です。AIへのプロンプト送信やモデル回答の取得は行いません。ただし、その後にCodexへ実際のタスクを依頼すれば、認証方法や組織設定に応じた通常のCodex利用になります。
.zshrcへ必ず保存する必要がありますか
ありません。まず一時読み込みだけで試し、便利だと思ったときだけ保存すれば十分です。共有PCや一時環境では、保存しない判断もありです。
元に戻すにはどうしますか
.zshrcへ追加した2行を削除し、新しいZ shellを起動します。今回の手順でバックアップを作った場合は、内容を確認したうえでバックアップから戻せます。現在のターミナルだけで試した段階なら、そのターミナルを閉じれば読み込みは消えます。
この機能の限界と、使わなくてよい人
入力補完は、候補を出してタイプミスを減らす機能です。どのコマンドを選ぶべきか、実行すると何が起きるかまで保証するものではありません。 初めて使うオプションは、候補が出ても--helpや公式ドキュメントで意味を確認してください。
また、Codex CLIを月に一度ほどしか使わず、毎回このコマンドで足りる方もいます。
codex --help
その場合は.zshrcへ設定を増やさなくても大丈夫です。よく使うから補完する。たまにしか使わないならhelpを見る。環境を自分に合わせるって、こういう小さな判断の積み重ねなんやと思います。
まとめ
今回使った機能はcodex completion zshだけです。
autoload -Uz compinit && compinit
eval "$(codex completion zsh)"
whence -w _codex
まず現在のターミナルだけで試し、_codex: functionを確認してからTabを押す。便利だと感じたら、重複を確認して.zshrcへ保存する。この順なら、設定変更への不安を小さくしながら進められます。
今日は、Tabで候補を1回出せたら十分です。その小さな成功が、Codexを自分の道具にしていく最初の一歩になります。
参考リンク
- OpenAI公式: CLI customization（Shell completions）
- OpenAI公式: Codex CLI
- OpenAI公式GitHub: openai/codex README
生成AI活用エンジニア&3児のパパ。AI×開発の実践知を毎日発信しています。Xで次の実践例を見る