シークレット管理

OpenClaw は、対応する認証情報を設定内に平文で保存しなくて済むように、追加型の SecretRefs をサポートします。

# 目標とランタイムモデル

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

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

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

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

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

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

# Gateway 認証サーフェス診断

gateway.auth.token、gateway.auth.password、gateway.remote.token、または gateway.remote.password に SecretRef が設定されている場合、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 コントラクト

どこでも同じオブジェクト形状を使用します。

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

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

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

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

# プロバイダー設定

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,
      },
    },
    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" } }
}

# 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: {
      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" },
      },
    },
  },
}

{
  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 サーバー env vars は 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} のような env テンプレート参照と SecretRef オブジェクトは、MCP サーバープロセスが生成される前の Gateway アクティベーション中に解決されます。他の SecretRef サーフェスと同様に、未解決の参照がアクティベーションをブロックするのは、acpx plugin が実質的にアクティブな場合のみです。

# Sandbox SSH 認証材料

コアの ssh sandbox バックエンドも、SSH 認証材料の SecretRefs をサポートします。

{
  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 呼び出しのたびに遅延してではなく、サンドボックスのアクティベーション中にこれらの ref を解決します。
• 解決された値は、制限付き権限の一時ファイルに書き込まれ、生成された SSH 設定で使用されます。
• 有効なサンドボックスバックエンドが ssh でない場合、これらの ref は非アクティブのままで、起動をブロックしません。

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

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

• SecretRef 認証情報サーフェス

# 必須の動作と優先順位

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

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

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

Google Chat 互換性動作:

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

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

シークレットのアクティベーションは次で実行されます。

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

アクティベーション契約:

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

# 低下状態と回復シグナル

正常状態の後にリロード時アクティベーションが失敗すると、OpenClaw はシークレット低下状態に入ります。

ワンショットのシステムイベントおよびログコード:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

動作:

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

# コマンドパスの解決

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

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

その他の注記:

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

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

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

openclaw secrets audit --check

openclaw secrets configure

openclaw secrets audit --check

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

# 一方向の安全ポリシー

安全モデル:

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

# レガシー認証互換性の注記

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

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

# Web UI の注記

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

# 関連

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