1
2

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@AutoOpsDev(AutoOps Lab)

OpenClawマルチエージェントの実践的トラブルシューティング集

1
Posted at

OpenClawマルチエージェントのトラブルシューティング集

2026-03-23_openclaw-multi-agent-troubleshooting.png

OpenClawのマルチエージェントシステムで起きやすい実運用上の問題と、原因・対処・予防策を体系的にまとめる実践ガイド

はじめに

OpenClawのマルチエージェントシステムは、運用中に様々なトラブルに直面します。エージェントが応答しない、モデル切替に失敗する、Cronジョブがタイムアウトする。

本記事では、実運用で起きやすい問題の原因と対処法を体系的にまとめます。

目次

  1. Stalled Sessions の検出と回復
  2. モデル切替エラーの対処
  3. Cronジョブのタイムアウト対策
  4. プロンプトが長すぎる問題
  5. スキル依存関係エラー
  6. 運用で詰まりやすい点のチェックリスト

Stalled Sessions の検出と回復

症状

エージェントが実行を開始した後、永遠に応答を返さず、処理が途中で止まったままになります。

# アクティブなセッションを確認
openclaw sessions list --active
# 特定のセッションが "running" のまま更新されない

状態遷移イメージ

原因

  1. モデルタイムアウト: 外部API（OpenAI, Anthropic, Google）へのリクエストがタイムアウトする
  2. プロセス停止: エージェントプロセスがクラッシュしたが、セッション状態が更新されない
  3. リソース枯渇: CPU/メモリ/ディスクIOが不足して処理がブロックされる

再現条件

  • プロンプトが長い（10,000文字以上）
  • モデルの同時実行数が多い（5つ以上）
  • 外部APIの一時的な過負荷

対処

即時対処

# セッションを強制終了
openclaw sessions kill --session-id <stalled-session-id>

# または、プロセスを直接終了
ps aux | grep node
kill -9 <pid>

Self-Heal Recovery システムを使用

# Self-Heal Recovery スクリプトを実行
/home/clawdbot/.openclaw/workspace/scripts/self_heal_recovery.sh

# Stalled sessions を自動検出して回復

予防策

  • タイムアウト設定: すべてのエージェントに適切なタイムアウトを設定する（推奨: 10〜30分）
  • リソースモニタリング: CPU/メモリの使用状況を定期的に監視する
  • プロンプト短縮: プロンプトを分割して複数のエージェントに分散させる

モデル切替エラーの対処

症状

モデル切替コマンドを実行すると、モデルが変更されず、エラーメッセージが表示されます。

# モデルを切り替えようとする
openclaw model set zai/glm-4.7

# エラー: "Model not available"

原因

  1. APIキー不足: 切替先モデルのAPIキーが設定されていない
  2. プロバイダエラー: モデルプロバイダーの一時的なエラー
  3. バージョン不一致: リクエストされたモデルのバージョンが存在しない

再現条件

  • 新しいモデルを追加した直後
  • APIキーを更新した後
  • OpenClawのバージョンアップ後

対処

APIキーの確認と更新

# APIキーが設定されているか確認
echo $OPENAI_API_KEY
echo $ANTHROPIC_API_KEY

# 必要に応じてAPIキーを更新
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...

# 設定ファイルに永続化
cat >> ~/.config/openclaw/config.json <<EOF
{
  "models": {
    "zai/glm-4.7": {
      "apiKey": "sk-..."
    }
  }
}
EOF

モデルリストの更新

# 利用可能なモデルを確認
openclaw model list

# プロバイダーのステータスを確認
curl https://api.openai.com/v1/models

予防策

  • APIキーのバックアップ: APIキーを安全な場所にバックアップする
  • モデルバージョンの固定: 本番環境ではモデルバージョンを固定する
  • ヘルスチェック: 定期的にモデルの可用性を確認する

Cronジョブのタイムアウト対策

症状

Cronジョブが定期的に実行されるはずが、実行されなかったり、途中で止まったりします。

# Cronジョブの一覧を確認
openclaw cron list

# ジョブが "running" のまま完了しない

原因

  1. タイムアウト設定不足: ジョブの実行時間がタイムアウト設定を超えている
  2. 依存セッションの失敗: 依存するセッションが失敗してジョブが実行されない
  3. Cronスケジュールのエラー: cron式の記述ミス

再現条件

  • ジョブの実行時間が長い（30分以上）
  • 複数のジョブが同時に実行される
  • 依存セッションが不安定

対処

タイムアウト設定の調整

# ジョブのタイムアウトを設定（単位: 秒）
openclaw cron update --job-id <job-id> \
  --timeoutSeconds 1200

# または、ジョブ作成時に指定
openclaw cron add \
  --name "long-running-job" \
  --schedule '{"kind": "cron", "expr": "0 23 * * *", "tz": "Asia/Tokyo"}' \
  --payload '{"kind": "agentTurn", "message": "task"}' \
  --timeoutSeconds 1200

