コンテンツへスキップ
最終更新

docs / トラブルシューティング

OpenClaw トラブルシューティング: gateway、Telegram、browser relay の問題を解決する

OpenClaw の導入、gateway token、Telegram チャネル、browser relay、Docker、ランタイム障害を、段階別のコマンドと確認方法つきでまとめています。

導入と環境

導入前

インストールスクリプトが止まる（ネットワーク/プロキシ）

開く

症状: curl や npm のダウンロードが失敗する、またはタイムアウトする。

原因: ネットワーク制限があるか、プロキシ設定が不足している。

対処方法

コマンド

curl -I https://openclaw.bot/install.sh
export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890

設定変更

+ https_proxy=http://127.0.0.1:7890
+ http_proxy=http://127.0.0.1:7890

効果の理由: 通信をプロキシ経由に切り替えることで、インストールスクリプトと依存取得が通るようになります。

確認方法: インストールコマンドを再実行し、ダウンロードが正常に進むことを確認します。

スクリーンショット:

インストールスクリプトが止まる（ネットワーク/プロキシ） screenshot

Docker デーモンが起動していない

開く

症状: Docker コマンドが失敗する、またはコンテナがすぐ終了する。

原因: Docker サービスが停止しているか、自動起動が有効になっていない。

対処方法

コマンド

sudo systemctl status docker
sudo systemctl enable --now docker

設定変更

- restart: "no"
+ restart: unless-stopped

効果の理由: Docker サービスを有効化し、再起動後もコンテナが自動で復旧するようにします。

確認方法: 再起動後に `docker ps` でコンテナが動作中のままか確認します。

スクリーンショット:

Docker デーモンが起動していない screenshot

データディレクトリの権限不足

開く

症状: 書き込み時に Permission denied や EACCES が出る。

原因: データディレクトリの所有者が適切でないか、ボリュームパスがずれている。

対処方法

コマンド

sudo chown -R $USER:$USER ~/.openclaw
ls -la ~/.openclaw

設定変更

- ./openclaw-data:/root/.openclaw
+ ~/.openclaw:/root/.openclaw

効果の理由: ユーザー所有のディレクトリに揃えることで、gateway が状態を書き込めるようになります。

確認方法: 再起動後に `~/.openclaw` 配下へ正常にファイルが作成されることを確認します。

スクリーンショット:

データディレクトリの権限不足 screenshot

オンボーディングと起動

セットアップ中

オンボーディングが止まる / モデル応答が返らない

開く

症状: CLI のオンボーディングが止まる、またはチャネル返信が返ってこない。

原因: API Key が未設定・無効、または外向き通信が遮断されている。

対処方法

コマンド

openclaw config get | head -n 20
openclaw gateway restart

設定変更

+ ANTHROPIC_API_KEY=sk-REPLACE_ME

効果の理由: モデルプロバイダへの認証情報が正しく読まれているか確認できます。

確認方法: `openclaw health` が OK になり、テストメッセージに応答が返るか確認します。

スクリーンショット:

オンボーディングが止まる / モデル応答が返らない screenshot

Control UI のポート競合

開く

症状: SSH トンネルや UI 接続で EADDRINUSE が出る。

原因: 18789 ポートを別プロセスが占有している。

対処方法

コマンド

sudo lsof -iTCP -sTCP:LISTEN -n -P | grep 18789

設定変更

- "18789:18789"
+ "18790:18789"

効果の理由: ホスト側の公開ポートだけずらし、内部ポートを保ったまま競合を避けます。

確認方法: 新しいポートでトンネル接続と UI 表示が正常か確認します。

スクリーンショット:

Control UI のポート競合 screenshot

設定変更が反映されない

開く

症状: 設定を変えても挙動が変わらない。

原因: 別の設定ファイルを編集しているか、gateway を再起動していない。

対処方法

コマンド

openclaw config get
openclaw gateway restart

設定変更

+ OPENCLAW_CONFIG_PATH=~/.openclaw/openclaw.json

