logo

コミュニティ

OpenClaw on Zeabur トラブルシューティング

実際のサポート対応記録から整理した解決策で、5分以内に自分で解決できます。

Can YuCan Yu

OpenClaw は Zeabur 上で問題なく動いていた。突然動かなくなるまでは。

これは仮定の話ではありません。過去3週間で、OpenClaw 関連のサポートチケットを40件以上処理しました。5分で自力解決できる問題もあれば、何日も詰まってしまう問題もありました。

この記事では、最もよくある問題を整理し、実際のケースから抽出した解決策を添えています。次に遭遇したとき、サポートの返信を待つ必要はありません。

何が表示されていますか？

症状参照
サービスが CRASHED と表示され、再起動を繰り返す問題1
サービスが STARTING のまま、RUNNING にならない問題2
Telegram bot が typing と表示されるが返信しない問題3
モデルを変更したいが設定方法がわからない問題4
URL を開くと 502 エラーが表示される問題5
ブラウザツールが起動していないと言われる問題6
パッケージのインストールで権限エラーが表示される問題7
openclaw gateway restart でエラーが発生する問題8
設定ファイルの場所がわからない問題9
手動で設定を変更した後にクラッシュした問題10
OpenClaw をアップグレードしたい問題11
アップグレード後に問題が発生した問題11
データをバックアップまたは復元したい問題12
2026.2.17 にアップグレード後 Telegram に接続できない問題13
Telegram のログに 409: Conflict が表示される問題14
2026.2.23 にアップグレード後 Web UI が開けない問題15
ログに Unrecognized key が表示される問題1 + レスキューモード
No API key found for provider問題3
connection refused on port 18789問題2
systemctl ENOENT問題8

まずこれを覚えましょう：レスキューモード

どんなクラッシュ問題に遭遇しても、この手順でほぼ復旧できます。まず覚えておいてください。後で何度も使います。

2026/2/22 以降にインストールしたバージョン（ヘルパーページあり）

Gateway がクラッシュした場合、サービスの URL を開くと自動的にヘルパーページが表示され、エラーログと修復のヒントが含まれています。

  1. ヘルパーページのエラーログを確認します（完全なログは Zeabur Dashboard のログタブで確認できます）
  2. Zeabur Dashboard のファイルタブで /home/node/.openclaw/openclaw.json を見つけて問題を修正します
  3. Zeabur Dashboard で再起動をクリックします

サービスが復旧すると、ヘルパーページは自動的に消えます。

2026/2/22 より前にインストールしたバージョン（ヘルパーページなし）

旧バージョンにはヘルパーページがないため、手動でコンテナに入って修復する必要があります。

  1. Zeabur Dashboard で OpenClaw サービスを見つけます
  2. ログタブでエラーメッセージを確認します
  3. 設定 → コマンドで、起動コマンドを sleep 3600 に変更し、再起動します — これによりコンテナが実行され続け、中に入って修復できるようになります
  4. ファイルタブで /home/node/.openclaw/openclaw.json を見つけて問題を修正します
  5. 起動コマンドを /opt/openclaw/startup.sh && /opt/openclaw/start_gateway.sh に戻し、サービスを再起動します

ヘルパーページを有効にしたい場合は、OpenClaw テンプレートから再デプロイしてください。

問題1：設定変更後にサービスがクラッシュし、再起動を繰り返す

これは現在最も多い問題で、サポートチケットの約半数を占めています。

症状： サービスのステータスが CRASHED または CrashLoopBackOff と表示され、ログに以下のようなエラーが表示されます：

Invalid config at /home/node/.openclaw/openclaw.json: - gateway: Unrecognized key: "cool" ◇ Unknown config keys ─╮ │ │ │ - gateway.cool │ │ │ ├───────────────────────╯ ◇ Doctor ────────────────────────────────────────────╮ │ │ │ Run "openclaw doctor --fix" to remove these keys. │ │ │ ├─────────────────────────────────────────────────────╯ Config invalid File: ~/.openclaw/openclaw.json Problem: - gateway: Unrecognized key: "cool" Run: openclaw doctor --fix

原因： 設定ファイルに OpenClaw が認識できない key が含まれています。よくあるケース：手動編集時に存在しないフィールドを追加した、OpenClaw に設定変更を頼んだが壊された、バージョンアップグレード後に古い設定フィールドが廃止または名前変更された。設定ファイルは永続ストレージに保存されており、認識できない key があると起動を拒否します。

解決策：

ケース A：サービスがまだ起動できる場合（ログに Doctor のヒントが表示されている）

コマンドタブに入って openclaw doctor --fix を実行すると、認識できない key が自動的に削除されます。

