環境変数

OpenClaw は複数のソースから環境変数を取り込みます。ルールは 既存の値を上書きしない ことです。 ワークスペースの .env ファイルは信頼度の低いソースです。OpenClaw は優先順位を適用する前に、ワークスペース .env 由来のプロバイダー認証情報と保護されたランタイム制御を無視します。

優先順位（高 → 低）

1. プロセス環境（Gateway プロセスが親シェル/デーモンからすでに受け取っているもの）。
2. 現在の作業ディレクトリの .env（dotenv のデフォルト。上書きしません。プロバイダー認証情報と保護されたランタイム制御は無視されます）。
3. グローバル .env（~/.openclaw/.env、別名 $OPENCLAW_STATE_DIR/.env。プロバイダー API キーに推奨。上書きしません）。
4. ~/.openclaw/openclaw.json の設定 env ブロック（不足している場合のみ適用）。
5. 任意のログインシェル取り込み（env.shellEnv.enabled または OPENCLAW_LOAD_SHELL_ENV=1）。不足している想定キーにのみ適用されます。

デフォルトの状態ディレクトリを使用する Ubuntu の新規インストールでは、OpenClaw はグローバル .env の後の互換性フォールバックとして ~/.config/openclaw/gateway.env も扱います。両方のファイルが存在して内容が一致しない場合、OpenClaw は ~/.openclaw/.env を維持し、警告を出力します。

設定ファイルがまったく存在しない場合、ステップ 4 はスキップされます。シェル取り込みは、有効な場合は引き続き実行されます。

プロバイダー認証情報とワークスペース .env

プロバイダー API キーをワークスペース .env のみに保存しないでください。OpenClaw は、ワークスペース .env ファイル由来のプロバイダー認証情報環境変数を無視します。これには GEMINI_API_KEY、GOOGLE_API_KEY、XAI_API_KEY、MISTRAL_API_KEY、GROQ_API_KEY、DEEPSEEK_API_KEY、PERPLEXITY_API_KEY、BRAVE_API_KEY、TAVILY_API_KEY、EXA_API_KEY、FIRECRAWL_API_KEY などの一般的なキーが含まれます。

プロバイダー認証情報には、次のいずれかの信頼済みソースを使用してください。

• シェル、launchd/systemd ユニット、コンテナーシークレット、CI シークレットなどの Gateway プロセス環境。
• ~/.openclaw/.env または $OPENCLAW_STATE_DIR/.env にあるグローバルランタイム dotenv ファイル。
• ~/.openclaw/openclaw.json の設定 env ブロック。
• env.shellEnv.enabled または OPENCLAW_LOAD_SHELL_ENV=1 が有効な場合の任意のログインシェル取り込み。

以前にプロバイダーキーをワークスペース .env のみに保存していた場合は、上記の信頼済みソースのいずれかに移動してください。ワークスペース .env は、認証情報、エンドポイントリダイレクト、ホスト上書き、または OPENCLAW_* ランタイム制御ではない通常のプロジェクト変数を引き続き提供できます。

セキュリティ上の理由については、ワークスペース .env ファイルを参照してください。

設定 env ブロック

インライン環境変数を設定する同等の方法は 2 つあります（どちらも上書きしません）。

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

設定 env ブロックはリテラル文字列値のみを受け付けます。 file:... 値は展開しません。たとえば、XAI_API_KEY: "file:secrets/xai-api-key.txt" は その正確な文字列としてプロバイダーに渡されます。

ファイルに基づくプロバイダーキーには、それをサポートする認証情報フィールドで SecretRef を使用してください。

{  secrets: {    providers: {      xai_key_file: {        source: "file",        path: "~/.openclaw/secrets/xai-api-key.txt",        mode: "singleValue",      },    },  },  models: {    providers: {      xai: {        apiKey: { source: "file", provider: "xai_key_file", id: "value" },      },    },  },}

サポートされるフィールドについては、シークレット管理と SecretRef 認証情報サーフェスを参照してください。

シェル環境の取り込み

env.shellEnv はログインシェルを実行し、不足している想定キーのみを取り込みます。

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

同等の環境変数:

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

exec シェルスナップショット

Windows 以外の Gateway ホストでは、bash と zsh の exec コマンドはデフォルトで起動時スナップショットを使用します。 この経路を無効にするには、Gateway プロセス環境で OPENCLAW_EXEC_SHELL_SNAPSHOT=0 を設定します。 値 false、no、off でも無効になります。呼び出しごとの exec.env 値では、 スナップショットの切り替えやスナップショットキャッシュのリダイレクトはできません。

