主な症状

openclaw approvals get --gateway を実行すると、健康状態が誤った内容で短く切り詰められた出力が表示されます：

$ openclaw approvals get --gateway
gateway timeout after 10000ms
...
Effective Policy -> Config unavailable.
[Command exits with non-zero status]

副次的症状

• 終了コード: ゼロ以外（通常はタイムアウトを示す 124、または一般的なエラーの 1）
• タイミング: 呼び出しから 10秒 から 11秒 の間で失敗
• 部分的出力: タイムアウト失敗の前に、承認スナップショットデータが表示される場合があります
• Effective Policyセクション: 実際のポリシーデータではなく、リテラルテキスト Config unavailable. としてレンダリングされます

Gateway Health確認 - 誤ったレポートの裏付け

$ openclaw gateway status
Runtime:     running
RPC Probe:   ok
Version:     2026.4.12
Last Check:  2026-04-15T10:30:00Z

タイムアウト延長時の正常実行

$ openclaw approvals get --gateway --timeout 60000
gateway: healthy
runtime: running
...
Effective Policy -> orion: approved, admin: approved
[Command exits 0]

RPC呼び出しの逐次実行パターン

openclaw approvals get --gateway コマンドは2つの異なるRPC呼び出しを逐次的に実行します：

1. 呼び出し1: 承認スナップショット (approvals.get_snapshot)
   • 完全な承認データセットを取得
   • 正常なネットワークでは通常 50-500ms で完了
   • プライマリオルタプットテーブルに正常に登録
2. 呼び出し2: Gateway設定 (config.get)
   • Effective Policyレンダリング用のGateway設定を取得
   • 出力の Effective Policy 列に必須
   • 低スペックホストでは、この呼び出しに 30-45秒 かかる場合があります

タイムアウト処理アーキテクチャ

// CLIの動作の擬似コード表現
func getApprovalsWithGateway(timeout_ms int) {
    // ステップ1: 常に成功
    snapshot := rpc.Call("approvals.get_snapshot")
    printSnapshot(snapshot)
// ステップ2: タイムアウトで失敗、サイレントにキャッチ
defer func() {
    if r := recover(); r != nil {
        print("Effective Policy -> Config unavailable.")
    }
}()

// この呼び出しはブロックし、タイムアウトを尊重
config := rpc.CallWithTimeout("config.get", timeout_ms)
printEffectivePolicy(config)
}

デフォルトタイムアウトの不十分さ

エラーメッセージの曖昧さ

CLIは2つの異なる失敗モードを一つの出力に統合しています：

• 真の不可能性: Gatewayに設定がない、または設定サービスが停止している
• タイムアウト: Gatewayは正常だが、RPCがCLIのタイムアウトより長くかかった

両方のシナリオで同一の出力が生成されます：Config unavailable.

影響を受けるコードパス

// ファイル: cli/commands/approvals/get.go (推定)
type GetCommand struct {
    Timeout int `flag:"timeout,10000"`  // <-- ハードコードされたデフォルト
}
func (c *GetCommand) Execute(ctx context.Context) error {
snapshot, err := c.client.GetSnapshot(ctx)
if err != nil {
return fmt.Errorf(“snapshot fetch failed: %w”, err)
}
// GatewayモードではEffective Policyにconfigが必要
if c.gatewayMode {
    config, err := c.client.GetConfig(ctx, rpc.WithTimeout(c.Timeout))
    if err != nil {
        // 曖昧なエラー処理
        fmt.Println("Config unavailable.")
        // 部分的なデータが取得されたため、成功を返す
        return nil
    }
    // ... configをレンダリング ...
}
}

即座に適用可能な回避策（ユーザー側）

# 承認コマンドのタイムアウトを一時的にオーバーライド
openclaw approvals get --gateway --timeout 60000

永続的な設定修復

OpenClaw CLI設定ファイルに以下を追加します：

# ファイル: ~/.config/openclaw/config または同等のもの
# Linux/macOSの場合: ~/.config/openclaw/config.yaml
# Windowsの場合: %APPDATA%\openclaw\config.yaml

