0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@akira_papa_AI(あきらパパ)

Codex CLIのインストールから最初の1タスクまで — はじめてのAIエージェントを、ターミナルで1回動かしてみる

0
Posted at

「AIエージェント」という言葉、ここ最近ほんとうによく見かけるようになりました。

でも、実際に自分で動かしたことがある人って、思っているより少ないんじゃないかなと思っています。記事を読んで「へえ」とは思う。デモ動画を見て「すごいな」とも思う。ただ、自分のパソコンで1回動かしたかというと、まだ、という。

正直に言うと、これはもったいないです。AIエージェントは、説明を10本読むより、1回動かしたほうが圧倒的に早く腹落ちするタイプの道具なので。

この記事では、OpenAIの Codex CLI を使って、はじめてのAIエージェントを1回動かすところまでをやります。インストールから、サインインから、最初の1タスクまで。それだけです。他の機能の話はしません。

この記事のゴール

読み終わって10分後、こうなっていることを目指します。

  • 自分のパソコンのターミナルに codex というコマンドが入っている
  • 自分のアカウントでサインインが終わっている
  • 練習用のフォルダを作って、そこにあるコードを AIに読ませて、日本語で説明させることができた

「理解した」ではなく「動いた」まで行きます。ここが今日のゴールです。

対象は、AIエージェントという言葉は聞いたことがあるけれど、自分で動かしたことはない方。ターミナルにあまり慣れていなくても大丈夫なように書きました。

なお、この記事の手順は macOS 14.8.3 / codex-cli 0.147.0 で、2026年8月9日に実際に実行して確認 しています。Windows と Linux でのインストールは公式の記載を紹介するにとどめ、筆者の手元では動作未確認である旨をその場で注記します。

そもそもAIエージェントって、チャットAIと何が違うのか

ここ、最初にはっきりさせておきたいところです。

チャット型のAIは、こちらが情報を貼り付けて、返事をもらう。情報を運ぶのは人間の仕事でした。コードを見てほしければ、コードをコピーして貼る。エラーを見てほしければ、エラーを貼る。

AIエージェントは、そこが違います。自分でファイルを探して、自分で読んで、そのうえで答えを返してくる。 運ぶ作業が要らない。

言葉だけだとふわっとするので、実際に手元で動かしたときの記録をそのまま置きます。これは筆者が練習用フォルダで実行したものです。

$ codex exec "このフォルダにあるファイルを読んで、このプロジェクトが何をするものか3行で日本語で説明してください。"

codex
フォルダ内の構成と主要ファイルを確認し、目的・主な機能・使い方が伝わる3行にまとめます。

exec
/bin/zsh -lc "pwd && rg --files ..." in /private/tmp/codex-practice
 succeeded in 293ms:
hello.py

exec
/bin/zsh -lc "sed -n '1,240p' hello.py" in /private/tmp/codex-practice
 succeeded in 0ms:
def add(a, b):
    return a + b
...

codex
2つの値を足し算するPythonのサンプルプロジェクトです。
`add(a, b)` 関数が、受け取った2つの値の合計を返します。
直接実行すると `2 + 3` の結果である `5` を表示します。

注目してほしいのは真ん中です。exec と書かれている行。

こちらは何も渡していないのに、まずフォルダの中身を一覧して、次に hello.py を開いて読んでいます。 そのうえで3行の説明を返してきた。所要時間は約25秒でした。

これが、チャットとエージェントの違いです。ファイルを貼っていない。それでも読んでいる。

出てくる言葉を、先に3つだけ

用語で止まってしまうのは本当にもったいないので、先に片づけます。

  • ターミナル … パソコンに文字で命令を出すための画面のこと。macOSなら「ターミナル」、Windowsなら「PowerShell」や「Windows Terminal」というアプリです。マウスで押す代わりに、文字を打って動かす窓、くらいの理解でまず十分です。
  • CLI … Command Line Interface の略で、いまのターミナルで文字を打って操作する方式そのもの。「Codex CLI」は「ターミナルで使うCodex」という意味になります。
  • リポジトリ … プログラムのソースコードが入っているフォルダのこと。Gitというツールで変更履歴を管理しているフォルダを指すことが多いです。この記事では、そこまで身構えなくて大丈夫。「作業したいフォルダ」と読み替えても、今日のところは困りません。

もうひとつだけ、安心のための言葉を足します。

  • サンドボックス … AIが実行できる範囲を、あらかじめ囲っておく仕組み。「読むだけ」「この作業フォルダの中だけ書き込んでよい」といった線引きができます。いきなり何でも実行される、ということにはなっていません。

準備するもの

3つだけです。

  1. ターミナルが使えるパソコン（macOS / Linux / Windows）
  2. ChatGPTのアカウント（サインインに使います）
  3. 10分

