Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

環境変数

すべての演算子の環境変数オーバーライドは、単一のスキーマミラー文法を使用します。ZEROCLAW_* 環境変数の末尾は、zeroclaw config set が受け付けるドット区切りのプロパティパスであり、各 __（二重アンダースコア）がパスセグメントを区切り、各単一の _ はフィールド名内の snake-case 結合子（set_prop における api_key → api-key）か、エイリアスキー内のリテラル文字のいずれかになります。

sh

ZEROCLAW_<dotted_path_with_double_underscores>=<value>

例

sh

# 型付きファミリーエイリアス資格情報を注入する
ZEROCLAW_providers__models__anthropic__home__api_key=sk-ant-...

# 既定以外の OpenRouter エイリアスにモデルを設定する（アンダースコアを含むエイリアスでも問題ありません）
ZEROCLAW_providers__models__openrouter__prod_v2__model=anthropic/claude-sonnet-4-6
ZEROCLAW_providers__models__openrouter__prod_v2__api_key=sk-or-...

# チャンネルの切り替えと設定
ZEROCLAW_channels__matrix__home__enabled=true
ZEROCLAW_channels__matrix__home__homeserver=https://matrix.example.org

# ゲートウェイのランタイム設定を上書きする
ZEROCLAW_gateway__request_timeout_secs=120
ZEROCLAW_gateway__long_running_request_timeout_secs=900

# ビルド済みのウェブダッシュボードをゲートウェイに指定する（絶対パス；~ / $HOME は使用不可）
ZEROCLAW_gateway__web_dist_dir=/srv/zeroclaw/web/dist

# Webhook署名シークレットを注入する
ZEROCLAW_channels__whatsapp__home__app_secret=...
ZEROCLAW_channels__linq__home__signing_secret=...
ZEROCLAW_channels__nextcloud_talk__home__webhook_secret=...

# Qdrant メモリバックエンド接続を注入する
ZEROCLAW_storage__qdrant__home__url=https://qdrant.example.com
ZEROCLAW_storage__qdrant__home__collection=ゼロクロー
ZEROCLAW_storage__qdrant__home__api_key=...

環境変数名から TOML パスへのマッピングは機械的です:

TOML環境変数
[providers.models.anthropic.home] api_key = "..."ZEROCLAW_providers__models__anthropic__home__api_key=...
[channels.matrix.home] homeserver = "..."ZEROCLAW_channels__matrix__home__homeserver=...
[gateway] request_timeout_secs = "..."ZEROCLAW_gateway__request_timeout_secs=...
[gateway] web_dist_dir = "..."ZEROCLAW_gateway__web_dist_dir=...

上記の <alias> セグメント（home、prod_v2）はオペレーターが選択するものです。実際の設定で使用している名前に置き換えてください。

ブートストラップ（大文字テール）

これらの環境変数は、Config が存在する前に、設定ファイルとインスタンスデータが_どこに_配置されるかを決定します。これらは UPPERCASE 形式を維持しているため、大文字小文字のルールによってスキーマミラーのサーフェスと区別されます。これらは ZEROCLAW_CONFIG_DIR > ZEROCLAW_DATA_DIR > ZEROCLAW_WORKSPACE（非推奨）の順に解決されます:

sh

ZEROCLAW_CONFIG_DIR=/etc/zeroclaw         # 設定ファイルの場所（優先される）
ZEROCLAW_DATA_DIR=/srv/zeroclaw           # インスタンスデータディレクトリ（正規）
ZEROCLAW_WORKSPACE=/srv/zeroclaw          # 非推奨 — ZEROCLAW_DATA_DIR のエイリアス

ゲートウェイの Web ダッシュボードの場所は、標準のスキーマミラー形式 ZEROCLAW_gateway__web_dist_dir で設定します。設定の完全なリファレンスについては、Web ダッシュボード (web_dist_dir) を参照してください。

永続性の境界

ZEROCLAW_* 環境変数を介して適用された値は、読み込み時にメモリ上の Config に反映され、ディスクには決して永続化されません。zeroclaw config save は、暗号化の前に、環境変数で上書きされたパスをディスク上の値またはデフォルト値にマスクし直します。シークレット型のパス（例：API キー）が環境変数で上書きされるたびに WARN ログ行が出力されるため、監査ログでインジェクションを可視化できます。

