0-03 Macの開発環境を整える

このページはプロモーション（広告）を含みます。

ターミナル、Homebrew、git、uv、VS Code、Claude Code を入れ、Google Colab から Gemini API を呼ぶところまでを、確認しながら一つずつ進めます。

この章でできるようになること

• ターミナルを開き、コマンドを入力して結果を確かめられる
• Homebrew・git・uv・Python・VS Code を入れ、バージョンを確認できる
• Claude Code をインストールしてログインし、最初の起動ができる
• Google AI Studio で Gemini APIキーを取得し、Colab のシークレットに登録できる
• Colab から Gemini API を呼び出し、アプリ内の模擬LLMと同じ形のコードで動くことを確かめられる
• command not found などの典型的なエラーを、原因から対処できる

ここまでの章は、すべてブラウザの中で完結していました。この課程の前半（Part 1）も、ほとんどはアプリの中で学べます。しかし、実務のAIエンジニアは自分のパソコンで開発し、AIコーディングエージェントを動かし、本物のLLM APIを呼びます。この章では、そのための道具をMacにそろえます。

手順書として読めるように書いています。各手順には「何をするか」「なぜか」「成功したときの表示」「うまくいかないときの対処」をそろえました。一度に全部やる必要はありません。セクションごとに区切りがよいので、2〜3回に分けて進めてください。目安は合計2〜3時間で、そのうちの多くはダウンロードの待ち時間です。

ツールの名前やコマンドは、2026年10月時点で公式ページに載っているものを使っています。この分野の道具は数か月で変わることがあります。表示が本文と違ったときは、焦らずに各ツールの公式ページで最新の手順を確認してください。公式ページへのリンクは章末にまとめています。

全体像と準備

何を、なぜ入れるのか

まず、入れる道具の一覧と、それぞれの役割を確認します。

順番には意味があります。後の道具は、前の道具に依存しているからです。

この章で示す「期待される表示」は一例です。バージョンの数字や細かな文言は、時期や環境によって変わります。成功か失敗かは、数字ではなく、表示の形（バージョンが出ているか、error や not found という言葉が出ていないか）で判断してください。

1. ターミナル
2. Command Line Tools
3. Homebrew
4. git設定
5. uv と Python
6. VS Code
7. Claude Code

1. Google アカウント
2. AI Studio でAPIキー
3. Colab のシークレットに登録
4. 最初のLLM呼び出し

2行目の Colab の流れは、Mac側の作業と独立しています。Mac の準備で詰まったときは、先に Colab のほうを進めても構いません。

自分のMacを確認する

始める前に、Macの情報を確認します。画面左上のアップルメニューから「このMacについて」を開いてください。

• チップ：「Apple M1」「Apple M4」のように Apple で始まれば Apple シリコンです。この課程は Apple シリコンの Mac を前提にしています。「Intel」と表示される場合も多くの手順は同じですが、Homebrew は2026年9月の版から Intel Mac の対応を縮小したと報じられています（二次情報）。うまくいかない場合は公式ページで最新の対応状況を確認してください。
• macOS：バージョン番号を控えておきます。Homebrew の公式ページは、Apple シリコンでは macOS 15（Sequoia）以降を主な対象としています。Claude Code は macOS 13 以降が必要です。
• メモリ：8GB、16GB などの数字を控えておきます。→ 5-06 モデルの選び方 で、Mac上でLLMを動かすときに使います。

あわせて、次の2つも準備してください。

• ストレージの空き容量：10GB 以上あると安心です。
• Macにログインするときのパスワード：インストールの途中で何度か求められます。

ターミナルを開く

起動とプロンプト

ターミナル（Terminal）は、Macに最初から入っているアプリです。command + space で Spotlight 検索を開き、「ターミナル」と入力して Enter を押します。

黒または白の画面に、次のような1行が表示されます。

taro@Taros-MacBook-Air ~ %

これをプロンプト（prompt）と呼びます。「命令を入力してください」という合図です。taro はユーザー名、~ は今いる場所（自分のホームフォルダ）、% は入力待ちを表す記号です。表示は人によって違います。

macOS のターミナルでは、入力された命令を zsh（ズィーシェル）というプログラムが解釈します。命令を解釈して実行するプログラムをシェル（shell）と呼びます。