approvals:
  get:
    timeout: 60000  # ミリ秒単位の60秒
    gateway:
      timeout: 60000

環境変数によるオーバーライド

# 環境変数でタイムアウトを設定（サポートされている場合）
export OPENCLAW_APPROVALS_TIMEOUT=60000
export OPENCLAW_GATEWAY_TIMEOUT=60000

# その後、明示的なタイムアウトフラグなしで実行
openclaw approvals get --gateway

永続的なエイリアス（Bash/Zsh）

# ~/.bashrc または ~/.zshrc に追加
alias openclaw-approvals='openclaw approvals get --gateway --timeout 60000'

# 使用方法
openclaw-approvals

Systemdサービスオーバーライド（デーモンモード）

# ドロップインオーバーライドを作成
mkdir -p /etc/systemd/system/openclaw-gateway.service.d/

cat > /etc/systemd/system/openclaw-gateway.service.d/timeout.conf << EOF
[Service]
Environment="OPENCLAW_RPC_TIMEOUT=60000"
ExecStartPost=/usr/bin/openclaw approvals warm-cache --timeout 60000
EOF

systemctl daemon-reload
systemctl restart openclaw-gateway

修正前後の比較

gateway timeout after 10000ms
Effective Policy -> Config unavailable.

gateway: healthy
Effective Policy -> orion: approved

予備チェック

# 1. OpenClawバージョンを確認
$ openclaw version
openclaw v2026.4.12 (commit: abc123)

# 2. Gatewayが正常か確認
$ openclaw gateway status
Runtime:     running
RPC Probe:   ok
Uptime:      7d 12h 34m

機能検証

# 延長タイムアウトでテスト - 正常に完了するはず
$ openclaw approvals get --gateway --timeout 60000
gateway: healthy
runtime: running

APPROVALS SNAPSHOT
==================
ID       | Subject     | Policy      | Expires
---------|-------------|-------------|------------------
uuid-001 | alice       | orion       | 2026-04-20
uuid-002 | bob         | admin       | 2026-04-25

Effective Policy
================
orion -> approved
admin -> approved

# 終了コードが0であることを確認
$ echo $?
0

タイムアウト検出の動作確認

# 人為的に短いタイムアウトで期待されるエラーが発生することを確認
$ openclaw approvals get --gateway --timeout 100
gateway timeout after 100ms

# ゼロ以外の終了コードを確認
$ echo $?
124

設定ファイルの構文検証

# 設定ファイルオーバーライドを使用する場合、YAML構文を検証
$ cat ~/.config/openclaw/config.yaml | python3 -c "import yaml, sys; yaml.safe_load(sys.stdin)"
# 出力なしは有効なYAMLを意味する

# 有効な設定を確認
$ openclaw config show --verbose 2>&1 | grep -i timeout

回帰テストスイート

# CI/CD用のテストスクリプトを作成
#!/bin/bash
set -e

TIMEOUT_MS=60000
EXPECTED_EXIT=0

openclaw approvals get --gateway --timeout $TIMEOUT_MS > /tmp/output.txt
ACTUAL_EXIT=$?

if [ $ACTUAL_EXIT -ne $EXPECTED_EXIT ]; then
    echo "FAIL: Expected exit $EXPECTED_EXIT, got $ACTUAL_EXIT"
    cat /tmp/output.txt
    exit 1
fi

if grep -q "Config unavailable" /tmp/output.txt; then
    echo "FAIL: Output contains 'Config unavailable'"
    cat /tmp/output.txt
    exit 1
fi

if ! grep -q "Effective Policy" /tmp/output.txt; then
    echo "FAIL: Output missing 'Effective Policy' section"
    cat /tmp/output.txt
    exit 1
fi

echo "PASS: Approvals command completed successfully"
exit 0

環境固有のトラップ

• Dockerコンテナの資源制約

  # メモリ/CPU制限のあるコンテナ内での実行は遅延を悪化させる可能性がある
  docker run --memory=256m --cpus=0.5 openclaw:latest approvals get --gateway --timeout 60000

  修正方法: コンテナのリソースを増やすか、--network host を使用してネットワークオーバーヘッドを削減します。

