マルチエージェント構成の各エージェントは、グローバルなサンドボックスとツールポリシーを上書きできます。このページでは、エージェントごとの設定、優先順位ルール、例を説明します。
サンドボックス化
バックエンドとモード — サンドボックスの完全なリファレンス。
サンドボックス vs ツールポリシー vs 昇格
「なぜこれはブロックされているのか？」をデバッグする。
認証はエージェント単位でスコープされます。各エージェントは ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite に独自の 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" }
}
]
}
}
レガシーの agents.defaults.*/agents.list[].* 設定キー（sandbox.perSession、agentRuntime、embeddedPi など）は 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" は、エージェント ID ではなく、セッションキーをメインセッションキー（常に "main"。session.mainKey はユーザー設定不可であり、OpenClaw はその他の値を警告して無視します）と照合します。グループ/チャンネルセッションには常に独自のキーが割り当てられるため、non-main として扱われ、サンドボックス化されます。あるエージェントを決してサンドボックス化したくない場合は、agents.list[].sandbox.mode: "off" を設定してください。
テスト
マルチエージェントのサンドボックスとツールを設定した後:
エージェント解決を確認する
openclaw agents list --bindings
サンドボックスコンテナを検証する
docker ps --filter "name=openclaw-sbx-"
ツール制限をテストする
- 制限されたツールを必要とするメッセージを送信します。
- エージェントが拒否されたツールを使用できないことを検証します。
ログを監視する
openclaw logs --follow | grep -E "routing|sandbox|tools"
トラブルシューティング
`mode: 'all'` なのにエージェントがサンドボックス化されない
- それを上書きするグローバルな
agents.defaults.sandbox.mode があるか確認してください。
- エージェント固有の設定が優先されるため、
agents.list[].sandbox.mode: "all" を設定してください。
- 完全なフィルタリング順序を確認してください: プロファイル → プロバイダープロファイル → グローバルポリシー → プロバイダーポリシー → エージェントポリシー → エージェントプロバイダーポリシー → サンドボックス → サブエージェント。
- 各レベルはさらに制限できるだけで、許可を戻すことはできません。
- 手順ごとのデバッグについては、サンドボックス vs ツールポリシー vs 昇格を参照してください。
- デフォルトの
scope は "agent" です（エージェント ID ごとに 1 つのコンテナ）。
- セッションごとに 1 つのコンテナを使うには
scope: "session" を設定し、複数のエージェントで 1 つのコンテナを再利用するには scope: "shared" を設定します。
