Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
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 を含むプランを拒否します）。その後、対象の平文残留物をスクラブします。
exec SecretRef/プロバイダーが含まれている場合は、dry-run と書き込み apply コマンドの両方で --allow-exec を渡してください。
CI/ゲート向けの終了コードに関する注記:
audit --checkは検出事項があると1を返します。- 未解決の参照は
2を返します。
- シークレットガイド: Secrets Management
- 認証情報サーフェス: SecretRef Credential Surface
- セキュリティガイド: Security
ランタイムスナップショットを再読み込みする
シークレット参照を再解決し、ランタイムスナップショットをアトミックに切り替えます。- 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などの断片）。
--checkは検出事項があると非ゼロで終了します。- 未解決の参照は、より優先度の高い非ゼロコードで終了します。
status:clean | findings | unresolvedresolution:refsChecked,skippedExecRefs,resolvabilityCompletesummary:plaintextCount,unresolvedRefCount,shadowedRefCount,legacyResidueCount- 検出コード:
PLAINTEXT_FOUNDREF_UNRESOLVEDREF_SHADOWEDLEGACY_RESIDUE
設定する（対話型ヘルパー）
プロバイダーと SecretRef の変更を対話的に構築し、事前チェックを実行し、必要に応じて適用します。- 最初にプロバイダー設定（
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 が必要です。
- Homebrew インストールでは、しばしば
/opt/homebrew/bin/*配下にシンボリックリンクされたバイナリが公開されます。 allowSymlinkCommand: trueは、信頼されたパッケージマネージャーパスで必要な場合にのみ設定し、trustedDirs（例:["/opt/homebrew"]）と組み合わせてください。- Windows では、プロバイダーパスの ACL 検証が利用できない場合、OpenClaw は closed で失敗します。信頼できるパスに限り、そのプロバイダーで
allowInsecurePath: trueを設定するとパスセキュリティチェックをバイパスできます。
保存済みプランを適用する
以前に生成したプランを適用または事前チェックします。--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 なインメモリ復元を伴う、ほぼアトミックな適用によって確保されます。
例
audit --check がまだ平文の検出事項を報告する場合は、報告された残りのターゲットパスを更新し、再度監査を実行してください。