シークレット管理

OpenClaw は加算的な SecretRefs をサポートしているため、対応する認証情報を設定内に平文で保存する必要はありません。

目標とランタイムモデル

シークレットはメモリ内のランタイムスナップショットに解決されます。

• 解決はリクエストパス上で遅延実行されるのではなく、アクティベーション中に先行して実行されます。
• 実質的にアクティブな SecretRef を解決できない場合、起動は即座に失敗します。
• リロードはアトミックスワップを使用します。完全に成功するか、最後に正常だったスナップショットを保持します。
• SecretRef ポリシー違反（たとえば OAuth モードの認証プロファイルと SecretRef 入力の組み合わせ）は、ランタイムスワップ前のアクティベーションに失敗します。
• ランタイムリクエストは、アクティブなメモリ内スナップショットからのみ読み取ります。
• 最初の設定アクティベーション/読み込みが成功した後、ランタイムコードパスは、成功したリロードでスワップされるまで、そのアクティブなメモリ内スナップショットを読み続けます。
• 送信配信パスもそのアクティブなスナップショットから読み取ります（たとえば Discord の返信/スレッド配信や Telegram アクション送信）。送信ごとに SecretRefs を再解決しません。

これにより、シークレットプロバイダーの停止がホットリクエストパスに乗らないようになります。

エージェントアクセス境界

SecretRefs は、対応する設定と生成されたモデルサーフェスに認証情報が永続化されることを防ぎますが、プロセス分離の境界ではありません。平文の認証情報が、エージェントが読み取れるパスのディスク上に残っている場合、エージェントはファイルツールやシェルツールを使ってそのファイルを検査することで、API レベルの墨消しを迂回できます。

エージェントがアクセス可能なファイルが対象となる本番デプロイでは、次のすべてが true の場合にのみ SecretRef 移行が完了したものとして扱ってください。

• 対応する認証情報が平文値ではなく SecretRefs を使用している
• 旧来の平文残存が openclaw.json、auth-profiles.json、.env、生成された models.json ファイルから消去されている
• 移行後に openclaw secrets audit --check がクリーンである
• 残っている未対応またはローテーション中の認証情報が、オペレーティングシステム分離、コンテナ分離、または外部認証情報プロキシで保護されている

このため、audit/configure/apply ワークフローは単なる便利ヘルパーではなく、セキュリティ移行ゲートです。

アクティブサーフェスのフィルタリング

SecretRefs は、実質的にアクティブなサーフェスでのみ検証されます。

• 有効なサーフェス: 未解決の参照は起動/リロードをブロックします。
• 非アクティブなサーフェス: 未解決の参照は起動/リロードをブロックしません。
• 非アクティブな参照は、コード SECRETS_REF_IGNORED_INACTIVE_SURFACE で非致命的な診断を出力します。

Gateway 認証サーフェス診断

SecretRef が gateway.auth.token、gateway.auth.password、gateway.remote.token、または gateway.remote.password に設定されている場合、Gateway の起動/リロードはサーフェス状態を明示的にログ出力します。

• active: SecretRef は実効認証サーフェスの一部であり、解決される必要があります。
• inactive: 別の認証サーフェスが優先される、またはリモート認証が無効/非アクティブであるため、このランタイムでは SecretRef は無視されます。

これらのエントリは SECRETS_GATEWAY_AUTH_SURFACE とともにログ出力され、アクティブサーフェスポリシーで使用された理由を含むため、認証情報がなぜアクティブまたは非アクティブとして扱われたかを確認できます。

オンボーディング参照のプリフライト

オンボーディングが対話モードで実行され、SecretRef ストレージを選択した場合、OpenClaw は保存前にプリフライト検証を実行します。

• Env 参照: env var 名を検証し、セットアップ中に空でない値が見えていることを確認します。
• プロバイダー参照（file または exec）: プロバイダー選択を検証し、id を解決し、解決された値の型をチェックします。
• クイックスタート再利用パス: gateway.auth.token がすでに SecretRef の場合、オンボーディングはプローブ/ダッシュボードのブートストラップ前に、同じ fail-fast ゲートを使ってそれを解決します（env、file、exec 参照）。

