Claude code

Railway with OpenClaw トラブルシューティング

Railway上のOpenClawサーバーで発生する典型的なトラブルと、その診断・解決手順をまとめたガイド。

0. 前提: 環境の構成を理解する

Railwayにデプロイされた典型的なOpenClawは2階建て構造になっている:

ブラウザ
  ↓ wss://<service>.up.railway.app/openclaw
Railway public プロキシ
  ↓ コンテナの $PORT (通常 8080)
node src/server.js  (PID 1) ← Railway エントリーポイント
  ↓ 内部プロキシ
openclaw gateway   (loopback 127.0.0.1:18789)

重要:

• PID 1 は node src/server.js（Railwayのエントリー）であり、Gateway本体ではない
• Gateway本体は別PIDで動いている（コンテナ起動時の自動起動分 or 手動起動分）
• bind=loopback のままで正しい設計（外向きは8080、内部gatewayはloopback）
• PID 1 を kill するとコンテナごと落ちる。Gateway停止/再起動の対象は別PID

1. 最初に必ず確認すべきこと

問題を診断する前に、以下を並列で実行して状態を把握する:

# プロセス状況
ps -ef | grep -i openclaw | grep -v grep

# ポート占有状況
lsof -i :18789   # gateway デフォルト
lsof -i :8080    # Railway公開ポート
lsof -i -P -n | grep LISTEN

# 環境変数
echo "PORT=$PORT"
echo "OPENCLAW_GATEWAY_TOKEN=$OPENCLAW_GATEWAY_TOKEN"

# 設定ファイル
cat /data/.openclaw/openclaw.json

# Gateway状態
openclaw gateway status

# 健康診断
openclaw doctor

これでほぼすべての問題が特定できる。

2. 既知の問題と解決パターン

問題1: ポート占有 (EADDRINUSE)

症状:

Gateway failed to start: another gateway instance is already listening on ws://127.0.0.1:18789
listen EADDRINUSE: address already in use 127.0.0.1:18789

原因: 別のopenclawプロセスがポート18789を掴んでいる

注意: openclaw gateway stop / restart は lsof/fuserが無い環境では実プロセスを掃除しない。「Gateway service disabled」とだけ出て終わる

解決: 問題2を先に対応してから --force で起動 or 別ポートで起動

問題2: ツール不足 (lsof / fuser not found)

症状:

lsof failed during initial stale-pid scan for port 18789: ENOENT
Force: Error: fuser not found; required for --force when lsof is unavailable

原因: Railwayのスリムコンテナに lsof も fuser も入っていない。--forceが機能しない

解決:

apt-get update && apt-get install -y psmisc lsof iproute2

• psmisc には fuser 同梱
• iproute2 に ss コマンド同梱
• lsof は単体で必須

問題3: TIME_WAIT でポートが解放されない

症状:

force: no listeners on port 18789
Force: Error: port 18789 still not bindable after 3000ms (TIME_WAIT or kernel hold)

原因: TCP仕様。プロセス終了後もポートが60〜120秒「使用中」扱いで予約される。--force でも回避不可

解決策（優先度順）:

1. 別ポートで起動（最速）:

   openclaw gateway run --port 18790
   

   ※ クライアント側の接続先URLも変更必要
2. 1〜2分待つ:

   sleep 90 && openclaw gateway run
   

問題4: device pairing required

症状: ブラウザで接続を試みると赤いエラー:

device pairing required (requestId: <UUID>)

原因: OpenClawは「トークン認証」と別に「このブラウザを信頼済みデバイスとして登録」する手続きが必要。#token=... のURL fragment だけでは不十分

解決: サーバー側のCLIで requestId を承認:

# Pending request一覧を確認
openclaw devices list

# 承認
openclaw devices approve <requestId>
# または
openclaw devices approve --latest

注意: 承認時に副産物として scope upgrade pending approval (requestId: <別UUID>) が発生する。これも放置せず承認すべき（問題5の原因になる）

問題5: 接続後即切断 (disconnected (1000))

症状:

• ブラウザ: disconnected (1000): no reason
• CLI: GatewayTransportError: gateway closed (1000 normal closure): no close reason

原因: ペアリング承認時の副産物 scope upgrade pending が pending のまま残り、gateway の認証状態が破綻している

解決: Gateway本体プロセスを kill → クリーン再起動（PID 1 ではなく、openclaw本体のPID を狙う）:

# 1. gateway本体のPIDを確認
ps -ef | grep -i openclaw | grep -v grep

# 2. PID 1 ではない方をkill（例: PID 1618）
kill <gateway PID>

# 3. すぐに再起動（background）
nohup openclaw gateway run > /tmp/openclaw-gw.log 2>&1 &

# 4. 確認
sleep 3
lsof -i :18789
tail -30 /tmp/openclaw-gw.log

成功時のログ:

[gateway] ready
[ws] webchat connected ... client=openclaw-control-ui
[ws] ⇄ res ✓ sessions.subscribe

問題6: モデル設定が反映されない

症状: 設定ファイル(/data/.openclaw/openclaw.json)を直したのに、ログでは古いモデル参照のままエラーが続く

原因: ホットリロードは効くが、既存セッションが古いモデル参照をメモリに保持 している

解決: 問題5と同じく Gateway本体を kill → 再起動。これで全セッションのメモリがクリアされる

問題7: openai/claude-opus-4-7 というモデル名