この課程でのコマンドの書き方

この課程では、ターミナルで打つコマンドを次のように書きます。

# これはコメント（説明）。打たなくてよい
echo "hello"

• 1行が1つのコマンドです。1行ずつ入力して Enter を押します。
• # から後ろはコメントです。打たなくて構いません（打っても無視されます）。
• 他の資料では、行の先頭に $ や % が付いていることがあります。それはプロンプトを表す記号なので、打ちません。

最初のコマンド

次の3つのコマンドを、1行ずつ入力して実行してください。

echo $SHELL
sw_vers
uname -m

期待される表示は次のとおりです（バージョンの数字は人によって違います）。

/bin/zsh
ProductName:            macOS
ProductVersion:         26.0
BuildVersion:           25A354
arm64

echo $SHELL は使っているシェル、sw_vers は macOS のバージョン、uname -m はチップの種類を表示します。arm64 なら Apple シリコン、x86_64 なら Intel です。

覚えておく操作

ターミナルでは、次の操作をよく使います。

パスワードを求められたときは、入力しても画面に何も表示されません。これは故障ではなく、盗み見を防ぐための仕様です。そのまま入力して Enter を押してください。

ターミナルの詳しい使い方は → 2-01 ターミナルとシェル で学びます。今はこの章の手順を進められれば十分です。

Command Line Tools と Homebrew

Xcode Command Line Tools

Command Line Tools は、Apple が提供する開発用の部品のセットです。git もこれに含まれています。次のコマンドを実行します。

xcode-select --install

画面にダイアログが表示されるので、「インストール」を押し、利用許諾に同意します。ダウンロードと導入には、回線の速さによって10〜30分ほどかかります。

終わったら、確認します。

xcode-select -p
git --version

/Library/Developer/CommandLineTools
git version 2.50.1 (Apple Git-155)

1行目のフォルダが表示され、2行目に git のバージョンが表示されれば成功です。数字は違っていて構いません。

すでに入っている場合は、xcode-select --install を実行したときに「すでにインストールされている」という趣旨のメッセージが表示されます。その場合は、そのまま次に進みます。

Homebrew

Homebrew（ホームブルー）は、Mac 用のパッケージマネージャー（ソフトを入れたり、更新したり、消したりする道具）です。公式ページ（brew.sh）に載っている次のコマンドを実行します。

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

途中で次のことが起きます。

Apple シリコンの Mac では、Homebrew は /opt/homebrew に入ります。このフォルダは、最初はシェルが命令を探す場所に入っていません。そのため「Next steps」に表示されたコマンドを実行して、シェルに場所を教える必要があります。多くの場合、表示は次のような形です。

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

ただし、自分の画面に表示されたコマンドを、そのままコピーして実行してください。版によって内容が変わることがあります。

終わったら確認します。

brew --version
brew doctor

Homebrew 7.0.4
Your system is ready to brew.

brew --version でバージョンが表示され、brew doctor で「Your system is ready to brew.」と表示されれば成功です。brew doctor が警告（Warning）を出すことがありますが、多くはすぐに困るものではありません。内容が分からなければ、全文をAIに貼って意味を尋ねてください。

PATH という仕組み

command not found は、この先も何度も出会うエラーです。仕組みを理解しておくと、原因の見当がすぐにつきます。

シェルは、brew のようなコマンドを入力されると、決められたフォルダを順番に探して、同じ名前のプログラムを見つけたら実行します。この「探すフォルダの一覧」が、環境変数（environment variable）PATH です。環境変数とは、シェルや、そこから起動されるプログラムが共通で参照する設定値のことです。

ターミナルで echo $PATH を実行すると、PATH の中身が表示されます。フォルダ名が : で区切られて並んでいます。この「順番に探して、最初に見つかったものを使う」という動作を、アプリ内のPythonで再現してみます。

実行前に出力を予想する

path = "/opt/homebrew/bin:/usr/bin:/bin"
folders = {
    "/opt/homebrew/bin": ["brew", "gh", "python3"],
    "/usr/bin": ["git", "python3", "curl"],
    "/bin": ["ls", "echo"],
}

