Claude Code --bareモードで認証エラーにハマった話と回避策

はじめに

Claude Code には -p（非対話モード）向けに、hooks・skills・plugins・MCP servers・auto memory・CLAUDE.md の自動発見をすべてスキップして起動を高速化する --bare フラグがあります。公式ドキュメントでは「スクリプト実行・SDK呼び出しの推奨モードで、将来的には -p のデフォルトになる予定」と明記されている、いわば「これからの標準」の機能です¹。

筆者は Claude Code のクラウド実行環境（OAuthベースの認証で動いている環境）で claude --bare -p を実際に動かしてみたところ、想定していなかった 認証エラー に遭遇しました。本記事では、その実測ログと原因、回避策をまとめます。

この記事で学べること

• --bare フラグが具体的に何をスキップするか
• OAuth認証環境で --bare を使うと何が起きるか（実機ログ付き）
• 回避策（ANTHROPIC_API_KEY / apiKeyHelper）
• --bare がCI・自動化スクリプトで推奨される理由

前提環境

• Claude Code: v2.1.198
• 実行環境: Claude Cloud（OAuthベース認証、ANTHROPIC_API_KEY 未設定）

TL;DR

• --bare は hooks・skills・plugins・MCP servers・auto memory・CLAUDE.md の自動発見をスキップする軽量モード
• OAuth・keychainからの認証情報読み取りも同時にスキップされる（公式ドキュメントに明記）
• OAuthログインで動いている環境（Claude Cloud のスケジュール実行等）でそのまま --bare を使うと Authentication error になる
• 回避には ANTHROPIC_API_KEY 環境変数、または --settings 経由の apiKeyHelper が必要
• Bedrock / Vertex / Foundry を使っている場合は各プロバイダの通常の認証情報がそのまま使われる

背景・課題

claude -p は素の非対話モードでも、対話セッションと同じコンテキスト（作業ディレクトリの .claude/ や ~/.claude の設定）を読み込みます。チームメイトの ~/.claude に置かれた hook や、プロジェクトの .mcp.json に登録された MCPサーバーまで一緒に読み込まれるため、実行するマシンによって挙動が変わってしまうことがあります¹。

--bare はこれを避けるためのフラグで、公式ドキュメントには次のように明記されています。

Bare mode is useful for CI and scripts where you need the same result on every machine. A hook in a teammate's ~/.claude or an MCP server in the project's .mcp.json won't run, because bare mode never reads them.¹

やったこと

ステップ1: バージョン確認

まず実行環境の Claude Code バージョンを確認しました。

$ claude --version
2.1.198 (Claude Code)

ステップ2: --bare -p を実際に動かす

--bare を付けて簡単なプロンプトを非対話実行してみます。

$ claude --bare -p "1+1は？"
Ignoring 2 permissions.allow entries from .claude/settings.json: this workspace has not been trusted...
Authentication error · This may be a temporary network issue, please try again

.claude/settings.json の permissions が無視される旨のメッセージに続き、認証エラー が返ってきました。この実行環境は通常の claude -p（--bare なし）ではOAuthベースの認証で問題なく動作するため、--bare を付けたことで認証の経路が変わったことがわかります。

ステップ3: 原因を公式ドキュメントで確認

公式ドキュメントの bare mode の項目を確認すると、原因が明記されていました。

Bare mode skips OAuth and keychain reads. Anthropic authentication must come from ANTHROPIC_API_KEY or an apiKeyHelper in the JSON passed to --settings. Bedrock, Vertex, and Foundry use their usual provider credentials.¹

つまり --bare は hooks や CLAUDE.md だけでなく、OAuthトークンやOSキーチェーンからの認証情報読み取りも一切スキップする 仕様です。この実行環境の認証変数を確認したところ ANTHROPIC_API_KEY は未設定で、OAuthログイン（Claude Cloud のスケジュール実行）のみで稼働していました。--bare がOAuth読み取りを行わない以上、認証情報が見つからずエラーになるのは仕様どおりの挙動でした。

