Claude CodeでCI向け長期トークンを発行する方法

claude setup-tokenで1年間有効なトークンを作る

claude setup-tokenは、対話的なブラウザーログインが使えないCI環境やスクリプト向けに、1年間有効なOAuthトークンを発行するコマンドです。手元のPCで一度実行するだけで済みます。Claude Pro・Max・Team・Enterpriseいずれかのサブスクリプションが必要です。発行したトークンはCLAUDE_CODE_OAUTH_TOKENという環境変数にセットして使います。

claude setup-token

コマンドを実行すると/loginと同じブラウザー認可フローが開き、アクセスを承認するとトークンがターミナルに表示されます。Claude Codeはこのトークンをどこにも保存しません。表示された値をそのままコピーし、CI側のSecrets機能に登録します。ターミナルの画面をスクロールし忘れて値を取りこぼすと、再取得にはもう一度コマンドを実行し直すしかありません。

発行したトークンをどう使うか

export CLAUDE_CODE_OAUTH_TOKEN=your-token

この環境変数がセットされていると、Claude Codeは認証方式の優先順位でこのトークンを使います。優先順位は上から、クラウドプロバイダー認証・ANTHROPIC_AUTH_TOKEN・ANTHROPIC_API_KEY・apiKeyHelper・CLAUDE_CODE_OAUTH_TOKEN・プロファイル認証情報・サブスクリプションOAuthの順です。CI用のトークンだけを使わせたい場合、他の認証情報を環境に残さないほうが事故が起きにくくなります。

GitHub Actionsでの具体的なSecrets登録手順とワークフロー例はClaude CodeをGitHub Actionsに組み込むにまとめています。ログイン方式全体の比較はClaude Codeログイン方法3種の使い分けを参照してください。

このトークンでできないことは何か

CLAUDE_CODE_OAUTH_TOKENはモデルへのリクエストしか認証できません。スマートフォンやブラウザーからセッションに割り込むRemote Controlの確立や、claude.ai側で設定したコネクタの取得はこのトークンではできません。ローカルの.mcp.jsonやsettings.jsonで設定したMCPサーバーは、この制限とは関係なくそのまま動きます。CIでコードを書かせるだけなら困りませんが、Remote Control前提のワークフローを組んでいる場合は/loginのサブスクリプション認証に戻す必要があります。

bareモードではこの環境変数を読みません。claude --bare -pのようにスクリプトの起動を高速化したい場合は、ANTHROPIC_API_KEYかapiKeyHelperで認証します。bareモードは自動起動系のhooks・skills・カスタムコマンド・サブエージェント・プラグイン・MCPサーバーの読み込みを省いて起動を速くする分、認証経路も絞られる仕様です。bareモードの詳細な使い分けはClaude Code -pモードでスクリプトやパイプラインを自動化する基本で扱っています。

APIキーとOAuthトークン、CIにはどちらが向くか

CI・自動化の認証情報には主に3つの選択肢があり、運用形態によって向き不向きが分かれます。

個人のPro・Maxプランで小さなリポジトリを1つ動かすだけなら、OAuthトークンの手軽さが勝ります。複数チームにまたがる共通CIへ育ってきた時点で、上の表のAPIキー、または次の節で扱うworkload identity federationへの切り替えを検討すると安全です。

workload identity federationでSecretそのものを持たない

GitHub Actionsに限っては、Secretを一切持たない選択肢もあります。ワークフローのGitHub OpenID Connect(OIDC)トークンをClaude Console側のservice accountと交換するworkload identity federationを設定すると、OAuthトークンともAPIキーとも違い、長期的な認証情報自体をリポジトリに置かずに済みます。設定にはfederation rule IDと組織ID、ワークフロー側のid-token: write権限が必要です。個人のサブスクリプションに紐づくOAuthトークンの共有を避けたい組織では、APIキーへの切り替えよりもこちらが根本対応になります。

発行前後で確認しておくこと

トークンをリポジトリに直接書かないことが大前提です。必ずCIのSecrets機能に登録し、ワークフローファイルからは${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}のような参照だけを書きます。ログに認証情報が出力される事故は、コミットへの直書きより見落とされやすいので注意します。