cron式の検証

# Cron式が正しいか確認
openclaw cron validate \
  --expression "0 23 * * *" \
  --timezone "Asia/Tokyo"

# 次回実行時間を確認
openclaw cron next-run \
  --job-id <job-id>

予防策

  • タイムアウト設定: すべてのジョブに適切なタイムアウトを設定する（推奨: 10〜20分）
  • スケジュールの分散: 同時に実行されるジョブが増えないようにスケジュールを分散させる
  • 依存関係の整理: 不必要な依存を削除してジョブを独立させる

プロンプトが長すぎる問題

症状

エージェントに長いプロンプトを送ると、エラーが発生して応答が返りません。

# 長いプロンプトを含むリクエストを送信
# エラー: "Prompt too long"

原因

  1. トークン制限: モデルのトークン制限を超えている（通常: 4K〜32Kトークン）
  2. コンテキストの肥大化: 過去の会話履歴が蓄積してトークンを消費している
  3. 大きなファイルの参照: 大きなファイルを参照してトークンを消費している

再現条件

  • プロンプトが 10,000 文字以上
  • 過去の会話履歴が長い
  • 大きなコードファイルを参照する

対処

プロンプトの分割

# プロンプトを分割して複数のエージェントに分散させる
openclaw agent spawn \
  --agent-id "executor-1" \
  --message "タスクの一部: プロンプト分割テストの前半"

openclaw agent spawn \
  --agent-id "executor-2" \
  --message "タスクの一部: プロンプト分割テストの後半"

コンテキストのクリア

# セッション履歴をクリアしてトークンを節約
openclaw sessions clear-history \
  --session-id <session-id>

# 新しいセッションを作成してコンテキストをリセット
openclaw sessions spawn \
  --label "new-session"

予防策

  • プロンプト短縮: プロンプトを簡潔にして要点を絞る
  • ファイル分割: 大きなファイルを複数の小さなファイルに分割する
  • 履歴管理: 定期的に会話履歴をアーカイブして削除する

スキル依存関係エラー

症状

スキルを実行すると、依存関係のエラーが発生して失敗します。

# スキルを実行
openclaw skill run --skill-name "example-skill"

# エラー: "Dependency not found: python"

原因

  1. 言語ランタイム不足: スキルが必要な言語ランタイム（Python, Node.js）がインストールされていない
  2. パッケージ不足: スキルが依存するパッケージがインストールされていない
  3. パス設定エラー: スキルの実行パスが正しく設定されていない

再現条件

  • 新しいスキルを導入した直後
  • OpenClawのバージョンアップ後
  • システム環境を変更した後

対処

言語ランタイムの確認

# Python がインストールされているか確認
python3 --version

# Node.js がインストールされているか確認
node --version

# 必要に応じてインストール
sudo apt install python3 nodejs npm

パッケージのインストール

# スキルの依存パッケージをインストール
cd ~/.openclaw/workspace/skills/<skill-name>
npm install

# または
pip install -r requirements.txt

スキルパスの確認

# スキルの実行パスを確認
ls -la ~/.openclaw/workspace/skills/<skill-name>/scripts/

# 設定ファイルを確認
cat ~/.config/openclaw/skills.json

予防策

  • 環境ドキュメント: 各スキルの環境要件をドキュメント化する
  • 依存関係の自動チェック: スキル導入時に依存関係を自動チェックする
  • バージョン管理: 言語ランタイムとパッケージのバージョンを固定する

運用で詰まりやすい点のチェックリスト

セッション管理

  • 定期的に Stalled sessions をチェックしているか
  • セッションのタイムアウト設定を確認しているか
  • 不必要なセッションを終了しているか

モデル管理

  • APIキーが有効であるか
  • モデルの可用性を確認しているか
  • モデル切替後に動作確認をしているか

Cronジョブ

  • ジョブのタイムアウト設定を確認しているか
  • cron式が正しいか検証しているか
  • ジョブの実行ログを確認しているか

プロンプト

  • プロンプトの長さを確認しているか
  • コンテキストが肥大化していないか
  • プロンプトを分割して分散させる必要があるか

スキル

  • スキルの依存関係を確認しているか
  • 言語ランタイムがインストールされているか
  • スキルの実行パスが正しいか

監視とアラート

  • システムリソース（CPU/メモリ/ディスク）を監視しているか
  • エラーログを定期的に確認しているか
  • アラート設定を行っているか

まとめ

OpenClawのマルチエージェントシステムは、適切なトラブルシューティングと予防策により安定運用が可能です。

  • Stalled Sessions: Self-Heal Recovery システムで自動回復
  • モデル切替: APIキーとモデルバージョンを確認
  • Cronジョブ: タイムアウト設定とスケジュールの分散
  • プロンプト: 分割してトークンを節約
  • スキル: 依存関係を確認してインストール

チェックリストを定期的に確認して、システムの健全性を維持してください。

1
2
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
Sign upLogin
1
2

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?