OpenClawにおける環境変数の管理方法

新しいツールを導入した際、APIキーや設定値がどこで読み込まれているのか分からず、デバッグに時間を取られたことはありませんか？特に複数のプロジェクトや環境を使い分けていると、環境変数の管理はすぐに複雑になってしまいます。

OpenClawでは、設定の競合を防ぎ、意図しない動作を避けるために明確なルールが設けられています。

必要なもの

• OpenClaw Gateway
• ~/.openclaw/openclaw.json (設定ファイル)
• 有効な API キー（OpenRouter や Groq など）

クイックスタート

OpenClawは複数のソースから環境変数を読み込みますが、最も重要なルールは**「既存の値を決して上書きしない」**ということです。

優先順位（高い順）

1. Process environment: 親シェルやデーモンから Gateway プロセスが既に持っている値。
2. カレントディレクトリの .env: dotenv のデフォルト動作（上書きはしません）。
3. グローバルな .env: ~/.openclaw/.env にあるファイル（上書きはしません）。
4. 設定ファイルの env ブロック: ~/.openclaw/openclaw.json 内の記述。
5. ログインシェルからのインポート: 不足しているキーがある場合のみ適用。

設定ファイルでの記述方法

env ブロックでは、以下の2つの方法で環境変数を定義できます。

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
  },
}

設定内での変数置換

設定ファイルの文字列内で ${VAR_NAME} 形式を使って、環境変数を直接参照できます。

{
  models: {
    providers: {
      "vercel-gateway": {
        apiKey: "${VERCEL_GATEWAY_API_KEY}",
      },
    },
  },
}

パスに関連する環境変数

特定のディレクトリ構成で実行したい場合は、以下の変数を使用してください。

変数名	用途
OPENCLAW_HOME	内部パス解決（設定、エージェント、セッションなど）に使用されるホームディレクトリを上書きします。
OPENCLAW_STATE_DIR	ステートディレクトリ（デフォルト ~/.openclaw）を上書きします。
OPENCLAW_CONFIG_PATH	設定ファイルのパス（デフォルト ~/.openclaw/openclaw.json）を上書きします。

トラブルシューティング

• シェル環境変数が読み込まれない: env.shellEnv.enabled が true に設定されているか、または環境変数 OPENCLAW_LOAD_SHELL_ENV=1 が設定されているか確認してください。デフォルトのタイムアウトは 15000ms です。
• 設定ファイルの値が反映されない: すでにプロセス環境や .env ファイルで同じ変数が定義されていないか確認してください。OpenClawは既存の値を優先し、後から読み込む値で上書きすることはありません。

セットアップに関する不明点は AI Setup Assistant でいつでも質問してください。

次のステップ

• Gateway configuration
• FAQ: env vars and .env loading
• Models overview