正規の xAI 認証パスで未解決の SecretRef 导致 x_search が失敗する

主なエラーの症状

組み込みのx_searchツールを、標準的なプラグイン所有のパスに設定されたexec SecretRefとしてxAI認証情報を設定して呼び出すと、以下のエラーレスポンスとともに操作が即座に失敗します：

{
  "status": "error",
  "tool": "x_search",
  "error": "plugins.entries.xai.config.webSearch.apiKey: unresolved SecretRef \"exec:onepassword_xai:value\". Resolve this command against an active gateway runtime snapshot before reading it."
}

CLIによる再現手順

# gateway CLI経由でx_searchを呼び出す
$ clawctl tools invoke x_search --input '{"query": "latest OpenClaw release notes"}'

# 期待結果: 正常な検索レスポンス
# 実際の結果: 未解決のSecretRefエラー

{
  "status": "error",
  "tool": "x_search",
  "error": "plugins.entries.xai.config.webSearch.apiKey: unresolved SecretRef \"exec:onepassword_xai:value\". Resolve this command against an active gateway runtime snapshot before reading it."
}

設定コンテキスト

4月以前、同じインフラストラクチャで正常に動作していた以下の設定形状で失敗が発生します：

{
  "tools": {
    "web": {
      "search": {
        "provider": "brave"
      },
      "x_search": {
        "enabled": true,
        "model": "grok-4-1-fast-non-reasoning",
        "maxTurns": 2,
        "timeoutSeconds": 30,
        "cacheTtlMinutes": 15
      }
    }
  },
  "plugins": {
    "entries": {
      "xai": {
        "config": {
          "webSearch": {
            "apiKey": {
              "source": "exec",
              "provider": "onepassword_xai",
              "id": "value"
            }
          }
        }
      }
    }
  }
}

環境詳細

• OpenClawバージョン: 2026.4.10 (commit 44e5b62)
• OS: macOS 25.3.0 (arm64)
• インストール方法: global npm install / local gateway service
• インストールタイプ: 1Passwordプロバイダ経由のexec SecretRef

混乱を招く観察事項

以下の理由からエラーが持続します：

• web_searchはbraveプロバイダを使用するように設定されている（xAIではない）
• xAI認証情報は標準的なプラグイン所有のパスに存在している
• 同じ設定は4月のxAIリファクタリング以前正常に動作していた

アーキテクチャのコンテキスト: 4月のxAIリファクタリング

この問題は、2026年4月のリファクタリングで導入された一連の破壊的変更に起因します：

1. Issue #59674 — x_search設定をxAIプラグイン境界の裏側に移動し、トップレベルのツールではなくプラグイン所有の機能にしました。
2. Issue #59691 — x_search認証をプラグイン所有にし、直接のツール設定ではなくxAIプラグインの設定パスを介して認証情報をフローさせることを必須にしました。

根本原因: Execプロバイダにおけるランタイムスナップショットのstaleness

具体的な失敗メカニズムは、プラグイン所有の認証に対してgatewayランタイムがexec SecretRefsを解決する方法における、レース条件またはスナップショットのstalenessを含みます：

1. スナップショットの初期化: gatewayが起動すると、すべての設定（包括的にSecretRefs）の解決済み値を含むランタイムスナップショットが作成されます。
2. Execプロバイダのタイミング: Execプロバイダ（1Passwordなど）は、シークレットを取得するために外部コマンドの実行を必要とします。これらはスナップショットの作成時に解決されます。
3. 初期化後のアクセス: x_searchツールパスは、最初のスナップショット作成時ではなくツール実行時にplugins.entries.xai.config.webSearch.apiKeyにアクセスします。
4. 古い参照: スナップショットの作成以降execプロバイダコマンドの出力が変更されている場合（またはスナップショットがプラグイン所有のパスに対して適切に初期化されていない場合）、SecretRefは未解決として表示されます。

コードパス分析

失敗はこの実行シーケンスで発生します：

