マルチエージェントのセットアップ手順

これはエージェントのセクションに対応するオペレーター側のガイドです。インストールに2つ目のエージェントを追加し、エージェント間のメモリアクセスを設定し、両方のエージェントを同一チャンネル上のピアグループに配置するには、これに従ってください。

背景: 各エージェントは <install>/agents/<alias>/workspace/ に独自のワークスペースディレクトリを持ち、作成時に1つのメモリバックエンドを選択し(変更不可)、[risk_profiles.<profile>] エントリによって制御されます。

このウォークスルー全体を通して、既存の単一エージェントは primary と呼ばれます（実際のインストールで使用されているものに置き換えてください）。新しく追加されるエージェントは researcher です。

前提条件

• 動作する model_provider、risk_profile、および少なくとも1つのチャネルバインディングが設定された [agents.primary] エントリ。
• 新しいエージェントが継承する [risk_profiles.<name>] エントリ。ほとんどの用途では primary のプロファイルを再利用して問題ありません。新しいエージェントが異なる信頼境界を持つ場合は、より厳格なエイリアス（例: hardened）を選択してください。

2 つ目のエージェントを追加

ゲートウェイダッシュボード、zerocode、または zeroclaw config set を使って別のエージェントを追加します。ランタイムは、エージェントループへの初回エントリ時に <install>/agents/<alias>/workspace/ を作成します。起動のたびに、エージェントループは存在するワークスペースのアイデンティティファイルをシステムプロンプトに注入します。順に AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、続いて BOOTSTRAP.md（初回起動時のみ）と MEMORY.md（メインセッションのみ）です。HEARTBEAT.md もワークスペースのパーソナリティファイルですが、これはハートビートエンジンによって読み込まれ、プロンプトには注入されません。ダッシュボードのパーソナリティエディタでは、SOUL.md、IDENTITY.md、USER.md、AGENTS.md、TOOLS.md、HEARTBEAT.md、MEMORY.md を編集できます。これらのファイルを作成・編集して、エージェントにペルソナを与えてください。（BOOTSTRAP.md は初回起動時のスキャフォールドで、エージェントが一度読み込んで削除します。エディタには表示されません。）

チャンネルをバインド

チャネルがないと、エージェントは待ち受ける場所がありません。エージェントの channels リストでチャネルをバインドし、デーモンを再起動してください。エージェントは次回起動時にチャネルを取得します。

エージェント間ファイルアクセス

デフォルトでは、エージェントは自身のワークスペースディレクトリ内でのみ読み書きできます。あるエージェントに、別のエージェントのワークスペースへの読み取りまたは書き込みアクセスを付与することができます（gateway、zerocode、または zeroclaw config set で設定）。実際の動作の例、例えば researcher に primary への書き込みと archivist への読み取りを付与した場合：

• researcherのfile_readは、<install>/agents/primary/workspace/と<install>/agents/archivist/workspace/の両方を読み取ることができます。
• researcher の file_write と file_edit は <install>/agents/primary/workspace/ に書き込めますが、<install>/agents/archivist/workspace/ には書き込めません。

POSIXデバイスファイル（/dev/null、/dev/zero、/dev/random、/dev/urandom）は常に読み取り可能であり、エージェントごとの設定は不要です。

エージェント間のメモリアクセス

同一バックエンドのみ。researcher が primary の書き込んだメモリを参照できるようにするには、両エージェントが同じメモリバックエンド（例: 両方とも sqlite）を使用する必要があります。スキーマバリデーターは、異なるバックエンド上の兄弟を指すエントリを拒否します。ランタイムは、エージェントごとのメモリラッパーを構築する時点で、バックエンドをまたぐ許可リストを認識することはありません。

バインドされたエージェントは常に自身の行を参照できます。許可リストは純粋に追加的なものです。エージェント自身の行を、そのエージェントから 隠す 方法はありません。

共有チャネル上のピアグループ

2 つのエージェントが「ピア」（互いにチャネル上で相手を指定できる状態）になるのは、両方が同じピアグループに含まれている場合のみです。ピアグループを参照してください。

external_peers には、同じチャンネルにいると想定されるユーザーや外部ボットを列挙します。ランタイムはこれらのユーザー名からの受信をエージェント間トラフィックとして受け付けます。ignore はグループごとのブロックリストで、各メンバーが認識する解決済みのピアセットから差し引かれ、ノイズの多い特定のボットアカウントを除外するのに便利です。

設定読み込み時のスキーマバリデーターは、以下を強制します:

1. すべてのメンバーのchannelsリストには、グループのchannelが含まれます（そこをリッスンしていないエージェントは、そこでピアになることができません）。
2. すべてのメンバーは構成済みのエージェントです（無効な参照はありません）。
3. read_memory_from がエージェント自身を指していません。

