OpenClawでのシークレット管理：SecretRefsによる安全な設定

設定ファイルにAPIキーなどの機密情報をプレーンテキストで保存するのは、セキュリティの観点から避けたいものです。しかし、外部のシークレット管理ツールを導入すると、リクエストのたびにネットワーク遅延が発生したり、プロバイダーの障害がシステム全体の停止につながったりする不安があります。

OpenClawでは、これらの課題を解決するために「SecretRefs」という仕組みを採用しています。これにより、セキュリティを確保しながら、実行時のパフォーマンスとシステムの安定性を両立させることができます。

What You’ll Need

OpenClawが動作する環境
管理対象となるAPIキーや認証情報（環境変数、ファイル、または外部コマンド経由）

Quick Start

OpenClawのSecretRefsは、設定内のどの場所でも共通のオブジェクト形式を使用します。シークレットは起動時にメモリ上のスナップショットとして展開されるため、リクエストの途中で外部プロバイダーに依存することはありません。

基本の形式（Contract） すべてのSecretRefは、以下の形状で記述します。

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

環境変数（source: “env”）を使用する 最も一般的な方法です。idには環境変数名を指定します。

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

外部ファイル（source: “file”）を使用する JSONファイルなどから値を読み込みます。idには絶対パスのJSONポインターを指定してください。

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

コマンド実行（source: “exec”）を使用する Vaultなどの外部ツールを介して取得する場合に使用します。

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

Troubleshooting

設定が正しく反映されない場合は、ログに出力される診断コードを確認してください。OpenClawは、アクティブな設定項目でシークレットが解決できない場合にのみ、起動を停止（Fail-fast）させます。

SECRETS_REF_IGNORED_INACTIVE_SURFACE 設定されたSecretRefが解決できなくても、その機能（特定のチャネルやアカウントなど）が無効化されている場合は、この警告が表示され、システムの起動は継続されます。
SECRETS_GATEWAY_AUTH_SURFACE Gatewayの認証（tokenやpassword）に関するステータスを表示します。ログにactiveと表示されている場合は解決が必須ですが、inactiveと表示されている場合は、他の認証方法（環境変数など）が優先されていることを意味します。

詳細は AI Setup Assistant で確認できます。

What’s Next

Gateway configuration
Interactive onboarding guide

---
title: Provider config の設定ガイド
description: OpenClaw でシークレットプロバイダーを設定し、環境変数、ファイル、外部コマンドから安全にデータを取得する方法を解説します。
---

開発環境や本番環境でシークレットを管理するのは、いつも頭を悩ませる問題です。環境変数がバラバラだったり、特定のツールからしか取得できなかったりと、管理が複雑になりがちですよね。

セキュアで一貫性のある方法でシークレットを扱いたいなら、プロバイダーを適切に構成するのが一番の近道です。OpenClaw を使って、環境変数、ローカルファイル、あるいは外部の Vault ツールからスマートにデータを取得する設定を見ていきましょう。

## 必要なもの

設定を始める前に、以下の準備ができているか確認してください。

- `secrets` ブロックを含む設定ファイル（JSON5形式）
- シークレットへの適切なアクセス権限
- `exec` プロバイダーを利用する場合、実行するバイナリの絶対パス

## クイックスタート

まずは最小限の設定から始めましょう。以下の例では、環境変数、JSON ファイル、そして外部コマンドの 3 つをプロバイダーとして定義しています。

