設定ライフサイクル

設定はオペレーターインターフェースであると同時にランタイム契約でもあります。明確な所有者を持つ状態として扱い、必要とするサブシステムにコピーされた緩い設定として扱わないでください。

正規の情報源は zeroclaw_config::schema::Config であり、config.toml から読み込まれます。ユーザー向けの設定サーフェス、生成される設定リファレンス、ゲートウェイの設定エディター、環境変数のオーバーライド、zeroclaw config set、zeroclaw config patch、クイックスタート、RPC の設定メソッドはすべて、この同じ型付きスキーマを経由します。

型付けされたスキーマを設定リファレンスに変換するビルド順序、追跡対象出力ルール、ドリフトチェックについては、生成ドキュメントパイプラインを参照してください。

何が何を所有するか

生成された設定リファレンスを手動で編集しないでください。フィールド、enum、alias セクション、secret マーカー、または説明が誤っている場合は、スキーマまたはジェネレーターを修正してリファレンスを再生成してください。

読み込み順序

設定の読み込みには、いくつかの明確なフェーズがあります:

1. ブートストラップ環境変数からインストールルートを解決します。これは Config が存在する前に行われるため、ブートストラップ名は大文字のまま維持され、スキーマミラー文法は使用されません。
2. config.toml を読み込み、メモリ内でスキーマ移行を実行し、設定されたシークレットを復号し、不正な形式のセキュリティ上重要なセクションをセキュリティ低下として記録します。
3. スキーマミラーのオーバーライドをインメモリ設定に適用します。環境変数では、__ は . にマップされるため、ZEROCLAW_providers__models__openai__api_key は providers.models.openai.api_key を対象とします。
4. オペレーターがゲートウェイエディターからロックアウトされることなく、検証して警告します。

新規インストール時には、環境変数によるオーバーライドが適用される前にデフォルトが保存されます。これにより、環境変数から注入されたシークレットとローカルCIの値が新しいファイルに含まれないようになります。

環境変数のオーバーライドは保存されません

スキーマミラーの環境変数は、実行時に注入される値です。ロード時にメモリ上の Config に反映され、env_overridden_paths で追跡されるため、CLI、ダッシュボード、クイックスタートでオーバーライドマーカーを表示できます。

保存時には、暗号化の前に、これらのパスをオーバーライド前のディスク上の値またはデフォルト値へマスクして戻す必要があります。これはシークレットにおいて特に重要です。オペレーターが暗号化されたディスク上のAPIキーを持っており、同じパスに対して環境変数のオーバーライドを一時的に指定して起動した場合、無関係な設定の保存によって、実際の認証情報が環境変数の値やマスクされた表示用文字列で置き換えられてはなりません。

この不変条件を念頭に置いて、設定変更を確認してください:

• ZEROCLAW_* スキーマミラー値は、ロード後の実行中プロセスに影響します。
• これらは永続的な設定にはなりません。
• 保存パスでは、同じパスが意図的に編集された場合を除き、暗号化されたシークレットおよび外部シークレット参照を保持する必要があります。

資格情報の入力は型付けされたまま

認証情報に類似したランタイム値は、依然として設定値です。APIキー、OAuth トークン、エンドポイントURL、その他のプロバイダー/チャンネル認証情報は、ランタイムコンストラクターが受け取る前に、型付き設定スキーマ、設定シークレット処理、またはスキーマミラーの ZEROCLAW_* オーバーライドを経由する必要があります。

provider、channel、tool、transcription、TTS、memory、gateway のコンストラクター内に、アドホックな std::env::var("PROVIDER_API_KEY") の読み取りを追加しないでください。これにより Config の外部に 2 つ目の認証情報ソースが作成され、環境変数オーバーライドの可視性が迂回され、CLI、gateway、RPC/TUI、quickstart、reload の動作に不一致が生じる可能性があります。

ZeroClaw が連携ファミリー向けのネイティブ環境ブリッジを意図的にサポートする場合は、そのブリッジを連携境界で文書化し、構築前に同じ型付き設定値へマッピングしてください。それ以外の場合、ANTHROPIC_API_KEY、OPENROUTER_API_KEY、QDRANT_URL などのエコシステム標準のシェル名は、運用者が対応する ZEROCLAW_* スキーマミラー変数へブリッジする必要があります。環境変数を参照してください。

ダーティパスと増分書き込み

ほとんどの編集サーフェスは、完全な書き換えではなく Config::mark_dirty() と save_dirty() を使用します。save_dirty() は変更されたドット区切りパスのみを書き込み、可能な場合は dirty でないエントリとコメントを保持し、現在の schema_version をスタンプし、アトミックな一時ファイル置換を通じて書き込みます。

そのパスは、マップキーのセクションも担当します。モデルプロバイダー、MCP サーバー、スキルバンドル、ナレッジバンドルなどのエイリアスを作成する際は、エイリアスが保存と再読み込み後も維持されるよう、適切なセクションを dirty 状態にする必要があります。メモリ内のダッシュボード状態のみを更新する設定変更は不完全です。

設定の書き込みをレビューする際は、次の点を確認してください。

• 編集されたパスは永続化の前にダーティとしてマークされます。
• map-key の作成、名前変更、削除は、親セクションまたはナチュラルキーをダーティにします。
• secret および env で上書きされたパスは、その保存マスキング動作を維持します。
• 増分書き込み後も schema_version は最新の状態を維持します。
• 変更された値は save_dirty() の後にリロードしても保持されます。

保存済みと適用済み

