`openclaw secrets`

openclaw secrets を使用してSecretRefを管理し、アクティブなランタイムスナップショットを健全に保ちます。

コマンドの役割:

reload: ゲートウェイRPC（secrets.reload）で参照を再解決し、完全に成功した場合のみランタイムスナップショットを入れ替えます（設定ファイルへの書き込みなし）。
audit: 設定/認証/生成モデルストアおよびレガシー残留データの読み取り専用スキャン。プレーンテキスト、未解決の参照、優先順位のドリフトを検出します。
configure: プロバイダセットアップ、ターゲットマッピング、プリフライトのための対話式プランナー（TTY必須）。
apply: 保存済みプランを実行し（--dry-run でバリデーションのみ）、対象のプレーンテキスト残留データをスクラブします。

推奨オペレータループ:

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets audit --check
openclaw secrets reload

CI/ゲート向けの終了コードに関する注意:

audit --check は検出項目がある場合 1 を返します。
未解決の参照は 2 を返します。

ランタイムスナップショットのリロード

シークレット参照を再解決し、ランタイムスナップショットをアトミックに入れ替えます。

openclaw secrets reload
openclaw secrets reload --json

補足:

ゲートウェイRPCメソッド secrets.reload を使用します。
解決に失敗した場合、ゲートウェイは最後の正常なスナップショットを保持しエラーを返します（部分的なアクティベーションなし）。
JSONレスポンスに warningCount が含まれます。

監査

OpenClawの状態をスキャンして以下を検出:

プレーンテキストでのシークレット保存
未解決の参照
優先順位のドリフト（auth-profiles.json のクレデンシャルが openclaw.json の参照をシャドウイング）
生成済み agents/*/agent/models.json の残留データ（プロバイダの apiKey 値と機密性のあるプロバイダヘッダー）
レガシー残留データ（レガシー認証ストアエントリ、OAuthリマインダー）

ヘッダー残留データに関する注意:

機密性のあるプロバイダヘッダーの検出は名前ヒューリスティックベースです（authorization、x-api-key、token、secret、password、credential などの一般的な認証/クレデンシャルヘッダー名およびフラグメント）。

openclaw secrets audit
openclaw secrets audit --check
openclaw secrets audit --json

終了動作:

--check は検出項目がある場合にゼロ以外で終了します。
未解決の参照はより高い優先度のゼロ以外コードで終了します。

レポート形式のハイライト:

status: clean | findings | unresolved
summary: plaintextCount、unresolvedRefCount、shadowedRefCount、legacyResidueCount
検出コード:
- PLAINTEXT_FOUND
- REF_UNRESOLVED
- REF_SHADOWED
- LEGACY_RESIDUE

configure（対話式ヘルパー）

プロバイダとSecretRefの変更を対話的に構築し、プリフライトを実行し、任意で適用します:

openclaw secrets configure
openclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.json
openclaw secrets configure --apply --yes
openclaw secrets configure --providers-only
openclaw secrets configure --skip-provider-setup
openclaw secrets configure --agent ops
openclaw secrets configure --json

フロー:

まずプロバイダセットアップ（secrets.providers エイリアスの add/edit/remove）。
次にクレデンシャルマッピング（フィールドを選択し {source, provider, id} 参照を割り当て）。
最後にプリフライトと任意の適用。

フラグ:

--providers-only: secrets.providers のみを設定し、クレデンシャルマッピングをスキップ。
--skip-provider-setup: プロバイダセットアップをスキップし、既存プロバイダにクレデンシャルをマッピング。
--agent <id>: auth-profiles.json ターゲットの検出と書き込みを1つのエージェントストアにスコープ限定。

補足:

対話式TTYが必要です。
--providers-only と --skip-provider-setup は併用できません。
configure は openclaw.json のシークレット保持フィールドと、選択されたエージェントスコープの auth-profiles.json を対象とします。
configure はピッカーフローで新しい auth-profiles.json マッピングの直接作成をサポートします。
正規のサポート対象サーフェス: SecretRef Credential Surface。
適用前にプリフライト解決を実行します。
生成されたプランはデフォルトでスクラブオプション（scrubEnv、scrubAuthProfilesForProviderTargets、scrubLegacyAuthJson すべて有効）を含みます。
適用パスはスクラブされたプレーンテキスト値に対して一方向です。
--apply なしの場合でも、プリフライト後に「このプランを今すぐ適用しますか？」とプロンプトが表示されます。
--apply あり（かつ --yes なし）の場合、追加の不可逆確認プロンプトが表示されます。

execプロバイダの安全性に関する注意:

Homebrewのインストールでは、/opt/homebrew/bin/* にシンボリックリンクされたバイナリが公開されることがよくあります。
信頼できるパッケージマネージャーのパスに必要な場合のみ allowSymlinkCommand: true を設定し、trustedDirs（例: ["/opt/homebrew"]）と組み合わせてください。
Windowsでは、プロバイダパスのACL検証が利用できない場合、OpenClawはクローズドに失敗します。信頼できるパスに限り、そのプロバイダに allowInsecurePath: true を設定してパスセキュリティチェックをバイパスできます。

保存済みプランの適用

以前に生成されたプランを適用またはプリフライトします:

openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --json

プラン規約の詳細（許可されるターゲットパス、バリデーションルール、失敗時のセマンティクス）:

Secrets Apply Plan Contract

apply が更新する可能性のあるもの:

openclaw.json（SecretRefターゲット + プロバイダのupsert/削除）
auth-profiles.json（プロバイダターゲットのスクラブ）
レガシー auth.json の残留データ
~/.openclaw/.env の移行済み値を持つ既知のシークレットキー

ロールバックバックアップがない理由

secrets apply は意図的に古いプレーンテキスト値を含むロールバックバックアップを書き込みません。

安全性は厳格なプリフライト + アトミックな適用（失敗時のベストエフォートのインメモリ復元）によって確保されています。

使用例

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets audit --check

audit --check でまだプレーンテキストの検出項目が報告される場合は、報告された残りのターゲットパスを更新し、auditを再実行してください。