回避策

回避策1: ANTHROPIC_API_KEY を渡す

最も単純な方法は、環境変数で直接APIキーを渡すことです。

ANTHROPIC_API_KEY="sk-ant-..." claude --bare -p "1+1は？"

回避策2: apiKeyHelper を --settings 経由で渡す

APIキーをハードコードしたくない場合は、キー取得コマンドを返す apiKeyHelper を settings JSON に指定します。

claude --bare -p "1+1は？" \
  --settings '{"apiKeyHelper": "/path/to/get-api-key.sh"}'

get-api-key.sh は標準出力にAPIキーを返すだけのスクリプトで構いません。CI/CDでシークレットマネージャーからキーを取得して渡す運用と相性が良い方法です。

回避策3: Bedrock / Vertex / Foundry を使う

Amazon Bedrock・Google Vertex AI・Microsoft Foundry 経由でClaudeを利用している場合は、--bare でもこれらのプロバイダの通常の認証情報（IAMロール等）がそのまま使われるため、追加対応は不要です¹。

なぜこの設計なのか

--bare は「どのマシンで実行しても同じ結果になること」を目的としたフラグです。OAuthトークンやOSキーチェーンはマシンごと・ユーザーごとに状態が異なるため、これらを読み込んでしまうと「手元では動くがCIでは動かない」「Aさんの環境では動くがBさんの環境では動かない」といった再現性の問題が起きます。--bare が認証もスキップして ANTHROPIC_API_KEY 明示指定を要求するのは、hooks や CLAUDE.md の自動発見をスキップするのと同じ「暗黙の環境依存を断ち切る」設計思想の一部だと考えられます。

公式ドキュメントは --bare を「スクリプト・SDK呼び出しの推奨モードであり、将来的には -p のデフォルトになる」としています¹。現時点で claude -p をCIやスケジュール実行に組み込んでいる場合、OAuth認証のまま --bare 化すると同じ認証エラーを踏むことになるため、移行前に ANTHROPIC_API_KEY の準備が必要になる点は覚えておくとよさそうです。

--bare がスキップする他の項目

認証以外にも、--bare は次を自動発見しません。必要なら明示的にフラグで渡す必要があります¹。

読み込みたいもの	渡すフラグ
システムプロンプトの追加	--append-system-prompt / --append-system-prompt-file
設定	--settings <file-or-json>
MCPサーバー	--mcp-config <file-or-json>
カスタムエージェント	--agents <json>
プラグイン	--plugin-dir <path> / --plugin-url <url>

--bare モードでも Bash・ファイル読み取り・ファイル編集の3ツールは利用できます¹。

著者視点の発見ポイント

実際に試すまでは「--bare は起動が速くなるだけの軽量フラグ」という理解だったが、実機で認証エラーを踏んだことで「hooks や CLAUDE.md と同列で、OAuth認証も『暗黙に読み込まれる環境依存の一つ』として扱われている」という設計の一貫性に気づけた。Claude Cloud のスケジュール実行のようにOAuthで動いている運用では、--bare への移行は「起動が速くなる」というメリットだけでなく「APIキー管理をどう用意するか」というコスト込みで判断する必要がある。

まとめ

• --bare は hooks・skills・plugins・MCP servers・auto memory・CLAUDE.md に加えて OAuth/keychain認証も自動発見の対象外
• OAuthログイン環境でそのまま使うと Authentication error になる（実機で確認済み）
• 回避には ANTHROPIC_API_KEY または apiKeyHelper が必要（Bedrock/Vertex/Foundryは対象外）
• 将来 -p のデフォルトになる予定のため、OAuth運用のスクリプトは早めにAPIキー移行を検討する価値がある

参考リンク

1. Run Claude Code programmatically - Claude Code Docs — "Start faster with bare mode" セクションで引用 ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