def which(command):
    for folder in path.split(":"):
        if command in folders[folder]:
            return folder + "/" + command
    return "command not found: " + command

print(which("python3"))
print(which("git"))
print(which("uv"))

python3 は2つのフォルダにありますが、PATH で先に書かれているほうが使われます。Mac には最初から /usr/bin/python3 があるため、自分で入れたつもりの Python ではなく、別の Python が動いていた、という混乱はよく起きます。そして、どのフォルダにもないコマンドは command not found になります。

つまり、command not found の原因はほぼ2つです。そもそも入っていないか、入っているが PATH に含まれる場所にないか。後者の場合、多くはインストール時に表示された「PATH に追加してください」という案内を見落としています。

git と GitHub CLI の初期設定

git に名前とメールアドレスを登録する

git は、ファイルの変更履歴を記録する道具です。AIエージェントに大きな変更をさせる前に履歴を記録しておけば、結果が気に入らなかったときに元に戻せます。使い方は → 2-02 Git と GitHub で学ぶので、ここでは最初の設定だけをします。

git config --global user.name "Taro Yamada"
git config --global user.email "taro@example.com"
git config --global init.defaultBranch main
git config --global --list

名前とメールアドレスは自分のものに置き換えてください。最後のコマンドで、設定した内容が表示されれば成功です。

user.name=Taro Yamada
user.email=taro@example.com
init.defaultbranch=main

ここで登録した名前とメールアドレスは、変更履歴に記録され、GitHub で公開すると誰でも見られます。メールアドレスを公開したくない場合は、GitHub が用意している非公開用のアドレスを使う方法があります。2-02 で説明します。

GitHub CLI

GitHub は、git の履歴をインターネット上で共有するサービスです。まだアカウントがなければ、github.com で作成しておきます。GitHub CLI（gh）は、GitHub をターミナルから操作する道具で、Claude Code もこれを使って Pull Request（変更の提案）などを作ります。

brew install gh
gh auth login

gh auth login を実行すると、どこにログインするか、どの方式で通信するか、などを順に質問されます。迷ったら、GitHub.com、HTTPS、ブラウザでログイン、を選びます。表示されたコードをブラウザに入力して承認すれば完了です。質問の内容は版によって変わることがあるので、画面の案内に従ってください。

gh auth status

自分のアカウント名とともに、ログインしている旨が表示されれば成功です。

uv と Python

なぜ uv を使うのか

Mac には、Command Line Tools と一緒に /usr/bin/python3 が入っています。しかし、これは Apple がシステムのために用意したもので、バージョンが古く、自由にライブラリを入れるのにも向いていません。この課程では、uv（ユーブイ）という道具で、Python 本体と、プロジェクトごとのライブラリをまとめて管理します。

uv を使う理由は3つあります。1つ目は、Python 本体を好きなバージョンで入れられること。2つ目は、プロジェクトごとに独立した環境（仮想環境、virtual environment）を自動で作り、あるプロジェクトのライブラリが別のプロジェクトを壊さないようにできること。3つ目は、とても速いことです。AIエージェントに作業させるときも、uv のコマンドは短く確実なので、指示が簡単になります。

uv を入れる

公式ページに載っている方法は2つあります。どちらか一方を使います。この課程では1つ目を使います。

curl -LsSf https://astral.sh/uv/install.sh | sh

（Homebrew で入れたい場合は brew install uv でも構いません。更新方法が brew upgrade uv になります。）

導入が終わったら、ターミナルを一度終了して、開き直してください。新しく入れたコマンドの場所は、開き直したターミナルで初めて有効になることが多いからです。

uv --version

uv 0.9.18

uv に続いてバージョンが表示されれば成功です。数字は違っていて構いません。

Python を入れる

uv で Python 3.13 を入れます。

uv python install 3.13
uv python list

uv python list で、入れた Python が一覧に表示されれば成功です。一覧には、Mac にもともとある Python なども並びます。

2026年10月時点の最新の安定版は 3.14 で、3.15 は10月9日に正式版が出る予定です。この課程は 3.13 か 3.14 を前提にしています。新しい版が出てすぐは、対応していないライブラリがあるので、正式版の公開から数週間は待つのが安全です。アプリ内の Python も 3.13 です。