古いANTHROPIC_API_KEYが同じ実行環境に残っていないかも確認します。認証方式の優先順位ではANTHROPIC_API_KEYがCLAUDE_CODE_OAUTH_TOKENより上位にあるため、意図せず古いAPIキーのほうが使われ続けるトラブルが起きえます。CI側でトークンに切り替える際は、unset ANTHROPIC_API_KEYを明示するか、Secretsから古いキーそのものを削除しておくと安全です。

CIのSecretsからトークンを削除しても、発行済みの認証情報そのものはそれだけでは無効になりません。GitHub上のSecretは参照が消えるだけです。誰かが発行したトークンを止めたい場合は、Secretsの削除だけで完了したと考えず、次節の失効時の対処に沿って新しいトークンへの切り替えが済んでいるかを確認します。

トークンが失効・取り消しされたときの対処

トークンが失効すると、Claude CodeはOAuth token revokedやOAuth token has expired、API Error: 401 ... authentication_errorのようなメッセージを返します。CLAUDE_CODE_OAUTH_TOKENで認証しているセッションは、401エラーが返っても保存済みログインのように自動で切り替わることはなく、環境変数にセットした値を送り続けます。/statusを実行するとAuth tokenの行にCLAUDE_CODE_OAUTH_TOKENと表示されるので、今どの認証情報でリクエストを送っているかはここで切り分けられます。エラーメッセージの詳しい読み方と/loginへの切り替え手順は「OAuth token revoked」の対処にまとめています。

ブラウザーを開けない環境での自動プロビジョニング

コンテナを毎回使い捨てるような環境では、claude setup-tokenをそのつど手動実行するのが現実的でない場合があります。Claude CodeにはCLAUDE_CODE_OAUTH_REFRESH_TOKENとCLAUDE_CODE_OAUTH_SCOPESという環境変数があり、これらを設定するとclaude auth loginがブラウザーを開かずに直接トークンを交換します。公式ドキュメントは自動化環境向けの認証プロビジョニング手段としてこの2つを挙げていますが、リフレッシュトークンとスコープをどう払い出すかの詳細な運用例までは示されていません。使う場合は、まず手元の環境でclaude auth loginの挙動を確認してから本番のCIに組み込むのが安全です。

まとめ

CI・自動化向けの認証は、単発のスクリプトならclaude setup-tokenで発行するOAuthトークンが手早く済み、組織で複数リポジトリに配るならAPIキーかworkload identity federationのほうが長期的に運用の破綻が少なくなります。トークンにはRemote Controlやclaude.aiコネクタが使えない制限があり、bareモードでは読まれない点も事前に押さえておくと、CI導入後のトラブルシュートが減ります。組織側でログインを特定組織に制限している場合との関係はClaude Codeで組織限定ログインを強制する方法で詳しく扱っています。

よくある質問

組織のログイン制限はCIトークン発行に影響しますか

影響しません。claude setup-tokenと/install-github-appはforceLoginMethodだけを適用し、組織のUUIDまでは検証しないため、組織限定ログインを配布していても発行自体は可能です。ただし発行者のアカウントがどの組織に属しているかは別途、運用ルールで管理する必要があります。

GitHub Actions以外のCIでも使えますか

使えます。CLAUDE_CODE_OAUTH_TOKENはGitHub Actions専用の仕組みではなく、Claude Code CLIが読む一般的な環境変数です。GitLab CIやDockerコンテナ内のcronジョブなど、CLIを直接呼び出せる環境ならどこでも同じ変数名で認証できます。

有効期限が切れる前に気付く方法はありますか

公式ドキュメントには事前通知に関する記載が見当たりません。CI実行が401エラーで失敗し始めたら期限切れを疑い、claude setup-tokenを再実行して新しいトークンでSecretsを更新します。発行日をどこかに控えておき、1年経つ前にカレンダーでローテーションを促す運用にしておくと、CIが突然止まる事態を避けやすくなります。

ローカルの/loginとCLAUDE_CODE_OAUTH_TOKENは同時に使えますか

環境変数をセットした状態で/loginを実行すると、そのセッションはログインし直したアカウントに切り替わります。ただし新しいセッションを起動するたびに、Claude Codeは環境変数の値を読みに行きます。恒久的にトークン側の認証をやめたいなら、シェルのプロファイルや設定ファイルのenvブロックからCLAUDE_CODE_OAUTH_TOKEN自体を削除しておく必要があります。