ケース B：サービスがクラッシュして shell にも入れない場合

これが最も一般的なケースです。上記のレスキューモードでコンテナに入り、/home/node/.openclaw/openclaw.json を開いて、ログに表示されている key（例：上記の gateway.cool）を削除し、サービスを再起動します。

問題2：サービスが「起動中」のまま、起動プローブがタイムアウトする

症状： サービスがずっと STARTING と表示され、RUNNING にならない。ログに以下が表示される場合があります：

Startup probe failed: dial tcp 10.0.5.87:18789: connect: connection refused

原因： OpenClaw は起動に比較的長い時間がかかる場合があり（60秒を超えることもある）、デフォルトの起動プローブが早すぎる可能性があります。もう1つのよくある原因は、設定ファイルの破損（問題1と同様）です。

解決策：

  1. まず数分待って初期化を完了させます
  2. 継続的に失敗する場合は、ログに config 関連のエラーがないか確認します
  3. メモリが少なくとも 4GB あることを確認します
  4. ログに config invalid と表示されている場合は、レスキューモードで対処します

問題3：AI Hub に接続したが bot が応答しない

症状： Telegram で bot にメッセージを送ると、typing と表示されるが返信がない、または全く反応しない。

原因： 通常は API Key の設定の問題、またはモデル接続の失敗です。最もよく見られるエラーは、Key と Provider の不一致です。

解決策：

  1. 環境変数の設定が正しいことを確認します：

    • ZEABUR_AI_HUB_API_KEY — Zeabur AI Hub を使用する場合
    • ANTHROPIC_API_KEY — Claude を直接使用する場合
    • OPENAI_API_KEY — OpenAI を使用する場合（Memory Search と TTS にも使用）

  2. Web UI でモデル設定を確認し、選択したモデルが API Key と一致していることを確認します

  3. 環境変数を設定した後は必ずサービスを再起動してください。再起動しないと反映されません

よくあるミス： AI Hub Key を設定したが、OpenClaw がデフォルトで Anthropic に接続しようとし、No API key found for provider "anthropic" というエラーが発生する。Provider の設定が Key と一致していることを確認してください。

問題4：モデルを変更したいが、設定方法がわからない

症状： デフォルトのモデルでは物足りないので、Claude Sonnet や他のモデルに変更したい。

解決策：

  1. OpenClaw Web UI にアクセスします（Zeabur Dashboard の指示タブから Web UI (with token) リンクを見つけます）
  2. Config ページに移動します
  3. モデル設定で使いたいモデルを選択します

Zeabur AI Hub を使用している場合、1つの Key で複数のモデルを切り替えることができます：

  • claude-sonnet-4-6 — 推奨、品質と速度のバランスが良い
  • claude-haiku-4-5 — より速く、より安価
  • gpt-5-mini — OpenAI オプション

他の Provider を使いたい場合は？ 環境変数タブで対応する API Key を追加し、サービスを再起動すれば使用できます：

Provider環境変数
Zeabur AI HubZEABUR_AI_HUB_API_KEY
OpenAIOPENAI_API_KEY
AnthropicANTHROPIC_API_KEY
Google GeminiGEMINI_API_KEY
xAI (Grok)XAI_API_KEY
MistralMISTRAL_API_KEY
OpenRouterOPENROUTER_API_KEY
GroqGROQ_API_KEY
Moonshot (Kimi)MOONSHOT_API_KEY
Z.AI (GLM)ZAI_API_KEY

その他の Provider については OpenClaw 公式ドキュメントを参照してください。

問題5：502 SERVICE_UNAVAILABLE

症状： OpenClaw の URL を開くと 502 エラーが表示される。

原因： よくある原因は3つあります：

  1. サービスの起動がまだ完了していない（ポートがまだ ready でない）
  2. Zeabur のネットワーク設定のポートが OpenClaw の実際のリスニングポート（デフォルト 18789）と異なる
  3. openclaw.json を削除した後、OpenClaw がデフォルト設定にフォールバックし、bind が loopback になって外部から接続できない

解決策：

  1. サービスのステータスが RUNNING であることを確認します
  2. Zeabur Dashboard のネットワークタブで設定されているポートが 18789 であることを確認します（環境変数 OPENCLAW_GATEWAY_PORT と一致させます）
  3. 環境変数 OPENCLAW_GATEWAY_BIND の値が lan であることを確認します（Zeabur テンプレートではデフォルトで設定されていますが、手動で削除やリセットした場合は消えている可能性があります）
  4. 設定ファイルをリセットした場合は、openclaw.json の gateway.bind も確認し、loopback ではなく lan になっていることを確認します
  5. ルーティングが反映されるまで数分待ちます
  6. 502 が続く場合は、サービスを再起動します