uv は、入れた Python を python3.13 という名前で ~/.local/bin に置きます。python3 という名前ではない点に注意してください。ターミナルで単に python3 と打つと、先ほどの PATH の仕組みにより、Mac に最初からある Python が動くことがあります。この課程では、Python を直接呼ぶのではなく、次に説明する uv run を通して使います。

最初のプロジェクトを作る

開発用のフォルダを作り、その中に最初のプロジェクトを作ります。

mkdir -p ~/dev
cd ~/dev
uv init hello-ai
cd hello-ai
ls -a

mkdir -p ~/dev はホームフォルダに dev という作業用のフォルダを作り、cd はそのフォルダに移動します。uv init hello-ai は hello-ai という名前のプロジェクトを作ります。ls -a で、作られたファイルを確認します。

.  ..  .git  .gitignore  .python-version  README.md  pyproject.toml  ...

pyproject.toml（プロジェクトの設定ファイル）や .python-version（使う Python のバージョンを書いたファイル）などが作られていれば成功です。作られるファイルの構成は uv の版によって少し異なります。.git があるのは、uv が git の履歴管理も始めてくれたからです。

プロジェクトの Python で、バージョンを確認します。

uv run python --version

Using CPython 3.14.0
Creating virtual environment at: .venv
Python 3.14.0

最初の uv run のときに、プロジェクト専用の仮想環境（.venv フォルダ）が自動で作られます。表示されるバージョンは、.python-version に書かれたものです。3.13 か 3.14 なら問題ありません。

ここまで来たら、Mac での Python の準備はできています。プロジェクトの構成や uv add によるライブラリの追加は、→ 2-03 Python プロジェクトの作り方（uv） で詳しく学びます。

VS Code と拡張機能

VS Code を入れる

VS Code（Visual Studio Code）は、Microsoft が無償で提供しているエディタです。AIエージェントが書いたコードを読んだり、変更の差分を確認したりする場所として使います。Homebrew で入れられます。

brew install --cask visual-studio-code

公式サイト（code.visualstudio.com）からダウンロードしても構いません。インストールしたら、アプリケーションフォルダから起動します。

ターミナルから開けるようにする

VS Code を起動したら、command + shift + P でコマンドパレット（命令を名前で探して実行する入力欄）を開き、「shell command」と入力します。「Shell Command: Install 'code' command in PATH」を選んで実行します。これで、ターミナルから code というコマンドで VS Code を開けるようになります。

cd ~/dev/hello-ai
code .

. は「今いるフォルダ」を意味します。VS Code が開き、左側に先ほど作ったプロジェクトのファイルが並べば成功です。初めて開くフォルダでは「このフォルダの作成者を信頼しますか」と尋ねられます。自分で作ったフォルダなので、信頼して構いません。他人から受け取ったフォルダでは慎重に判断します。

最初のファイルを作って動かす

VS Code の左側のファイル一覧で右クリックし、「新しいファイル」から hello.py を作ります。次の2行を書いて保存します（command + S）。

import sys
print("Mac の Python で動いています:", sys.version_info[:2])

ターミナルに戻り、プロジェクトのフォルダで実行します。

uv run hello.py

Mac の Python で動いています: (3, 14)

uv run ファイル名 で、プロジェクトの環境の Python を使ってファイルを実行します。表示される数字は、自分の環境のバージョンです。

拡張機能を入れる

VS Code は、拡張機能（extension）で機能を足せます。次の2つを入れます。

左端の四角が4つ並んだアイコン（または command + shift + X）で拡張機能の画面を開き、名前で検索してインストールします。似た名前の拡張機能が多数あるので、提供元の名前を必ず確認してください。拡張機能はパソコンの中でプログラムとして動くため、出どころの怪しいものを入れるのは危険です。

ターミナルからは次のコマンドでも入れられます。うまくいかない場合は画面から入れてください。

code --install-extension ms-python.python
code --install-extension charliermarsh.ruff

Python の拡張機能を入れたら、コマンドパレットで「Python: Select Interpreter」を実行し、プロジェクトの .venv の中の Python を選びます。これで、VS Code がプロジェクトの環境を使ってコードを解析するようになります。

AIコーディングツールを入れる

Claude Code

