--- read_when: - OpenClaw が HashiCorp Vault から API キーを読み取るようにする - ローカルマシンまたはサーバーでSecretRefsを設定しています - Vault に保存されたモデルプロバイダーの認証情報を設定する必要があります summary: バンドルされている Vault Plugin を使用して、HashiCorp Vault から SecretRefs を解決する title: Vault SecretRef x-i18n: generated_at: "2026-07-11T22:34:22Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: c1fa4895414e8cf44bb4ada191a7f7aa7b4eeda58f16be04d0c77080b7af96e3 source_path: plugins/vault.md workflow: 16 --- # Vault SecretRef 同梱の Vault Plugin を使用すると、OpenClaw は Gateway の起動時および再読み込み時に HashiCorp Vault から `exec` SecretRef を解決できます。OpenClaw は Vault への参照を設定に保存し、解決された値をメモリ内のシークレットスナップショットに保持します。解決された API キーが `openclaw.json` に書き戻されることはありません。 すでに Vault を運用している場合や、モデルプロバイダーのキーを OpenClaw の設定ファイル外に保存したい場合に使用します。SecretRef のランタイムモデルについては、[シークレット管理](/ja-JP/gateway/secrets)を参照してください。 ## 始める前に 必要なもの： - 同梱の `vault` Plugin を利用できる OpenClaw - 接続可能な Vault サーバー - OpenClaw が解決するシークレットパスへの読み取りアクセス権を持つクライアントトークンを生成できる Vault 認証 - Gateway を起動する環境に `VAULT_ADDR` と、`VAULT_TOKEN`、`OPENCLAW_VAULT_AUTH_METHOD=token_file` と `VAULT_TOKEN_FILE` の組み合わせ、または設定済みの JWT/Kubernetes ログインのいずれかが含まれていること リゾルバーは Node から HTTP 経由で Vault と通信します。Gateway が SecretRef を解決するために Vault CLI は必要ありません。 `openclaw vault` コマンドを実行する前に、同梱の Plugin を有効にします。 ```bash openclaw plugins enable vault ``` ## プロバイダーキーを Vault に保存する OpenClaw のデフォルトは、Vault 開発サーバーの例に合わせて、`secret` にマウントされた KV v2 です。本番環境の Vault では、SecretRef ID を作成する前に `OPENCLAW_VAULT_KV_MOUNT` を実際の KV マウントパスに設定してください。OpenClaw のデフォルトでは、次の SecretRef ID： ```text providers/openrouter/apiKey ``` は、次の Vault フィールドを読み取ります。 ```text secret/data/providers/openrouter -> apiKey ``` Vault CLI で作成する方法の一例： ```bash export OPENROUTER_API_KEY= vault kv put secret/providers/openrouter apiKey="$OPENROUTER_API_KEY" ``` OpenClaw にはルートトークンではなく、スコープを限定したクライアントトークンを使用してください。デフォルトの KV v2 レイアウトでは、モデルプロバイダーキー用の最小限のポリシーは次のようになります。 ```hcl path "secret/data/providers/*" { capabilities = ["read"] } ``` ## Gateway から Vault を利用できるようにする コンテナ化されていないローカル Gateway では、OpenClaw を起動するシェルと同じシェルで Vault の設定をエクスポートします。デフォルトの認証方式では、`VAULT_TOKEN` から Vault クライアントトークンを読み取ります。 ```bash export VAULT_ADDR=https://vault.example.com export VAULT_TOKEN= ``` Vault Agent がトークンシンクファイルを書き込む場合は、トークンファイル認証を使用します。 ```bash export VAULT_ADDR=https://vault.example.com export OPENCLAW_VAULT_AUTH_METHOD=token_file export VAULT_TOKEN_FILE=/vault/secrets/token ``` プライベート CA で署名された Vault サーバーの場合、その CA をホストの信頼ストアにインストールし、Node のシステム信頼ストアを有効にします。 ```bash export NODE_USE_SYSTEM_CA=1 ``` または、PEM バンドルを直接指定します。 ```bash export NODE_EXTRA_CA_CERTS=/path/to/vault-ca.pem ``` これらの変数は OpenClaw の起動時に存在している必要があります。Vault Plugin はこれらをリゾルバープロセスに転送します。 非対話型 JWT 認証では、ワークロード JWT ファイルと、タイプが `jwt` の Vault ロールを使用します。 ```bash export VAULT_ADDR=https://vault.example.com export OPENCLAW_VAULT_AUTH_METHOD=jwt export OPENCLAW_VAULT_AUTH_MOUNT=jwt export OPENCLAW_VAULT_AUTH_ROLE=openclaw export OPENCLAW_VAULT_JWT_FILE=/var/run/secrets/tokens/vault ``` JWT ファイルには、Vault ロールが受け入れるオーディエンスを持つ Kubernetes サービスアカウントトークンなど、投影されたワークロードトークンを使用してください。 対話型の OIDC ブラウザログインは人間による操作には便利ですが、Gateway のランタイムには非対話型 JWT ログインまたはトークンファイルが必要です。 Vault の Kubernetes 認証方式では、`kubernetes` を使用します。これは Pod として実行される Gateway を対象としています。デフォルトのマウントは `kubernetes`、デフォルトの JWT ファイルは標準のサービスアカウントトークンパスです。 ```bash export VAULT_ADDR=https://vault.example.com export OPENCLAW_VAULT_AUTH_METHOD=kubernetes export OPENCLAW_VAULT_AUTH_ROLE=openclaw ``` Vault が Kubernetes 認証を `auth/kubernetes` 以外にマウントしている場合にのみ、`OPENCLAW_VAULT_AUTH_MOUNT` を設定します。サービスアカウントトークンがカスタムパスに投影されている場合にのみ、`OPENCLAW_VAULT_JWT_FILE` を設定します。 任意の設定： ```bash export VAULT_NAMESPACE= export OPENCLAW_VAULT_KV_MOUNT=secret export OPENCLAW_VAULT_KV_VERSION=2 ``` 現在のシェルから参照できる内容を確認します。 ```bash openclaw vault status ``` Vault を使用するシークレットプロバイダーが複数設定されている場合は、エイリアスでプロバイダーを選択します。 ```bash openclaw vault status --provider-alias corp-vault ``` `openclaw vault status` が `VAULT_TOKEN` を表示することはありません。トークン、トークンファイル、JWT ファイルが設定されているかどうかのみを報告します。 Gateway がサービス、LaunchAgent、systemd ユニット、スケジュールされたタスク、またはコンテナとして実行される場合、そのランタイム環境にも同じ Vault 変数を渡す必要があります。対話型シェルで変数を設定して確認できるのは、そのシェルだけであり、すでに実行中の Gateway ではありません。 ## SecretRef プランを生成して適用する OpenRouter のモデルプロバイダー API キーを Vault にマッピングするプランを作成します。 ```bash openclaw vault setup \ --plan-out ./vault-secrets-plan.json \ --openrouter-id providers/openrouter/apiKey ``` プランを適用して検証します。 ```bash openclaw secrets apply --from ./vault-secrets-plan.json --dry-run --allow-exec openclaw secrets apply --from ./vault-secrets-plan.json --allow-exec openclaw secrets audit --check --allow-exec openclaw secrets reload ``` Vault Plugin は OpenClaw が管理する exec SecretRef プロバイダーを介して解決を行うため、`--allow-exec` を使用します。 Gateway がまだ実行されていない場合は、プランの適用後に `openclaw secrets reload` を実行する代わりに、通常どおり起動してください。 ## さらにプロバイダーキーを設定する 組み込みのショートカット： ```bash openclaw vault setup --openai-id providers/openai/apiKey openclaw vault setup --anthropic-id providers/anthropic/apiKey openclaw vault setup --openrouter-id providers/openrouter/apiKey ``` 1 つのプランに複数のプロバイダーキーを含める場合： ```bash openclaw vault setup \ --plan-out ./vault-secrets-plan.json \ --openai-id providers/openai/apiKey \ --anthropic-id providers/anthropic/apiKey \ --openrouter-id providers/openrouter/apiKey ``` ショートカットのない同梱プロバイダー、または設定済みの OpenAI 互換プロバイダーやカスタムモデルプロバイダーには、`--provider-key` を使用します。 ```bash openclaw vault setup \ --plan-out ./vault-secrets-plan.json \ --provider-key local-openai=providers/local-openai/apiKey \ --provider-key groq=providers/groq/apiKey ``` 各 `--provider-key ` は、SecretRef を `models.providers..apiKey` に書き込みます。カスタムプロバイダーの場合、プロバイダーの `baseUrl`、`api`、`models` の設定は作成されないため、先にそれらを設定してください。 既知の SecretRef ターゲットパスには、`--target ` を使用します。 ```bash openclaw vault setup \ --target channels.telegram.botToken=channels/telegram/botToken \ --target models.providers.openai.headers.x-api-key=providers/openai/proxyKey \ --target auth-profiles:main:profiles.openai.key=providers/openai/apiKey ``` 修飾子のないターゲットパスは `openclaw.json` に適用されます。既存の `auth-profiles.json` のターゲットには、`auth-profiles::` を使用します。 ターゲットパスは、登録済みの OpenClaw SecretRef ターゲットである必要があります。setup コマンドは OpenClaw 内に任意の名前付きシークレットを作成しません。シークレットストアは引き続き Vault であり、OpenClaw は対応する設定フィールドにのみ SecretRef を保存します。 ## SecretRef ID の形式 Vault SecretRef ID では、次の規則を使用します。 ```text / ``` 例： | SecretRef ID | デフォルトの KV v2 Vault 読み取り | 返されるフィールド | | ----------------------------- | ---------------------------------- | ------------------ | | `providers/openrouter/apiKey` | `secret/data/providers/openrouter` | `apiKey` | | `providers/openai/apiKey` | `secret/data/providers/openai` | `apiKey` | | `teams/agent-prod/openrouter` | `secret/data/teams/agent-prod` | `openrouter` | 返される Vault フィールドは文字列である必要があります。 KV v1 の場合は、次を設定します。 ```bash export OPENCLAW_VAULT_KV_VERSION=1 ``` この場合、`providers/openrouter/apiKey` は次を読み取ります。 ```text secret/providers/openrouter -> apiKey ``` ## OpenClaw が保存する内容 Vault setup プランを適用すると、Plugin が管理するプロバイダーが保存されます。 ```json { "source": "exec", "pluginIntegration": { "pluginId": "vault", "integrationId": "vault" } } ``` 認証情報フィールドはそのプロバイダーを参照します。 ```json { "source": "exec", "provider": "vault", "id": "providers/openrouter/apiKey" } ``` 解決された値は、アクティブなランタイムのシークレットスナップショット内にのみ存在します。 ## コンテナとマネージドデプロイ コンテナ化された Gateway でも、同じ Plugin と SecretRef 設定を使用します。コンテナには次を渡す必要があります。 - `VAULT_ADDR` - 次のいずれかの認証ソース： - `VAULT_TOKEN` - `OPENCLAW_VAULT_AUTH_METHOD=token_file` と `VAULT_TOKEN_FILE` - `OPENCLAW_VAULT_AUTH_METHOD=jwt` と `OPENCLAW_VAULT_AUTH_MOUNT`、`OPENCLAW_VAULT_AUTH_ROLE`、`OPENCLAW_VAULT_JWT_FILE` - `OPENCLAW_VAULT_AUTH_METHOD=kubernetes` と `OPENCLAW_VAULT_AUTH_ROLE`。必要に応じて `OPENCLAW_VAULT_AUTH_MOUNT` または `OPENCLAW_VAULT_JWT_FILE` を上書き - 任意の `VAULT_NAMESPACE`、`OPENCLAW_VAULT_KV_MOUNT`、`OPENCLAW_VAULT_KV_VERSION` Kubernetes を使用する場合、Vault にクラスター用の Kubernetes 認証が設定されているときは、`OPENCLAW_VAULT_AUTH_METHOD=kubernetes` を推奨します。Vault がクラスターを汎用 JWT/OIDC 発行者として扱うよう設定されている場合にのみ、`OPENCLAW_VAULT_AUTH_METHOD=jwt` を使用します。どちらの方法も、Kubernetes Secret に有効期間の長い Vault トークンを保存するより適切です。Vault Agent のサイドカーまたはインジェクターを使用するデプロイでは、代わりに `token_file` を使用できます。 マルチテナントの Vault 構成では、テナントのルーティングを Vault ポリシーとデプロイ設定で管理してください。OpenClaw は固定のマウント、ロール、パスを必要としません。各 Gateway 環境で独自の `OPENCLAW_VAULT_KV_MOUNT`、`OPENCLAW_VAULT_AUTH_ROLE`、SecretRef ID を設定できます。1 つの共有 Gateway で異なる Vault ユーザーを同時に解決する必要がある場合は、異なる認証環境をラップするよう手動設定した exec プロバイダーを使用するか、個別の Vault 環境変数を持つ Gateway 環境にテナントを分割してください。 ## 関連項目 - [シークレット管理](/ja-JP/gateway/secrets) - [`openclaw secrets`](/ja-JP/cli/secrets) - [Plugin 一覧](/ja-JP/plugins/plugin-inventory)