この記事では、その最小の仕組みをVS CodeのOpenAI Codexと一緒に作ります。まずは読み取り専用で安全に始め、次に書き込みを追加する二段階で進めます。
準備、同意画面と権限（スコープ）の決め方、動作確認、失敗しやすい点の直し方までまとめて扱います。
この回のゴール
- できること：Googleカレンダーの予定を読み取り、AIで要約し、同意のうえ“下書き（仮）”イベントを追加できる最小アプリを完成させる。
- 用意するもの：Googleアカウント、Google Cloudのプロジェクト、OpenAIアカウント、VS Code、OpenAI Codex拡張、Node.jsまたはPython。
- 大切な約束：最小権限から始める、APIキーの実値は絶対に共有しない、公式ドキュメントで料金と仕様の最新情報を確認する。
最初に知っておきたい用語
- Googleカレンダー API：アプリから予定（イベント）の読み書きを行うための入り口。
- OAuth：アプリがあなたの代わりにサービスへアクセスする許可の仕組み。鍵の貸し借りのようなもの。
- スコープ：どこまで触ってよいかを決める範囲。読むだけか、書くのもOKか、など。
- Event：カレンダーの1つの予定。開始・終了、タイトル、メモなどの情報を持つ。
- Calendar：予定を入れるノート冊子のような入れ物。複数持てる。
- ACL：誰がそのカレンダーを見たり編集できるかのルール一覧。
- OpenAI Codex：VS Code内で依頼するとコードや設定を作ってくれるAIの開発支援ツール。
- 環境変数：APIキーなど秘密をファイルに直書きせず安全にアプリへ渡す方法。
1. この記事でできること
目標は「読む→提案→書く」を小さく体験することです。
たとえるなら、まずは家の中を“見るだけの見学許可”で入り、安全が確かめられたら“メモを置く”許可を追加する流れです。見学を先にすることで安心して次に進めます。
- Googleカレンダーから予定を読み取る（読み取り専用スコープ）
- OpenAIを使って「今日・明日」の予定を要約する
- 同意後に“下書き（仮）”の予定を追加する（書き込みスコープ）
学べることは、OAuthの考え方、最小権限スコープ、予定データの基本、安全なAPIキー管理です。所要時間は目安で約50分です。料金や仕様は変わるため、必ず公式の説明を確認してください。参照先は記事末尾の出典にまとめています。
2. 完成イメージ
完成後の操作と結果は次のとおりです。引っ越し前に間取り図を見るように、ゴールをイメージしてから作業を始めましょう。
- アプリを起動すると、ブラウザでGoogleの同意画面が開き、読み取りのみを許可する。
- ターミナル画面に「今日と明日の予定要約」が表示される。
- 追加の同意で書き込みを許可すると、プロンプト内容に沿った“下書き（仮）”の予定が自分のカレンダーに作成される。
- 読み取り専用→書き込み追加の2段階で安全に確認できる。
3. 最初に知っておきたいこと
OAuthのスコープは、家の合鍵を「必要な部屋だけ」渡すイメージです。最初は廊下とリビングだけ見学、問題なければ書き置きを残せるように鍵を1本足す、という流れです。
Google Calendar APIの用語は公式の定義に沿って使います。Eventは1つの予定、Calendarは予定を入れる入れ物、ACLはアクセス権のルール表です。最小権限を選ぶと安全で、ユーザーも同意しやすくなります。
4. 対象読者
- 予定調整AIの仕組みを仕事に活かしたい人
- OAuthは初心者〜中級で、まず安全に試したい人
- VS CodeとOpenAI Codexで、指示どおりに一歩ずつ進めたい人
旅行で迷わないように地図アプリを開くのと同じで、この記事は画面で「何を押すか」「何が出たら成功か」を言葉で案内します。
5. 必要なものと入れ方
ここでは、道具ごとに「これは何？」「用意するもの」「入れ方・開き方」「最初の設定」「できたか確認」を順番に説明します。家電の取り扱い説明書のように、一手順ずつ確かめましょう。料金や制限は公式の最新情報を確認してください。Google Calendar APIの仕様はGoogle Calendar API overview、認証はGoogle Calendar API authentication、OpenAIはOpenAI API Quickstartが確認先です。
VS Code
- これは何？：プログラム用のノートと机。ファイルを並べたり、拡張で道具を足せます。
- 用意するもの：インターネット接続、PC本体、公式サイトにアクセスするブラウザ。
- 入れ方・開き方：公式サイトからダウンロードし、インストール後にアプリを開きます。
- 最初の設定：日本語表示やフォルダを開くなど、画面の指示に従います。
- できたか確認：「Visual Studio Code」のタイトルとサイドバーが見えればOKです。
OpenAI Codex（VS Code拡張）
- これは何？：お手伝いロボ。作りたい物を伝えると、必要なファイルや設定を書いてくれます。
- 用意するもの：OpenAIアカウント。サインインに使うメールアドレス。
- 入れ方・開き方：VS Code左の四角いアイコン（拡張機能）を押し、検索欄に「Codex」と入力。OpenAIのCodex拡張を選び、「インストール」を押す。完了後に「有効」表示になる。
- 最初の設定：拡張の案内に沿ってサインインする。サイドバーか下部にCodexのチャット欄を開く。
- できたか確認：「Codex」ロゴとチャット入力欄が見える。メッセージが送れる。
GoogleアカウントとGoogle Cloud
- これは何？：Googleのサービスでアプリを作るための管理場所。カレンダーAPIのスイッチを入れます。
- 用意するもの：Googleアカウントとブラウザ。
- 入れ方・開き方：ブラウザでGoogle Cloudコンソールを開き、プロジェクトを作成。ダッシュボードに入る。
- 最初の設定：APIとサービスから「Calendar API」を検索し、「有効にする」を押す。
- できたか確認：「有効」ステータスが表示され、ダッシュボードにCalendar APIが並ぶ。
Node.jsまたはPython
- これは何？：アプリを動かすエンジン。どちらか一つでOKです。
- 用意するもの：公式サイトからインストーラーを入手できるブラウザ。
- 入れ方・開き方：案内に従いインストール。VS Codeでフォルダを開けば使えます。
- 最初の設定：言語パックや拡張は不要でも進められます。
- できたか確認：Codexに「バージョンを表示して」と頼み、表示できればOK。
Google/ OpenAI公式クライアント
- これは何？：Google Calendar APIやOpenAIを簡単に呼ぶための道具箱。
- 用意するもの：インターネット接続。パッケージの入手はCodexに任せます。
- 入れ方・開き方：手入力は不要。後の手順でCodexに依頼します。
- 最初の設定：環境変数からキーを読むようにします。
- できたか確認：後の「動かして確認する」でAPI呼び出しが通ればOK。
前回の記事のUIとつなげたい人は、時間があればこちらも参考にどうぞ：AIを読む人から使う人へ：中学生にも分かるNext.jsでAIチャットUIを作る #3。
6. エージェントと作るものの全体像
全体像は「CLIアプリ — Google OAuth — Calendar API — OpenAI API」の一直線です。
台所で材料（予定データ）を取り出し、料理人（OpenAI）が要約や候補を作り、食卓（カレンダー）に並べるイメージ。配膳前には必ず持ち主の許可（同意）を取ります。
- 予定を読む：読み取り専用スコープでイベント一覧を取得
- AIで処理：今日と明日の要約、候補イベントの作成文面
- 書き込む：合意が取れたら下書きイベントとして追加
7. 手順1: ツールを準備する
目的と流れ
ここでは、Google Cloudの設定、VS CodeとCodexの準備、公式クライアントの導入をCodexに任せる準備をします。引っ越しの前に段ボールとラベルをそろえる時間です。
読者が行う画面操作
- Google Cloudコンソールを開き、プロジェクトを作成してCalendar APIを有効化
- VS Codeを開き、拡張機能で「Codex」を検索し、OpenAIのCodex拡張をインストールしてサインイン
- VS Codeで作業用の空フォルダを開き、Codexのチャット欄を表示
成功の見分け方
- Google CloudのダッシュボードにCalendar APIが「有効」と表示される
- VS CodeにCodexのチャット欄が出て、メッセージを送れる
次に進む前の確認
Googleアカウントでサインインしていること、Codexが使えることを確認します。ここが整えば、以降はCodexに依頼して進められます。
8. 手順2: APIキーを安全に用意する
目的と流れ
APIキーは「金庫の鍵」です。机の上に置かず、引き出し（環境変数）にしまい、引き出しの場所（.env）は公開しないようにします。GoogleのOAuthクレデンシャルも、同意画面を最小で設定し、ローカルに安全に保存します。
読者が行う画面操作
- OpenAIアカウントでAPIキーを発行し、値はコピーせずにこの後のCodex依頼に備える（実値は貼らない）
- Google Cloudの「APIとサービス」→「認証情報」でOAuthクライアントIDを作成
- OAuth同意画面を最小で設定（アプリ名、サポート連絡先、対象ユーザーなど）。スコープは最初は読み取り専用を選択
成功の見分け方
- OpenAIダッシュボードでAPIキーが発行されている
- Google CloudでOAuthクライアントID/シークレットが作成され、ダウンロード可能になっている
次に進む前の確認
キーの実値を他人に渡していないこと、同意画面が保存されていることを確認します。料金・制限の最新情報は、各公式ドキュメントで必ず確認してください。
9. 手順3: エージェントにアプリを作ってもらう
目的
Codexに、読み取り専用の最小アプリを先に作ってもらい、その後で書き込み機能を足します。料理でいえば、まず味見できるスープを作り、その後に具材を増やします。
操作：このボックスをコピーして、VS Code内のCodexチャットに送ります
Codexに送るプロンプト
目的：Googleカレンダーを「読み取り→要約→同意して下書きを書き込み」の二段階で試せる最小CLIアプリを作ってください。Node.jsまたはPythonのどちらでもOK。以下を必ず守ってください。
要件：
- ステップ1（読み取り専用）：Google Calendar APIのreadonlyスコープのみで、今日と明日の予定（Event）を取得し、OpenAI APIで日本語の短い要約を出力する。
- ステップ2（書き込み追加）：ユーザーが同意した場合のみ、カレンダーに“下書き（仮）”のイベントを1件追加できる機能を別コマンドまたは明示的な確認で提供する。
- スコープ設計：初期は読み取り専用。書き込み時に必要な最小スコープだけを追加し、同意フローを再実行する。
- ファイル構成：src/ 配下に本体、.env.example、README.md、.gitignore を用意。.env は実値なしで説明コメントを入れる。
- 秘密情報：OpenAI APIキー、Google OAuthクレデンシャルは環境変数またはローカル安全ファイルから読み込む。コードやREADMEに実値を書かない。
- 例外処理：ネットワーク障害、認証エラー、スコープ不足をユーザーにわかる日本語メッセージで表示し、次の行動（再認可や設定ファイル確認）を案内する。
- 動作確認：初回起動時にブラウザでGoogleの同意画面が開き、トークンをローカルへ安全に保存。読み取り後、ターミナルに要約を表示。書き込み同意後は“下書き（仮）”イベントが追加されたことを標準出力に表示する。
- 質問：前提が不足していれば必ず質問してから進める（例：NodeかPythonか、タイムゾーン、カレンダーIDなど）。
納品物：
- 主要ファイル一式（コード、設定テンプレート、README）
- 実行と検証の手順（コマンド例はプレースホルダー表記で。ユーザーに実行を強制しない）
- OAuth同意画面の設定で使うスコープ一覧と意味の説明（公式名称を使用）
- 書き込み用の拡張手順：readonly→書き込みの差分をREADMEに明記Codexが作るものと、読者が確認する点
- src/以下のコードとREADME、.env.example、.gitignoreができている
- READMEに、読み取り→書き込みの二段階の説明があり、スコープ名が公式名称で書かれている
- 例外時の日本語メッセージと、次の行動案内が表示される
10. 手順4: 動かして確認する
目的
初回起動で読み取り専用を確認し、必要に応じて書き込みの同意を追加します。試食をしてからメニューを増やす流れです。
読者が行う画面操作
- CodexのREADME案内に従ってアプリを起動（コマンド入力はCodexに聞きながら進める）
- ブラウザにGoogleの同意画面が開いたら、読み取り専用スコープを許可
- ターミナルに「今日と明日の予定要約」が出ることを確認
- 次に、書き込み機能を試すときは、Codexの案内どおりに同意画面で書き込みスコープを追加して再実行
成功の見分け方
- 初回後、ローカルにトークンが保存された（Codexの案内に保存先が記載）
- 要約テキストが表示された
- “下書き（仮）”イベントが自分のGoogleカレンダーに追加された（カレンダーアプリで見える）
次に進む前の確認
書き込みを試す前に、どのカレンダーに追加されるかと、イベントのタイトル・時間帯を確認します。誤って大事な予定を上書きしないためです。
11. 手順5: エージェントと直す
目的
細かな直しをCodexへ依頼して品質を上げます。自転車のサドル高さやブレーキの効き具合を調整するイメージです。
Codexに送る観点（例）
- タイムゾーンの明示（例：アジア/東京）と終日予定の扱い
- 重複作成の回避（同じタイトル・時間の場合はスキップ）
- エラーハンドリング強化（API制限、認可切れ、ネットワーク）
- ログの粒度（ユーザーに見せる要約と開発用詳細を分ける）
短い改善プロンプト例
Codexのチャットに、次のように依頼します（コピーして使えます）。
Codexに送るプロンプト（改善）
読み取りと書き込みが動きました。次を改善してください：
- タイムゾーンを「アジア/東京」に固定。終日予定は開始00:00、終了23:59として表示。
- 直近7日以内に同一タイトル・開始時刻のイベントがある場合は新規作成せずメッセージ表示。
- 失敗時に「原因の候補」「ユーザーが次に見る場所（例：同意スコープ、.env、トークン）」「再実行手順」を日本語で案内。
- READMEに、readonly→書き込みの差分（スコープ名・同意フローの違い）を表で追記。12. よくあるエラー
- invalid_scope が表示される
画面で見えること：同意画面やターミナルに、要求したスコープが無効と出る。
よくある原因：同意画面で選んだスコープとコード側の指定が不一致。
最初に確認する場所：Google CloudのOAuth同意画面のスコープ一覧、READMEの指定。
エージェントに送る質問：「要求スコープと同意画面の設定が一致しているか点検し、必要な最小スコープ名を公式名称で教えて。差分を修正して。」 - redirect_uri_mismatch
画面で見えること：ブラウザでリダイレクトURIが一致しないと表示。
よくある原因：コード側のローカル受け取りURLと、Google Cloudの認証情報に登録したリダイレクトURIが不一致。
最初に確認する場所：Google CloudのOAuthクライアントの設定。
エージェントに送る質問：「ローカルの受け口URLとGoogle CloudのリダイレクトURIをそろえて。どの値を登録すべきかREADMEに明記して。」 - insufficientPermissions / 403
画面で見えること：ターミナルで権限不足エラー。
よくある原因：読み取り専用トークンで書き込み操作を呼んだ。
最初に確認する場所：保存済みトークンのスコープ、READMEの“書き込み追加”手順。
エージェントに送る質問：「読み取りトークンを破棄して、書き込みスコープで再認可する手順を自動化して。」 - OpenAIキー未設定
画面で見えること：OpenAI呼び出し時に認証エラー。
よくある原因：環境変数にキーがない、.envを読み込んでいない。
最初に確認する場所：.env.example、READMEの設定手順。
エージェントに送る質問：「環境変数読み込み処理を点検し、未設定なら分かりやすい警告を出して。」 - レート制限やクォータ
画面で見えること：429や割り当て超過メッセージ。
よくある原因：短時間に呼び過ぎ。
最初に確認する場所：Google Cloudのクォータ画面、OpenAIの利用状況。
エージェントに送る質問：「指数バックオフで再試行し、上限値と待ち時間をREADMEに書いて。」
13. 次に試すこと
- 参加者の空き時間検索と提案（複数カレンダーの読み取り）
- “外出/集中タイム”のテンプレートを用意し、条件に応じて自動作成
- Webhook/Push通知で変更を検知し、要約や再提案を更新
14. まとめ
最小権限から始め、段階的に書き込みを追加する流れは、安全で現実的です。VS CodeのOpenAI Codexに作業を任せつつ、私たちは設計（権限とデータ）に集中できます。今日作った「読む→提案→下書き」の小さな一歩が、業務の予定調整を賢くする土台になります。
時間があれば、シリーズの前回で作ったUIとつないで体験を広げてください：AIを読む人から使う人へ：中学生にも分かるNext.jsでAIチャットUIを作る #3。
参考文献・出典
- Google Calendar API overview：APIの基本概念と機能一覧。
- Google Calendar API authentication：OAuth同意画面、スコープ選定、クレデンシャル作成。
- OpenAI API Quickstart：OpenAI APIの開始方法、キー管理。