プログラミングの経験は、今日の範囲では必須ではありません。むしろ「コードがよく分からないから、説明してほしい」という状態は、AIエージェントの一番おいしい使い方でもあります。

手順1: Codex CLIをインストールする

公式が案内しているインストール方法は4つあります。どれか1つでかまいません。

macOS / Linux（公式のインストーラ）

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

Windows（PowerShellで実行）

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

npmを使う場合

npm install -g @openai/codex

Homebrewを使う場合（macOS）

brew install --cask codex

筆者の手元は npm で入れた環境で確認しています。Windows と Linux のコマンドは公式ドキュメントの記載どおりに引用したもので、筆者の環境では動作未確認 です。

入ったかどうかは、これで分かります。

codex --version

こう返ってきたら成功です。

codex-cli 0.147.0

数字の部分は、みなさんが試すタイミングによって変わります。数字が違っても気にしなくて大丈夫。何か表示されれば入っています。

もし command not found: codex と出た場合は、ターミナルを一度閉じて開き直してみてください。インストール直後は、新しいコマンドの場所がそのウィンドウにまだ伝わっていないことがあります。これ、最初にみんな一度は踏みます。

手順2: サインインする

Codexには2通りのサインイン方法があります。

  1. ChatGPTアカウントでサインインする（契約中のChatGPTプランの範囲で使う）
  2. APIキーでサインインする（使った分だけAPIの料金がかかる）

はじめての1回は、1つ目で問題ありません。

codex login

これを実行するとブラウザが開いて、見慣れたChatGPTのサインイン画面が出ます。サインインが終わると、ブラウザ側からターミナルへ認証情報が戻ってきて、完了です。

うまくいったかどうかは、次のコマンドで確認できます。

codex login status

筆者の手元では、こう返りました。

Logged in using ChatGPT

APIキーで入りたい場合は、公式が標準入力から渡す形を案内しています。

printenv OPENAI_API_KEY | codex login --with-api-key

このとき注意点がひとつ。ChatGPTでサインインした場合はChatGPTのプランに従い、APIキーでサインインした場合はAPIの料金体系になります。 課金の出どころが変わるので、ここは意識しておいたほうが安心です。

サインアウトしたくなったら codex logout です。

なお、サインイン情報はパソコンの中にキャッシュされます。公式によると、保存先は ~/.codex/auth.json か、OSの資格情報ストア（キーチェーンなど）。auth.json にはアクセストークンが入るので、パスワードと同じ扱いで、共有もコミットもしない のが原則です。

手順3: 練習用フォルダを作る

ここ、地味ですが今日いちばん大事な手順です。

はじめての1回を、仕事のリポジトリでやらないでください。何かが壊れるという話ではなく、「何が起きたか分からない」状態が一番こわい からです。まっさらな練習場を作って、そこで起きることを全部見たほうが、結果的にずっと早く慣れます。

mkdir -p ~/codex-practice
cd ~/codex-practice

中に、読ませるためのファイルを1つ置きます。中身は本当に何でもいいのですが、この記事ではこれを使いました。

def add(a, b):
    return a + b


def main():
    print(add(2, 3))


if __name__ == "__main__":
    main()

これを hello.py という名前で保存します。エディタを開くのが面倒なら、ターミナルからそのまま作ってしまってもいいです。

cat > hello.py << 'EOF'
def add(a, b):
    return a + b


def main():
    print(add(2, 3))


if __name__ == "__main__":
    main()
EOF

これで準備完了。作業場ができました。

手順4: 最初の1タスクを頼む

いよいよです。練習用フォルダにいることを確認して、次を実行します。

codex exec "このフォルダにあるファイルを読んで、このプロジェクトが何をするものか3行で日本語で説明してください。"

codex exec は、対話画面を開かずに、1回のお願いを投げて結果を受け取るコマンド です。はじめての1回は、これがいちばん分かりやすいと思っています。画面の使い方を覚える前に、エージェントの動きだけを見られるので。

数十秒待つと、こういう流れが目の前を流れていきます。

  1. まず、何をするつもりかを短く宣言する
  2. exec として、実際に実行したコマンドと、その結果を表示する
  3. 最後に、頼んだとおりの答えを返す

筆者の環境では約25秒で、冒頭に貼った3行の説明が返ってきました。

ここでぜひ、2番目を眺めてみてください。AIが「何をしたか」が、全部その場に出ています。 隠れて何かをやっているわけではない。この透明さが、慣れていない時期のいちばんの安心材料になります。

うまく動いたら、質問を変えてもう一度やってみると、感覚がつかめます。

codex exec "hello.py の add 関数に、数値以外が渡されたときに何が起きるか説明してください。修正はしないでください。"

