環境変数

OpenClaw は複数のソースから環境変数を読み込みます。基本ルールは既存の値を上書きしないことです。

優先順位（高い順）

1. プロセス環境変数（ゲートウェイプロセスが親シェル/デーモンから持っている値）。
2. カレントディレクトリの .env ファイル（dotenv のデフォルト動作。上書きしません）。
3. グローバル .env ファイル（~/.openclaw/.env、つまり $OPENCLAW_STATE_DIR/.env。上書きしません）。
4. 設定の env ブロック（~/.openclaw/openclaw.json 内。未設定の場合のみ適用）。
5. オプションのログインシェルインポート（env.shellEnv.enabled または OPENCLAW_LOAD_SHELL_ENV=1）。不足している期待されるキーにのみ適用されます。

設定ファイルが完全に存在しない場合、ステップ 4 はスキップされます。シェルインポートは有効であれば実行されます。

設定の env ブロック

インライン環境変数を設定する 2 つの等価な方法（どちらも上書きしません）：

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

シェル環境インポート

env.shellEnv はログインシェルを実行し、不足している期待されるキーのみをインポートします：

{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

環境変数での設定：

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

ランタイムで注入される環境変数

OpenClaw は子プロセスにコンテキストマーカーも注入します：

• OPENCLAW_SHELL=exec：exec ツールで実行されるコマンドに設定。
• OPENCLAW_SHELL=acp：ACP ランタイムバックエンドプロセスの起動時に設定（例：acpx）。
• OPENCLAW_SHELL=acp-client：openclaw acp client が ACP ブリッジプロセスを起動する際に設定。
• OPENCLAW_SHELL=tui-local：ローカル TUI の ! シェルコマンドに設定。

これらはランタイムマーカーであり（ユーザー設定ではありません）、シェル/プロファイルのロジックでコンテキスト固有のルールを適用するために使用できます。

UI 環境変数

• OPENCLAW_THEME=light：端末の背景が明るい場合に、明るい TUI パレットを強制。
• OPENCLAW_THEME=dark：暗い TUI パレットを強制。
• COLORFGBG：端末がこの変数をエクスポートしている場合、OpenClaw は背景色のヒントを使用して TUI パレットを自動選択します。

設定での環境変数の置換

設定の文字列値で ${VAR_NAME} 構文を使用して環境変数を直接参照できます：

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

詳細は 設定：環境変数の置換 を参照してください。

Secret ref と ${ENV} 文字列

OpenClaw は 2 つの環境変数駆動パターンをサポートしています：

• ${VAR} 文字列置換（設定値内）。
• SecretRef オブジェクト（{ source: "env", provider: "default", id: "VAR" }）。シークレット参照をサポートするフィールド用。

どちらもアクティベーション時にプロセス環境変数から解決されます。SecretRef の詳細は シークレット管理 に記載されています。

パス関連の環境変数

ログ

OPENCLAW_HOME

設定時、OPENCLAW_HOME はすべての内部パス解決でシステムのホームディレクトリ（$HOME / os.homedir()）を置き換えます。ヘッドレスのサービスアカウントでファイルシステムの完全な分離を可能にします。

優先順位： OPENCLAW_HOME > $HOME > USERPROFILE > os.homedir()

例（macOS LaunchDaemon）：

<key>EnvironmentVariables</key>
<dict>
  <key>OPENCLAW_HOME</key>
  <string>/Users/kira</string>
</dict>

OPENCLAW_HOME はチルダパス（例：~/svc）も設定でき、使用前に $HOME を使用して展開されます。

関連ドキュメント

• ゲートウェイ設定
• FAQ：環境変数と .env の読み込み
• モデル概要