claude setup-tokenの使い方｜Claude Codeをcron・CIでログインなしに動かす1年トークンの作り方
cronやCIでClaude Codeを動かすとき、ブラウザでのログインができず止まることがあります。claude setup-tokenは、そうした環境向けに1年間使える認証トークンを発行するコマンドです。この記事では、発行から環境変数への設定、使えないこと、–bareとの相性までを、公式ドキュメントに沿って整理します。
claude setup-tokenとは：スクリプト用の長期トークンを作るコマンド
公式のCLIリファレンスでは、claude setup-tokenを「CIとスクリプト向けに、長期のOAuthトークンを発行するコマンド」と説明しています。トークンは画面に表示されるだけで、どこにも保存されません。Claudeのサブスクリプションが必要です。
| 項目 | 公式ドキュメントの内容 |
|---|---|
| 使う場面 | CIパイプラインやスクリプトなど、ブラウザでのログインができない環境 |
| 有効期間 | 1年間 |
| 必要なプラン | Pro、Max、Ultra、Team、Enterprise |
| 保存 | されない（表示されたものを自分でコピーする） |
| 使い方 | 環境変数CLAUDE_CODE_OAUTH_TOKENに入れる |
普段のPCでは/loginで足ります。トークンが要るのは、サーバーのcron、GitHub Actionsのような自動実行、ブラウザのないコンテナなどです。関連する手順はheadlessモード×cronのガイドにもあります。
トークンの発行と設定の手順
- ブラウザが使える自分のPCで発行する：次のコマンドを実行します。
/loginと同じブラウザでの認可画面が開きます。
claude setup-token- ブラウザで承認する：承認すると、ターミナルにトークンが表示されます。保存はされないので、この場でコピーします。
- 環境変数に設定する：スクリプトを動かす場所で、
CLAUDE_CODE_OAUTH_TOKENにトークンを入れます。
公式ドキュメントのmacOS・Linux・WSLの書き方は次のとおりです（your-tokenの部分に、発行されたトークンを入れます）。
export CLAUDE_CODE_OAUTH_TOKEN=your-tokenWindows PowerShellなら$env:CLAUDE_CODE_OAUTH_TOKEN = "your-token"、コマンドプロンプトならset CLAUDE_CODE_OAUTH_TOKEN=your-tokenと書きます。
トークンの扱いに注意
トークンは、あなたのClaudeサブスクリプションで使える鍵です。記事やGitのリポジトリ、チャットには貼らないでください。CIならシークレットの機能に登録し、サーバーなら自分だけが読めるファイルに置くのが基本です。
cronやスクリプトで使うときの書き方と、確認方法
環境変数を設定したら、あとは通常どおりclaude -pで動かせます。cronは普段のシェルの設定を読まないのが一般的なので、cronの行かスクリプトの先頭で、変数を渡すようにしてください。たとえば、スクリプトの冒頭に環境変数を読み込む処理を置く形です。
#!/bin/bash
# トークンを書いたファイル（自分だけ読める権限にしておく）を読み込む
source "$HOME/.claude-token.env"
claude -p "昨日のコミットを要約して" --allowedTools "Read"認証が通っているかは、claude auth statusで確認できます。公式のCLIリファレンスでは、認証の状態をJSONで表示し、ログインしていれば終了コード0、していなければ1を返すと説明されています。JSONのauthMethodという項目は、none、claude.ai、oauth_token、api_key、api_key_helper、third_partyのどれかです。トークンで認証されていれば、oauth_tokenが出る想定です。実際の出力は、この記事では確認していません。
人が読みやすい形にしたいときは、claude auth status --textを使います。
このトークンでできないこと・使えない場面
公式ドキュメントには、次の制限が書かれています。
- モデルへのリクエストだけできる。Remote Controlのセッションは作れず、claude.aiのコネクタも取得できない
- 自分でローカルに設定したMCPサーバーは、そのまま使える
- –bareを付けると、このトークンは読まれない。bareモードでは、OAuthの認証情報やキーチェーンを読まないため
つまり、Googleカレンダーのようなclaude.aiのコネクタをスクリプトから使いたい場合は、このトークンでは動きません。ローカルのMCPサーバーを設定して使う形になります。
–bareを付けたいとき
公式のheadlessのページでは、CIやスクリプトでは--bareの使用が勧められています（今後-pの既定になる予定とも書かれています）。ただしbareモードはサブスクリプションのログインを使わないため、ANTHROPIC_API_KEYか、apiKeyHelperで認証する必要があります。
| やりたいこと | 認証の方法 |
|---|---|
| サブスクリプションで、–bareなしで動かす | CLAUDE_CODE_OAUTH_TOKEN |
| –bareで、毎回同じ状態で動かす | ANTHROPIC_API_KEY（Claude Consoleで作成）かapiKeyHelper |
–bareなしの-pは、作業フォルダの設定やMCPサーバー、フックを読み込みます。自分のPCやサーバーで、自分のリポジトリだけを動かす用途なら、これで十分です。
うまくいかないときの確認点
- Not logged inで止まる：環境変数がそのシェルやcronに渡っているかを確認する。
claude auth statusを、同じ環境で実行してみる - /loginを実行したら状態が変わった：公式ドキュメントによると、変数が設定されたまま
/loginを実行すると、現在のセッションは新しいログインに切り替わる。以降のセッションでもそのログインを使いたいときは、シェルのプロファイルや設定ファイルから変数を消す - –bareで認証できない：上の表のとおり、bareではトークンは読まれない。APIキーを使う
- 組織の制限がある：公式ドキュメントによると、
setup-tokenはforceLoginMethodだけを強制し、forceLoginOrgUUIDは確認しない。組織の管理者が設定している場合は、管理者に確認する
ログインの期限について（変更履歴にある内容）
Claude CodeのCHANGELOGのv2.1.318には、保存されたclaude.aiのログインが切れる日付が、claude auth statusのJSON（loginExpiresAt）とclaude -pのJSON結果に追加された、とあります。claude -pの通常のテキスト出力では、ログインが切れる10日前から、標準エラーに1行の警告が出るとも書かれています。ただし、この内容は公式ドキュメントのページでは確認できませんでした。また、これは/loginで保存されたログインの話で、setup-tokenで作った1年のトークンにも同じ表示が出るのかは、確認できていません。
よくある質問（FAQ）
Q. APIキーとの違いは何ですか？
setup-tokenのトークンは、Claudeのサブスクリプションの枠で動きます。APIキーはClaude Consoleで作り、API利用の課金になります。–bareを使うなら、APIキーが必要です。
Q. トークンは何度でも発行できますか？
公式ドキュメントに、回数の上限は書かれていませんでした。失効や取り消しの方法も、今回確認したページには見つかりませんでした。漏らしてしまった場合は、Claudeのアカウント側の設定を確認してください。
Q. 1年たつと、どうなりますか？
1年のトークンなので、期限が切れたら再発行が必要になります。発行した日をメモしておくと安心です。
Q. 無料プランでも使えますか？
公式ドキュメントでは、Pro、Max、Ultra、Team、Enterpriseのプランが必要とされています。
まとめ
claude setup-tokenは、ブラウザのない環境用に、1年間使えるトークンを発行する- 発行されたトークンは保存されない。コピーして
CLAUDE_CODE_OAUTH_TOKENに設定する - モデルへのリクエストだけに使える。Remote Controlやclaude.aiのコネクタは使えない
--bareではトークンが読まれない。bareにするならANTHROPIC_API_KEYを使う- トークンは、記事やリポジトリに貼らず、シークレットとして管理する
まずは自分のPCでclaude setup-tokenを試し、claude auth statusで認証の状態が変わるかを見るところから始めてみてください。