検証に失敗すると、オンボーディングはエラーを表示し、再試行できるようにします。

SecretRef 契約

どこでも 1 つのオブジェクト形状を使用します。

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

{ source: "env", provider: "default", id: "OPENAI_API_KEY" }

"${OPENAI_API_KEY}""$OPENAI_API_KEY"

{ source: "file", provider: "filemain", id: "/providers/openai/apiKey" }

{ source: "exec", provider: "vault", id: "providers/openai/apiKey#value" }

プロバイダー設定

secrets.providers の下にプロバイダーを定義します。

{  secrets: {    providers: {      default: { source: "env" },      filemain: {        source: "file",        path: "~/.openclaw/secrets.json",        mode: "json", // or "singleValue"      },      vault: {        source: "exec",        command: "/usr/local/bin/openclaw-vault-resolver",        args: ["--profile", "prod"],        passEnv: ["PATH", "VAULT_ADDR"],        jsonOnly: true,      },      "team-secrets": {        source: "exec",        pluginIntegration: {          pluginId: "acme-secrets",          integrationId: "secret-store",        },      },    },    defaults: {      env: "default",      file: "filemain",      exec: "vault",    },    resolution: {      maxProviderConcurrency: 4,      maxRefsPerProvider: 512,      maxBatchBytes: 262144,    },  },}

{ "protocolVersion": 1, "provider": "vault", "ids": ["providers/openai/apiKey"] }

{ "protocolVersion": 1, "values": { "providers/openai/apiKey": "<openai-api-key>" } } // pragma: allowlist secret

{  "protocolVersion": 1,  "values": {},  "errors": { "providers/openai/apiKey": { "message": "not found" } }}

ファイルベースの API キー

設定の env ブロックに file:... 文字列を入れないでください。env ブロックはリテラルで、上書きしないため、file:... は解決されません。

代わりに、対応する認証情報フィールドで file SecretRef を使用してください。

{  secrets: {    providers: {      xai_key_file: {        source: "file",        path: "~/.openclaw/secrets/xai-api-key.txt",        mode: "singleValue",      },    },  },  models: {    providers: {      xai: {        apiKey: { source: "file", provider: "xai_key_file", id: "value" },      },    },  },}

mode: "singleValue" の場合、SecretRef id は "value" です。mode: "json" の場合は、"/providers/xai/apiKey" などの絶対 JSON ポインターを使用します。

SecretRefs を受け付ける設定フィールドについては、SecretRef 認証情報サーフェス を参照してください。

Exec 統合の例

{  secrets: {    providers: {      onepassword_openai: {        source: "exec",        command: "/opt/homebrew/bin/op",        allowSymlinkCommand: true, // required for Homebrew symlinked binaries        trustedDirs: ["/opt/homebrew"],        args: ["read", "op://Personal/OpenClaw QA API Key/password"],        passEnv: ["HOME"],        jsonOnly: false,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: { source: "exec", provider: "onepassword_openai", id: "value" },      },    },  },}

{  secrets: {    providers: {      bws: {        source: "exec",        command: "/usr/local/bin/openclaw-bws-resolver.mjs",        passEnv: ["BWS_ACCESS_TOKEN", "BWS_SERVER_URL", "PATH", "BWS_BIN"],        jsonOnly: true,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: {          source: "exec",          provider: "bws",          id: "openclaw/providers/openai/apiKey",        },      },    },  },}

openclaw secrets audit --allow-exec

{  secrets: {    providers: {      vault_openai: {        source: "exec",        command: "/opt/homebrew/bin/vault",        allowSymlinkCommand: true, // required for Homebrew symlinked binaries        trustedDirs: ["/opt/homebrew"],        args: ["kv", "get", "-field=OPENAI_API_KEY", "secret/openclaw"],        passEnv: ["VAULT_ADDR", "VAULT_TOKEN"],        jsonOnly: false,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: { source: "exec", provider: "vault_openai", id: "value" },      },    },  },}

#!/usr/bin/env nodeconst { spawnSync } = require("node:child_process"); let stdin = "";process.stdin.setEncoding("utf8");process.stdin.on("data", (chunk) => {  stdin += chunk;});process.stdin.on("error", (err) => {  process.stderr.write(`${err.message}\n`);  process.exit(1);});process.stdin.on("end", () => {  let request;  try {    request = JSON.parse(stdin || "{}");  } catch (err) {    process.stderr.write(`Failed to parse request: ${err.message}\n`);    process.exit(1);  }   const passBin = process.env.PASS_BIN || "pass";  const values = {};  const errors = {};   for (const id of request.ids ?? []) {    const result = spawnSync(passBin, ["show", id], { encoding: "utf8" });    if (result.status === 0) {      values[id] = result.stdout.split(/\r?\n/, 1)[0] ?? "";    } else {      errors[id] = { message: (result.stderr || `pass exited ${result.status}`).trim() };    }  }   process.stdout.write(JSON.stringify({ protocolVersion: 1, values, errors }));});

{  secrets: {    providers: {      pass_store: {        source: "exec",        command: "/usr/local/bin/openclaw-pass-resolver",        passEnv: ["PATH", "HOME", "GNUPGHOME", "GPG_TTY", "PASSWORD_STORE_DIR", "PASS_BIN"],        jsonOnly: true,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: {          source: "exec",          provider: "pass_store",          id: "openclaw/providers/openai/apiKey",        },      },    },  },}

openclaw secrets audit --checkopenclaw secrets audit --allow-exec

{  secrets: {    providers: {      sops_openai: {        source: "exec",        command: "/opt/homebrew/bin/sops",        allowSymlinkCommand: true, // required for Homebrew symlinked binaries        trustedDirs: ["/opt/homebrew"],        args: ["-d", "--extract", '["providers"]["openai"]["apiKey"]', "/path/to/secrets.enc.json"],        passEnv: ["SOPS_AGE_KEY_FILE"],        jsonOnly: false,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: { source: "exec", provider: "sops_openai", id: "value" },      },    },  },}

MCP サーバー環境変数

plugins.entries.acpx.config.mcpServers 経由で設定される MCP サーバー環境変数は SecretInput をサポートします。これにより、API キーとトークンを平文設定から除外できます。

{  plugins: {    entries: {      acpx: {        enabled: true,        config: {          mcpServers: {            github: {              command: "npx",              args: ["-y", "@modelcontextprotocol/server-github"],              env: {                GITHUB_PERSONAL_ACCESS_TOKEN: {                  source: "env",                  provider: "default",                  id: "MCP_GITHUB_PAT",                },              },            },          },        },      },    },  },}

平文文字列値も引き続き機能します。${MCP_SERVER_API_KEY} のような環境テンプレート参照と SecretRef オブジェクトは、MCP サーバープロセスが起動される前の gateway 有効化中に解決されます。他の SecretRef サーフェスと同様に、未解決の参照が有効化をブロックするのは、acpx Plugin が実質的にアクティブな場合のみです。

サンドボックス SSH 認証素材

コアの ssh サンドボックスバックエンドも、SSH 認証素材向けの SecretRef をサポートします。

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "ssh",        ssh: {          target: "user@gateway-host:22",          identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },          certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },          knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },        },      },    },  },}

ランタイム動作:

• OpenClaw は、各 SSH 呼び出し中に遅延解決するのではなく、サンドボックス有効化中にこれらの参照を解決します。
• 解決済みの値は制限付き権限の一時ファイルに書き込まれ、生成された SSH 設定で使用されます。
• 有効なサンドボックスバックエンドが ssh でない場合、これらの参照は非アクティブのままで、起動をブロックしません。

サポートされる認証情報サーフェス

正規のサポート対象およびサポート対象外の認証情報は、次に一覧化されています。

• SecretRef 認証情報サーフェス

必須動作と優先順位

• ref のないフィールド: 変更なし。
• ref のあるフィールド: 有効化中のアクティブサーフェスでは必須。
• 平文と ref の両方が存在する場合、サポートされる優先順位パスでは ref が優先されます。
• リダクションセンチネル __OPENCLAW_REDACTED__ は内部設定のリダクション/復元用に予約されており、送信された設定データのリテラルとしては拒否されます。

警告と監査シグナル:

• SECRETS_REF_OVERRIDES_PLAINTEXT (ランタイム警告)
• REF_SHADOWED (auth-profiles.json 認証情報が openclaw.json 参照より優先される場合の監査検出)

Google Chat 互換性動作:

• serviceAccountRef は平文の serviceAccount より優先されます。
• 兄弟 ref が設定されている場合、平文値は無視されます。

有効化トリガー

シークレットの有効化は次で実行されます。

• 起動時 (プリフライトと最終有効化)
• 設定リロードのホット適用パス
• 設定リロードの再起動チェックパス
• secrets.reload 経由の手動リロード
• 編集を永続化する前に、送信された設定ペイロード内のアクティブサーフェス SecretRef 解決可能性を確認する Gateway 設定書き込み RPC プリフライト (config.set / config.apply / config.patch)

有効化契約:

• 成功時はスナップショットをアトミックに入れ替えます。
• 起動失敗時は gateway 起動を中止します。
• ランタイムリロード失敗時は、最後に正常だったスナップショットを保持します。
• 書き込み RPC プリフライト失敗時は、送信された設定を拒否し、ディスク上の設定とアクティブなランタイムスナップショットの両方を変更しません。
• 送信ヘルパー/ツール呼び出しに明示的な呼び出しごとのチャネルトークンを提供しても、SecretRef 有効化はトリガーされません。有効化ポイントは起動、リロード、明示的な secrets.reload のままです。

低下状態と復旧シグナル

健全な状態の後にリロード時の有効化が失敗すると、OpenClaw は低下したシークレット状態に入ります。

ワンショットシステムイベントとログコード:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

動作:

• 低下状態: ランタイムは最後に正常だったスナップショットを保持します。
• 復旧: 次に有効化が成功した後に 1 回だけ発行されます。
• すでに低下状態の間に失敗が繰り返される場合、警告をログに記録しますが、イベントを大量発行しません。
• 起動時のフェイルファストでは、ランタイムが一度もアクティブになっていないため、低下イベントは発行されません。

コマンドパス解決

コマンドパスは、gateway スナップショット RPC 経由でサポートされる SecretRef 解決にオプトインできます。

大きく分けて 2 つの動作があります。

その他の注意:

• バックエンドのシークレットローテーション後のスナップショット更新は、openclaw secrets reload によって処理されます。
• これらのコマンドパスで使用される Gateway RPC メソッド: secrets.resolve。

監査と設定のワークフロー

デフォルトのオペレーターフロー:

openclaw secrets audit --check

openclaw secrets configure --apply

openclaw secrets audit --check

再監査がクリーンになるまで、移行が完了したと扱わないでください。監査で 保存時のプレーンテキスト値がまだ報告される場合、ランタイム API が編集済みの値を返していても、 エージェントアクセスリスクはまだ存在します。

configure 中に適用せずにプランを保存した場合は、再監査の前に openclaw secrets apply --from <plan-path> でその保存済みプランを適用してください。

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

一方向の安全ポリシー

安全モデル:

• 書き込みモードの前にプリフライトが成功している必要があります
• コミット前にランタイムの有効化が検証されます
• apply はアトミックなファイル置換と、失敗時のベストエフォート復元を使ってファイルを更新します

レガシー auth 互換性に関する注意

静的認証情報について、ランタイムはプレーンテキストのレガシー auth ストレージに依存しなくなりました。

• ランタイム認証情報のソースは、解決済みのインメモリスナップショットです。
• レガシーの静的 api_key エントリは、検出時に消去されます。
• OAuth 関連の互換性動作は別個のままです。

Web UI に関する注意

一部の SecretInput union は、フォームモードより raw editor モードの方が設定しやすい場合があります。

関連

• 認証 — auth セットアップ
• CLI: secrets — CLI コマンド
• 環境変数 — 環境の優先順位
• SecretRef 認証情報サーフェス — 認証情報サーフェス
• Secrets Apply Plan Contract — プラン契約の詳細
• セキュリティ — セキュリティ態勢