ランタイムが注入する環境変数

OpenClaw は、生成された子プロセスにもコンテキストマーカーを注入します。

• OPENCLAW_SHELL=exec: exec ツールを通じて実行されるコマンドに設定されます。
• OPENCLAW_SHELL=acp: ACP ランタイムバックエンドプロセスの生成時（例: acpx）に設定されます。
• OPENCLAW_SHELL=acp-client: ACP ブリッジプロセスを生成するときの openclaw acp client に設定されます。
• OPENCLAW_SHELL=tui-local: ローカル TUI の ! シェルコマンドに設定されます。
• OPENCLAW_CLI=1: CLI エントリーポイントによって生成された子プロセスに設定されます。

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

UI 環境変数

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

設定内の環境変数置換

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

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

詳細については、設定: 環境変数置換を参照してください。

シークレット参照と ${ENV} 文字列

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

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

どちらも有効化時にプロセス環境から解決されます。SecretRef の詳細はシークレット管理に記載されています。 設定 env ブロック自体は、SecretRef や file:... 省略値を解決しません。

パス関連の環境変数

ログ出力

OPENCLAW_HOME

設定されている場合、OPENCLAW_HOME は OpenClaw 内部パスのデフォルトに対して、システムのホームディレクトリ（$HOME / os.homedir()）を置き換えます。これには、デフォルトの状態ディレクトリ、設定パス、エージェントディレクトリ、認証情報、インストーラーのオンボーディングワークスペース、openclaw update --channel dev で使用されるデフォルトの開発チェックアウトが含まれます。

優先順位: OPENCLAW_HOME > $HOME > USERPROFILE > Android 上の Termux PREFIX ホームフォールバック > os.homedir()

例（macOS LaunchDaemon）:

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

OPENCLAW_HOME はチルダパス（例: ~/svc）にも設定でき、使用前に同じ OS ホームフォールバックチェーンを使って展開されます。

OPENCLAW_STATE_DIR、OPENCLAW_CONFIG_PATH、OPENCLAW_GIT_DIR などの明示的なパス変数は引き続き優先されます。シェル起動ファイルの検出、パッケージマネージャーのセットアップ、ホストの ~ 展開などの OS アカウントタスクは、実際のシステムホームを引き続き使用する場合があります。

nvm ユーザー: web_fetch の TLS 失敗

Node.js が（システムパッケージマネージャーではなく）nvm 経由でインストールされている場合、組み込みの fetch() は nvm に同梱された CA ストアを使用しますが、そこには最新のルート CA（Let's Encrypt の ISRG Root X1/X2、 DigiCert Global Root G2 など）がない場合があります。これにより、ほとんどの HTTPS サイトで web_fetch が "fetch failed" で失敗します。

Linux では、OpenClaw は nvm を自動検出し、実際の起動環境で修正を適用します。

• openclaw gateway install は systemd サービス環境に NODE_EXTRA_CA_CERTS を書き込みます
• openclaw CLI エントリーポイントは、Node 起動前に NODE_EXTRA_CA_CERTS を設定して自分自身を再実行します

手動修正（古いバージョンまたは直接の node ... 起動向け）:

OpenClaw を起動する前に変数をエクスポートします。

export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crtopenclaw gateway run

この変数については、~/.openclaw/.env のみに書き込む方法に依存しないでください。Node はプロセス起動時に NODE_EXTRA_CA_CERTS を読み取ります。

レガシー環境変数

OpenClaw は OPENCLAW_* 環境変数のみを読み取ります。以前のリリース由来のレガシーな CLAWDBOT_* および MOLTBOT_* プレフィックスは黙って無視されます。

起動時に Gateway プロセスでそれらがまだ設定されている場合、OpenClaw は検出されたプレフィックスと合計数を列挙する 単一の Node 非推奨警告（OPENCLAW_LEGACY_ENV_VARS）を出力します。 各値は、レガシープレフィックスを OPENCLAW_ に置き換えて名前変更してください（例: CLAWDBOT_GATEWAY_TOKEN → OPENCLAW_GATEWAY_TOKEN）。古い名前は効果を持ちません。

関連

• Gateway 設定
• FAQ: 環境変数と .env の読み込み
• モデル概要