症状: 設定に "primary": "openai/claude-opus-4-7" という存在しないモデル名がある

原因: OpenClawのセットアップウィザードのバグ or エクスポート時の混入。Claude OpusはAnthropic製でありOpenAI製ではないので、openai/claude-opus-4-7 というモデルは存在しない

解決: 設定ファイルを修正:

"agents": {
  "defaults": {
    "model": {
      "primary": "anthropic/claude-opus-4-7"
    },
    "models": {
      "anthropic/claude-opus-4-7": {}
    }
  }
}

修正後は問題6と同じく Gateway再起動

3. 標準トラブルシュートフロー

新しいRailway+OpenClawの問題に遭遇したら、以下の順で診断:

1. ps + lsof で現状把握
   ↓
2. gateway は生きている？
   ├─ いいえ → 問題1〜3（起動失敗）→ ツール入れて再起動
   └─ はい
       ↓
3. ブラウザから接続できる？
   ├─ device pairing required → 問題4 → devices approve
   ├─ disconnected (1000)    → 問題5 → gateway 再起動
   └─ 別のエラー
       ↓
4. 設定は意図通り反映されている？
   ├─ いいえ → 問題6,7 → 設定確認 → gateway 再起動
   └─ はい → openclaw doctor で深掘り

4. よく使うコマンド早見表

プロセス・ポート確認

ps -ef | grep -i openclaw | grep -v grep
lsof -i :18789
lsof -i -P -n | grep LISTEN

Gateway 起動/停止

# foreground（ログを見たい時）
openclaw gateway run

# background（運用時）
nohup openclaw gateway run > /tmp/openclaw-gw.log 2>&1 &

# 停止（PID 1 ではない方）
kill <gateway PID>

# 占有プロセスごとkillして起動
openclaw gateway run --force

認証・デバイス管理

openclaw devices list
openclaw devices approve <requestId>
openclaw devices approve --latest
openclaw devices reject <requestId>
openclaw devices clear

設定・診断

openclaw gateway status
openclaw doctor
openclaw doctor --fix
cat /data/.openclaw/openclaw.json

ログ

tail -f /tmp/openclaw-gw.log
tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log
openclaw logs

Dashboard URL取得

openclaw dashboard           # トークン付きURLを表示
openclaw dashboard --no-open # 開かずURLだけ

5. ハマりどころ

落とし穴	注意点
openclaw gateway stop	lsof/fuserが無い環境では実プロセスを掃除せず、サービス登録だけ無効化して終了
--force フラグ	lsof か fuser のどちらかに依存。両方無いと無力
TIME_WAIT	--force でも回避不可。別ポート起動か時間経過しかない
device pairing	トークン認証とは別物。#token=... だけでは入れない
scope upgrade pending	ペアリング承認の副産物。放置するとgateway認証破綻
PID 1 を kill	Railway の node src/server.js を殺すとコンテナごと落ちる
dashboard コマンド	ポート指定オプションがない。CLI環境では auto-auth URL を発行できない
openai/claude-opus-4-7	存在しないモデル名。anthropic/... に修正必須

6. 恒久対策

Dockerfileに追記

RUN apt-get update && apt-get install -y --no-install-recommends \
    psmisc lsof iproute2 \
    && rm -rf /var/lib/apt/lists/*

これでフェーズ1〜3は自動で解消。

Gateway 自動再起動

node src/server.js (PID 1) は openclaw を 自動再起動しない。落ちると gateway停止＝全停止。対策:

• tini -- openclaw gateway run で init系プロセスマネージャを噛ませる
• PM2 / supervisord を導入
• エントリーポイント側で子プロセス死亡時の再起動ロジックを実装

ペアリング運用

• ペアリング承認時に出る scope upgrade pending も 必ず一緒に承認 する
• 起動直後に openclaw devices list で pending を確認するルーチンを習慣化

環境変数

Railway の Variables で以下を設定:

• OPENCLAW_GATEWAY_TOKEN: gateway認証トークン
• PORT: Railway公開ポート（通常 Railway が自動設定）

7. 接続URLの組み立て方

ブラウザでアクセスする際のURL:

https://<service>.up.railway.app/#token=<OPENCLAW_GATEWAY_TOKEN>

• ?token= ではなく #token=（URL fragment）
• フラグメントはサーバーに送信されずブラウザJSだけが読むのでログに残らない（セキュリティ）
• 設定の gateway.controlUi.allowInsecureAuth: true が有効ならこれで認証通過

WebSocket URL:

wss://<service>.up.railway.app/openclaw

8. デバッグ時のセオリー

1. 症状をエラーメッセージ完全一致で検索 → Slack共有/GitHub issueで既知問題か確認
2. ログをリアルタイムでtail しながらブラウザで操作を再現:

   tail -f /tmp/openclaw-gw.log
   

3. CLIでも同じ操作を再現 → CLI/ブラウザ両方で発生するなら認証/scope問題、ブラウザだけならネットワーク/URL問題
4. Gateway再起動は最後の手段 だが効果は確実。kill対象を間違えないこと

9. 関連リソース

• OpenClaw公式ドキュメント: https://docs.openclaw.ai/
• Gateway リモート接続ガイド: https://docs.openclaw.ai/gateway/remote
• Control UI: https://docs.openclaw.ai/web/control-ui
• トラブルシューティング: https://docs.openclaw.ai/troubleshooting