2
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Claude Codeの--fallback-modelで無人ジョブを止めない:混雑・利用上限・終了コードの3つの落とし穴と実装

2
Posted at

はじめに:朝起きたらジョブが全部落ちていた

当社(合同会社ジョインクラス)は、記事作成・朝のレポート・各部署の作業など30以上のジョブを launchd から claude -p で無人実行しています。

2026年9月、朝のログを見ると複数のジョブが同じ時間帯にまとめて失敗していました。原因はコードのバグではありません。主モデルが混雑していて、応答を返せなかっただけです。人が見ていれば「少し待ってもう一度」で済みますが、無人ジョブはそのまま終わります。

この記事では、僕がこの問題に対応した方法を、実際に動いている共通ラッパーのコードと一緒に紹介します。

  • --fallback-model で混雑時に別モデルで最後まで動かす
  • 利用上限に当たったら、無駄に再実行せず一定時間待つ
  • パイプを通すと失敗が rc=0 になる問題の直し方

1. まず1行:--fallback-model を付ける

Claude Code の print モード(-p)では、主モデルが過負荷のときに切り替える先のモデルを --fallback-model で指定できます。

claude -p "今日のログを要約して" \
  --model opus \
  --fallback-model sonnet

主モデルが混雑で使えないときは、エラーで終わらずに sonnet で処理を続けます。品質が少し落ちても、ジョブが止まるよりはずっと良いというのが無人運用での判断です。

落とし穴:主モデルとフォールバック先を同じにしない

--model sonnet のジョブに --fallback-model sonnet を指定しても意味がありません(同じモデルを指定するとエラーになるバージョンもあります)。当社では「主モデルが sonnet なら haiku、それ以外なら sonnet」と自動で決めています(後述のコード43行目)。

2. 実装:全ジョブ共通のラッパー claude_run

1ジョブずつフラグを書くと、どこかで必ず付け忘れます。実際、最初は9スクリプト・12箇所に手で入れて回りました。今は共通の関数に1本化しています。以下は当社で動いている .company/scripts/lib/claude-run.sh です(社内画面への通知部分だけ省いています)。

lib/claude-run.sh
#!/bin/bash
# claude を無人実行するときの共通ラッパー
_CLAUDE_RUN_LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

claude_run() {
  local label="$1"; shift
  local marker="$_CLAUDE_RUN_LIB/../logs/.usage-limited"

  # 利用上限に当たってから60分は呼ばない
  if [ -f "$marker" ] && [ $(( $(date +%s) - $(stat -f %m "$marker") )) -lt 3600 ]; then
    echo "(Claudeの利用上限に当たった直後のため見送り: $(cat "$marker"))"
    return 0
  fi

  local session
  session=$(uuidgen | tr '[:upper:]' '[:lower:]')
  claude --output-format json \
         --session-id "$session" \
         --no-session-persistence \
         ${CLAUDE_MODEL:+--model "$CLAUDE_MODEL"} \
         --fallback-model "$([ "${CLAUDE_MODEL:-opus}" = sonnet ] && echo haiku || echo sonnet)" \
         --max-budget-usd 3 \
         "$@" 2>>"$_CLAUDE_RUN_LIB/../logs/claude-run.err" \
    | python3 "$_CLAUDE_RUN_LIB/record-cost.py" "$label"

  # パイプの $? は python 側の値になるので、claude 側の終了コードを優先する
  local status=("${PIPESTATUS[@]}")
  local rc=${status[0]}
  [ "$rc" -eq 0 ] && rc=${status[1]}
  [ "$rc" -ne 0 ] && echo "$(date '+%F %T') [$label] rc=$rc (claude=${status[0]} record-cost=${status[1]})" \
    >>"$_CLAUDE_RUN_LIB/../logs/claude-run.err"
  return $rc
}

各ジョブからはこう呼びます。claude -p をそのまま置き換えられます。

source /path/to/.company/scripts/lib/claude-run.sh
RESULT=$(claude_run dept-dev --effort low -p "backlog.md の未着手を1件進めて")

設計のポイントは次のとおりです。

フラグ 目的
--fallback-model 混雑時に落ちずに最後まで動かす
--max-budget-usd 3 ループの暴走だけを止める。普段は当たらない値にする
--no-session-persistence 無人ジョブは再開しないので会話記録を残さない(1日約200MB溜まっていた)
--output-format json 応答本文・is_error・total_cost_usd を後ろの処理で読むため

3. フォールバックでは防げないもの:利用上限