Claude Code は Anthropic のAIコーディングエージェントで、この課程の主役です。ここでは、インストールと最初の起動までを行います。詳しい使い方は Part 3 で学びます。

利用には、Claude の有料プラン（Pro 以上）が必要です。無料プランでは使えません。2026年10月時点で、Pro は月20ドルです。料金とプランは変わることがあるので、公式の料金ページで確認してください。

公式が推奨しているのは、ネイティブインストーラという方法です。

curl -fsSL https://claude.ai/install.sh | bash

終わったら、ターミナルを開き直してから確認します。

claude --version
claude doctor

2.1.290 (Claude Code)

バージョンに続いて「(Claude Code)」と表示されれば成功です。claude doctor は、インストールの状態を詳しく診断します。問題があれば、その内容が表示されます。

このインストーラで入れた Claude Code は、裏で自動的に更新されます。Homebrew でも入れられますが（brew install --cask claude-code）、その場合は自動更新されないので、自分で brew upgrade claude-code を実行する必要があります。どちらか一方だけを使ってください。

最初の起動とログイン

練習用のプロジェクトのフォルダで起動します。

cd ~/dev/hello-ai
claude

初回はブラウザが開き、claude.ai のアカウントでのログインを求められます。ログインして承認すると、ターミナルに「Login successful」と表示されます。ブラウザが自動で開かない場合は、画面の案内に従って c キーでURLをコピーし、ブラウザに貼り付けます。コードが表示された場合は、ターミナルの「Paste code here if prompted」の欄に貼り付けます。

続いて、このフォルダを信頼するかを尋ねられます。自分で作った練習用のフォルダなので、信頼して構いません。

起動したら、入力欄に次のように日本語で入力してみてください。

このフォルダにあるファイルを一覧にして、それぞれの役割を1行ずつ説明してください。

Claude Code がフォルダを調べ、pyproject.toml や hello.py について説明すれば成功です。終了するには control + C を押します（1回で終わらない場合はもう1回押します。操作は版によって変わることがあるので、画面下の案内も見てください）。

ターミナルが苦手な人には、Claude のデスクトップアプリから Claude Code を使う方法もあります。ただし、この課程ではターミナルでの使い方を基本にします。

Codex CLI と Antigravity CLI（任意）

他社のAIコーディングエージェントも、比較のために入れておくことができます。どちらも任意です。この課程の演習は Claude Code で進められます。

Codex CLI は、インストール後に codex で起動し、「Sign in with ChatGPT」を選んでログインします。Node.js を入れている人は npm install -g @openai/codex でも入れられます。プランごとの利用範囲は変わりやすいので、公式ページで確認してください。

Antigravity CLI は、インストール後に agy で起動し、Google アカウントでログインします。無料枠の残りは、起動後に /usage で確認できます。なお、以前の Google の無料のAIコーディングツールだった Gemini CLI は、2026年6月18日に、無料利用者向けには Antigravity CLI に置き換えられました。古い記事に書かれた Gemini CLI の無料枠の説明は、今は当てはまらないので注意してください。

3つのツールの使い分けは → 3-07 Claude Code を使いこなす で扱います。

Google Colab と Gemini API

Colab の基本

Google Colab（コラボ）は、ブラウザで Python を実行できる Google のサービスです。Google アカウントがあれば無料で使えます。コードは自分のMacではなく、Google のサーバー上の仮想マシンで動きます。この課程では、本物のLLM APIを呼ぶコードを Colab で実行します。

colab.research.google.com を開き、「ノートブックを新規作成」を選びます。ノートブック（notebook）は、コードと文章を並べて書ける文書です。

アプリ内の Python と違い、Colab ではセルの最後の式の値が自動で表示されます。

Colab の無料枠には注意点があります。公式のよくある質問によれば、ノートブックの実行は最長12時間で、操作しないでいると途中で切断されます。具体的な上限は公開されておらず、時期や利用状況で変わります。ランタイムが切断されると、それまでに入れたライブラリや作ったファイルは消えます。だから、各ノートブックの最初のセルに、必要な準備（!pip install など）を書いておきます。