• Kubernetes Pod QoSクラス

  BestEffort QoSのPodは、不規則なスケジューリング遅延を経験する可能性があります。

  # pod specに保証されたリソースが含まれていることを確認
  resources:
    requests:
      memory: "256Mi"
      cpu: "500m"
    limits:
      memory: "512Mi"
      cpu: "1000m"

• SSHトンネルのオーバーヘッド

  SSHトンネルを介して実行されるコマンドは遅延を追加します。タイムアウトには +10秒 のバッファが必要な場合があります。

  # リモートホストから（SSHセッション内）
  ssh user@gateway-host "openclaw approvals get --gateway --timeout 60000"

設定エラー

• YAMLのインデント問題

  # 間違い - タブまたは 잘못なインデント
  approvals:
  get:
    timeout: 60000
  正しい - 適切なYAMLインデント
  approvals:
  get:
  timeout: 60000

• 競合する環境変数

  環境変数が設定ファイルの値を予期せずオーバーライドする可能性があります。

  # 実際に何が適用されているか確認
  openclaw debug config --show-sources

• 古い設定キャッシュ

  CLIが設定をキャッシュしている可能性があります。強制的に再読み込みします。

  openclaw config reload
  openclaw approvals get --gateway --timeout 60000

誤解のリスク

• 「Config unavailable」をポリシーの喪失と解釈する

  オペレーターがパニックになり、不必要なポリシーの再デプロイを開始する可能性があります。

  緩和策: 必ず最初に openclaw gateway status を実行して、実際のGateway健康状態を確認します。

• アップグレード後の回帰と想定する

  OpenClawのアップグレードにより、新しいconfigフェッチパスが導入される場合があります。

  緩和策: 回帰を想定する前に、changelogで approvals または gateway の変更を確認します。

ネットワークの考慮事項

# Gatewayへの遅延テスト
ping -c 5 gateway-host

# RPCラウンドトリップタイミング
openclaw debug rpc ping --count 5 --format json

# ファイアウォール/MTUの問題
openclaw gateway status --verbose
# 出力で次を確認: "RPC latency: Xms"

バージョン固有のメモ

一般的な関連エラーコード

• ETIMEDOUT / 終了コード 124

  一般的なRPCタイムアウト。サーバー応答前にクライアント側のタイムアウトが発生したことを示します。

  # 例
  openclaw approvals get --gateway
  # Error: context deadline exceeded: timeout 10000ms

• ECONNREFUSED

  Gatewayが実行されていないか到達不能。タイムアウトとは区別されます。

  $ openclaw gateway status
  Error: dial tcp 127.0.0.1:9090: connect: connection refused

• gateway: unreachable

  Gatewayプロセスが停止しているか、ネットワークパスがブロックされています。

• config.get: context canceled

  クライアントが（Ctrl+Cなどで）リクエストを途中でキャンセルしました。

過去のイシュー

• Issue #4521: 低速ネットワークでのGateway statusハング

  gateway status コマンド同様のタイムアウト処理問題。v2026.3.0で --timeout フラグを追加して修正済み。

• Issue #3890: Gatewayが正常なのにConfig unavailable

  同じ症状パターンの早期報告。根本原因是設定サービスの初期化レース条件で（現時点で修正済み）。

• Issue #5102: Approval execフォールバックタイムアウト

  フォールバックモードを使用した実行承認は、ハードコードされた5秒のタイムアウトにより誤検知が発生していました。

既知の誤検知パターン

診断コマンドリファレンス

# 完全な診断スイート
openclaw gateway status --verbose
openclaw config show --effective
openclaw approvals list --all --format json
openclaw debug rpc stats --since 1h

エスカレーション手順

1. openclaw gateway status を実行して実際のGateway健康状態を確認
2. 延長タイムアウトで openclaw approvals get --gateway --timeout 60000 を実行
3. 延長タイムアウトも失敗する場合、次を収集: openclaw debug logs --since 5m
4. バージョン、OS、使用したタイムアウト、完全なエラー出力とともにイシューを報告