シークレット管理

OpenClaw は追加型の SecretRef をサポートしているため、サポート対象の認証情報を設定内に平文で保存する必要はありません。

ランタイムモデル

• シークレットは、リクエスト経路で遅延解決されるのではなく、アクティベーション中に先行してメモリ内ランタイムスナップショットへ解決されます。
• 実質的にアクティブな SecretRef を解決できない場合、起動は即座に失敗します。
• 再読み込みはアトミックな交換です。すべて成功するか、最後に正常だったスナップショットを維持します。
• ポリシー違反（たとえば OAuth モードの認証プロファイルと SecretRef 入力の組み合わせ）がある場合、ランタイムを交換する前にアクティベーションが失敗します。
• ランタイムリクエストは、アクティブなメモリ内スナップショットのみを読み取ります。モデルプロバイダーの SecretRef 認証情報は、外部送信されるまで、プロセスローカルなセンチネルとして認証ストレージとストリームオプションを通過します。外向きの配信経路（Discord の返信／スレッド配信、Telegram のアクション送信）もそのスナップショットを読み取り、送信ごとに参照を再解決しません。

これにより、シークレットプロバイダーの障害が高頻度のリクエスト経路に影響しなくなります。

外部送信時の注入（センチネル）

SecretRef によって提供されるモデルプロバイダーの認証情報について、OpenClaw はモデル認証の解決中に、不透明なプロセスローカルのセンチネルを生成します。そのため、認証ストレージ、ストリームオプション、SDK 設定、ログ、エラーオブジェクト、およびランタイムのほとんどの内部調査では、プロバイダーの認証情報ではなく oc-sent-v1-... のような値が見えます。保護されたモデル fetch と、管理対象のローカルプロバイダーのヘルスプローブは、各リクエストがプロセス外へ出る直前に、URL とヘッダーの値に含まれる既知のセンチネルを置換します。

未知のセンチネル形式の値がある場合、ネットワーク通信を行う前に安全側に倒して失敗します。OpenClaw は、未解決のセンチネルをプロバイダーへ転送せず、リクエストの送信を拒否します。多層防御として、解決済みのシークレット値も、完全一致によるログ秘匿化の対象として登録されます。

プロバイダーアダプターは、SDK がサポートする最も遅い注入ポイントを使用します。

• カスタム fetch オプションを持つ SDK には OpenClaw の保護された fetch が渡されるため、SDK 内ではセンチネルが維持されます。
• カスタム fetch オプションを持たない SDK では、クライアントを構築する直前にセンチネルを展開します。Plugin が所有するプロバイダーストリームとエージェントハーネスは OpenClaw の保護された fetch を共有しないため、コアが所有する最後の受け渡し地点で展開します。

センチネルはモデル呼び出しチェーン全体での平文露出を減らしますが、プロセス分離ではありません。実際の値は同一プロセスのメモリ内に引き続き存在し、最終的なアダプター境界に現れます。SecretRef を介して設定されていない通常の環境変数の認証情報は平文のままであり、この仕組みの対象外です。

インシデント対応または互換性のトラブルシューティング中にセンチネルの生成を無効化するには、OPENCLAW_SECRET_SENTINELS=off（大文字と小文字を区別せず、0 または false も使用可能）を設定します。この緊急停止スイッチは、完全一致による秘匿化の登録を無効化しません。

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

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

エージェントがアクセス可能なファイルが対象範囲に含まれる本番環境では、次のすべてを満たす場合にのみ移行が完了したものとして扱ってください。

• サポート対象の認証情報で、平文値の代わりに SecretRef を使用している。
• openclaw.json、auth-profiles.json、.env、および生成された models.json ファイルから、従来の平文の残留を除去している。
• 移行後の openclaw secrets audit --check で問題が検出されない。
• 残っているサポート対象外またはローテーション対象の認証情報が、OS 分離、コンテナ分離、または外部の認証情報プロキシによって保護されている。

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

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

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

• 有効なサーフェス：未解決の参照は起動／再読み込みを阻止します。
• 非アクティブなサーフェス：未解決の参照は起動／再読み込みを阻止せず、致命的ではない SECRETS_REF_IGNORED_INACTIVE_SURFACE 診断を出力します。

Gateway 認証サーフェスの診断

gateway.auth.token、gateway.auth.password、gateway.remote.token、または gateway.remote.password に SecretRef が設定されている場合、Gateway の起動／再読み込みでは、コード SECRETS_GATEWAY_AUTH_SURFACE の下にサーフェスの状態が記録されます。