GPU（画像処理装置。機械学習の計算を高速にする部品）は、メニューの「ランタイム」から「ランタイムのタイプを変更」で選べます。無料枠では T4 という GPU が使えることが多いものの、保証はされていません。LLM API を呼ぶだけなら GPU は不要です。GPU を使うのは → 8-07 ファインチューニングを判断し、試す です。

Gemini APIキーを取得する

API キー（API key）は、APIを使うときに「誰が使っているか」を示す文字列です。他人に知られると勝手に使われてしまうので、パスワードと同じように扱います。

無料枠の利用にクレジットカードの登録は不要です。画面の文言や配置は変わることがあるので、見つからない場合は Gemini API の公式ドキュメントの「APIキー」のページで最新の手順を確認してください。

Colab のシークレットに登録する

APIキーをコードに直接書くと、ノートブックを人に共有したときにキーも一緒に渡ってしまいます。Colab には、キーをノートブックとは別に保管する「シークレット」という機能があります。

最初のLLM呼び出し

Colab の最初のコードセルに、次のコードを貼り付けて実行します。この課程で本物のLLMを呼ぶときは、毎回この形から始めます。

Google Colab で実行するコード

# Colab の左側「鍵」アイコン（シークレット）に GEMINI_API_KEY を登録しておく
!pip -q install openai
from google.colab import userdata
from openai import OpenAI

client = OpenAI(
    api_key=userdata.get("GEMINI_API_KEY"),
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)
MODEL = "gemini-flash-lite-latest"  # 無料枠で回数に余裕のある軽量モデル。最新の名前は AI Studio で確認

このセルは、openai というライブラリを入れ、シークレットからキーを取り出し、Gemini API に接続するクライアント（APIを呼ぶための窓口となるオブジェクト）を作ります。何も表示されずに終われば成功です。

ここで不思議に思うかもしれません。Google の Gemini を呼ぶのに、なぜ OpenAI のライブラリを使うのでしょうか。Gemini API は、OpenAI の API と同じ形で呼べる入り口（OpenAI 互換エンドポイント）を用意しています。base_url に Gemini の住所を指定すれば、OpenAI のライブラリのまま Gemini と話せます。この形は、Mac 上でLLMを動かす Ollama や LM Studio などでも使える、業界で最も広く使われている形です。

次のセルで、実際に質問を送ります。

Google Colab で実行するコード

resp = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": "AIエンジニアの仕事を、初学者向けに2文で説明してください。"}],
)
print(resp.choices[0].message.content)
print(resp.usage)

数秒後に、日本語の説明が2文ほど表示されれば成功です。本物のLLMなので、文章は実行のたびに変わります。最後の行は、使ったトークン（LLMが文章を扱う単位）の数です。料金や上限は、このトークン数で決まります（→ 5-02 トークンとコンテキスト）。

アプリ内の模擬LLMと同じ形

同じコードを、アプリ内の模擬LLM（llmsim）で動かしてみます。違うのは、最初の import とクライアントの作り方、モデル名だけです。

アプリで実行できるコード

from llmsim import OpenAI

client = OpenAI()  # 模擬LLM。APIキーは不要で、通信もしない
MODEL = "sim-small"

resp = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": "AIエンジニアの仕事を、初学者向けに2文で説明してください。"}],
)
print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens, resp.usage.total_tokens)

模擬LLMは、ルールを渡さないと、受け取った質問を言い返すだけです。中身は本物とまったく違いますが、client.chat.completions.create(...) の呼び方と、resp.choices[0].message.content で答えを取り出す形は同じです。だから、アプリ内で組み立て方を練習したコードは、Colab に持っていけば、少しの書き換えで本物のLLMで動きます。この流れは Part 6 で繰り返し使います。

失敗したときの表示と対処

最初の呼び出しで失敗したときは、エラーメッセージの最後の行を読み、次の表で対処を探します。

HTTP の後の数字はステータスコードと呼ばれ、サーバーが「どういう結果だったか」を伝える番号です。400番台は送った側の問題、500番台はサーバー側の問題を表します。429 は「呼びすぎ」で、待てば直ります。一方、401 や 403 は何度やり直しても直りません。この区別は、本番のアプリで再試行を設計するときに重要になります（→ 2-05 HTTP と Web API、→ 6-06 本番に耐える呼び出し方）。