エイリアス文法

エイリアス（上記の例における <alias> セグメント、home、prod_v2、mymatrixalias など）は、以下のルールに従います。

  1. ASCII小文字、数字、単一のアンダースコア。
  2. 文字または数字で開始 かつ 終了する必要があります（先頭または末尾にアンダースコアは使用できません）。
  3. __ という部分文字列は使用できません（env-var グラマーのパス区切り文字として予約されています）。
  4. ハイフンは使用できません（環境変数の識別子では不正です）。
  5. 大文字は使用できません（ブートストラップ名と競合します）。
  6. 1–63文字。

prod_v2 は単一のエイリアストークンです。home__api_key は2つのセグメント（エイリアス home、フィールド api_key）として解析されます。準拠していないエイリアスを含む設定は、問題のあるエイリアスを示すロード時エラーを発生させます。

エラー

解決できない ZEROCLAW_<lowercase_*> 名（タイプミスや、スキーマ内のいずれのプロパティにも一致しないパス）は、問題のある環境変数名を示すハードエラーで起動を中止します。ZEROCLAW_ プレフィックスのない環境変数名は、このオーバーライドレイヤーでは読み取られません。

表示

設定がレンダリングされる場所では、オーバーライドの状態が表示され、💉インジケーターによって環境変数でオーバーライドされたフィールドが示されます:

  1. zeroclaw config list: 凡例 💉 env-overridden 🔒 secret を先頭に1回だけ表示します。env でオーバーライドされたフィールドの行には 💉 を先頭に付けます。
  2. Web Config エディター: すべての ListEntry には is_env_overridden のブール値が付与されます。環境変数で上書きされたフィールド行には 💉 バッジと、「ここでの編集は反映されません。ZEROCLAW_… によって上書きされています」 という常時表示の警告が表示されるため、オペレーターは編集を試みなくても上書きを確認できます。
  3. CLI/TUI のオンボーディング: prompt_field は環境変数で上書きされたフィールドをスキップし、💉 の3行のメモ（環境変数名、TOML パス、スキップ通知）を表示します。このメモは次へ／戻る操作で消去されます。オペレーターは、すでに注入済みの値を入力するよう求められることはありません。
  4. Reload drift: GET /api/config/drift、GET /api/config/list、およびリロードバナーは、環境変数でオーバーライドされたパスをドリフト計算から除外します。これらの値はメモリ上にのみ存在し、ディスクには書き込まれないため、除外しないと設定ファイルの編集では解消できない永続的なドリフトとして報告されてしまいます。除外することで、ドリフト出力はオペレーターが保存された設定を編集することで実際に解決できる差分に限定されます。
  5. プログラム的: Config::prop_is_env_overridden(path) -> bool は O(1) の HashSet ルックアップです。カスタムレンダリングレイヤー向けのフックをここに配置します。

設定からの環境変数名の導出

TOML キーから環境変数名を導出する 3 つの機械的な手順:

  1. パスの先頭に ZEROCLAW_ を付けます。 ドット区切りの設定パスが信頼できる情報源です。zeroclaw config schema でフィールドを見つけてください。
  2. . を __（ダブルアンダースコア、パスの区切り文字）に置き換えてください。
  3. フィールド名はそのまま維持されます（snake_case）。エイリアスもそのまま維持されます。それ以外は何も変換されません。

たとえば、[providers.models.anthropic.home] api_key = "sk-..." はドットパス providers.models.anthropic.home.api_key に存在します。3 つのルールを適用すると、環境変数は ZEROCLAW_providers__models__anthropic__home__api_key=sk-... になります。どのセクションのどのフィールドでも、同じ機械的なマッピングが適用されます。

エコシステムのデフォルト環境変数のブリッジ

スキーマミラー文法は値を注入する正規の方法ですが、ANTHROPIC_API_KEY / OPENROUTER_API_KEY / QDRANT_URL などは依然として .env ファイルや CI 設定でよく使われる名前です。1行のシェル展開で、スキーマミラー名をエコシステムのデフォルト値に向けることができます:

