Claw3D 权限与沙箱机制详解AI Agent 执行安全的完整解析【免费下载链接】Claw3DClaw3D is an open source 3D engine built on OpenClaw for creating games, simulations, and high-performance 3D applications.项目地址: https://gitcode.com/gh_mirrors/cl/Claw3DClaw3D 是一个面向 AI Agent 的 3D 虚拟办公室它的权限与沙箱机制是整个系统的执行安全核心。本文带你从零理解 Claw3D 权限模型Studio 如何写配置、Gateway 如何强制拦截、沙箱如何隔离工作区以及命令执行审批Exec Approvals如何让你对每一条命令保留最终决定权。为什么 AI Agent 需要权限控制Claw3D 中的 AI Agent 能力远不止聊天——它们可以️ 执行系统命令安装依赖、运行脚本 读写工作区文件改代码、打补丁 访问网络资源能力越强越需要一套安全护栏。想象一下你让 Agent 跑npm install它却顺手删掉了你的配置文件——没有权限控制时这完全可能发生。Claw3D 的答案是三件套分层权限模型 沙箱隔离 执行前审批。官方完整说明在 docs/permissions-sandboxing.md。三层权限模型谁来配置谁来执行Claw3D 的权限体系是UI 只做决策执行交给后端的分离设计层级负责什么关键配置Studio本仓库 UI 代理写配置与策略提供能力开关和审批卡片openclaw.json、exec-approvals.jsonGatewayOpenClaw 后端真正的强制执行点决定沙箱、挂载工作区、构建工具集、发起审批沙箱上下文、PI 工具策略会话Session决定命令在哪里执行、是否提示execHost/execSecurity/execAsk关键认知权限不是在浏览器里生效的。Studio 只是把配置写到 Gateway拦截发生在 Gateway 主机上可能是你的本机也可能是远程服务器。创建 Agent 时Studio 会自动应用一套宽松的默认能力包命令模式Auto、网络访问On、文件工具On你可以随时在设置面板的 Capabilities 选项卡里收紧它。沙箱机制给 Agent 一个隔离房间3 种沙箱模式sandbox.mode模式行为off完全不用沙箱Agent 直接在宿主上跑all所有会话都进沙箱最严格non-main除主会话外其余会话都进沙箱3 种沙箱作用域sandbox.scopesession每个会话独立容器——隔离性最高但开销最大agent同一个 Agent 的会话共享容器shared全局共用一个容器——隔离性最低工作区访问权限workspaceAccess沙箱的窗户大小这是最容易踩坑的配置三种取值行为完全不同取值Agent 工作区在沙箱里的状态文件工具write/edit/apply_patchrw直接作为沙箱根目录使用✅ 可写ro只读挂载到/agent供命令行查看❌ 被强制禁用none完全不挂载❌ 操作的是独立沙箱目录注意两个硬防线设计路径根守卫Path Guard即使容器里有其他挂载点文件工具也无法访问沙箱根目录之外的路径工具层面的越界在代码上就被封死了。ro不只是只读它在工具策略层直接禁用了write/edit/apply_patch工具双保险。如果沙箱目录为空系统还会自动从 Agent 工作区播种seed引导文件并尽力同步 skills所以隔离不等于失去能力。命令执行审批Exec Approvals每条命令的守门员这是普通用户最常接触的机制。审批策略按 Agent 独立存储securityaskallowlist三个维度ask 的三种模式off不提示按 allowlist 直接放行或拒绝on-miss命令命中 allowlist 时静默通过未命中才弹出审批always每条命令都弹审批卡片且运行会暂停等待你的决定审批卡片上的三个按钮当 Agent 想执行命令时聊天面板会弹出审批卡片见 AgentChatPanel.tsx你可以选择Allow once——只放行这一次Always allow——此类命令以后自动放行加入 allowlist⛔Deny——直接拒绝Agent 的这次运行会被终止决策类型定义在 execApprovalLifecycleWorkflow.ts。当askalways时Agent 的运行会真正暂停在等待审批的状态暂停策略见 execApprovalPausePolicy.ts——不是假暂停而是后端真的停下来了你批了才继续。一个细节写审批策略时需要带上baseHash做版本匹配防止多人同时改配置导致覆盖丢失。工具策略叠加为什么开了还是用不了这是很多调试困惑的根源——工具能不能用要连续通过两道门常规工具策略tools.profile、tools.allow / alsoAllow / tools.deny按 Agent 可覆盖沙箱工具策略仅沙箱会话生效tools.sandbox.tools.allow / deny即使你在 Studio 里给 Agent 开了group:runtime命令执行工具沙箱工具策略仍可能把它拦下来。想理解具体哪个环节拦截了工具按 docs/permissions-sandboxing.md 里的 Debug Checklist 逐项排查即可。⚠️一个隐藏坑沙箱allow列表设为空数组[]并不等于全禁上游会自动把image工具加进允许列表实际效果变成只能用 image。如果想表达沙箱里全放行应写[*]。Studio 甚至为此内置了一键修复连接 Gateway 时自动扫描沙箱全开sandbox.modeall但 allow 列表为空的 Agent并自动改为[*]防止沙箱会话莫名失去几乎全部工具。会话级执行设置命令到底在哪里跑独立于 Agent 配置每个会话还有三个执行开关execHost命令在哪跑 →sandbox/gateway/nodeexecSecurity允许范围 →deny/allowlist/fullexecAsk提示策略 →off/on-miss/alwaysStudio 会在首次发消息时自动同步这些设置。有个重要的兜底逻辑当sandbox.modeall且存在执行覆盖时Studio 会强制execHostsandbox杜绝以为在沙箱跑、实际在宿主机跑的意外。一句话总结这套关系审批策略管要不要问你会话执行设置管在哪里跑。Studio 自身的防护访问门控与网络策略Claw3D 不只会看住 Agent它自己也是安全的——相关加固清单见 SECURITY_HARDENING.md防护点机制令牌校验常数时间比较timingSafeEqual防止时序侧信道攻击access-gate.js暴力破解认证失败限流每 IP 每分钟最多 10 次超出返回 429WebSocket 帧单帧上限 256 KB、30 帧/秒超限断连防资源耗尽上游代理UPSTREAM_ALLOWLIST限制代理可连的 Gateway 主机防 SSRF/DNS 劫持响应头CSP、X-Content-Type-Options、Referrer-Policy等安全基线媒体路由拒绝符号链接文件读取前做 realpath 校验防路径穿越公网绑定绑定公网地址却没设STUDIO_ACCESS_TOKEN时启动直接报错拒绝network-policy.js调试排查清单感觉不对时查哪里按 docs/permissions-sandboxing.md 的 Debug Checklist最常见的四类问题和对应检查项Agent 编辑不了文件→ 先查workspaceAccessro会禁用写工具再查tools.deny是否显式禁了write/edit审批卡片不弹→ 查securityask配置若askon-miss且命令命中了 allowlist就不弹这是正常行为Agent 看到的文件不对→rw操作的是 Agent 工作区ro/none操作的是独立沙箱工作区/agent挂载仅在ro下存在命令根本没执行→ 很可能group:runtime被工具策略拦了而不仅仅是审批问题上游还提供了openclaw sandbox explain --agent agentId命令一条命令就能看出当前会话是否沙箱化、用的哪个工作区是排查问题的第一手工具。总结Claw3D 权限与沙箱的设计哲学️分离Studio 只写配置Gateway 负责强制——UI 层永远不能绕过策略层纵深防御沙箱容器 路径根守卫 工具策略 沙箱工具策略四道闸门层层叠加人在回路exec approvals 让每条敏感命令都能暂停下来等你点头且支持一次放行 / 永久放行 / 拒绝三档粒度可解释sandbox explain Debug Checklist任何不生效都能定位到具体配置项这套机制让 Claw3D 在让 AI 真正动手干活和把风险关在笼子里之间取得了很好的平衡。如果你的 Agent 要跑生产任务建议的组合是sandbox.modeallworkspaceAccessroaskon-miss——隔离、只读、白名单外必审批安全又不至于每条命令都打断你。【免费下载链接】Claw3DClaw3D is an open source 3D engine built on OpenClaw for creating games, simulations, and high-performance 3D applications.项目地址: https://gitcode.com/gh_mirrors/cl/Claw3D创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