保存が成功したことは、ファイルが変更されたことを意味します。すべてのランタイムコンポーネントが変更を反映したことを常に意味するわけではありません。

デーモンは長寿命のサブシステムグラフを所有します。ゲートウェイ、チャネルリスナー、スケジューラー、MQTT リスナー、セッション接続、メモリバックエンド、プロバイダーファクトリー、コスト接続などです。POST /admin/reload はデーモンループにシグナルを送り、デーモンループは config.toml を再読み込みして、同一プロセス内でこれらのサブシステムを再インスタンス化します。PID は変わりませんが、リスナーは一時的に再バインドされます。

ゲートウェイ設定の書き込みは persist_and_swap() を呼び出します: ディスクに保存し、その後ゲートウェイから見えるインメモリ設定を置き換え、pending_reload を設定します。これにより設定エディターは書き込みを即座に反映し、一方でリロードバナーはオペレーターに、チャネル、プロバイダー、スケジューラー、またはその他のデーモン所有コンポーネントが前のサブシステムインスタンスからまだ実行中である可能性があることを伝えます。

スタンドアロンの zeroclaw gateway start にはデーモンスーパーバイザーがありません。シグナルを送る外部のデーモンループが存在しないため、そのリロードエンドポイントは再起動が必要であるというレスポンスを返します。

アクセスを再読み込み

ローカルリロードはループバックから許可されています。リモートリロードには両方が必要です:

1. gateway.allow_remote_admin = true
2. ペアリングが有効で、有効なペアリング済みベアラートークンがある状態

ペアリングが無効のときにリモート管理をオプトインすると、匿名のリモートリロードアクセスとして扱われるのではなく拒否されます。

セキュリティ上重要な不正な設定セクションは、オペレーターが明示的に劣化状態での提供を選択した場合にのみ、劣化を許容します。それ以外の場合、デフォルトへのリセットによるセキュリティ体制がファイルの意図よりも弱くなる可能性があるため、プロセスは提供を拒否します。

ロールバックと修復

設定の書き込みでは、アトミックな一時ファイル置換と所有者専用のパーミッションを使用します。既存のファイルを置き換える場合、ライターは置換中に同じディレクトリに config.toml.bak を作成し、書き込みが成功した後にそれを削除します。Gateway の書き込みでは、書き込み前のファイルのスナップショットも取得し、メモリ内の状態を入れ替える前に永続化に失敗した場合はベストエフォートで復元します。

保存されて適用された後の、有効だが望ましくない設定変更に対する一般的なトランザクションロールバックはありません。バックアップから以前の config.toml を復元し、CLI またはダッシュボードでフィールドを元に戻し、上記のランタイム境界に応じてリロードまたは再起動してください。

設定で可視のものが常にランタイムでサポートされているとは限らない

フィールドは、すべてのランタイムパスがそれを消費する前にスキーマ可視になり得ます。それは、ドキュメントとレビューノートが明確にそう述べている場合にのみ許容されます。

例えば、knowledge_bundles はスキーマ可視であり、config section API に現れます。そのようなサーフェスを追加または変更する PR は、設定のみを保存するのか、ランタイムの動作を配線するのか、あるいはその両方を完了するのかについて正確でなければなりません。

スキーマ上は可視だがまだ実行時には使用されていないフィールドに触れる PR をレビューする際は、実行時の配線が延期されているのか、対象外なのか、または同じ変更で完了しているのかを PR の説明に明記するよう求めてください。

レビュー担当者向けチェックリスト

設定スキーマ、環境変数、デフォルト、またはリロードの変更については、尋ねてください:

• 新しい値の信頼できる情報源は何ですか？
• これは重複した状態を作成していますか、それとも使用時に Config から解決していますか？
• 生成されたリファレンスは、手作業で維持された散文ではなくコードから来ていますか？
• env オーバーライドはロード時のみで、保存時にマスクされますか？
• CLI、gateway、RPC/TUI、および quickstart のサーフェスは、ドット区切りパスについて一致していますか？
• 認証情報は、アドホックなプロバイダー固有の env 読み取りではなく、型付き設定または文書化されたスキーマミラー ブリッジを通じて解決されますか？
• 保存は、単なる即座のインメモリレンダリングだけでなく、プロセスのリロード後も存続しますか？
• PRには、ユーザーがリロード、再起動、マイグレーション、または手動ロールバックを必要とするかどうかが記載されていますか？
• フィールドが設定でのみ可視の場合、PR はランタイムサポートを主張することを避けていますか？

ソースポインタ

• 設定スキーマと永続化: crates/zeroclaw-config/src/schema.rs
• 環境変数オーバーライドの構文: crates/zeroclaw-config/src/env_overrides.rs
• 設定 CLI コマンド: src/main.rs
• RPC および TUI の設定メソッド: crates/zeroclaw-runtime/src/rpc/dispatch.rs
• 共有クイックスタートの適用パス: crates/zeroclaw-runtime/src/quickstart/mod.rs
• Web Quickstart のリロードシグナル: crates/zeroclaw-gateway/src/api_quickstart.rs
• ゲートウェイ設定APIおよびリロードバナー: crates/zeroclaw-gateway/src/api_config.rs
• リロードエンドポイントとアクセスゲート: crates/zeroclaw-gateway/src/lib.rs
• Gateway Bearer 認証ヘルパー: crates/zeroclaw-gateway/src/api.rs
• 生成されたリファレンスパイプライン: xtask/src/cmd/mdbook/refs.rs