完了チェックと、うまくいかないとき

チェックリスト

ここまでの作業が終わったかを確認します。終わったものにチェックを付けてください。

• ターミナルを開き、sw_vers と uname -m で自分のMacの情報を確認した
• git --version で git のバージョンが表示される
• brew --version で Homebrew のバージョンが表示され、brew doctor を実行した
• git config --global --list で名前・メールアドレス・main が表示される
• gh auth status で GitHub にログインしていることを確認した
• uv --version で uv のバージョンが表示される
• uv python install 3.13 を実行し、uv python list に表示された
• ~/dev/hello-ai を作り、uv run python --version と uv run hello.py が動いた
• VS Code を code . で開け、Python と Ruff の拡張機能を入れた
• claude --version が表示され、claude でログインして質問に答えてもらえた
• echo $ANTHROPIC_API_KEY が空であることを確認した
• AI Studio で Gemini APIキーを取得し、Colab のシークレットに GEMINI_API_KEY として登録した
• Colab で最初のLLM呼び出しが成功し、答えとトークン数が表示された

すべてにチェックが付けば、この課程を進める準備は整っています。Claude Code の契約がまだの場合は、Part 3 までに用意すれば十分です。それまでの章はアプリと Colab で進められます。

よくあるつまずき

AIに環境の問題を相談する

環境構築のトラブルは、AIに相談すると解決しやすい種類の問題です。ただし、AIは古い手順（古いインストール方法や、今はないオプション）を答えることがあります。AIが示したコマンドは、公式ページの手順と照らし合わせてから実行してください。特に sudo や rm（削除）を含むコマンドは、意味を説明してもらい、自分が理解してから実行します。

Macで開発環境を整えている初学者です。次の問題を解決したいです。
いきなり解決のコマンドを並べるのではなく、まず原因の候補を説明し、原因を確かめるための安全なコマンド（何も変更しないもの）を先に教えてください。
sudo や rm を含むコマンドを提案する場合は、その理由と危険性も説明してください。

Macの情報：
- チップ：{例：Apple M2}（uname -m の結果：{arm64}）
- macOS：{sw_vers の ProductVersion}

やろうとしたこと：
{例：uv をインストールした後、uv --version を実行した}

実行したコマンド（そのまま）：
{コマンド}

表示された結果（全文）：
{エラーメッセージ}

echo $PATH の結果：
{結果}

すでに試したこと：
{例：ターミナルを開き直した}

アプリ内でも確かめておく

最後に、アプリ内のPythonと、自分のMacのPythonの違いを確認しておきます。アプリ内で次を実行してください。

アプリで実行できるコード

import sys
print("Python のバージョン:", sys.version_info[:2])
print("動いている場所:", sys.platform)

アプリ内の Python は、ブラウザの中で動く特別な版です。sys.platform は、Mac で実行すれば darwin（macOS の内部名）になりますが、アプリ内では別の値になります。同じ Python の言語でも、どこで動いているかによって、使えるライブラリや、ファイル・ネットワークへのアクセスが変わります。「どの環境で動かしているか」を意識することは、エラーの原因を考えるときの最初の手がかりです。

環境変数も、アプリ内で試せます。APIキーのような秘密の値は、コードに直接書かずに環境変数やシークレットから読み込むのが基本です。

アプリで実行できるコード

import os

print(os.environ.get("GEMINI_API_KEY"))          # 設定されていなければ None
os.environ["APP_MODE"] = "practice"               # このプログラムの中だけで有効な設定
print(os.environ.get("APP_MODE"))
print(os.environ.get("NO_SUCH_SETTING", "既定値"))  # なければ2つ目の値を使う

os.environ.get("名前") は、環境変数の値を読み、なければ None（値がないことを表す特別な値）を返します。2つ目の引数を渡すと、ないときにその値を使います。Colab の userdata.get("GEMINI_API_KEY") も、考え方は同じです。値そのものをコードに書かないので、コードを人に見せたり GitHub に公開したりしても、キーは漏れません。

キーを画面に表示するのも避けます。確認が必要なときは、一部だけを表示します。

実行前に出力を予想する

key = "AQ.Ab8RN6sample0123456789XYZ"
masked = key[:4] + "..." + key[-4:]
print(masked)
print(len(key), len(masked))