x_search tool invocation
  → xAI plugin-owned auth path
  → plugins.entries.xai.config.webSearch.apiKey
  → SecretRef resolution check
  → Runtime snapshot lookup for "exec:onepassword_xai:value"
  → Result: UNRESOLVED (snapshot doesn't contain active value)

なぜこれはリグレッションなのか

4月のリファクタリング以前：

• x_searchはプラグイン所有の認証情報の解決を必要としない直接の認証パスを使用していた
• Exec SecretRefsはスナップショット依存の時間ではなく、ツール呼び出し時に解決されていた
• 解決パスがプラグイン境界を通過しなかったため、同じ1Password execコマンドが動作していた

4月以降：

• x_searchは完全にプラグイン所有になった
• 認証解決はgatewayランタイムスナップショットに対して実行される
• Exec SecretRefsは、スナップショットが現在の解決済み値を含まない場合「未解決」として評価される

関連 이슈

このリグレッションは、より広範なランタイムスナップショット / SecretRef解決の問題に接続しています：

• #50161 — gatewayランタイムでの一般的な未解決SecretRef処理
• #51263 — 動的プロバイダでのスナップショットstaleness
• #57272 — Execプロバイダのキャッシュと新鮮な解決
• #54555 — 欠落しているxAI APIキーの検出（関連する認証 поверхности）

オプションA: 静的なSecretRefの使用（本番環境推奨）

exec SecretRefを、ランタイムコマンドの実行を必要としない静的参照に置き換えます：

{
  "plugins": {
    "entries": {
      "xai": {
        "config": {
          "webSearch": {
            "apiKey": {
              "source": "static",
              "value": "${XAI_API_KEY}"
            }
          }
        }
      }
    }
  }
}

次に、環境変数を設定します：

# シェルプロファイルまたはgateway環境に追加
export XAI_API_KEY="xai-your-actual-api-key-here"

# またはgateway起動時に注入
XAI_API_KEY="xai-your-actual-api-key-here" clawctl gateway start

オプションB: インライン静的値（開発のみ）

開発/テスト用には、configに直接インライン静的値を使用します：

{
  "plugins": {
    "entries": {
      "xai": {
        "config": {
          "webSearch": {
            "apiKey": {
              "source": "inline",
              "value": "xai-your-actual-api-key-here"
            }
          }
        }
      }
    }
  }
}

オプションC: スナップショットの強制更新（回避策）

execプロバイダを使用する必要がある場合は、gatewayスナップショットの強制更新を行います：

# gatewayを停止
clawctl gateway stop

# ランタイムスナップショットキャッシュをクリア
rm -rf ~/.config/openclaw/runtime/snapshots/
rm -rf ~/.local/share/openclaw/snapshots/

# gatewayを再起動（新しいスナップショットが作成される）
clawctl gateway start

# スナップショットが新しいことを確認
clawctl gateway status --verbose

次にテストします：

clawctl tools invoke x_search --input '{"query": "test"}'

オプションD: ネイティブシークレットプロバイダへの移行

1Passwordを使用している場合、execコマンドを必要としないネイティブOpenClaw 1Password統合に移行します：

{
  "plugins": {
    "entries": {
      "xai": {
        "config": {
          "webSearch": {
            "apiKey": {
              "source": "onepassword",
              "vault": "openclaw-secrets",
              "item": "xai-api-key",
              "field": "api_key"
            }
          }
        }
      }
    }
  }
}

変更前後の設定

変更前（失敗）

{
  "plugins": {
    "entries": {
      "xai": {
        "config": {
          "webSearch": {
            "apiKey": {
              "source": "exec",
              "provider": "onepassword_xai",
              "id": "value"
            }
          }
        }
      }
    }
  }
}

変更後（正常動作）

{
  "plugins": {
    "entries": {
      "xai": {
        "config": {
          "webSearch": {
            "apiKey": {
              "source": "static",
              "value": "${XAI_API_KEY}"
            }
          }
        }
      }
    }
  }
}

ステップ1: Gatewayが実行中であることを確認

$ clawctl gateway status

Gateway Status: RUNNING
Version: 2026.4.10 (44e5b62)
Runtime: Active
Snapshot: Valid (created: 2026-04-XX XX:XX:XX)

ステップ2: xAIプラグイン設定を確認

$ clawctl config get plugins.entries.xai.config.webSearch.apiKey

{
  "source": "static",
  "value": "${XAI_API_KEY}"
}

ステップ3: 環境変数が設定されていることを確認

$ echo $XAI_API_KEY | head -c 10 && echo "..."

xai-sk-12...

ステップ4: x_searchツール呼び出しをテスト

$ clawctl tools invoke x_search --input '{"query": "OpenClaw troubleshooting guide"}'

{
  "status": "success",
  "tool": "x_search",
  "results": {
    "query": "OpenClaw troubleshooting guide",
    "results": [
      {
        "title": "OpenClaw Professional Troubleshooting Guide",
        "url": "https://docs.openclaw.io/guides/troubleshooting",
        "snippet": "..."
      }
    ],
    "model": "grok-4-1-fast-non-reasoning",
    "tokensUsed": 142
  }
}

ステップ5: 終了コードを確認

$ echo $?
0

正常に動作したx_search呼び出しは終了コード0を返します。

ステップ6: ログにSecretRefエラーがないことを確認

$ clawctl logs --tail 50 | grep -E "(x_search|SecretRef|xai)"

# 正常な解決が表示され、未解決エラーがないはず:
[INFO] x_search: Tool invocation successful
[INFO] xai.plugin: Credential resolved successfully

ステップ7: プラグイン認証情報の解決を確認

$ clawctl debug resolve-secret --path plugins.entries.xai.config.webSearch.apiKey

Resolved: true
Value Preview: xai-sk-12****
Source: static (env: XAI_API_KEY)
TTL: Persistent

1. Gatewayサービスとユーザーシェル環境の不一致

問題: シェルに設定した環境変数は、gatewayサービスデーモンでは利用できません。

# これはあなたのシェルに変数を設定します:
export XAI_API_KEY="xai-..."

# しかしGATEWAY SERVICEは別のコンテキストで実行されます:
# システム全体で設定されていない限り、この変数は見えません

解決策: gatewayサービス用に環境変数を設定します：

# launchd (macOS) の場合
# /Library/LaunchDaemons/com.openclaw.gateway.plist を編集
<key>EnvironmentVariables</key>
<dict>
    <key>XAI_API_KEY</key>
    <string>xai-...</string>
</dict>

# systemd (Linux) の場合
# /etc/systemd/system/openclaw-gateway.service.d/override.conf を作成
[Service]
Environment="XAI_API_KEY=xai-..."

2. 設定変更後にスナップショットが更新されていない

問題: execからstatic SecretRefへの変更は、スナップショットの更新まで有効になりません。

解決策:

# 設定変更後は常にgatewayを再起動
clawctl gateway restart

# またはスナップショットの強制更新
clawctl gateway snapshot --refresh

3. プラグインが有効になっていない

問題: xAIプラグインは明示的に有効にする必要があり、プラグイン所有のx_searchが機能するにはプラグインがアクティブな必要があります。

解決策:

# xAIプラグインが有効になっていることを確認
clawctl plugins list --enabled

# 有効になっていない場合:
clawctl plugins enable xai

4. バージョンの不一致

問題: 4月のリファクタリング（x_searchプラグイン所有）はOpenClaw 2026.4.0以降が必要です。

解決策:

# 現在のバージョンを確認
clawctl --version

# 必要に応じて更新
npm update -g @openclaw/cli
clawctl self-update

5. Execプロバイダのタイムアウト

問題: 1Password CLIの実行に時間がかかりすぎると、exec SecretRefsがスナップショットの作成中にタイムアウトします。

解決策: execプロバイダにタイムアウト設定を追加します：

{
  "providers": {
    "exec": {
      "onepassword_xai": {
        "command": "op read op://.../api_key/value",
        "timeout": 10000
      }
    }
  }
}

6. macOS Gatekeeper/コード署名問題

問題: macOSでは、1Password CLI（op）が適切に署名されていない場合、Gatekeeperによってブロックされることがあります。

解決策:

# opバイナ리가許可されていることを確認
xattr -l /usr/local/bin/op
# com.apple.quarantine が表示されないはず

# 検疫されている場合、削除:
xattr -d com.apple.quarantine /usr/local/bin/op

7. Docker/コンテナ環境での環境変数

問題: 環境変数はコンテナに明示的に渡す必要があります。

解決策:

# Dockerコンテナにenv変数を渡す
docker run -e XAI_API_KEY="xai-..." openclaw/gateway:latest

# またはdocker-compose.ymlを使用
environment:
  - XAI_API_KEY=xai-...

• UNRESOLVED_SECRET_REF — SecretRefが現在のランタイムスナップショットに対して解決できない場合の一般的なエラー。unresolved SecretRef "exec:provider:id"として表示されます。Issue #50161、#51263を参照。
• MISSING_XAI_API_KEY — xAI認証情報が設定に存在しないことを示します。形式に関係なく、認証情報が存在しても標準的なプラグイン所有のパスにない場合に発生する可能性があります。Issue #54555を参照。
• SNAPSHOT_STALE — ランタイムスナップショットに古い値が含まれており、更新が必要です。SecretRef解決の失敗と同時に発生することが多いです。
• PLUGIN_NOT_INITIALIZED — xAIプラグインがロードまたは有効になっていません。x_searchはプラグインがアクティブである必要があります。
• EXEC_PROVIDER_TIMEOUT — exec SecretRefの外部コマンドがタイムアウトを超えました。op（1Password CLI）コマンドが遅いまたはブロックされている可能性があります。
• INVALID_SECRET_REF_FORMAT — SecretRefが予期されるsource:provider:id形式に準拠していません。
• GATEWAY_NOT_RUNNING — gatewayサービスが停止しているときにツールを呼び出せません。clawctl gateway statusがRUNNINGを表示していることを確認してください。

過去の問題

ドキュメント参照

• OpenClaw Secrets Management
• xAI Plugin Configuration
• x_search Tool Reference
• Runtime Snapshots