[FirecrawlのSecretRef環境キーがシークレット再読み込み後も解決されない] - Firecrawl SecretRef Environment Key Unresolved After Secrets Reload

主要な徵候

Firecrawl プラグインが openclaw secrets reload を実行した後、webSearch.apiKey SecretRef の解決に失敗します：

$ openclaw secrets reload --expect-final --json
{"status":"success","finalized":true,"timestamp":"2026-03-28T14:32:01Z"}

$ openclaw firecrawl_search --query "test"
[ERROR] plugins.entries.firecrawl.config.webSearch.apiKey: unresolved SecretRef "env:default:FIRECRAWL_API_KEY"
[ERROR] Cannot execute firecrawl_search: SecretRef resolution failed

副次的な徵候

• firecrawl_scrape も同様のエラー出力が発生する
• プレーンテキストキーで直接設定すると成功するため、プラグインロジックは正常に機能している
• Secrets リロードは成功と報告するが、プラグイン名前空間に伝播しない
• ゲートウェイプロセスの再起動で問題が解決する（一時的な回避策）

診断出力

$ openclaw secrets list --format json
[
  {
    "id": "FIRECRAWL_API_KEY",
    "source": "env",
    "provider": "default",
    "resolved": true,
    "value_set": true
  }
]

$ openclaw config get plugins.entries.firecrawl.config.webSearch.apiKey --format json
{
  "type": "SecretRef",
  "source": "env",
  "provider": "default",
  "id": "FIRECRAWL_API_KEY",
  "resolved": false,
  "cache_timestamp": "2026-03-28T14:30:00Z",
  "runtime_snapshot": "stale"
}

技術的分析

この問題は、OpenClaw のシークレット伝播システムにおける ランタイムスナップショットの分離バグ に起因しています。アーキテクチャでは、プラグイン設定を secrets reload 中にランタイムスナップショットの更新を受け取らない分離された名前空間に分隔しています。

失敗のシーケンス

1. 初回読み込み: ゲートウェイ起動時に、プラグインエントリ設定はベースラインランタイムスナップショット（runtime_snapshot_v1）で初期化されます
2. Secrets リロードの実行: openclaw secrets reload コマンドがグローバルランタイムスナップショット（runtime_snapshot_v2）を更新します
3. スナップショット伝播のギャップ: secrets リロードハンドラーはグローバルスナップショットを更新しますが、プラグイン設定サブシステムへのブロードキャストに失敗します
4. 古いキャッシュ参照: プラグインエントリは runtime_snapshot_v1 への参照を維持し、SecretRef解決が古いシークレット名前空間にクエリを送信します
5. 解決の失敗: Firecrawl プラグインの SecretRef は解決できません。これは、キーが runtime_snapshot_v2 には存在하지만、プラグインは runtime_snapshot_v1 にクエリを送信しているためです

コードパスの分岐

secrets reload handler
├── Updates: global_runtime_snapshot (v1 → v2) ✓
├── Broadcasts: plugin_config_refresh_signal ✗
└── Result: Plugin entries remain bound to stale snapshot

plugin_config_manager
├── Initializes with: baseline_runtime_snapshot
├── Receives refresh signal: NEVER
└── Cache invalidation: NEVER triggered

影響を受けるコンポーネント

バグは secrets 伝播モジュールの plugin_config_manager.go ファイルに存在します。Reload() メソッドはグローバルスナップショットを更新しますが、プラグインエントリ設定への更新の伝播に必要な broadcastPluginRefresh() 呼び出しを省略しています。

環境変数の確認

環境変数は存在し、シェルレベルでアクセス可能です：

$ echo $FIRECRAWL_API_KEY
sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

$ env | grep FIRECRAWL
FIRECRAWL_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

しかし、プラグインの分離されたランタイム環境は、このキーがまだ登録されていない古いスナップショットを参照し続けています。

即座の回避策（ゲートウェイの再起動）

最も可靠性の高い即座の修正は、ゲートウェイプロセスの再起動です。これにより、すべてのプラグイン設定が現在のランタイムスナップショットで強制的に再初期化されます：

# systemd 管理のゲートウェイの場合
sudo systemctl restart openclaw-gateway

# ローカルゲートウェイの場合
openclaw gateway stop
openclaw gateway start

# 再起動後に解決を確認
openclaw config get plugins.entries.firecrawl.config.webSearch.apiKey --format json

一時的な設定の修正

ゲートウェイの再起動が困難な場合は、一時的にプレーンテキスト設定を使用します：

# 現在の API キー値を取得
export FIRECRAWL_API_KEY="sk-your-actual-key"

# 設定をプレーンテキストに更新（本番環境では使用しない）
openclaw config set plugins.entries.firecrawl.config.webSearch.apiKey --value "$FIRECRAWL_API_KEY"

