OpenClawの「Gateway Start Blocked」を修正 — gateway.mode=local

OpenClawのゲートウェイが「gateway start blocked」エラーで起動を拒否する場合、gateway.modeを設定する必要があります。このガイドでは、このエラーのすべてのバリエーション、ワンコマンドの修正方法、再発防止の方法を解説します。

すべての「Gateway Start Blocked」エラーメッセージ

OpenClawはバージョンと設定状態に応じてわずかに異なるメッセージを出力します。以下のいずれかからここにたどり着いた場合、正しい場所です：

gateway start blocked: set gateway.mode=local (current: unset)
  or pass --allow-unconfigured

gateway start blocked: set gateway.mode=local --allow-unconfigured

Missing config. Run `openclaw setup` or set gateway.mode=local
  (or pass --allow-unconfigured).

gateway.mode unset — gateway start will be blocked

gateway.mode is unset

ERROR: gateway.mode not configured. Run openclaw setup or set
  gateway.mode=local to start in local-only mode.

missing config: run openclaw setup or set gateway.mode=local

gateway start blocked: gateway.mode is unset — expected local, remote, or hybrid

[gateway] start blocked — config key gateway.mode has no value

これらすべてが同じ意味です：モードを明示的に選択するまで、OpenClawはゲートウェイを起動しません。これはバグではなく、意図的なセキュリティ対策です。

30秒で修正

コマンド1つを実行します：

openclaw config set gateway.mode local

その後再起動：

openclaw restart

完了です。ゲートウェイは正常に起動します。

openclaw setupウィザード内でこのエラーに遭遇した場合、ゲートウェイモードの入力を求められた時にlocalと入力すれば、ウィザードが残りを処理します。

gateway.modeとは？

gateway.mode設定は、ゲートウェイがリッスンするネットワークインターフェースを指定します。各モードにはセキュリティ上の意味があるため、OpenClawはデフォルトを選択しません。

特別な理由がない限りlocalを選んでください。 CaddyやNginxのようなリバースプロキシ経由でOpenClawにアクセスする場合でも、プロキシは同じマシン上で動作しlocalhostで接続するため、localが正解です。

モードの設定：

# ローカルのみ（推奨）
openclaw config set gateway.mode local

# リモートアクセス
openclaw config set gateway.mode remote

# 両方
openclaw config set gateway.mode hybrid

現在の設定をいつでも確認できます：

openclaw config get gateway.mode

--allow-unconfiguredとは？

エラーメッセージは代替として--allow-unconfiguredを提案します。このフラグは設定を保存せずにゲートウェイを一度だけ起動します：

openclaw gateway start --allow-unconfigured

これは一回限りのテストやクイックデバッグセッションに便利です。ただし、次にOpenClawを再起動すると、何も設定に保存されていないため同じ「gateway start blocked」エラーが再び表示されます。

代わりにopenclaw config set gateway.mode localを使用してください。 永続的で、このエラーを二度と見ることはありません。

--allow-unconfiguredを渡すと、ゲートウェイはそのセッションでローカルのみモードにデフォルト設定されます。リモートアクセスは開かれません。

Dockerユーザー

OpenClawをDockerで実行する場合、設定コマンドの代わりに環境変数でモードを設定します：

docker run -e OPENCLAW_GATEWAY_MODE=local openclaw-stack

またはdocker-compose.ymlで：

services:
  openclaw:
    image: openclaw-stack
    environment:
      - OPENCLAW_GATEWAY_MODE=local

リバースプロキシの背後のDockerコンテナの場合、ゲートウェイが転送された接続を受け入れるようにtrusted proxiesも設定します：

environment:
  - OPENCLAW_GATEWAY_MODE=local
  - OPENCLAW_GATEWAY_TRUSTED_PROXIES=127.0.0.1

実行中のコンテナにexecで入る場合、CLIも使用できます：

docker exec -it <container> openclaw config set gateway.mode local
docker exec -it <container> openclaw restart

まだブロックされている？他の原因

gateway.modeを設定済みでゲートウェイがまだ起動しない場合、別の問題です。診断を実行します：

openclaw doctor

検出されたすべての問題を自動修正：

openclaw doctor --fix

gateway.mode以外の一般的な原因：

ポートの競合

別のプロセスがゲートウェイポート（デフォルト3001）を使用しています。確認して変更します：

# ポートを使用しているものを確認
lsof -i :3001

# 別のポートに切り替え
openclaw config set gateway.port 3002
openclaw restart

設定ファイルの破損

不正な設定ファイルはgateway.modeが設定されていても起動をブロックする可能性があります：

# 設定を検証
openclaw config validate

# バリデーションが失敗した場合、設定をリセットして再設定
openclaw config reset
openclaw setup

権限の問題

設定ディレクトリまたはデータファイルが現在のユーザーで書き込み不可：

ls -la ~/.openclaw/

# 必要に応じて所有権を修正
sudo chown -R $(whoami) ~/.openclaw/

古いPIDファイル

以前のクラッシュでPIDファイルが残り、クリーンな起動を妨げています：

rm ~/.openclaw/gateway.pid
openclaw restart

動作確認

修正を適用した後、ゲートウェイが実行中であることを確認します：

openclaw status

出力にgateway: runningが表示されるはずです。詳細はログを確認：

openclaw logs --tail 20

[gateway] listening onの行がゲートウェイが完全に起動し接続を受け付けていることを確認します。この行が表示されれば、修正は成功です。

FAQ

なぜOpenClawはデフォルトでlocalモードにしないのか？

OpenClawはゲートウェイモードをセキュリティ上重要な設定として扱います。暗黙的にデフォルト設定すると、意図しないインターフェースでゲートウェイが公開される可能性があります。明示的な選択を強制することで、インスタンスがどのように到達可能かを確実に認識させます。

gateway.modeを設定したのに再起動後もエラーが出る

openclaw config set gateway.mode localを使用したことを確認してください（シェルの環境変数だけではダメです）。configコマンドは~/.openclaw/config.yamlに書き込み、再起動後も永続化されます。openclaw config get gateway.modeで保存されたことを確認してください。

gateway.mode=localはCloudflare Tunnel / ngrokで動作しますか？

はい。Cloudflare Tunnelもngrokもゲートウェイにlocalhostで接続するため、localモードが正解です。トンネリングサービスにremoteモードは不要です。

再起動なしでgateway.modeを変更できますか？

いいえ。ゲートウェイは起動時にモードを読み取ります。設定変更後、openclaw restartを実行して適用してください。

openclaw setupとopenclaw config setの違いは？

openclaw setupはゲートウェイモード、APIキー、統合を含むすべての設定オプションを案内するインタラクティブウィザードです。openclaw config set gateway.mode localはゲートウェイモードだけを直接変更します。どちらも最終的に同じ設定ファイルに書き込みます。

CI/CDパイプライン内で「gateway start blocked」が出る

CIでは永続的な設定がないため、--allow-unconfiguredを渡してください。または、パイプライン定義でOPENCLAW_GATEWAY_MODE=local環境変数を設定してください。どちらのアプローチもインタラクティブセットアップを回避します。

ゲートウェイ設定のデバッグに疲れましたか？ClawTankなら、完全に設定済みのOpenClawインスタンスが手に入ります — 1分以内にデプロイ、ターミナル不要です。