English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

CLI commands

シークレット

openclaw secrets

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

コマンドの役割:

  • reload: gateway RPC（secrets.reload）。参照を再解決し、完全成功時にのみランタイムスナップショットを切り替えます（config の書き込みなし）。
  • audit: 設定/auth/生成済みモデルストアおよびレガシー残留物を読み取り専用でスキャンし、平文、未解決の参照、優先順位ドリフトを検出します（--allow-exec が設定されていない限り exec 参照はスキップされます）。
  • configure: プロバイダー設定、ターゲットマッピング、事前チェック用の対話型プランナー（TTY 必須）。
  • apply: 保存済みプランを実行します（検証のみには --dry-run。dry-run はデフォルトで exec チェックをスキップし、書き込みモードでは --allow-exec が設定されていない限り exec を含むプランを拒否します）。その後、対象の平文残留物をスクラブします。

推奨オペレーターループ:

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

プランに exec SecretRef/プロバイダーが含まれている場合は、dry-run と書き込み apply コマンドの両方で --allow-exec を渡してください。

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

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

関連:

ランタイムスナップショットを再読み込みする

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

openclaw secrets reload
openclaw secrets reload --json
openclaw secrets reload --url ws://127.0.0.1:18789 --token <token>

注:

  • gateway RPC メソッド secrets.reload を使用します。
  • 解決に失敗した場合、gateway は最後に正常だったスナップショットを保持し、エラーを返します（部分的な有効化は行いません）。
  • JSON レスポンスには warningCount が含まれます。

オプション:

  • --url <url>
  • --token <token>
  • --timeout <ms>
  • --json

監査

OpenClaw 状態をスキャンして次を検出します。

  • 平文のシークレット保存
  • 未解決の参照
  • 優先順位ドリフト（auth-profiles.json の認証情報が openclaw.json の参照をシャドーイングしている状態）
  • 生成済み agents/*/agent/models.json の残留物（プロバイダーの apiKey 値および機密性のあるプロバイダーヘッダー）
  • レガシー残留物（レガシー auth ストアエントリ、OAuth リマインダー）

ヘッダー残留物に関する注記:

  • 機密性のあるプロバイダーヘッダー検出は、名前ヒューリスティックに基づいています（一般的な auth/credential ヘッダー名と、authorization、x-api-key、token、secret、password、credential などの断片）。
openclaw secrets audit
openclaw secrets audit --check
openclaw secrets audit --json
openclaw secrets audit --allow-exec

終了動作:

  • --check は検出事項があると非ゼロで終了します。
  • 未解決の参照は、より優先度の高い非ゼロコードで終了します。

レポート形状の主な項目:

  • status: clean | findings | unresolved
  • resolution: refsChecked, skippedExecRefs, resolvabilityComplete
  • summary: plaintextCount, unresolvedRefCount, shadowedRefCount, legacyResidueCount
  • 検出コード:
    • PLAINTEXT_FOUND
    • REF_UNRESOLVED
    • REF_SHADOWED
    • LEGACY_RESIDUE

設定する（対話型ヘルパー）

プロバイダーと 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 つのエージェントストアに限定します。
  • --allow-exec: 事前チェック/適用時の exec SecretRef チェックを許可します（プロバイダーコマンドを実行する場合があります）。

注:

  • 対話型 TTY が必要です。
  • --providers-only と --skip-provider-setup は組み合わせできません。
  • configure は openclaw.json 内のシークレットを保持するフィールドと、選択したエージェントスコープの auth-profiles.json を対象にします。
  • configure は picker フロー内で新しい auth-profiles.json マッピングの直接作成をサポートします。
  • 正式にサポートされるサーフェス: SecretRef Credential Surface。
  • 適用前に事前解決を実行します。
  • 事前チェック/適用に exec 参照が含まれる場合は、両方のステップで --allow-exec を設定したままにしてください。
  • 生成されたプランでは、デフォルトでスクラブオプション（scrubEnv、scrubAuthProfilesForProviderTargets、scrubLegacyAuthJson がすべて有効）が使われます。
  • 適用パスは、スクラブされた平文値に対して一方向です。
  • --apply がない場合でも、事前チェック後に Apply this plan now? が CLI で確認されます。
  • --apply があり（かつ --yes がない）場合、CLI は追加の不可逆確認を求めます。
  • --json はプラン + 事前チェックレポートを出力しますが、このコマンドには引き続き対話型 TTY が必要です。

exec プロバイダー安全性に関する注記:

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

保存済みプランを適用する

以前に生成したプランを適用または事前チェックします。

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

exec 動作:

  • --dry-run はファイルを書き込まずに事前チェックを検証します。
  • dry-run では、exec SecretRef チェックはデフォルトでスキップされます。
  • 書き込みモードでは、--allow-exec が設定されていない限り、exec SecretRef/プロバイダーを含むプランを拒否します。
  • どちらのモードでも、exec プロバイダーチェック/実行に明示的に同意するには --allow-exec を使用してください。

プラン契約の詳細（許可されるターゲットパス、検証ルール、失敗セマンティクス）:

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

  • openclaw.json（SecretRef ターゲット + プロバイダー upsert/delete）
  • auth-profiles.json（プロバイダーターゲットのスクラブ）
  • レガシー auth.json の残留物
  • 値が移行された ~/.openclaw/.env の既知のシークレットキー

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

secrets apply は、古い平文値を含むロールバックバックアップを意図的に書き込みません。

安全性は、厳格な事前チェック + 障害時の best-effort なインメモリ復元を伴う、ほぼアトミックな適用によって確保されます。

例

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

audit --check がまだ平文の検出事項を報告する場合は、報告された残りのターゲットパスを更新し、再度監査を実行してください。

関連