```json
{
  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,
      },
    },
    defaults: {
      env: "default",
      file: "filemain",
      exec: "vault",
    },
    resolution: {
      maxProviderConcurrency: 4,
      maxRefsPerProvider: 512,
      maxBatchBytes: 262144,
    },
  },
}

Env provider

環境変数から値を読み取るシンプルなプロバイダーです。

allowlist を設定して、アクセス可能な変数を制限できます。
環境変数が存在しない、または空の場合は解決に失敗します。

File provider

ローカルファイルを読み取ります。

mode: "json"：ファイルを JSON オブジェクトとして扱い、id をポインタとして解決します。
mode: "singleValue"：ファイルの内容全体をそのまま返します（この場合、参照 ID は "value" と指定します）。
パスは所有権と権限のチェックを通過する必要があります。

Exec provider

外部バイナリを実行してシークレットを取得します。シェルを介さず直接実行されるため、command には絶対パスを指定してください。

デフォルトでは、シンボリックリンクではない通常のファイルである必要があります。
Homebrew の shim など、シンボリックリンクを経由させる場合は allowSymlinkCommand: true を設定し、trustedDirs（例: ["/opt/homebrew"]）と組み合わせて使用してください。

リクエスト（stdin）の形式:

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

レスポンス（stdout）の形式:

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

トラブルシューティング

設定中に遭遇しそうな問題とその対処法です。

Windows でパスの解決に失敗する: Windows 環境で ACL 検証が利用できないパスの場合、セキュリティのために解決が失敗します。信頼できるパスであれば、そのプロバイダーに allowInsecurePath: true を設定してチェックをスキップしてください。
実行コマンドがシンボリックリンクでエラーになる: exec プロバイダーでシンボリックリンクを使用するには、allowSymlinkCommand: true が必要です。OpenClaw は解決された後のターゲットパスを検証します。
特定の ID だけエラーを返したい: exec プロバイダーでは、以下のように ID ごとのエラーメッセージを返すことが可能です。

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

設定で困ったことがあれば、いつでも AI Setup Assistant に相談してください。

次のステップ

APIキーなどの機密情報をコードに直接書き込んだり、`.env` ファイルに平文で放置したりするのは、セキュリティ上の不安が尽きません。管理が煩雑になるだけでなく、誤ってリポジトリに公開してしまうリスクもあります。外部のCLIツールと連携して、必要な時だけ安全にシークレットを呼び出す方法が最もスマートな解決策です。

## 必要なもの

- 1Password CLI、HashiCorp Vault CLI、または `sops` のいずれか
- Homebrew（バイナリを `/opt/homebrew` にインストールしている場合）
- 各ツールに応じた認証設定（`HOME`、`VAULT_ADDR`、`SOPS_AGE_KEY_FILE` などの環境変数）

## クイックスタート

外部コマンド（Exec）を使用してシークレットを取得するための設定例を紹介します。お使いのツールに合わせて、以下の設定を configuration ファイルに追加してください。

### 1Password CLI

`op` コマンドを使用して、1Password の保管庫から直接シークレットを読み込みます。

```json
{
  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" },
      },
    },
  },
}

HashiCorp Vault CLI

Vault を使用している場合は、KV（Key-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" },
      },
    },
  },
}

sops

暗号化された JSON ファイルから特定のパスの値を抽出する場合は、sops を利用するのが便利です。

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

トラブルシューティング

コマンドが見つからない、または実行権限エラー: Homebrew でインストールしたバイナリを使用する場合、allowSymlinkCommand: true が設定されていることを確認してください。
ディレクトリの信頼性: 実行ファイルが配置されているパス（例: /opt/homebrew）が trustedDirs に含まれているか確認してください。
環境変数の不足: CLIツールの動作に必要な HOME や VAULT_ADDR などの環境変数が passEnv で正しく渡されているか確認してください。
JSONパースエラー: コマンドの出力形式と jsonOnly 設定が一致しているか確認してください。

設定の詳細や不明な点がある場合は、AI Setup Assistant を活用してください。

次のステップ

開発において認証情報の管理は常に頭の痛い問題です。設定ファイルに機密情報を直接書き込むのは避けたい一方で、複数の環境で安全に秘密情報を同期させるのは簡単ではありません。

「どの設定が優先されるのか」「なぜ更新したはずの秘密情報が反映されないのか」といった疑問に直面したことがある方は多いはずです。OpenClaw では、これらの課題を解決するために明確な SecretRef の解決ルールとアクティベーションの仕組みを提供しています。

必要なもの

作業を始める前に、以下のリソースを確認してください。

SecretRef Credential Surface のドキュメント
OpenClaw Gateway が動作する環境

クイックスタート

SecretRef を使いこなすための最小限のステップは以下の通りです。

サポート範囲の確認 SecretRef はすべての認証情報をカバーしているわけではありません。Runtime で生成される認証情報や、OAuth のリフレッシュトークンなどは、読み取り専用の SecretRef 解決の対象外となります。
優先順位の理解 同じフィールドに対して Plaintext（プレーンテキスト）と Ref の両方が存在する場合、サポートされているパスでは Ref が優先されます。Google Chat の互換性動作においても、serviceAccountRef は Plaintext の serviceAccount よりも優先されます。
アクティベーションの実行 秘密情報の有効化（Activation）は、Startup 時や設定の再読み込み時に行われます。手動で反映させたい場合は、secrets.reload を実行してください。
コマンドパスの活用 openclaw memory などの厳密なパスでは、必要な SecretRef が利用できない場合に即座にエラー（Fail fast）となります。一方で openclaw status などの読み取り専用パスでは、情報の取得に失敗しても診断メッセージを表示したまま動作を継続します。

トラブルシューティング

運用中に遭遇する可能性のあるシグナルと、その解決策について説明します。

警告と監査シグナル

SECRETS_REF_OVERRIDES_PLAINTEXT: Runtime の警告です。Ref が Plaintext を上書きしていることを示します。
REF_SHADOWED: auth-profiles.json の認証情報が openclaw.json の Ref よりも優先されている場合に発生する監査ログです。