問題6：ブラウザツールが使えない

症状： OpenClaw にウェブ検索やブラウザ操作を頼むと、ブラウザが起動していない・使用できないと言われ、代わりに Web Fetch が使われる。

原因： コンテナ環境では、headless Chrome の動作に追加の sandbox サービスが必要です。OpenClaw を単純にデプロイしただけではブラウザは含まれません。

解決策： OpenClaw Sandbox Browser テンプレートをデプロイすると、headless Chrome が自動的に設定されます。デプロイ後、OpenClaw の Config で remote Profile を sandbox に向ける設定が必要です。

Sandbox Browser をデプロイ

OpenClaw にブラウザ操作機能を追加します。

ワンクリックデプロイ永久無料プランあり。

単純なウェブページの読み取り（記事の要約など）であれば、Web Fetch で十分な場合が多く、完全なブラウザ操作は必要ありません。

問題7：権限不足でパッケージをインストールできない

症状： bot に pip、Homebrew、その他のツールをインストールさせようとすると、権限エラーが表示される。

原因： Zeabur の Docker コンテナは非 root ユーザー（node）で実行されているため、システムレベルのパッケージを直接インストールできません。Homebrew もコンテナ環境では使用できません。

解決策： これは設計上のトレードオフです — コンテナの分離がデータのセキュリティを保護しています。代替手段：

  • OpenClaw の skill システムを使用します。多くの機能は既存の skill で利用可能です（50以上あります）
  • 完全な開発環境（pip、apt など）が必要な場合は、Zeabur Devbox を OpenClaw の sandbox としてデプロイし、そこでコマンドを実行させることができます
Devbox をデプロイ

OpenClaw に完全な開発環境を追加します。

ワンクリックデプロイ永久無料プランあり。

問題8：Gateway restart が失敗する

症状： openclaw gateway restart を実行すると以下が表示される：

Gateway service check failed: Error: systemctl --user unavailable: spawn systemctl ENOENT

原因： コンテナ環境には systemd がありません。

解決策： Zeabur では openclaw gateway restart を使う必要はありません。Dashboard から直接サービス全体を再起動してください。

問題9：openclaw.json 設定ファイルが見つからない

症状： 手動で設定を編集したいが、ファイルの場所がわからない。

解決策： 設定ファイルはコンテナ内の以下の場所にあります：

/home/node/.openclaw/openclaw.json

Zeabur Dashboard のファイルまたはコマンドタブからアクセスして確認・編集できます。

ただし、設定の変更には Web UI の Config ページを優先的に使用することをお勧めします。JSON フォーマットを壊しにくいためです。手動で JSON を壊すことは、問題1（クラッシュ）のよくある原因の1つです。

問題10：設定を変更する正しい方法

方法1：Web UI（推奨）

Web UI の Settings → Config ページで設定を変更します。フォーマットの検証を行ってくれるため、JSON を壊しにくいです。

方法2：OpenClaw に変更してもらう

会話の中で OpenClaw に変更したい設定を伝えると、openclaw.json を修正してくれます。ただし、2つ注意点があります：

  • 十分なコンテキストを提供する — 何を、どう変更したいか明確に伝えてください。「設定を変えて」とだけ言わないでください
  • 十分な能力のあるモデルを使用する — シンプルなモデルではフォーマットを壊したり、存在しないフィールドを追加したりする可能性があります。設定操作には claude-sonnet-4-6 または gpt-5 以上のモデルを使用することをお勧めします

方法3：手動編集

  1. Zeabur Dashboard のファイルまたはコマンドタブに移動します
  2. /home/node/.openclaw/openclaw.json を編集します
  3. 編集後にサービスを再起動します

注意： どの方法を使う場合でも、OpenClaw が認識しない key を追加しないでください。追加すると問題1のクラッシュが発生します。

問題11：OpenClaw をアップグレードする正しい方法

正しい手順：

  1. Zeabur Dashboard で OpenClaw サービスを開きます
  2. サービス設定で Docker image のタグ（tag）を変更します
  3. 例えば 2026.2.19 から 2026.2.23 に変更します
  4. 保存するとサービスが自動的に再起動し、新しいバージョンが使用されます

アップグレード前の推奨事項： まず Web UI の Config ページで既存の設定をエクスポートしてバックアップしてください。新バージョンで一部の設定フィールドが廃止される可能性があります。

アップグレード後の注意： 新バージョンでは一部の設定フィールドが変更または廃止される場合があり、起動時に Unrecognized key エラーが発生してクラッシュすることがあります。アップグレード後にサービスが起動しない場合は、問題1とレスキューモードを参照してください。

