Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
マルチエージェント設定内の各エージェントは、グローバルなサンドボックスとツールポリシーを上書きできます。このページでは、エージェントごとの設定、優先順位ルール、例について説明します。
サンドボックス化
バックエンドとモード — サンドボックスの完全なリファレンス。
サンドボックスとツールポリシーと昇格の違い
「なぜこれはブロックされるのか?」をデバッグする。
昇格モード
信頼済み送信者向けの昇格済み exec。
認証はエージェントごとにスコープされます。各エージェントには、~/.openclaw/agents/<agentId>/agent/auth-profiles.json に独自の agentDir 認証ストアがあります。複数のエージェント間で agentDir を再利用しないでください。エージェントはローカルプロファイルを持たない場合、デフォルト/メインエージェントの認証プロファイルを読み取れますが、OAuth 更新トークンはセカンダリエージェントのストアに複製されません。認証情報を手動でコピーする場合は、移植可能な静的 api_key または token プロファイルのみをコピーしてください。
設定例
例 1: 個人用 + 制限付きファミリーエージェント
{
"agents": {
"list": [
{
"id": "main",
"default": true,
"name": "Personal Assistant",
"workspace": "~/.openclaw/workspace",
"sandbox": { "mode": "off" }
},
{
"id": "family",
"name": "Family Bot",
"workspace": "~/.openclaw/workspace-family",
"sandbox": {
"mode": "all",
"scope": "agent"
},
"tools": {
"allow": ["read", "message"],
"deny": ["exec", "write", "edit", "apply_patch", "process", "browser"],
"message": {
"crossContext": {
"allowWithinProvider": false,
"allowAcrossProviders": false
}
}
}
}
]
},
"bindings": [
{
"agentId": "family",
"match": {
"provider": "whatsapp",
"accountId": "*",
"peer": {
"kind": "group",
"id": "120363424282127706@g.us"
}
}
}
]
}
main エージェント: ホスト上で実行され、すべてのツールにアクセスできます。family エージェント: Docker 内で実行され (エージェントごとに 1 つのコンテナ)、read と現在の会話へのメッセージ送信のみが許可されます。
例 2: 共有サンドボックスを使う仕事用エージェント
{
"agents": {
"list": [
{
"id": "personal",
"workspace": "~/.openclaw/workspace-personal",
"sandbox": { "mode": "off" }
},
{
"id": "work",
"workspace": "~/.openclaw/workspace-work",
"sandbox": {
"mode": "all",
"scope": "shared",
"workspaceRoot": "/tmp/work-sandboxes"
},
"tools": {
"allow": ["read", "write", "apply_patch", "exec"],
"deny": ["browser", "gateway", "discord"]
}
}
]
}
}
例 2b: グローバルなコーディングプロファイル + メッセージング専用エージェント
{
"tools": { "profile": "coding" },
"agents": {
"list": [
{
"id": "support",
"tools": { "profile": "messaging", "allow": ["slack"] }
}
]
}
}
- デフォルトエージェントはコーディングツールを取得します。
support エージェントはメッセージング専用です (+ Slack ツール)。
例 3: エージェントごとに異なるサンドボックスモード
{
"agents": {
"defaults": {
"sandbox": {
"mode": "non-main",
"scope": "session"
}
},
"list": [
{
"id": "main",
"workspace": "~/.openclaw/workspace",
"sandbox": {
"mode": "off"
}
},
{
"id": "public",
"workspace": "~/.openclaw/workspace-public",
"sandbox": {
"mode": "all",
"scope": "agent"
},
"tools": {
"allow": ["read"],
"deny": ["exec", "write", "edit", "apply_patch"]
}
}
]
}
}
設定の優先順位
グローバル (agents.defaults.*) とエージェント固有 (agents.list[].*) の両方の設定が存在する場合:
サンドボックス設定
エージェント固有の設定がグローバル設定を上書きします。
agents.list[].sandbox.mode > agents.defaults.sandbox.mode
agents.list[].sandbox.scope > agents.defaults.sandbox.scope
agents.list[].sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRoot
agents.list[].sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccess
agents.list[].sandbox.docker.* > agents.defaults.sandbox.docker.*
agents.list[].sandbox.browser.* > agents.defaults.sandbox.browser.*
agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
agents.list[].sandbox.{docker,browser,prune}.* は、そのエージェントについて agents.defaults.sandbox.{docker,browser,prune}.* を上書きします (サンドボックススコープが "shared" に解決される場合は無視されます)。
ツール制限
フィルタリング順序は次のとおりです。
ツールプロファイル
tools.profile または agents.list[].tools.profile。
プロバイダーツールプロファイル
tools.byProvider[provider].profile または agents.list[].tools.byProvider[provider].profile。
グローバルツールポリシー
tools.allow / tools.deny。
プロバイダーツールポリシー
tools.byProvider[provider].allow/deny。
エージェント固有のツールポリシー
agents.list[].tools.allow/deny。
エージェントプロバイダーポリシー
agents.list[].tools.byProvider[provider].allow/deny。
サンドボックスツールポリシー
tools.sandbox.tools または agents.list[].tools.sandbox.tools。
サブエージェントツールポリシー
該当する場合は tools.subagents.tools。
そのチェーン内の明示的な許可リストによって呼び出し可能なツールが 1 つも残らない場合、OpenClaw はプロンプトをモデルに送信する前に停止します。これは意図された動作です。agents.list[].tools.allow: ["query_db"] のように存在しないツールで設定されたエージェントは、query_db を登録する Plugin が有効化されるまで明確に失敗すべきであり、テキスト専用エージェントとして続行すべきではありません。
group:* 省略形をサポートします。完全な一覧は ツールグループ を参照してください。
エージェントごとの昇格上書き (agents.list[].tools.elevated) で、特定のエージェントの昇格済み exec をさらに制限できます。詳しくは 昇格モード を参照してください。
単一エージェントからの移行
移行前（単一エージェント）
移行後（マルチエージェント）
{
"agents": {
"defaults": {
"workspace": "~/.openclaw/workspace",
"sandbox": {
"mode": "non-main"
}
}
},
"tools": {
"sandbox": {
"tools": {
"allow": ["read", "write", "apply_patch", "exec"],
"deny": []
}
}
}
}
{
"agents": {
"list": [
{
"id": "main",
"default": true,
"workspace": "~/.openclaw/workspace",
"sandbox": { "mode": "off" }
}
]
}
}
従来の agent.* 設定は openclaw doctor によって移行されます。今後は agents.defaults + agents.list を使用してください。
ツール制限の例
読み取り専用エージェント
ファイルシステムツールを無効にしたシェル実行
通信のみ
{
"tools": {
"allow": ["read"],
"deny": ["exec", "write", "edit", "apply_patch", "process"]
}
}
{
"tools": {
"allow": ["read", "exec", "process"],
"deny": ["write", "edit", "apply_patch", "browser", "gateway"]
}
}
このポリシーは OpenClaw のファイルシステムツールを無効にしますが、exec は引き続きシェルであり、選択されたホストまたはサンドボックスのファイルシステムが許可する場所であればファイルを書き込めます。読み取り専用エージェントでは、exec と process を拒否するか、シェルアクセスを agents.defaults.sandbox.workspaceAccess: "ro" や "none" などのサンドボックスファイルシステム制御と組み合わせてください。
{
"tools": {
"sessions": { "visibility": "tree" },
"allow": ["sessions_list", "sessions_send", "sessions_history", "session_status"],
"deny": ["exec", "write", "edit", "apply_patch", "read", "browser"]
}
}
sessions_history は、生のトランスクリプトダンプではなく、境界が設定されサニタイズされたリコールビューを返します。アシスタントのリコールでは、思考タグ、<relevant-memories> の足場、プレーンテキストのツール呼び出し XML ペイロード（<tool_call>...</tool_call>、<function_call>...</function_call>、<tool_calls>...</tool_calls>、<function_calls>...</function_calls>、および切り詰められたツール呼び出しブロックを含む）、格下げされたツール呼び出しの足場、漏えいした ASCII/全角のモデル制御トークン、不正な MiniMax ツール呼び出し XML を、リダクション/切り詰めの前に除去します。
よくある落とし穴: “non-main”
agents.defaults.sandbox.mode: "non-main" は agent id ではなく session.mainKey（デフォルトは "main"）に基づきます。グループ/チャンネルセッションには常にそれぞれ独自のキーが割り当てられるため、non-main として扱われ、サンドボックス化されます。エージェントを一切サンドボックス化しない場合は、agents.list[].sandbox.mode: "off" を設定します。
テスト
マルチエージェントサンドボックスとツールを設定した後:
エージェント解決を確認する
openclaw agents list --bindings
サンドボックスコンテナを検証する
docker ps --filter "name=openclaw-sbx-"
ツール制限をテストする
- 制限付きツールを必要とするメッセージを送信します。
- エージェントが拒否されたツールを使用できないことを確認します。
ログを監視する
tail -f "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs/gateway.log" | grep -E "routing|sandbox|tools"
トラブルシューティング
`mode: 'all'` にもかかわらずエージェントがサンドボックス化されない
- それを上書きするグローバルな
agents.defaults.sandbox.mode があるか確認します。
- エージェント固有の設定が優先されるため、
agents.list[].sandbox.mode: "all" を設定します。
deny list にもかかわらずツールがまだ利用可能
- ツールフィルタリングの順序を確認します: グローバル → エージェント → サンドボックス → サブエージェント。
- 各レベルではさらに制限することだけが可能で、許可を戻すことはできません。
- ログで確認します:
[tools] filtering tools for agent:${agentId}。
- エージェント固有のサンドボックス設定で
scope: "agent" を設定します。
- デフォルトは
"session" で、セッションごとに 1 つのコンテナを作成します。