状態の異常（Degraded）

再読み込み時にアクティベーションが失敗すると、システムは「Degraded（劣化）」状態に入ります。

SECRETS_RELOADER_DEGRADED: 正常な状態からアクティベーションに失敗した際に出力されます。この時、システムは「最後に確認された正常なスナップショット（Last-known-good）」を保持し続けます。
SECRETS_RELOADER_RECOVERED: 次のアクティベーションが成功した際に一度だけ出力されます。

なお、Startup 時の失敗は Gateway 自体の起動を停止させるため、これらの Degraded イベントは発行されません。

不明な点がある場合や、具体的な構成エラーの解決には AI Setup Assistant を活用してください。

次のステップ

設定ファイルの中にAPIキーを直接書き込んでしまい、ヒヤッとしたことはありませんか？.envやJSONファイルに平文でパスワードが残っていると、セキュリティ上の大きなリスクになります。

OpenClawでは、こうした機密情報を安全に管理し、誤って露出させないための強力なワークフローが用意されています。

必要なもの

openclaw.json や auth-profiles.json などの設定ファイル
<config-dir>/.env ファイル
OpenClaw CLI

クイックスタート

まずは、5分でできる最小限のステップで現在の状態を確認し、設定を最適化しましょう。

# 現在の機密情報の露出状況をチェックします
openclaw secrets audit --check

# 対話型ウィザードでSecretを設定します
openclaw secrets configure

# 再度チェックして、問題が解決したか確認します
openclaw secrets audit --check

secrets audit

このコマンドは、環境内のセキュリティ上の問題を検出します。主な検出対象は以下の通りです。

平文の値: openclaw.json、auth-profiles.json、.env、および生成された agents/*/agent/models.json 内に保存されている平文のデータ
ヘッダー内の残存データ: 生成された models.json 内に残っている、プロバイダー固有の機密性の高いヘッダー情報
未解決の参照: 適切に解決できていない SecretRef
優先順位によるシャドウイング: auth-profiles.json が openclaw.json の参照より優先されている状態
レガシーな残存物: auth.json や OAuth 関連の不要なデータ

なお、ヘッダーの検出は名前ベースのヒューリスティック（authorization、x-api-key、token、secret、password、credential など）に基づいて行われます。

secrets configure

機密情報を設定するための対話型ヘルパーです。以下の手順をガイドします。

secrets.providers の設定: env、file、exec の追加・編集・削除を最初に行います。
ターゲットの選択: openclaw.json や auth-profiles.json 内の機密情報を含むフィールドを選択します。
SecretRef の詳細入力: source、provider、id を指定します。
検証と適用: 実行前に preflight resolution（事前解決テスト）を行い、即座に適用できます。

便利なオプションフラグも利用可能です。

openclaw secrets configure --providers-only
openclaw secrets configure --skip-provider-setup
openclaw secrets configure --agent <id>

適用（apply）時のデフォルト動作として、auth-profiles.json や auth.json、.env から一致する古い平文の認証情報を自動的に削除（スクラブ）します。

secrets apply

保存されたプランファイルを使用して設定を適用します。

# プランを適用する
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json

# 実際の書き込みを行わずにシミュレーションする
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run

ターゲットやパスの厳密なルールについては、Secrets Apply Plan Contract を参照してください。

One-way safety policy

OpenClawは意図的に、過去の平文の機密情報を含むロールバック用のバックアップを作成しない設計になっています。

書き込み前の検証: preflight が成功しない限り、書き込みモードは実行されません。
実行時のバリデーション: コミット前にランタイムでの有効性が確認されます。
原子的な置換: ファイルの更新は atomic file replacement（原子的なファイル置換）によって行われ、失敗した場合はベストエフォートで復元を試みます。

Legacy auth compatibility notes

現在のランタイムは、平文のレガシーな認証ストレージに依存していません。

実行時の認証情報は、メモリ上で解決されたスナップショットから取得されます。
auth.json 内の古い api_key エントリは、検出時に削除されます。
OAuth 関連の互換動作は、これらとは別に維持されます。

Web UI note

一部の SecretInput の組み合わせは、フォームモードよりも raw editor モード（直接編集）の方が設定しやすい場合があります。

トラブルシューティング

監査で unresolved refs が表示される: secrets.providers が正しく設定されているか、または指定した id がプロバイダー側に存在するか確認してください。
.env の値が消えた: secrets configure を実行すると、管理対象となった機密情報は安全のために元のファイルからスクラブされます。これは正常な動作です。

AI Setup Assistant

次のステップ

CLI commands: secrets
Plan contract details: Secrets Apply Plan Contract
Credential surface: SecretRef Credential Surface
Auth setup: Authentication
Security posture: Security
Environment precedence: Environment Variables

OpenClaw Expert

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。