多代理沙箱和工具

多代理设置中的每个代理都可以覆盖全局沙箱和工具策略。本页介绍按代理配置、优先级规则和示例。

沙箱

后端和模式——完整的沙箱参考。

沙箱 vs 工具策略 vs 提权

调试“为什么这被阻止了？”

提权模式

为受信任的发送者执行提权。

身份验证按代理作用域划分：每个代理都有自己位于 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite 的 agentDir 身份验证存储。切勿在不同代理之间复用 agentDir。当代理没有本地配置文件时，它们可以读取默认/主代理的身份验证配置文件，但 OAuth 刷新令牌不会被克隆到次级代理存储中。如果你手动复制凭据，只复制可移植的静态 api_key 或 token 配置文件。

配置示例

示例 1：个人代理 + 受限的家庭代理

{
  "agents": {
    "entries": {
      "main": {
        "default": true,
        "name": "个人助手",
        "workspace": "~/.openclaw/workspace",
        "sandbox": { "mode": "off" }
      },
      "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": {
        "channel": "whatsapp",
        "accountId": "*",
        "peer": {
          "kind": "group",
          "id": "[email protected]"
        }
      }
    }
  ]
}

结果：

main 代理：在主机上运行，拥有完整的工具访问权限。
family 代理：在配置的容器沙箱后端中运行（每个代理使用一个容器），仅可使用 read 和发送当前对话消息。

示例 2：具有共享沙箱的工作代理

{
  "agents": {
    "entries": {
      "personal": {
        "default": true,
        "workspace": "~/.openclaw/workspace-personal",
        "sandbox": { "mode": "off" }
      },
      "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": {
    "entries": {
      "main": {
        "default": true
      },
      "support": {
        "tools": { "profile": "messaging", "allow": ["slack"] }
      }
    }
  }
}

结果：

默认代理使用编码工具。
support 代理仅限消息功能（加上 Slack 工具）。

示例 3：每个代理使用不同的沙箱模式

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "session"
      }
    },
    "entries": {
      "main": {
        "default": true,
        "workspace": "~/.openclaw/workspace",
        "sandbox": {
          "mode": "off"
        }
      },
      "public": {
        "workspace": "~/.openclaw/workspace-public",
        "sandbox": {
          "mode": "all",
          "scope": "agent"
        },
        "tools": {
          "allow": ["read"],
          "deny": ["exec", "write", "edit", "apply_patch"]
        }
      }
    }
  }
}

配置优先级

当全局（agents.defaults.*）和特定代理（agents.entries.*.*）配置同时存在时：

沙箱配置

特定代理设置会覆盖全局设置：

agents.entries.*.sandbox.mode > agents.defaults.sandbox.mode
agents.entries.*.sandbox.scope > agents.defaults.sandbox.scope
agents.entries.*.sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRoot
agents.entries.*.sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccess
agents.entries.*.sandbox.docker.* > agents.defaults.sandbox.docker.*
agents.entries.*.sandbox.browser.* > agents.defaults.sandbox.browser.*
agents.entries.*.sandbox.prune.* > agents.defaults.sandbox.prune.*

对于该代理，agents.entries.*.sandbox.{docker,browser,prune}.* 会覆盖 agents.defaults.sandbox.{docker,browser,prune}.*（当沙箱范围解析为 "shared" 时会被忽略）。docker 配置块会配置两个内置容器后端。

工具限制

过滤顺序如下：

工具配置文件

tools.profile 或 agents.entries.*.tools.profile。

提供方工具配置文件

tools.byProvider[provider].profile 或 agents.entries.*.tools.byProvider[provider].profile。

全局工具策略

tools.allow / tools.deny。

提供方工具策略

tools.byProvider[provider].allow/deny。

特定代理工具策略

agents.entries.*.tools.allow/deny。

代理提供方策略

agents.entries.*.tools.byProvider[provider].allow/deny。

沙箱工具策略

tools.sandbox.tools 或 agents.entries.*.tools.sandbox.tools。