sh

# POSIX (bash, zsh, sh) — ~/.bashrc / ~/.zshrc / .env / Dockerfile に追加
export ZEROCLAW_providers__models__anthropic__home__api_key=$ANTHROPIC_API_KEY
export ZEROCLAW_providers__models__openai__home__api_key=$OPENAI_API_KEY
export ZEROCLAW_providers__models__openrouter__home__api_key=$OPENROUTER_API_KEY
export ZEROCLAW_providers__models__nearai__tee__api_key=$NEARAI_API_KEY
export ZEROCLAW_providers__models__zerorouter__gateway__api_key="$ZEROROUTER_API_KEY"
export ZEROCLAW_storage__qdrant__home__url="$QDRANT_URL"
export ZEROCLAW_storage__qdrant__home__api_key=$QDRANT_API_KEY
export ZEROCLAW_gateway__request_timeout_secs=$GATEWAY_TIMEOUT_SECS

PowerShell

# PowerShell — drop into $PROFILE
$env:ZEROCLAW_providers__models__anthropic__home__api_key = $env:ANTHROPIC_API_KEY
$env:ZEROCLAW_providers__models__openai__home__api_key = $env:OPENAI_API_KEY
$env:ZEROCLAW_providers__models__nearai__tee__api_key = $env:NEARAI_API_KEY
$env:ZEROCLAW_storage__qdrant__home__url = $env:QDRANT_URL

設定に合わせて、home の部分をエイリアス名に置き換えてください。同じファミリーに複数のエイリアスがある場合は、各エイリアスごとに行を繰り返してください。

これらの行は、シェルから型付き設定へのブリッジであり、コンストラクターがプロバイダー固有の環境変数を読み取るという一般的なルールではありません。実行時コードは、インテグレーションファミリーがネイティブ環境変数ブリッジを明示的に文書化している場合を除き、Config から解決済みの値を受け取るべきです。

OAuth と CLI パスフィールド

スキーマフィールドとして存在する一部のフィールドは、標準のマッピングを介してアクセスできます:

  1. MiniMax OAuth リフレッシュフロー: [providers.models.minimax.<alias>] oauth_refresh_token = "..."（オプションで oauth_client_id を指定可能）。リージョンの選択は、型付き endpoint 列挙型（cn / intl）で行います。ランタイムは、プロバイダー構築時にリフレッシュトークンを短命のアクセストークンと交換します。
  2. Qwen OAuth リフレッシュフロー: [providers.models.qwen.<alias>] oauth_refresh_token = "..."（オプションで oauth_client_id と oauth_resource_url を指定可能）。
  3. Gemini OAuth: [providers.models.gemini.<alias>] oauth_client_id と oauth_client_secret。オプションの oauth_project は Code Assist GCP プロジェクト ID を固定します。
  4. KiloCLI / Gemini CLI / Grok Build CLI のプロセス設定: [providers.models.kilocli.<alias>] binary_path、[providers.models.gemini_cli.<alias>] binary_path、および [providers.models.grok_cli.<alias>] のフィールド binary_path、必須の絶対パス working_directory、オプションの extra_args、max_acp_stdout_bytes。Grok Build のエイリアスでは、env_passthrough に環境変数名（ツールの認証情報とオプションの XAI_API_KEY 認証ブリッジ）を列挙することもできます。値は子プロセスの起動時にのみ解決され、設定には保存されません。認証ではデフォルトで CLI のログインキャッシュが使用されます。正確な名前 XAI_API_KEY は、明示的に列挙した場合の API キー認証用に文書化されたネイティブブリッジです。それ以外の XAI_* とすべての GROK_* の名前は拒否されます。
  5. 文字起こし / TTS キー: [transcription].api_key, [providers.tts.openai.<alias>].api_key, [providers.tts.elevenlabs.<alias>].api_key, [providers.tts.google.<alias>].api_key。
  6. Notion / WhatsApp: [notion].api_key、[channels.whatsapp.<alias>].ws_url（テスト/プロキシ用のWebSocketオーバーライド）。