シークレット管理

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.

​

目標とランタイムモデル

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

​

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

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

​

Gateway 認証サーフェス診断

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

​

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

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

​

Sandbox SSH 認証材料

{
  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 より優先される場合の監査検出)

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

​

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

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

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

​

低下状態と回復シグナル

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

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

​

コマンドパスの解決

• バックエンドシークレットのローテーション後のスナップショット更新は、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 の注記

​

関連

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