key[:4] は先頭の4文字、key[-4:] は末尾の4文字を取り出す書き方です（→ 1-02 文字列を扱う）。ここで使ったキーは、形だけを似せた架空の文字列です。本物のキーは、ログにも画面にも、AIへの質問にも、そのまま貼らないでください。

演習

path = "/Users/taro/.local/bin:/opt/homebrew/bin:/usr/bin:/bin"
folders = path.split(":")
print("フォルダの数:", len(folders))

def find_command(command, path, folders):
    for folder in path.split(":"):
        if command in folders.get(folder, []):
            return folder + "/" + command
    return None

def is_supported(version_text):
    number = version_text.split()[1]
    parts = number.split(".")
    major = int(parts[0])
    minor = int(parts[1])
    return (major, minor) >= (3, 13)

def mask_key(key):
    if not key:
        return "(未設定)"
    if len(key) < 12:
        return "****"
    return key[:4] + "..." + key[-4:]

【質問文】
Macで開発環境を整えている初学者です。次の問題を解決したいです。
いきなり解決のコマンドを並べるのではなく、まず原因の候補を説明し、原因を確かめるための安全なコマンド（何も変更しないもの）を先に教えてください。
sudo や rm を含むコマンドを提案する場合は、その理由と危険性も説明してください。

Macの情報：
- チップ：Apple M2（uname -m の結果：arm64）
- macOS：26.0

やろうとしたこと：
uv の公式ページにある curl -LsSf https://astral.sh/uv/install.sh | sh でインストールした後、翌日 uv --version を実行した。

実行したコマンド（そのまま）：
uv --version

表示された結果（全文）：
zsh: command not found: uv

echo $PATH の結果：
/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin

すでに試したこと：
ターミナルを開き直した。インストールの最後に英語の案内が出ていたが、読まずに閉じてしまった。

【実行前に確認すること】
1. 提案されたコマンドが何を変更するのか（設定ファイルに書き込むのか、ファイルを消すのか）を説明でき、それが uv の公式ページの手順や、インストール時に表示されるはずの案内と一致しているか。
2. sudo や rm が含まれていないか。含まれている場合、本当に必要か。この問題（PATH に ~/.local/bin がない）なら、通常は sudo も rm も不要のはず。
3. まず ls ~/.local/bin などの「何も変更しない」コマンドで、uv が実際にインストールされているかを確かめてから、PATH の設定を変えること。原因を確かめずに再インストールなどを重ねない。

理解度チェック

client = OpenAI(
    api_key=userdata.get("GEMINI_API_KEY"),
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)

print("3.9.6" >= "3.13")

まとめ

• 入れる順番は、ターミナル → Command Line Tools → Homebrew → git の設定 → uv と Python → VS Code → Claude Code。Colab と Gemini APIキーは独立して進められる。
• curl ... | bash のコマンドは、この章か公式ページからだけコピーする。表示が違ったら公式ページで最新の手順を確認する。
• command not found の原因は、入っていないか、入っているが PATH に含まれていないかのほぼ2つ。インストール後はターミナルを開き直し、表示された案内を読む。
• PATH は、シェルがコマンドを探すフォルダの一覧で、先に書かれたフォルダが優先される。
• Python は uv で管理し、uv run を通して使う。Mac に最初からある Python は使わない。
• Claude Code はネイティブインストーラで入れ、Pro 以上のプランでログインする。ANTHROPIC_API_KEY が設定されているとAPI課金になる。AIエージェントは練習用のフォルダでだけ起動する。
• Gemini APIキーは Colab のシークレットに GEMINI_API_KEY として登録し、コードに直接書かない。無料枠には個人情報や機密を送らない。
• Colab の Gemini 呼び出しと、アプリ内の模擬LLMは、同じ形のコードで動く。

参考資料

いずれも任意です。手順の表示が本文と違ったときは、ここに挙げた公式ページで最新の手順を確認してください。

• Claude Code のセットアップ（公式、英語）
• Homebrew（公式）
• uv のインストール（公式、英語）
• Gemini API キーの取得（公式）
• Gemini API の OpenAI 互換エンドポイント（公式）
• Google Colab のよくある質問（公式）