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

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

<AIHubShutdownNotice />

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

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

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

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

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

---

<div id="rescue" />

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

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

### 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 テンプレート](https://zeabur.com/ja-JP/templates/VTZ4FX)から再デプロイしてください。

---

<div id="p1" />

## 問題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 にも入れない場合**

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

---

<div id="p2" />

## 問題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 と表示されている場合は、**レスキューモード**で対処します

---

<div id="p3" />

## 問題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 と一致していることを確認してください。

---

<div id="p4" />

## 問題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 Hub | `ZEABUR_AI_HUB_API_KEY` |
| OpenAI | `OPENAI_API_KEY` |
| Anthropic | `ANTHROPIC_API_KEY` |
| Google Gemini | `GEMINI_API_KEY` |
| xAI (Grok) | `XAI_API_KEY` |
| Mistral | `MISTRAL_API_KEY` |
| OpenRouter | `OPENROUTER_API_KEY` |
| Groq | `GROQ_API_KEY` |
| Moonshot (Kimi) | `MOONSHOT_API_KEY` |
| Z.AI (GLM) | `ZAI_API_KEY` |

その他の Provider については [OpenClaw 公式ドキュメント](https://docs.openclaw.ai/providers)を参照してください。

---

<div id="p5" />

## 問題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 が続く場合は、サービスを再起動します

---

<div id="p6" />

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

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

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

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

<TemplateCTA
  code="H8L4G1"
  title="Sandbox Browser をデプロイ"
  description="OpenClaw にブラウザ操作機能を追加します。"
  buttonText="ワンクリックデプロイ"
/>

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

---

<div id="p7" />

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

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

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

**解決策：** これは設計上のトレードオフです — コンテナの分離がデータのセキュリティを保護しています。代替手段：
- OpenClaw の **skill システム**を使用します。多くの機能は既存の skill で利用可能です（50以上あります）
- 完全な開発環境（pip、apt など）が必要な場合は、Zeabur Devbox を OpenClaw の sandbox としてデプロイし、そこでコマンドを実行させることができます

<TemplateCTA
  code="ZBVZNH"
  title="Devbox をデプロイ"
  description="OpenClaw に完全な開発環境を追加します。"
  buttonText="ワンクリックデプロイ"
/>

---

<div id="p8" />

## 問題8：Gateway restart が失敗する

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

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

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

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

---

<div id="p9" />

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

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

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

```
/home/node/.openclaw/openclaw.json
```

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

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

---

<div id="p10" />

## 問題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のクラッシュが発生します。

---

<div id="p11" />

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

**正しい手順：**

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

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

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

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

---

<div id="p12" />

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

Zeabur には[バックアップ機能](https://zeabur.com/docs/data-management/backup)が組み込まれており、定期的な自動バックアップが可能です。まず設定しておくことをお勧めします。以下は手動バックアップの方法です。

**手動バックアップ：**

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
```

3. **サービスを再起動**します

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

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

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

---

<div id="p13" />

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

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

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

**解決策：**

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

```
OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=true
```

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

---

<div id="p14" />

## 問題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 が正常にメッセージを受信できるようになります。

---

<div id="p15" />

## 問題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` に以下を追加します：

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

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

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

---

## それでも解決しない場合

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

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

---

この記事の内容に誤りや古い情報がある場合も、[Zeabur Forum](https://zeabur.com/forum) でご報告ください。