Claude Code・Codexでスプレッドシートを定期操作する定番パターン

なぜAPI連携が「定期操作」の定番なのか

Claude CodeやCodexは「ターミナル上で動くAIエージェント」です。これらが直接セルをクリックするわけではなく、実際には次の流れで処理が進みます。

1. ユーザーが自然言語で指示を出す。例：「毎朝、売上シートを集計してサマリーシートに書き込んで」
2. AIがGoogle Sheets APIを叩くPythonスクリプトを生成する
3. AIがそのコードを実行・検証し、動くスクリプトとして仕上げる
4. そのスクリプトをスケジューラ、cronなどに登録し、以降は自動で回す

ここで重要なのは、一度AIにスクリプトを作らせてしまえば、あとは無人で繰り返し実行できるという点です。手動でファイルをダウンロードして編集する方式は毎回人手が必要になり、定期運用には向きません。だからこそ、継続的に操作するならAPI連携が前提になります。

制約なしパターン：サービスアカウント＋APIで定期操作する

個人のGoogleアカウントや、API利用に制限のない環境であれば、サービスアカウントとGoogle Sheets APIを使う構成が定番です。

全体像

[スケジューラ(cron等)] → [Pythonスクリプト] → [Google Sheets API] → [スプレッドシート]
                              ↑
                  Claude Code / Codex が作成・保守

STEP 1：事前準備

1. Google Cloud Consoleでプロジェクトを作成する
2. Google Sheets APIとGoogle Drive APIを有効化する
3. サービスアカウントを作成し、JSONキーをダウンロードする
4. 操作したいスプレッドシートを、サービスアカウントのメールアドレスに編集者として共有する

STEP 2：必要なライブラリを入れる

pip install gspread google-auth

STEP 3：読み書きの基本コード

Claude CodeやCodexに「このサービスアカウントでスプレッドシートを操作するスクリプトを書いて」と指示すると、次のようなコードを生成できます。

import gspread
from google.oauth2.service_account import Credentials

scopes = ["https://www.googleapis.com/auth/spreadsheets"]
creds = Credentials.from_service_account_file("service_account.json", scopes=scopes)
gc = gspread.authorize(creds)

# スプレッドシートをIDで開く
sh = gc.open_by_key("スプレッドシートのID")

# データを読み込む
src = sh.worksheet("売上データ")
records = src.get_all_records()

# 集計（例：合計を計算）
total = sum(r["売上"] for r in records)

# 別シートに書き戻す
dst = sh.worksheet("サマリー")
dst.update("B2", [[total]])
print(f"書き込み完了: {total}")

これでAIに「B列を集計してサマリーシートに書き戻すスクリプトを作って」といった指示が通ります。ポイントは、対象のスプレッドシートをサービスアカウントに共有しておくことです。これを忘れると権限エラーになります。

STEP 4：定期実行に組み込む

スクリプトが完成したら、スケジューラに登録して自動化します。MacやLinuxのcronなら、毎朝9時に実行する例は次のようになります。

# crontab -e で以下を追記
0 9 * * * /usr/bin/python3 /path/to/update_sheet.py >> /path/to/log.txt 2>&1

GitHub Actionsを使えば、自分のPCを起動していなくてもクラウド上で定期実行できます。サービスアカウントのJSONキーはGitHub Secretsに保存し、リポジトリに直接置かないようにします。

Claude CodeやCodexには、cron設定やGitHub Actionsのワークフローファイルまで一括で書かせることができます。「このスクリプトを毎朝9時に動かすcron設定を教えて」と頼めば、必要な設定例まで出してくれます。

STEP 5：スクリプトの保守もAIに任せる

定期運用で価値が出るのが保守フェーズです。列が増えた、集計ロジックを変えたい、エラーが出たといった変更を、Claude CodeやCodexに既存スクリプトを読ませて修正させられます。ログを貼って「このエラーを直して」と頼めば、原因の特定から修正まで進めやすくなります。

制約あり：企業のGoogle Workspaceの場合にできること

個人環境では上記がそのまま動きますが、企業のGoogle Workspaceでは管理者のセキュリティポリシーによって手順がブロックされることがあります。ここでは、よくある制約と対応の方向性を整理します。

外部共有が禁止されている場合

組織のポリシーで「組織外への共有禁止」が設定されていると、サービスアカウントにスプレッドシートを共有できないことがあります。

対応の方向性：自社のGoogle Cloud組織配下で作った組織内サービスアカウントなら共有できる場合があります。あるいは管理者がドメイン全体の委任、Domain-Wide Delegationを設定すれば、組織内ユーザーの代理としてアクセスできます。いずれも管理者の協力が必要なので、情報システム部門に相談します。

OAuthアプリの利用が制限されている場合

管理コンソールでAPIアクセス制御が有効だと、許可されていないサードパーティ製アプリがブロックされます。

対応の方向性：ユーザーのOAuthログインではなくサービスアカウント認証を使うと、同意画面を経由しないためブロックの影響を受けにくくなります。どうしてもユーザー認証が必要なら、作成したクライアントIDを管理者に許可リスト登録してもらう形になります。

Google Cloudプロジェクトを作れない場合

一般ユーザーによるプロジェクト作成が制限されていると、サービスアカウントを自分で発行できません。

対応の方向性：情報システム部門や管理者に、プロジェクトとサービスアカウントの発行を依頼するのが正攻法です。自部門で発行が完結しない場合は、申請ベースでの運用になります。

制約と対応の早見表

Claude CodeとCodexで使い方に違いはある？

基本的な考え方、つまりAIにスクリプトを書かせ、API経由で操作させる流れは共通です。ただし、運用面では少し違いがあります。

どちらを使う場合でも、サービスアカウントのJSONキーの場所、対象スプレッドシートのID、読み書きするシート名と範囲を明確に伝えると、安定して動くスクリプトが得られます。

つまずきやすいポイントと対処法

• PermissionErrorが出る：対象スプレッドシートをサービスアカウントのメールアドレスに共有し忘れている可能性があります。編集者として共有されているか確認します。
• APIのレート制限に当たる：Google Sheets APIには読み書き回数の上限があります。1セルずつ更新せず、まとめて読み書きするバッチ処理に変えます。定期実行の頻度も見直します。
• 認証キーの管理が不安：JSONキーはコードに直書きせず、環境変数やGitHub Actions Secretsで管理します。
• 定期実行が動いていない：cronのパス指定ミスが多いです。python3やスクリプトを絶対パスで書き、ログを取って原因を確認します。
• シート名・列名の変更で壊れる：スプレッドシート側の構造変更に弱いです。列名をキーで参照するget_all_records()など、壊れにくい書き方をAIに依頼します。

まとめ

Claude CodeやCodexでスプレッドシートを定期的に操作するなら、定番は次の構成です。

• 制約なしの環境：サービスアカウントとgspreadでAPI連携し、cronやGitHub Actionsで定期実行。スクリプトの作成・保守はAIに任せる
• 企業のGoogle Workspace：外部共有禁止、OAuth制限、GCP作成不可といった制約に応じて、組織内サービスアカウント、ドメイン委任、管理者への発行依頼で対応する

定期運用で本当に効くのは、一度AIに動くスクリプトを作らせ、それを自動実行に乗せてしまうことです。最初の構築を越えれば、あとは無人で集計・転記が回り続けます。

企業環境では技術的な可否よりも、まず社内のデータ取り扱いルールを確認することを最優先にしてください。そのうえで、サービスアカウント発行など管理者の協力が必要な部分を早めに相談しておくと、導入が進めやすくなります。