インストールを確認する

すべての設定済みエージェントは、リスクプロファイル、モデルプロバイダー、メモリバックエンド、チャネルセットとともに agents.<alias> エントリの配下に存在します。

zeroclaw agents ライフサイクルコマンドは、標準配布バイナリを含め、gateway と agent-runtime が有効なビルドでのみ、完全な所有状態のカスケードを実行します。機能縮小版 CLI でも設定は変更されますが、所有状態はカスケードされなかったことが表示されます。所有状態が存在する場合、以下の操作には gateway ダッシュボード、または両方の機能が有効なバイナリを使用してください。

エージェントの名前を変更する

ゲートウェイダッシュボードの Config > Agents でエージェントの名前変更コントロールを使用するか、次を実行します:

zeroclaw agents rename researcher analyst

両方のサーフェスで、エイリアスへの参照を書き換え、設定を永続化し、エイリアスごとのデフォルトワークスペースを移動し、所有するメモリ、cron、ACP、およびセッション状態の参照先を付け替えます。カスタムワークスペースパスは、エイリアスから派生したものではないため移動されません。予約済みの default エイリアスは、名前変更元にも名前変更先にもできません。

レスポンス内の警告をすべて確認してください。config のリネームは workspace および owned-state のマイグレーションより前にコミットされるため、警告は依然として対応が必要な副作用を示します。同じ gateway API のリネームリクエストを再発行することで、古いエイリアスの下に残った残留物の再試行が可能です。

エージェントを削除

Config > Agents の下にある削除コントロールを使用するか、CLI 操作をプレビューして適用します:

zeroclaw agents delete researcher --dry-run
zeroclaw agents delete researcher --yes

1. 影響プレビューを確認し、そこで報告されるブロッカーをすべて解消します。よくある構成上のブロッカーには、エージェントが所有する有効なハートビートや、他の有効なエージェントが所有していない有効なチャネルバインディングがあります。プレビューには、カスケードによって自動的に削除されるソフト参照も一覧表示されます。
2. ライブの ACP セッションをすべて終了してください。ダッシュボードはそれらをプレビューに含めます。CLI は、設定のみの --dry-run プレビューの後、--yes を実行する際にそれらを検証します。
3. ダッシュボードで削除を確認するか、CLIコマンドを--yes付きで実行してください。この操作では、まず設定からエージェントとソフト参照を削除し、その後所有状態のカスケードを実行します。
4. アーカイブまたはクリーンアップの結果を信頼する前に、<data_dir>/agents/_deleted/<alias>-<timestamp>/ とゲートウェイログを確認してください。

所有状態のカスケードは、次のことを試みます:

• 設定済みのワークスペースを削除アーカイブに移動する;
• エクスポートされたメモリ、cron、およびACP データを cascade/ 以下に書き込みます。
• エージェントのメモリ行とcronジョブを削除します。
• 非アクティブな ACP セッションを削除します;
• 保持された会話セッションからエージェントの帰属情報を消去し、かつ
• manifest.json にカウントと表示される警告を書き込みます。

これらの副作用はベストエフォートです。エクスポートまたはアーカイブファイルの書き込みが失敗しても、その後のクリーンアップは継続されます。アーカイブが完全であると仮定せず、該当する workspace/、cascade/*.json、および manifest.json のエントリを確認してください。CLIはカスケード警告を表示します。削除APIもそれらを返しますが、ダッシュボードは現在それらを表示しません。ダッシュボードオペレーターはゲートウェイログも確認する必要があります。

このフローを、TOML の直接編集、zeroclaw config set、ワークスペースの手動削除、または SQL による削除に置き換えないでください。これらの方法では、ゲートウェイの参照および所有状態のカスケード処理が実行されません。

自動復元コマンドはありません。検査や手動復旧が不要になるまで、削除アーカイブを保持してください。

確認

マージされたログストリームを確認してください。すべての行に [<alias>] または [system] のプレフィックスが付いているはずです:

zeroclaw daemon 2>&1 | grep '\[researcher\]'   # researcher's lines only
zeroclaw daemon 2>&1 | grep '\[system\]'       # ブート/マイグレーション/スケジューラの行のみ

境界チェックが正しく機能している場合、任意のエージェントからの file_read /dev/null は成功し（POSIX デバイスファイルの許可リスト）、ワークスペースおよびアクセスリストの外部に対する file_read は Path escapes workspace directory で失敗し、読み取り専用で許可リストに登録された兄弟ディレクトリへの file_write も同じメッセージで失敗します。