• active：SecretRef は実効認証サーフェスの一部であり、解決する必要があります。
• inactive：別の認証サーフェスが優先されるか、リモート認証が無効または非アクティブです。

ログエントリには、アクティブサーフェスポリシーが使用した理由が含まれます。

オンボーディングの参照事前検証

対話型オンボーディングで SecretRef ストレージを選択すると、保存前に事前検証が実行されます。

• Env 参照：環境変数名を検証し、セットアップ中に空でない値が参照可能であることを確認します。
• プロバイダー参照（file または exec）：プロバイダーの選択を検証し、id を解決して、解決された値の型を確認します。
• クイックスタートフロー：gateway.auth.token がすでに SecretRef の場合、オンボーディングでは同じ即時失敗ゲートを使用して、プローブ／ダッシュボードのブートストラップ前にそれを解決します（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", // または "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": { "code": "NOT_FOUND" } }}

ファイルに保存された API キー

設定の 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 ポインターを使用してください。

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

Exec 統合の例

{  secrets: {    providers: {      onepassword_openai: {        source: "exec",        command: "/opt/homebrew/bin/op",        allowSymlinkCommand: true, // Homebrew のシンボリックリンクされたバイナリに必要        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, // Homebrew のシンボリックリンクされたバイナリに必要        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(`リクエストの解析に失敗しました: ${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 が ${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, // Homebrew のシンボリックリンクされたバイナリに必要        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 呼び出しごとに遅延解決するのではなく、サンドボックスのアクティベーション時にこれらの参照を解決します。
• 解決された値は制限の厳しいファイル権限（0o600）で一時ディレクトリに書き込まれ、生成される SSH 設定で使用されます。
• 有効なサンドボックスバックエンドが ssh でない場合（またはサンドボックスモードが off の場合）、これらの参照は非アクティブのままであり、起動をブロックしません。

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

サポート対象および対象外の正式な認証情報一覧は、SecretRef 認証情報サーフェスに記載されています。

必須の動作と優先順位

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

警告および監査シグナル:

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

Google Chat の互換性: serviceAccountRef は平文の serviceAccount より優先されます。兄弟フィールドの参照が設定されると、平文値は無視されます。

アクティベーションのトリガー

Secret のアクティベーションは、以下の場合に実行されます。

• 起動時（事前チェックと最終アクティベーション）
• 設定リロードのホット適用パス
• 設定リロードの再起動チェックパス
• secrets.reload による手動リロード
• Gateway の設定書き込み RPC 事前チェック（config.set / config.apply / config.patch）。編集内容を永続化する前に、送信された設定ペイロード内でアクティブなサーフェスの SecretRef が解決可能かどうかを確認します

アクティベーションのコントラクト:

• 成功すると、スナップショットがアトミックに交換されます。
• 起動時の失敗は Gateway の起動を中止します。
• ランタイムのリロードに失敗した場合、最後に正常だったスナップショットが維持されます。
• 書き込み RPC の事前チェックに失敗した場合、送信された設定は拒否されます。ディスク上の設定とアクティブなランタイムスナップショットは、どちらも変更されません。
• 送信ヘルパー/ツール呼び出しに呼び出し単位の明示的なチャンネルトークンを指定しても、SecretRef のアクティベーションはトリガーされません。アクティベーションポイントは引き続き、起動、リロード、および明示的な secrets.reload です。

機能低下および復旧シグナル

正常な状態の後にリロード時のアクティベーションが失敗すると、OpenClaw は Secret の機能低下状態に入り、一度限りのシステムイベントとログコードを発行します。

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

動作:

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

コマンドパスの解決

コマンドパスは、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

一方向の安全性ポリシー

安全性モデル:

• 書き込みモードの前に、事前チェックが成功する必要があります。
• コミット前に、ランタイムのアクティベーションが検証されます。
• 適用処理では、アトミックなファイル置換を使用してファイルを更新し、失敗時にはベストエフォートで復元します。

レガシー認証の互換性に関する注意事項

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

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

Web UI に関する注意

一部の SecretInput ユニオンは、フォームモードよりも raw editor モードのほうが構成しやすくなっています。

関連項目

• 認証 - 認証のセットアップ
• CLI: シークレット - CLI コマンド
• Vault SecretRef - HashiCorp Vault プロバイダーのセットアップ
• 環境変数 - 環境変数の優先順位
• SecretRef 認証情報サーフェス - 認証情報サーフェス
• シークレット適用プランの契約 - プラン契約の詳細
• セキュリティ - セキュリティ態勢