子代理工具策略

tools.subagents.tools，如适用。

优先级规则

每个层级都可以进一步限制工具，但不能恢复先前层级已拒绝的工具。
如果设置了 agents.entries.*.tools.sandbox.tools，它会替代该代理的 tools.sandbox.tools。
如果设置了 agents.entries.*.tools.profile，它会覆盖该代理的 tools.profile。
提供方工具键可以使用 provider（例如 anthropic）或 provider/model（例如 openai/gpt-5.4）。

空允许列表行为

如果该链中的任何显式允许列表导致运行时没有可调用工具，OpenClaw 会在将提示提交给模型之前停止。这是有意为之：若某个代理配置了缺失的工具，例如 agents.entries.*.tools.allow: ["query_db"]，那么在注册 query_db 的插件启用之前，它应当明确失败，而不是继续作为仅文本代理运行。

工具策略支持会展开为多个工具的 group:* 简写。完整列表请参见工具组。每个代理的 elevated 覆盖（agents.entries.*.tools.elevated）可以进一步限制特定代理的 elevated exec。详情请参见 Elevated 模式。

从单代理迁移

迁移前（单代理）
迁移后（多代理）

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "sandbox": {
        "mode": "non-main"
      }
    }
  },
  "tools": {
    "sandbox": {
      "tools": {
        "allow": ["read", "write", "apply_patch", "exec"],
        "deny": []
      }
    }
  }
}

{
  "agents": {
    "entries": {
      "main": {
        "default": true,
        "workspace": "~/.openclaw/workspace",
        "sandbox": { "mode": "off" }
      }
    }
  }
}

旧版的 agents.list 代理列表以及已弃用的代理级配置项（例如 sandbox.perSession、agentRuntime 和 embeddedPi）会由 openclaw doctor 迁移；今后请优先使用 agents.defaults + agents.entries。

工具限制示例

只读代理
为文件系统工具禁用 Shell 执行
仅通信

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

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

此策略会禁用 OpenClaw 的文件系统工具，但 exec 仍然是一个 shell，并且可以在所选主机或沙箱文件系统允许的任何位置写入文件。对于只读代理，请禁止 exec 和 process，或者将 shell 访问与沙箱文件系统控制结合使用，例如 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" 会将会话密钥与主会话密钥进行比较（始终为 "main"；session.mainKey 不能由用户配置，OpenClaw 会对任何其他值发出警告并忽略），而不是与代理 id 比较。群组/频道会话始终会获得自己的密钥，因此它们会被视为非主会话并进入沙箱。如果你希望某个代理永远不进入沙箱，请设置 agents.entries.*.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.entries.*.sandbox.mode: "all"。

尽管在拒绝列表中，工具仍然可用

检查完整的过滤顺序：配置档案 → 提供商配置档案 → 全局策略 → 提供商策略 → 智能体策略 → 智能体提供商策略 → 沙箱 → 子智能体。
每一层只能进一步限制，不能重新授予权限。
参见沙箱 vs 工具策略 vs 提权进行逐步调试。

容器未按智能体隔离

默认 scope 为 "agent"（每个智能体 ID 对应一个容器）。
将 scope: "session" 设置为每个会话一个容器，或将 scope: "shared" 设置为在多个智能体之间复用一个容器。

概览

插件

插件指南

构建插件

技能

自动化

工具

智能体协作

沙箱

沙箱 vs 工具策略 vs 提权

提权模式

配置示例

配置优先级

沙箱配置

工具限制

从单代理迁移

工具限制示例

常见陷阱：“non-main”

测试

故障排查

相关内容

沙箱

沙箱 vs 工具策略 vs 提权

提权模式

​配置示例

​配置优先级

​沙箱配置

​工具限制

​从单代理迁移

​工具限制示例

​常见陷阱：“non-main”

​测试

​故障排查

​相关内容

配置示例

配置优先级

沙箱配置

工具限制

从单代理迁移

工具限制示例

常见陷阱：“non-main”

测试

故障排查

相关内容