Claude Code Remote Trigger の API エラーを体系的にデバッグする手順

Claude Code のリモートトリガーを API 経由で操作する際、特定のアクションだけでエラーが返ることがあります。この記事では、原因を体系的に切り分けてデバッグする手順を解説します。

Step 1: アクション別の動作切り分け

リモートトリガーには get・update・run の 3 つのアクションがあります。まずどのアクションでエラーが起きるかを特定しましょう。

# 1. トリガー情報の取得（get）
claude-code-tool RemoteTrigger action=get trigger_id=$TRIGGER_ID

# 2. トリガーの更新（update）
claude-code-tool RemoteTrigger action=update trigger_id=$TRIGGER_ID body='{}'

# 3. 手動実行（run）
claude-code-tool RemoteTrigger action=run trigger_id=$TRIGGER_ID

ここで重要なのは、同じ trigger_id を 3 つのアクションに渡して結果を比較することです。get と update が成功して run だけ失敗するなら、ID やトークンの問題ではなく run アクション固有の原因だと切り分けられます。

Step 2: リクエスト形式のバリエーション検証

アクション固有のエラーが確認できたら、リクエストの形式を変えて試します。

// パターン A: 基本形式
{ action: "run", trigger_id: "trig_XXXXX" }

// パターン B: 空の body を追加
{ action: "run", trigger_id: "trig_XXXXX", body: {} }

// パターン C: body 内に trigger_id を重複
{ action: "run", trigger_id: "trig_XXXXX", body: { trigger_id: "trig_XXXXX" } }

// パターン D: parameters を追加
{ action: "run", trigger_id: "trig_XXXXX", parameters: { immediate: true } }

すべてのパターンで同じエラーが出る場合、クライアント側のリクエスト形式ではなくサーバー側の実装に原因がある可能性が高いと判断できます。

Step 3: ツール定義（JSONSchema）との照合

Claude Code の RemoteTrigger ツールは JSONSchema で入力形式が定義されています。スキーマ上 trigger_id が required に含まれていても、サーバー側が run だけ異なるパスでパラメータを受け取る場合があります。スキーマと実際の動作にズレがあれば、公式ドキュメントやリリースノートで仕様変更を確認しましょう。

Step 4: 回避策の実装

API 経由の run が使えない場合でも、運用を止めずに対処できます。

回避策	メリット	デメリット
Web UI で手動実行	確実に動作する	自動化できない
スケジュール頻度を上げる	追加実装不要	即時実行はできない
GitHub Actions で代替	CI/CD に統合可能	ワークフロー設計が必要

Web UI からの手動実行は claude.ai/code/scheduled にアクセスし、対象トリガーの「Run Now」ボタンをクリックするだけです。

GitHub Actions で代替する場合は workflow_dispatch + repository_dispatch で同等の即時実行を実現できます。

実際のデバッグ事例

あるプロジェクトで、リモートトリガー（ID: trig_XXXXX）の run アクションだけが 400 Bad Request を返す事象が発生しました。

{
  "error": {
    "type": "invalid_request_error",
    "message": "trigger_id: Field required"
  }
}

Step 1 の切り分けで get・update は正常動作を確認。Step 2 で 4 パターンすべてが同じエラー。Step 3 でスキーマ上は trigger_id が必須フィールドであることを確認しました。

結論として、run エンドポイントがトップレベルの trigger_id ではなく body 内から値を読み取るサーバー側の設計差異が原因と推定されました。自動スケジュール実行は正常に動作していたため、スケジュール頻度の調整と Web UI の手動実行を組み合わせて運用を継続しています。

まとめ

リモートトリガーの API エラーは、アクション別の動作比較から始めることで効率的に原因を絞り込めます。API の仕様変更や不整合はユーザー側では修正できないため、回避策を複数用意しておくことが安定運用のポイントです。最新の仕様は Claude Code 公式ドキュメント や スケジュールタスクのドキュメント を参照してください。

関連記事

• Claude Managed Agents 完全ガイド — リモートトリガーの基盤となる Managed Agents の概念と実践
• Claude Code Hooks・カスタムコマンドで開発品質を自動化する — ローカル環境での Claude Code フック・コマンドによる自動化