ランタイム内部構造

このページは、Agentsセクションの残りの部分を補完するアーキテクチャの詳細解説です。ランタイムがエージェントごとの権限をどのように適用し、メモリのスコープをどのように決定し、ログをどのように帰属させるかを扱います。エージェントの設定と実行については、まずAgentsから始めてください。スキーマレベルのフィールドリファレンスについてはConfigを、実際のセットアップ手順についてはMulti-agent setupを参照してください。

権限モデル

各エージェントの実効的な SecurityPolicy は SecurityPolicy::for_agent(config, alias) によって構築されます:

エージェントのリスクプロファイル（[risk_profiles.<profile>]）から始めます。
境界をエージェントごとのワークスペースディレクトリ（<install>/agents/<alias>/workspace/）に設定します。
[agents.<alias>.workspace.access] を確認:
- Read → 兄弟のワークスペースが読み取り専用の許可リストに追加されます。
- Write → 兄弟エージェントのワークスペースが書き込み専用の許可リストに追加されます。
- ReadWrite → 兄弟ワークスペースが読み書き許可リストに追加されます。
[agents.<alias>.workspace.unrestricted_filesystem] が true の場合は、workspace_only をオフにします。

読み取り専用の許可リストは、file_read や、git_operations の status、diff、log、branch、stash-list、worktree-list コマンドを含むその他の読み取り側ツールで適用されます。worktree-list は、worktree のパスが解決でき、かつ Git のメタデータが該当する読み取り権限を通じて検証できるエントリのみを返します。読み取り書き込み許可リストは、file_write、file_edit、書き込み扱いの git_operations コマンド（worktree add/remove/prune を含む）、およびシェルツールのパスに触れる呼び出しを制御します。書き込み専用の兄弟ワークスペースは git_operations で利用できません。Git は、いかなる操作の前にもリポジトリのメタデータを読み取る必要があります。worktree の対象および連結 worktree の .git／gitdir／commondir のメタデータは、該当する許可の範囲内にある必要があります。git_operations は、そのメタデータ内のシンボリックリンクを、最終的な参照先が許可されている場合でも、追跡せずに拒否します。Git の呼び出しでは、継承された GIT_* 変数は破棄されます。コミット時の ID は、環境変数ではなく、リポジトリまたはグローバルの Git 設定で構成してください。読み取り専用コマンドは、リポジトリで設定された実行可能な統合機能と mailmap による ID 解決を抑止します。また、固定のログ形式では生の author フィールドを使用するため、これらのコマンドは .mailmap や mailmap.file を一切読み込みません。Git のトランスポートは禁止されており、暗黙的な promisor オブジェクトの取得も無効化されています。そのため、利用できない部分クローンのオブジェクトを必要とする読み取りは、リポジトリが選択したトランスポートを起動するのではなく、失敗します。書き込みコマンドは、オペレーターが読み取り書き込みアクセスを許可した場合に、通常の Git フックとフィルターを保持し、エージェントごとに設定されたサンドボックスの境界を適用します。[runtime] kind = "docker" の場合、書き込み扱いの Git コマンドは起動される前に、すべて git_operations によって拒否されます。Git はランタイムコンテナに入らないためです。読み取り扱いのコマンドは変更されません。シェルツールは引き続きコンテナ内でのコマンド実行経路です。ネイティブのランタイムモードでは、no-op サンドボックスは Git を制限しません。設定された兄弟ルートにサンドボックスを拡張するのは Landlock バックエンドのみです。他のサンドボックスバックエンドでは、エージェントのワークスペース外への書き込みを拒否したり、ワークスペースを読み取り専用でマウントしたり、ワークスペースを省略したり、グローバルな Git 設定を隠したりすることがあります。バックエンドの動作についてはサンドボックスを参照してください。POSIX のデバイスファイル（/dev/null、/dev/zero、/dev/random、/dev/urandom）は、エージェントごとの設定がなくてもシェルのイディオムが動作し続けるよう、常に読み取り可能です。

SubAgent の生成では、子が親を超えて権限を昇格できないというルールが適用されます。バリデーターの全軸リストと予算共有の動作については、委譲 → 権限の継承に記載されています。

Single-tool rounds

単一ツールラウンドでは、プロバイダーの応答ごとに最大 1 件のネイティブツール呼び出しを要求します。既存のエージェントループがその呼び出しを実行して結果を記録し、同じユーザーターン内でプロバイダーに次の応答を求めます。モデルは呼び出しの合間に説明を述べてもかまいませんが、その説明は必須ではなく、ZeroClaw が生成するものでもありません。

このモードはデフォルトでオフです。ZeroCode Config で runtime_profiles.<profile>.single_tool_rounds を true に設定し、agents.<alias>.runtime_profile でそのプロファイルを選択してください。値が未設定の場合や false の場合は、バッチ動作のままです。この設定は parallel_tools とは独立しています。parallel_tools は、プロバイダーが返せる呼び出し数ではなく、許可されたバッチの実行並行性を制御します。