やってはいけないこと：

  • イメージを ghcr.io/openclaw/openclaw 以外のものに変更しないでください
  • コンテナ内で openclaw update や npm i -g openclaw を実行しないでください — これらはローカルインストールのアップグレード方法です。Zeabur では image tag を変更するだけで十分です
  • latest タグの使用は非推奨です — サービスの再起動時に自動的に最新バージョンが取得され、知らないうちにアップグレードされて問題が発生する可能性があります。特定のバージョン番号（例：2026.2.23）を固定し、必要な時に手動で変更してください

問題12：バックアップと復元

Zeabur にはバックアップ機能が組み込まれており、定期的な自動バックアップが可能です。まず設定しておくことをお勧めします。以下は手動バックアップの方法です。

手動バックアップ：

Zeabur Dashboard のコマンドタブで以下を実行します：

backup

バックアップファイルは /home/node/ に生成されます（例：backup-1430.tar.gz）。ファイルタブでファイルを見つけ、右側のダウンロードボタンをクリックしてパソコンに保存します。

旧バージョンで backup コマンドがない場合：

cd /home/node && tar -czvf backup.tar.gz .openclaw

復元：

  1. ファイルタブで /home/node/ に移動し、右上のアップロードボタンをクリックしてバックアップファイルをアップロードします
  2. コマンドタブで以下を実行します：
restore backup-1430.tar.gz
  1. サービスを再起動します

Zeabur Backup Service から生成されたバックアップファイルの場合は、--strip 2 を追加します：

restore backup-xxxxx.tar.gz --strip 2

バックアップすべきタイミング： 初期設定完了後、アップグレード前、大幅な設定変更前。

問題13：2026.2.17 にアップグレード後 Telegram に接続できない

症状： 2026.2.17 またはそれ以降のバージョンにアップグレード後、Telegram bot が接続できないか応答しない。

原因： 2026.2.17 ではネットワーク接続のデフォルト動作が変更され、一部のコンテナ環境で Telegram API への接続が失敗するようになりました。

解決策：

Zeabur Dashboard の環境変数タブで以下を追加します：

OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=true

サービスを再起動すれば完了です。

問題14：Telegram のログに 409 Conflict が繰り返し表示される

症状： ログに以下のエラーが繰り返し表示され、Telegram bot が全く反応しない：

[telegram] getUpdates conflict: Call to 'getUpdates' failed! (409: Conflict: terminated by other getUpdates request; make sure that only one bot instance is running)

原因： Telegram Bot API にはメッセージを受信する方法が2つあります：Polling（能動的なポーリング）と Webhook（Telegram からのプッシュ）。この2つは排他的で、同時に使用できません。

この 409 エラーは、この bot に以前 webhook が設定されていたが、現在 OpenClaw が polling 方式でメッセージを受信しようとしており、Telegram に拒否されていることを意味します。よくある原因：

  • 以前、他のサービスや環境でこの bot に webhook を設定していた
  • bot を polling モードに戻す前に webhook をクリアしなかった

解決策：

Zeabur Dashboard のコマンドタブで、以下のコマンドを実行して webhook をクリアします（<TOKEN> を自分の bot token に置き換えてください）：

curl https://api.telegram.org/bot<TOKEN>/deleteWebhook

{"ok":true,"result":true} と表示されればクリア成功です。サービスを再起動すれば bot が正常にメッセージを受信できるようになります。

問題15：2026.2.23 にアップグレード後 Web UI が開けない

症状： 2026.2.23 にアップグレード後、Web UI を開くと空白ページや CORS エラーが表示され、正常に読み込めない。

原因： 2026.2.23 から Control UI の allowedOrigins チェックが強制されるようになりました。Zeabur ではユーザーのドメインが動的に生成されるため、Gateway が正当な origin を自動判定できず、リクエストが拒否されます。

解決策：

Zeabur Dashboard のファイルタブで /home/node/.openclaw/openclaw.json を編集し、gateway.controlUi に以下を追加します：

{ "gateway": { "controlUi": { "dangerouslyAllowHostHeaderOriginFallback": true } } }

サービスを再起動すれば完了です。

サービスがクラッシュして入れない場合は、レスキューモードで設定ファイルを編集してください。

それでも解決しない場合

上記をすべて試しても解決しない場合：

  1. ログページのエラーメッセージをスクリーンショットします
  2. Zeabur Forum でサポートチケットを作成し、スクリーンショットを添付してください

この記事の内容に誤りや古い情報がある場合も、Zeabur Forum でご報告ください。

return Blogs