チュートリアル 08 — 設定システムの詳細解説：API Keyの正しい保存方法
目標：OpenClawの三層設定体系を理解し、Secret Providerの三つのモードをマスターして、あなたのAPIキーを安全かつ柔軟に管理できるようにします。
学べること
- OpenClaw設定ファイルの構造と読み込み順序
- API Keyの三つの書き方：文字列 / 環境変数参照 / 外部コマンド
- Secret Providerシステムのセキュリティ設計
- 1Password、Vaultなどのシークレット管理ツールとの連携方法
一、設定ファイルの場所
OpenClawの設定は ~/.openclaw/openclaw.json（または .yaml）に保存されており、ゲートウェイ起動時に自動的に読み込まれます。
# 現在の設定を確認
openclaw config show
# コマンドラインで特定のフィールドを設定
openclaw config set gateway.mode local全体の構造は以下の通りです：
{
"gateway": { ... }, // ゲートウェイの動作モード
"agents": { ... }, // AIエージェントのデフォルト動作
"models": { ... }, // モデルプロバイダーのリスト
"channels": { ... }, // メッセージチャンネル（Telegram、Discordなど）
"env": { ... }, // 実行時に注入される環境変数
"secrets": { ... }, // Secret Providerの設定（高度）
"hooks": { ... } // ライフサイクルフック
}二、API Keyの三つの書き方
方法A：直接文字列を書く（クイック体験用）
最もシンプルですが、設定ファイルにキーが平文で保存されるため、本番環境や複数人で共有する場面では推奨しません。
{
"models": {
"providers": {
"openai": {
"apiKey": "sk-proj-xxxxxxxxxxxxxxxx"
}
}
}
}方法B：環境変数参照（日常の推奨）
${VAR_NAME} プレースホルダーでシステム環境変数を参照します。設定ファイルには実際のキーを保存しません。
ステップ1：shellでexportするか、~/.profile に書き込みます：
export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxx"
export MINIMAX_API_KEY="eyJhbGci..."ステップ2：設定ファイルでプレースホルダーを参照します：
{
"models": {
"providers": {
"openai": {
"apiKey": "${OPENAI_API_KEY}"
},
"minimax": {
"apiKey": "${MINIMAX_API_KEY}"
}
}
}
}構造化された書き方も使えます（より明確）：
{
"apiKey": { "source": "env", "provider": "default", "id": "OPENAI_API_KEY" }
}仕組み：ゲートウェイ起動時に、OpenClawは ${VAR_NAME} パターンを照合して process.env から対応する値を読み取り、メモリ内のみで解決し、ディスクには書き込みません。
方法C：Secret Provider（チーム / サーバーデプロイ）
これが最も安全で柔軟な方法で、以下の場合に適しています：
- サーバー上で環境変数を設定したくない場合
- チームでゲートウェイを共有し、キーを集中管理する場合
- 1Password CLI、HashiCorp Vaultなどのツールと連携する場合
Secret Providerには三つのソースがあります：
source: "file" — ファイルから読み取り
権限が厳しく設定されたファイルにキーを保存するのに適しています（OpenClawはファイル権限を検証し、グループ書き込み可能なファイルは許可しません）：
{
"secrets": {
"providers": {
"my-keys": {
"source": "file",
"path": "~/.openclaw/secrets.json",
"mode": "json"
}
}
},
"models": {
"providers": {
"openai": {
"apiKey": { "source": "file", "provider": "my-keys", "id": "/openai/apiKey" }
}
}
}
}対応する ~/.openclaw/secrets.json：
{
"openai": { "apiKey": "sk-proj-xxxxxxxx" },
"minimax": { "apiKey": "eyJhbGci..." }
}セキュリティ要件：ファイルは現在のユーザーが所有し、権限は
600以下でなければなりません（chmod 600 ~/.openclaw/secrets.json）。
source: "exec" — 外部プログラムを呼び出す
1Password CLI、Vault、システムのキーチェーンとの連携に適しています：
{
"secrets": {
"providers": {
"op-vault": {
"source": "exec",
"command": "/usr/local/bin/op-resolver",
"timeoutMs": 5000
}
}
},
"models": {
"providers": {
"openai": {
"apiKey": { "source": "exec", "provider": "op-vault", "id": "openai/api-key" }
}
}
}
}外部プログラムは stdin でリクエストを受け取り、stdout で結果を返します。プロトコルは以下の通りです：
# stdin 受信（JSON）：
{ "protocolVersion": 1, "provider": "op-vault", "ids": ["openai/api-key"] }
# stdout 返却（JSON）：
{ "protocolVersion": 1, "values": { "openai/api-key": "sk-proj-xxx" } }
三、1Passwordとの連携例
1PasswordにAPI Keyを保存している場合、シンプルなリゾルバースクリプトを作成できます：
#!/usr/bin/env bash
# ~/.openclaw/op-resolver.sh
# 権限設定：chmod 700 ~/.openclaw/op-resolver.sh
set -euo pipefail
INPUT=$(cat)
ID=$(echo "$INPUT" | jq -r '.ids[0]')
# 1Passwordから読み取り
VALUE=$(op read "op://Private/$ID" 2>/dev/null)
echo "{\"protocolVersion\":1,\"values\":{\"$ID\":\"$VALUE\"}}"その後、設定します：
{
"secrets": {
"providers": {
"1password": {
"source": "exec",
"command": "/Users/あなたのユーザー名/.openclaw/op-resolver.sh",
"timeoutMs": 8000
}
}
}
}注意：
commandは絶対パスでなければならず、他のユーザーが書き込めないファイルである必要があります。
四、設定の env ブロック
Secret Providerに加えて、env ブロックは別の便利な方法を提供します。設定ファイル内で直接実行時の環境変数を宣言できます：
{
"env": {
"vars": {
"HTTP_PROXY": "http://127.0.0.1:7890",
"OPENAI_BASE_URL": "https://api.openai.com"
}
}
}ルール：
- 設定ファイルの
env.varsの値のみが注入され、同名のシステム変数を上書きしません PATH、LD_PRELOADなどの危険な変数名は自動的にブロックされ、この方法では注入できません
五、機密フィールドの自動マスキング
OpenClawはZod sensitive レジストリを使ってすべてのキーフィールドをマークしています。ダッシュボードやログに設定情報が公開される際、これらのフィールドは自動的に [REDACTED] に置き換えられます：
# ログやAPIレスポンスで見えるのは：
{ "apiKey": "[REDACTED]" }
# メモリ内の実際の値はログに表示されません
六、完全な設定例（マルチモデル + セキュリティキー）
{
"gateway": { "mode": "local" },
"secrets": {
"providers": {
"env-keys": { "source": "env" }
},
"defaults": { "env": "env-keys" }
},
"agents": {
"defaults": {
"model": { "primary": "openai/gpt-4o" }
}
},
"models": {
"mode": "merge",
"providers": {
"openai": {
"apiKey": "${OPENAI_API_KEY}",
"models": [
{ "id": "gpt-4o", "name": "GPT-4o" }
]
},
"minimax": {
"baseUrl": "https://api.minimax.io/anthropic",
"apiKey": "${MINIMAX_API_KEY}",
"api": "anthropic-messages",
"models": [
{
"id": "MiniMax-M2.1",
"name": "MiniMax M2.1",
"contextWindow": 200000,
"maxTokens": 8192
}
]
}
}
},
"channels": {
"telegram": {
"token": "${TELEGRAM_BOT_TOKEN}"
}
}
}対応する環境変数（~/.profile または .env に書き込み）：
export OPENAI_API_KEY="sk-proj-..."
export MINIMAX_API_KEY="eyJhbGci..."
export TELEGRAM_BOT_TOKEN="8543054163:AAH..."七、よくある質問
設定を変更したのに反映されない場合は？
ゲートウェイはSkill（SKILL.md）を除き、設定を再読み込みするために再起動が必要です：
openclaw gateway restartキーが正しく読み込まれているか確認するには？
openclaw models list
# 対応するプロバイダーのモデルが表示されればapiKeyの解析が成功していますモデルリストが空の場合は、openclaw config show を実行して設定が正しく解析されているか確認し、${VAR_NAME} プレースホルダーに対応する環境変数がexportされているかチェックしてください。
fileソースで権限エラーが出る場合は？
chmod 600 ~/.openclaw/secrets.json
# ファイルが現在のユーザーに属しているか確認
ls -la ~/.openclaw/secrets.jsonOpenClawはキーファイルの権限が 600 以下であることを要求し、ファイルは現在のユーザーが所有している必要があります（rootが所有していても実行ユーザーが読み取れる場合は不可）。
execソースのスクリプトがタイムアウトする場合の対処法は？
timeoutMs を増やします（最大120000ms）。最も一般的な原因は外部コマンドがログイン状態を必要とすることです。例えば1Password CLIは先に op signin が必要です。スクリプトに自動再ログインのロジックを追加するか、セッショントークンをファイルにキャッシュすることをお勧めします。
.envファイルとopenclaw.jsonのenvブロックの違いは？
.env ファイルはシステムレベルの環境変数であり、すべてのプロセスに有効です。openclaw.json の env.vars ブロックはOpenClawゲートウェイプロセス内のみで有効で、他のプログラムには影響しません。どちらも ${VAR_NAME} を使って apiKey などのフィールドで参照できます。機密データは .env に保存し、env.vars にはOpenClaw専用の非機密設定（プロキシアドレスなど）を保存することを推奨します。
複数の設定ファイルを同時に持てますか？
OpenClawは設定のマージ（"mode": "merge"）をサポートしていますが、メイン設定ファイルのパスは ~/.openclaw/openclaw.json 固定です。openclaw.json の import フィールドを使って他の設定ファイルフラグメントを取り込み、設定のモジュール化管理を実現できます。
次のステップ
- チュートリアル 05 — 複数のモデルProviderを設定して自動切り替えを行う
- チュートリアル 03 — AIにカスタムSkillを追加する