多代理沙盒和工具

多代理设置中的每个代理现在都可以拥有自己的：

- ''沙盒设置'' (''agents.list[].sandbox'' 是 ''agents.defaults.sandbox'' 覆盖执行)

- ''工具限制'' (''tools.allow'' / ''tools.deny''、以及 ''agents.list[].tools'')

这允许您运行具有不同安全配置文件的多个代理：

- 具有完全访问权限的个人助手

- 具有限制工具的家庭/工作代理

- 在沙箱中运行的面向公众的代理

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

''setupCommand'' belongs under ''sandbox.docker'' (global or per-agent) and runs once when the container is created.

Auth is per-agent: each agent reads from its own ''agentDir'' auth store at:

Credentials are ''not'' shared between agents. Never reuse ''agentDir'' across agents. If you want to share creds, copy ''auth-profiles.json'' into the other agent's ''agentDir''.

Example 1: Personal + Restricted Family Agent

{
  "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"],
          "deny": ["exec", "write", "edit", "apply_patch", "process", "browser"]
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "family",
      "match": {
        "provider": "whatsapp",
        "accountId": "*",
        "peer": {
          "kind": "group",
          "id": "[email protected]"
        }
      }
    }
  ]
}

结果：

- ''main'' 代理：主机上在运行、完全那工具访问

- ''family'' 代理：Docker 在运行（代理每个 1 次的容器）、''read'' 工具仅

Example 2: Work Agent with Shared Sandbox

{
  "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"]
        }
      }
    ]
  }
}

Example 2b: Global coding profile + messaging-only agent

{
  "tools": { "profile": "coding" },
  "agents": {
    "list": [
      {
        "id": "support",
        "tools": { "profile": "messaging", "allow": ["slack"] }
      }
    ]
  }
}

结果：

- default agents get coding tools

- ''support'' agent is messaging-only (+ Slack tool)

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main", // Global default
        "scope": "session"
      }
    },
    "list": [
      {
        "id": "main",
        "workspace": "~/.openclaw/workspace",
        "sandbox": {
          "mode": "off" // Override: main never sandboxed
        }
      },
      {
        "id": "public",
        "workspace": "~/.openclaw/workspace-public",
        "sandbox": {
          "mode": "all", // Override: public always sandboxed
          "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}.* overrides agents.defaults.sandbox.{docker,browser,prune}.* for that agent (ignored when sandbox scope resolves to "shared").

工具限制

过滤顺序如下：

1. ''Tool profile'' (''tools.profile'' or ''agents.list[].tools.profile'')

2. ''Provider tool profile'' (''tools.byProvider[provider].profile'' or ''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. ''Sandbox tool policy'' (''tools.sandbox.tools'' or ''agents.list[].tools.sandbox.tools'')

8. ''子代理工具策略'' (''tools.subagents.tools''、該当执行場合)

每个级别可以进一步限制工具，但无法恢复之前级别拒绝的工具。

If ''agents.list[].tools.sandbox.tools'' is set, it replaces ''tools.sandbox.tools'' for that agent.

''agents.list[].tools.profile'' 但设置如果已被、那个代理的 ''tools.profile'' 覆盖执行。

提供商工具键接受 ''provider''（例如 ''google-antigravity''）或 ''provider/model''（例如 ''openai/gpt-5.2''）。

工具群组（簡略表記）

工具策略（全局、代理、沙盒）支持 ''group:*'' 条目，这些条目会扩展为多个具体工具：

- ''group:runtime''：''exec''、''bash''、''process''

- ''group:fs''：''read''、''write''、''edit''、''apply_patch''

- ''group:sessions''：''sessions_list''、''sessions_history''、''sessions_send''、''sessions_spawn''、''session_status''

- ''group:memory''：''memory_search''、''memory_get''

- ''group:ui''：''browser''、''canvas''

- ''group:automation''：''cron''、''gateway''

- ''group:messaging''：''message''

- ''group:nodes''：''nodes''

- ''group:openclaw''：所有組见入见 OpenClaw 工具（提供商插件除可）

Elevated Mode

''tools.elevated'' is the global baseline (sender-based allowlist). ''agents.list[].tools.elevated'' can further restrict elevated for specific agents (both must allow).

緩和模式：

- 信頼未被代理的 ''exec'' 拒绝 (''agents.list[].tools.deny: ["exec"]'')

- Avoid allowlisting senders that route to restricted agents

- 沙盒运行仅需要那場合是、昇格全局在禁用在执行 (''tools.elevated.enabled: false'')

- Disable elevated per agent (''agents.list[].tools.elevated.enabled: false'') for sensitive profiles

- Deny `exec` for untrusted agents (`agents.list[].tools.deny: ["exec"]`)

- Avoid allowlisting senders that route to restricted agents

- Disable elevated globally (`tools.elevated.enabled: false`) if you only want sandboxed execution

- Disable elevated per agent (`agents.list[].tools.elevated.enabled: false`) for sensitive profiles

- Deny `exec` for untrusted agents (`agents.list[].tools.deny: ["exec"]`)

- Avoid allowlisting senders that route to restricted agents

- Disable elevated globally (`tools.elevated.enabled: false`) if you only want sandboxed execution

- Disable elevated per agent (`agents.list[].tools.elevated.enabled: false`) for sensitive profiles

- Deny `exec` for untrusted agents (`agents.list[].tools.deny: ["exec"]`)

- Avoid allowlisting senders that route to restricted agents

- Disable elevated globally (`tools.elevated.enabled: false`) if you only want sandboxed execution

読见取里专用代理

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

Safe Execution Agent (no file modifications)

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

通信専用代理

{
  "tools": {
    "allow": ["sessions_list", "sessions_send", "sessions_history", "session_status"],
    "deny": ["exec", "write", "edit", "apply_patch", "read", "browser"]
  }
}

''agents.defaults.sandbox.mode: "non-main"'' is based on ''session.mainKey'' (default ''"main"''), not the agent id. Group/channel sessions always get their own keys, so they are treated as non-main and will be sandboxed. If you want an agent to never sandbox, set ''agents.list[].sandbox.mode: "off"''.

多代理沙盒和工具设置已执行後：

openclaw agents list --bindings

1. 代理的解决确认执行：

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

2. 沙盒容器确认执行：

3. 工具限制测试执行：

- Send a message requiring restricted tools

- Verify the agent cannot use denied tools

tail -f "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs/gateway.log" | grep -E "routing|sandbox|tools"

- ''多代理路由''