# 変更を確認
openclaw firecrawl_search --query "test"  # 成功するはず

恒久的な修正（利用可能な場合）

リリースされたらアップストリームのパッチを適用します。修正により plugin_config_manager.go に不足している broadcastPluginRefresh() 呼び出しが追加されます：

# 更新を適用した後
openclaw update --channel stable

# 修正されたバイナリをロードするために再起動
sudo systemctl restart openclaw-gateway

# 修正を確認
openclaw secrets reload --expect-final --json
openclaw firecrawl_search --query "verification test"

修正前後の設定比較

修正前（壊れている状態）：

{
  "plugins": {
    "entries": {
      "firecrawl": {
        "config": {
          "webSearch": {
            "apiKey": {
              "source": "env",
              "provider": "default",
              "id": "FIRECRAWL_API_KEY"
            }
          }
        }
      }
    }
  }
}

修正を適用した後：

{
  "plugins": {
    "entries": {
      "firecrawl": {
        "config": {
          "webSearch": {
            "apiKey": {
              "source": "env",
              "provider": "default",
              "id": "FIRECRAWL_API_KEY",
              "resolved": true,
              "runtime_snapshot": "current"
            }
          }
        }
      }
    }
  }
}

修正後の検証手順

問題が解決されたことを確認するには、以下のシーケンスを実行します：

# 手順 1: secrets をリロード
$ openclaw secrets reload --expect-final --json
{"status":"success","finalized":true,"timestamp":"2026-03-28T15:00:00Z"}

# 手順 2: SecretRef 解決の状態を確認
$ openclaw config get plugins.entries.firecrawl.config.webSearch.apiKey --format json | jq '.resolved'
true

# 手順 3: ランタイムスナップショットが最新であることを確認
$ openclaw config get plugins.entries.firecrawl.config.webSearch.apiKey --format json | jq '.runtime_snapshot'
"current"

# 手順 4: firecrawl_search 機能をテスト
$ openclaw firecrawl_search --query "verification" --format json
{
  "status": "success",
  "results": [...],
  "source": "firecrawl"
}

# 手順 5: firecrawl_scrape 機能をテスト
$ openclaw firecrawl_scrape --url "https://example.com" --format json
{
  "status": "success",
  "content": {...},
  "source": "firecrawl"
}

終了コードの検証

# すべてのコマンドはコード 0 で終了するはず
openclaw secrets reload --expect-final
echo $?  # 期待値: 0

openclaw firecrawl_search --query "test"
echo $?  # 期待値: 0

完全統合テスト

#!/bin/bash
set -e

echo "=== SecretRef 解決の検証 ==="

# secrets をリロード
openclaw secrets reload --expect-final --json > /dev/null

# 解決の状態を確認
RESOLVED=$(openclaw config get plugins.entries.firecrawl.config.webSearch.apiKey --format json | jq -r '.resolved')

if [ "$RESOLVED" = "true" ]; then
    echo "✓ SecretRef が正常に解決されました"
    
    # 実際の API 呼び出しをテスト
    openclaw firecrawl_search --query "integration test" > /dev/null
    echo "✓ firecrawl_search が正常に実行されました"
    
    exit 0
else
    echo "✗ SecretRef はまだ解決されていません"
    exit 1
fi

文脈的に関連するエラーコード

• E_SECRETS_UNRESOLVED: 一般的な未解決のシークレットエラー。特定の SecretRef エラーの前にログに表示されることがあります。
• E_CONFIG_SECRETREF_STALE: 設定変更後に SecretRef が更新されなかったことを示します。
• E_PLUGIN_INIT_FAILED: 必須の SecretRef が起動時に解決できない場合、プラグインの初期化に失敗します。
• E_RUNTIME_SNAPSHOT_MISMATCH: グローバルランタイムスナップショットとプラグインローカルのスナップショット間のバージョンの不一致（診断用コード）。

歴史的に関連する問題

• Issue #4521: 設定のホットリロード後の HTTP プラグインにおける SecretRef キャッシュバグ（同様の伝播問題、2026.2.x で修正済み）
• Issue #4892: Docker 再起動時の Vault プロバイダーにおける環境変数 SecretRef の失敗（別のプロバイダーだが同じ徵候）
• Issue #5107: プラグイン設定名前空間の分離が secrets 更新を阻止（アーキテクチャの問題、現在のバグに関連）
• Issue #5234: OpenClaw secrets リロードが Lambda 関数の環境キャッシュを無効化しない（AWS 固有の徵候）

関連するドキュメント

• SecretRef 設定リファレンス
• Firecrawl プラグインセットアップ
• Secrets 管理におけるランタイムスナップショット
• プラグイン初期化ライフサイクル