AIコーディングガイド

Claude Code で長いコマンドがタイムアウトするときの BASH_DEFAULT_TIMEOUT_MS と出力上限の設定

Claude Code 公開:

Claude Code の Bash ツールが 2 分で打ち切られる、出力が途中で切れる問題を BASH_DEFAULT_TIMEOUT_MS・BASH_MAX_TIMEOUT_MS・bashOutputMaxChars で調整する方法と既定値、設定場所を解説します。

検証日 2026年9月10日 仕様変更が早い分野です。最新の公式ドキュメントも併せてご確認ください。
#Claude Code#Bash#タイムアウト#環境変数#settings.json
目次
  1. タイムアウトの仕組み
  2. 出力の上限
  3. settings.json にまとめて書く
  4. 作業ディレクトリが戻らないとき
  5. まとめ

テストスイートやビルドを Claude に実行させると、2 分で「タイムアウト」になって結果を見てもらえない。あるいは長いログの後半が切れて、Claude が肝心のエラーを見落とす。どちらも Claude Code の Bash ツールに既定の上限があるために起きます。

結論として、タイムアウトは BASH_DEFAULT_TIMEOUT_MS と BASH_MAX_TIMEOUT_MS、出力の上限は bashOutputMaxChars(または BASH_MAX_OUTPUT_LENGTH)で調整します。settings.json の env に書けば毎回付ける必要はありません。

KEY POINT

この記事で分かること

  • タイムアウトを決める 2 つの環境変数と、その関係
  • 出力上限を決める設定キーと環境変数、どちらが優先されるか
  • settings.json への書き方と、作業ディレクトリが戻らない問題の対処

タイムアウトの仕組み

Bash ツールには「既定のタイムアウト」と「モデルが指定できる上限」の 2 つがあります。

変数既定意味
BASH_DEFAULT_TIMEOUT_MS120000(2 分)モデルがタイムアウトを指定しなかったときの値
BASH_MAX_TIMEOUT_MS600000(10 分)モデルが指定できるタイムアウトの上限

実際の上限は BASH_MAX_TIMEOUT_MS と BASH_DEFAULT_TIMEOUT_MS の 大きい方 です。既定値を 10 分より大きくすると、上限もそれに合わせて広がります。

これらの数値は 2e3 のような指数表記や 64_000 のような桁区切りも受け付けます。

用語解説

ミリ秒指定: これらの変数はすべてミリ秒です。5 分なら 300000、30 分なら 1800000 と書きます。単位を間違えると「一瞬でタイムアウトする」状態になります。

出力の上限

コマンドが成功したとき、Claude が読み返せる出力には文字数の上限があります。上限を超えると、Claude Code は出力をファイルに保存し、Claude には短いプレビューとファイルのパスだけを渡します。Claude はそのファイルを読めば全文を見られますが、自動で全部読むわけではありません。

設定既定備考
bashOutputMaxChars(settings.json)未設定のとき 30,000 文字4000〜128000 の範囲にクランプされる。v2.1.261 以降
BASH_MAX_OUTPUT_LENGTH(環境変数)30000最大 150000。bashOutputMaxChars を設定するとこの変数は無視される

冗長なビルドログや、テストスイート全体のログをファイルを開かずに読ませたい場合は、bashOutputMaxChars を上げます。

{
  "bashOutputMaxChars": 100000
}

settings.json にまとめて書く

環境変数は settings.json の env キーに書くと、起動方法に関係なくすべてのセッションとサブプロセスに適用されます。シェルで同名の変数を設定していても settings 側が優先されます。

{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "300000",
    "BASH_MAX_TIMEOUT_MS": "1800000"
  },
  "bashOutputMaxChars": 100000
}

チーム共通で必要なら .claude/settings.json、自分だけなら ~/.claude/settings.json か .claude/settings.local.json に書きます。ファイルの使い分けは settings.local.json と settings.json の違い を参照してください。

タイムアウトを伸ばす前に、バックグラウンド実行を検討する

開発サーバーや監視系のコマンドは、タイムアウトを伸ばしても終わらないので意味がありません。そうしたコマンドは Claude にバックグラウンドで実行させ、必要なときにログを読ませる方が確実です。タイムアウトの延長は「必ず終わるが時間がかかる」テストやビルドに限ってください。

作業ディレクトリが戻らないとき

cd を含むコマンドを実行した後、以降のコマンドが別のディレクトリで実行されて失敗することがあります。CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR を設定すると、メインセッションの Bash や PowerShell の各コマンドの後に元の作業ディレクトリへ戻ります。

{
  "env": {
    "CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR": "1"
  }
}

長いコマンドの出力はコンテキストも消費します。出力上限を上げるほど 1 回のコマンドで消費するトークンも増えるので、コンテキスト管理 の観点では「必要なときだけ上げる」のが無難です。実行を許可するコマンドの範囲は permissions の設計 で決めます。

まとめ

  • 既定のタイムアウトは 2 分(BASH_DEFAULT_TIMEOUT_MS)、モデルが指定できる上限は 10 分(BASH_MAX_TIMEOUT_MS)。実効上限は両者の大きい方
  • 出力は既定 30,000 文字まで。超えた分はファイルに保存される。bashOutputMaxChars(4,000〜128,000)で調整し、設定すると BASH_MAX_OUTPUT_LENGTH は無視される
  • settings.json の env に書けばシェルより優先され、毎回付けなくてよい
  • 終わらないコマンドはタイムアウト延長ではなくバックグラウンド実行にする
  • cd でディレクトリがずれるなら CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR

よくある質問

Bash ツールの既定のタイムアウトは何分ですか?
既定は 120000 ミリ秒(2 分)です。BASH_DEFAULT_TIMEOUT_MS で変更できます。
モデルが自分で長いタイムアウトを指定することはできますか?
できますが上限があります。上限は BASH_MAX_TIMEOUT_MS(既定 10 分)と BASH_DEFAULT_TIMEOUT_MS の大きい方です。
コマンドの出力が長いと途中で切れるのはなぜですか?
Claude が受け取る出力には文字数の上限があるためです。既定は 30,000 文字で、超えた分はファイルに保存され、Claude にはプレビューとファイルパスが渡されます。

参考にした一次情報

この記事は公式ドキュメントを基に AI が下書きを作成し、運営者が内容を確認して公開しています。誤りを見つけた場合は お問い合わせからお知らせください。

関連記事