「修正はしないでください」と添えているのがポイントです。最初のうちは、読んで答えるだけのお願い から始めるのが気楽でいいです。

ちなみに codex exec には、実行できる範囲を選ぶオプションもあります。

codex exec -s read-only "このコードの気になる点を3つ挙げてください。"

-s（--sandbox）で指定できるのは read-only / workspace-write / danger-full-access の3つ。名前のとおり、上から順に「読むだけ」「作業フォルダに書ける」「制限なし」です。詳しい話は1本まるごと必要になるので、この記事では「そういう線引きができる」という事実だけ持ち帰ってもらえれば十分です。

手順5: 対話モードで会話を続ける

codex exec が1往復だとすると、引数なしの codex は会話です。

codex

こう打つと対話画面が立ち上がり、質問を続けて投げられるようになります。1回目の答えを踏まえて2回目を聞ける、というのが対話モードの価値です。「じゃあ、そこをどう直せばいい？」が自然に続けられる。

最初の1タスクが動いた直後の勢いのまま、ここまで来てしまうのがおすすめです。

つまずきポイント5つ

最初はみんな、だいたいこのへんで一度止まります。

1. command not found: codex と出る

ターミナルを閉じて開き直す。それでも駄目なら、インストール方法を変えてみる（npm で入れたなら Homebrew、など）のが早いです。

2. サインインのブラウザが開かない / 戻ってこない

リモートのサーバーに接続して作業している場合や、ネットワークの設定でブラウザからの戻りが遮られる場合に起きます。公式ではこうしたケース向けに、ブラウザを使わないデバイスコード認証の案内があります。まずは手元のパソコンで試すのが確実です。

3. 日本語で答えてくれない

お願いの文の中に「日本語で」と入れてしまうのが手っ取り早いです。この記事のコマンドにも、そのまま入れてあります。

4. 何も起きていないように見える

考えている時間は表示が静かなことがあります。数十秒は待ってみてください。筆者の例でも、答えが返るまで約25秒かかりました。

5. 何かおかしいけれど、原因が分からない

診断用のコマンドが用意されています。

codex doctor

バージョン、インストール方法、Gitの有無、サンドボックスの状態などをまとめて表示してくれます。人に相談するときにも、この出力があると話が早いです。

これは向いていない、という話

ここは正直に書いておきます。

最初の1タスクとして、「仕様がまだ決まっていない仕事」を渡すのは向いていません。

たとえば「このアプリをいい感じにして」「使いやすくして」。こういうお願いは、人間同士でも要件を詰めないと進まないやつです。エージェントは手が速いぶん、決まっていない部分を勝手に埋めて進んでしまう。結果、出てきたものを見て「そうじゃないんだよな」となる。これは道具の性能の問題ではなく、渡し方の問題です。

なので、はじめのうちは 読み取り系のお願い から入るのが安全です。「説明して」「どこで何をしているか教えて」「気になる点を挙げて」。判断は自分が持ったまま、調べる手間だけを渡す。この距離感から始めると、失敗しにくいです。

逆に言えば、すでに正解が自分の中にある作業 なら、最初から任せてしまって大丈夫。「このファイルのテストを書いて」のような、ゴールが自分で判定できるものですね。

次の一歩は、1つだけ

今日ここまで来たら、次に触るとしたら AGENTS.md かなと思っています。

これは、プロジェクトのフォルダに置いておくと、Codexが作業を始める前に自動で読んでくれる指示書です。「テストは npm test で走らせて」「新しい依存を追加する前に確認して」といった前提を、毎回説明しなくてよくなる。

ただ、今日はそこまで行かなくていいです。まずは、自分のコードが説明されて返ってきた、あの1回を持ち帰ってもらえたら十分 かと。

このシリーズの他の記事

今日の続きとして、そのまま読める記事を並べておきます。

参考リンク

この記事を書くにあたって、2026年8月9日時点で実際に読んだ公式ドキュメントです。

補足として、以前案内されていた https://developers.openai.com/codex/cli は、2026年8月9日時点では https://learn.chatgpt.com/docs/codex/cli へ転送されました。古い記事のリンクが飛ばないときは、こちらを見に行ってみてください。

おわりに

AIエージェントの話は、どうしても大きな言葉になりがちです。開発が変わる、仕事が変わる、と。

でも、入口はもっと素っ気なくて、codex exec "このコード説明して" と打つだけなんですよね。そして、その素っ気ない1回を通った人と、記事だけ読んで通っていない人とでは、次に来る話の入り方がまったく変わる。

今日の10分は、そのための10分だったかなと思っています。

生成AI活用エンジニア&3児のパパ。AI×開発の実践知を毎日発信しています。Xでも発信中です → https://x.com/akira_papa_AI

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?