効果の理由: gateway に正しい設定ファイルを読ませることで反映漏れを防ぎます。

確認方法: 再起動後に `openclaw config get` の値が変更内容と一致するか確認します。

スクリーンショット:

設定変更が反映されない screenshot

チャネルとアクセス制御

最初の導入成功後

Telegram ボットが起動するが返信しない

開く

症状: Telegram で /start は通るが、通常メッセージに応答しない。

原因: Bot Token の誤り、gateway 未再起動、または Telegram API への疎通不良。

対処方法

コマンド

openclaw config get channels.telegram.botToken
openclaw gateway restart
curl -I https://api.telegram.org

設定変更

- channels.telegram.enabled: false
+ channels.telegram.enabled: true
+ channels.telegram.botToken: "YOUR_TELEGRAM_BOT_TOKEN"

効果の理由: Telegram チャネルの有効化、Bot Token の存在、gateway の再読み込み、外部疎通の 4 点をまとめて確認できます。

確認方法: Telegram で /start を送り直し、通常のテキストにも返信が返るか確認します。

スクリーンショット:

Telegram ボットが起動するが返信しない screenshot

Gateway token が無効 / 未設定 / 拒否される

開く

症状: gateway 呼び出しで unauthorized、forbidden、token missing などが返る。

原因: ランタイム token が未設定、値が食い違っている、または古い値がプロキシ側に残っている。

対処方法

コマンド

openclaw config get gateway.token
openclaw gateway restart
printenv | grep -i OPENCLAW

設定変更

- gateway.token: ""
+ gateway.token: "REPLACE_WITH_A_STRONG_SECRET"

効果の理由: ランタイム、クライアント、プロキシ経路で同じ gateway token を使うことで、認証エラーや設定不整合を避けられます。

確認方法: 正しい token を与えたときだけ health チェックや保護 API が通ることを確認します。

スクリーンショット:

Gateway token が無効 / 未設定 / 拒否される screenshot

browser relay が接続できない / タイムアウトする

開く

症状: ブラウザ機能を使う workflow が開始できない、または relay timeout が頻発する。

原因: browser relay が無効、対象サービスが到達不能、または relay のアドレス解決に失敗している。

対処方法

コマンド

openclaw config get browserRelay
curl -I http://127.0.0.1:3000 || true
openclaw gateway restart

設定変更

- browserRelay.enabled: false
+ browserRelay.enabled: true
+ browserRelay.baseUrl: "http://127.0.0.1:3000"

効果の理由: browser relay は到達可能な中継サービスと一致したランタイム設定が前提です。gateway の再起動で設定を確実に読み直させます。

確認方法: browser 依存の skill または workflow を 1 つ実行し、relay timeout が消えたか確認します。

スクリーンショット:

browser relay が接続できない / タイムアウトする screenshot

ランタイムと安定性

起動後

再起動後にデータが保持されない

開く

症状: コンテナ再起動後に設定や履歴が消える。

原因: 状態保存用のホストボリュームがマウントされていない。

対処方法

コマンド

ls -la ~/.openclaw
docker compose ps

設定変更

- volumes:
-   - ./openclaw-data:/root/.openclaw
+ volumes:
+   - ~/.openclaw:/root/.openclaw

効果の理由: 状態をホスト側に保存することで、再起動後も設定とデータを引き継げます。

確認方法: gateway 再起動後も設定と履歴が残っていることを確認します。

スクリーンショット:

再起動後にデータが保持されない screenshot

メモリ不足 / OOM

開く

症状: 高負荷時にプロセスが kill される、または OOM ログが出る。

原因: 現在のワークロードに対して RAM が不足している。

対処方法

コマンド

free -m
journalctl -k | grep -i oom

設定変更

- plan: entry
+ plan: standard

効果の理由: メモリ量や VPS プランを上げることで OOM kill を防ぎやすくなります。

確認方法: ピーク時にも OOM イベントが発生しないことを確認します。

スクリーンショット:

メモリ不足 / OOM screenshot

あわせて確認する