サポートされているプロバイダールートでのみ、このポリシーが有効になります。選択されたルートまたは到達可能なフォールバックのいずれかがサポートしていない場合、ZeroClaw はバッチ動作を維持し、ターンごとに1回制限事項の通知を表示します。ポリシーが有効な状態で、ネイティブまたは復元されたツール呼び出しを複数含むレスポンスは、いずれのツール呼び出しも実行される前、またはツール交換履歴に追加される前に失敗します。拒否されたプロバイダーリクエストの使用量も、トークンおよびコストの計算に含まれます。ストリーミングされた途中の出力はすでに表示されている場合があります。ZeroClaw は違反したレスポンスを再生しません。

ツールの承認、レシート、キャンセル、反復回数の上限は、既存の動作を維持します。逐次呼び出しでは、プロバイダーへのリクエストが増え、レイテンシーが高くなる場合があり、max_tool_iterations にもより早く到達することがあります。元に戻すには、選択中のランタイムプロファイルで single_tool_rounds を false に設定するか、設定を解除してください。

メモリモデル

各エージェントは独自の Arc<dyn Memory> インスタンスを持ちます。ファクトリ（zeroclaw_memory::create_memory_for_agent）はバックエンドの種類に応じてディスパッチします:

SQLite / Postgres / Lucid: インストール全体で共有されるストア。agents テーブルはエイリアスから UUID へのマッピングを保持し、memories テーブルは、その UUID を参照する agent_id を保持します。ファクトリは内部バックエンドを AgentScopedMemory でラップします。AgentScopedMemory は、すべての保存時に store_with_agent を通じて、バインドされたエージェントの UUID を付与し、すべての検索を、解決済みの許可リストによって recall_for_agents でフィルタリングします。構造化された権限付与により、各兄弟エージェントをさらに正確なカテゴリ名に絞り込むことができます。バインドされたエージェントは、自身のすべてのカテゴリを常に参照できます。
Markdown: エージェントごとのディレクトリ。各エージェントの MarkdownMemory は <install>/agents/<alias>/workspace/MEMORY.md と memory/YYYY-MM-DD.md に書き込みます。Markdown は行ごとのカスタムカテゴリを保持できないため、設定バリデーターとファクトリーはこのバックエンドに対するカテゴリ単位の権限付与を拒否します。受け入れられるのは制限のない兄弟エージェントへの権限付与のみです。ラッパーは、直接のピア構築に対しても防御的にフィルタリングを行います。
Qdrant: 共有コレクション、ペイロードをキーとして使用。agent_id ペイロードフィールドはエージェントごとの帰属情報です。recall_for_agents は多めにフェッチし、ペイロードで事後フィルタリングします。
None: no-op スタブ。ランタイムパスを統一するため、ラッパー自体は引き続き存在します。

バックエンドをまたぐクロスエージェントメモリはサポートされていません。設定読み込み時のスキーマバリデータは、別のバックエンド上の兄弟エージェントを指す read_memory_from のエントリを拒否します。カテゴリの権限付与は完全一致で、推移的ではありません。未知のカテゴリはどの行にも一致しません。

名前の変更と削除のライフサイクル

名前変更と削除には、gateway ダッシュボードのエージェント操作、または専用の zeroclaw agents CLI を使用してください。gateway と agent-runtime を有効にした標準ビルドでは、どちらのインターフェイスでも参照と所有状態のカスケードが実行されますが、TOML 内で agents.<alias> を直接削除またはキー変更したり、汎用の設定セッターを介して操作したりしても、カスケードは実行されません。機能を削減した CLI でも設定参照は更新されますが、所有状態のカスケードは行われなかったことを警告するため、ライフサイクル操作には両方の機能を有効にしたビルドを使用してください。

どちらの操作も、所有状態のサイドエフェクトを実行する前に設定変更を永続化します。Rename は最初に設定参照を書き換え、次にエイリアスごとのデフォルトワークスペースを移動して、メモリ、cron、ACP、およびセッション状態を再指定します。Delete は最初にハード参照とライブ ACP セッションを拒否し、次に設定エントリとソフト参照を削除してから、ワークスペースのアーカイブ、所有状態のエクスポートとクリーンアップ、およびセッション帰属のクリアを試みます。

永続化後の副作用はベストエフォートで実行され、表面化した失敗は報告されますが、アーカイブファイルへの書き込み失敗はゲートウェイのログにしか現れない場合があります。名前変更の警告が出た場合は、古いエイリアスの下に残された残留物を収束させるため、同じゲートウェイ API の名前変更を再試行してください。削除後は、アーカイブを復旧に利用する前に、アーカイブの内容とログを確認してください。自動復元はサポートされていません。

現在の制御、ブロッカー、アーカイブのレイアウト、オペレーターによる確認事項については、マルチエージェントのセットアップ手順を参照してください。

現在サポートされていません

バックエンド間・エージェント間のメモリアクセス（例: SQLite エージェントが Postgres エージェントの行を読み取る）。
エージェント削除アーカイブからの自動復元。
エージェントごとのシークレット名前空間: ワークスペース全体で単一の SecretStore が存在します。
クロスエージェントスコープ用のLucidワイヤーフォーマット拡張。