跳轉到主要內容
多代理設定中的每個代理都可以覆寫全域沙箱與工具政策。本頁說明每個代理的設定、優先順序規則與範例。

沙箱化

後端與模式 — 完整沙箱參考。

沙箱 vs 工具政策 vs 提權

除錯「為什麼這被封鎖？」

提權模式

供受信任傳送者使用的提權 exec。
驗證以代理為範圍：每個代理都有自己的 agentDir 驗證儲存區，位於 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite。絕不要在代理之間重複使用 agentDir。當代理沒有本機設定檔時，可以讀取預設/主要代理的驗證設定檔，但 OAuth 重新整理權杖不會複製到次要代理儲存區。如果你手動複製認證，請只複製可攜式的靜態 api_key 或 token 設定檔。

​
設定範例

{
  "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 中執行（每個代理一個容器），只能使用 read 與目前對話的訊息傳送。
{
  "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"]
        }
      }
    ]
  }
}

{
  "tools": { "profile": "coding" },
  "agents": {
    "list": [
      {
        "id": "support",
        "tools": { "profile": "messaging", "allow": ["slack"] }
      }
    ]
  }
}
結果：
  • 預設代理會取得寫程式工具。
  • support 代理僅能處理訊息（+ Slack 工具）。
{
  "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" 時會被忽略）。

​
工具限制

篩選順序如下：
1

工具設定檔

tools.profile 或 agents.list[].tools.profile。
2

提供者工具設定檔

tools.byProvider[provider].profile 或 agents.list[].tools.byProvider[provider].profile。
3

全域工具政策

tools.allow / tools.deny。
4

提供者工具政策

tools.byProvider[provider].allow/deny。
5

代理專屬工具政策

agents.list[].tools.allow/deny。
6

代理提供者政策

agents.list[].tools.byProvider[provider].allow/deny。
7

沙箱工具政策

tools.sandbox.tools 或 agents.list[].tools.sandbox.tools。
8

子代理工具政策

tools.subagents.tools，如果適用。
  • 每一層都可以進一步限制工具，但不能重新授予先前層級已拒絕的工具。
  • 如果設定了 agents.list[].tools.sandbox.tools，它會取代該代理的 tools.sandbox.tools。
  • 如果設定了 agents.list[].tools.profile，它會覆寫該代理的 tools.profile。
  • 提供者工具鍵可接受 provider（例如 google-antigravity）或 provider/model（例如 openai/gpt-5.4）。
如果該鏈中的任何明確允許清單讓執行沒有任何可呼叫工具，OpenClaw 會在將提示提交給模型之前停止。這是刻意設計：設定了缺少工具（例如 agents.list[].tools.allow: ["query_db"]）的代理，應該在註冊 query_db 的外掛啟用之前明確失敗，而不是以純文字代理繼續執行。
工具政策支援會展開為多個工具的 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.defaults.*/agents.list[].* 設定鍵（例如 sandbox.perSession、agentRuntime、embeddedPi）會由 openclaw doctor 遷移；往後請優先使用 agents.defaults + agents.list。

​
工具限制範例

{
  "tools": {
    "allow": ["read"],
    "deny": ["exec", "write", "edit", "apply_patch", "process"]
  }
}

​
常見陷阱：「non-main」

agents.defaults.sandbox.mode: "non-main" 會將工作階段鍵與主要工作階段鍵比對（永遠是 "main"；session.mainKey 不可由使用者設定，OpenClaw 會警告並忽略任何其他值），而不是比對代理 ID。群組/頻道工作階段永遠會取得自己的鍵，因此會被視為非主要並進入沙箱。如果你希望某個代理永不進入沙箱，請設定 agents.list[].sandbox.mode: "off"。

​
測試

設定多代理沙箱與工具之後：
1

檢查代理解析

openclaw agents list --bindings
2

驗證沙箱容器

docker ps --filter "name=openclaw-sbx-"
3

測試工具限制

  • 傳送一則需要受限制工具的訊息。
  • 驗證代理無法使用被拒絕的工具。
4

監控記錄

openclaw logs --follow | grep -E "routing|sandbox|tools"

​
疑難排解

  • 檢查是否有全域 agents.defaults.sandbox.mode 覆寫它。
  • 代理專屬設定優先，因此請設定 agents.list[].sandbox.mode: "all"。
  • 查看完整篩選順序：設定檔 → 供應商設定檔 → 全域政策 → 供應商政策 → 代理政策 → 代理供應商政策 → 沙盒 → 子代理。
  • 每一層只能進一步限制，不能重新授權。
  • 請參閱沙盒與工具政策與提權，取得逐步除錯說明。
  • 預設 scope 是 "agent"（每個代理 ID 一個容器）。
  • 設定 scope: "session" 以讓每個工作階段使用一個容器，或設定 scope: "shared" 以在多個代理之間重用同一個容器。

​
相關