ここが一番の落とし穴でした。--fallback-model が効くのはモデルの混雑です。アカウントの利用上限(セッション上限・週の上限)に当たると、どのモデルに切り替えても動きません。

2026年11月15〜16日、当社ではこれが起きました。毎分起動するジョブが、上限のエラーを受けて4秒で終わり、また次の分に起動する。これを約1,000回繰り返していました。上限の判定に使う正規表現が「You've hit your weekly limit」という文言に当てはまらなかったのが原因です。

今は、--output-format json の結果を受け取る record-cost.py で上限エラーを見つけ、印のファイルを置いています。

lib/record-cost.py(抜粋)
text = str(d.get("result") or "")
if d.get("is_error") and re.search(
        r"usage limit|rate limit|limit reached|hit your .*limit|上限", text, re.I):
    marker = DEFAULT_COST_FILE.parent / "logs" / ".usage-limited"
    marker.write_text(f"{datetime.datetime.now():%Y-%m-%d %H:%M} {label}", encoding="utf-8")
    notify_slack(f":hourglass: Claudeの利用上限に当たりました(ジョブ: {label})。60分見送ります。")

claude_run は、この印ファイルの更新時刻が60分以内なら claude を呼ばずに終わります。つまり役割を分けています。

  • 混雑 → --fallback-model で別モデルに切り替えて続ける
  • 利用上限 → 呼ばずに待つ(再実行しても失敗が増えるだけ)

なお、見送りのときに return 0 にしているのは、当社のジョブ監視が「失敗したら再実行する」作りだからです。ここで失敗を返すと、監視が再実行してまた失敗を増やします。

4. 落とし穴:パイプを通すと失敗が成功に見える

claude ... | python3 record-cost.py のように書くと、$? は最後のコマンド(python)の終了コードになります。claude が失敗しても、python が正常に終われば rc=0 です。当社では11月11日まで、これで失敗が監視に引っかかっていませんでした。

対応は PIPESTATUS をすぐに配列へ保存することです。他のコマンドを1つでも挟むと値が上書きされます。

cmd_a | cmd_b
local status=("${PIPESTATUS[@]}")   # 必ず直後に保存する
local rc=${status[0]}               # 先に claude 側を見る
[ "$rc" -eq 0 ] && rc=${status[1]}  # claude が成功なら python 側を見る

set -o pipefail でも同じことができますが、ラッパーを source する側のスクリプト全体の動きが変わるので、当社では関数の中だけで済む PIPESTATUS にしました。

5. 確認のしかた

設定したつもりで効いていない、という事故を防ぐために、次の3つを確かめます。

① フラグが全ジョブに入っているか

# claude_run を通さずに claude -p を直接呼んでいる箇所を探す
grep -rn "claude -p\|claude --print" .company/scripts --include="*.sh" | grep -v "lib/claude-run.sh"

何も出なければ、全ジョブがラッパーを通っています。

② 上限の見送りが動くか

echo "test" > .company/scripts/logs/.usage-limited
source .company/scripts/lib/claude-run.sh
claude_run test -p "1+1は?"   # →「利用上限に当たった直後のため見送り」と出れば OK
rm .company/scripts/logs/.usage-limited

③ 失敗が rc に出るか

claude_run test -p "hi" --model not-exist-model; echo "rc=$?"
# rc=0 以外なら OK。claude-run.err に claude=… record-cost=… が残る

②③は claude を実際に呼ばない、またはすぐ失敗するので、利用枠をほとんど使いません。

まとめ

起きること 対策
主モデルの混雑 --fallback-model(主モデルと違うものを自動で選ぶ)
利用上限 エラー文を判定して印を置き、60分は呼ばない
ループの暴走 --max-budget-usd を普段は当たらない値で
失敗が rc=0 になる PIPESTATUS を直後に保存
フラグの付け忘れ 共通ラッパーに1本化し、grep で確かめる

一人で会社を回していると、夜中に止まったジョブを直す人はいません。「落ちない」より「落ちても自分で元に戻る」「落ちるときは無駄に何度も失敗しない」ほうが大事だと、この2ヶ月で実感しました。--fallback-model はその一番手前の、1行で入れられる対策です。

参考:自動化の全体像をまとめた本

launchd・Hooks・無人実行の作り方をまとめて知りたい方は、『Claude Code 全自動化バイブル』で詳しく書いています。

書籍一覧: https://zenn.dev/joinclass?tab=books
社内で同じような仕組みを作りたいが手が回らない場合は、合同会社ジョインクラスで中小企業向けの業務システム開発・DX支援(国内)を受けています。
👉 業務システム・DXの無料相談

2
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
2
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?