把 shell 权限交给龙虾之前：沙箱、白名单和网关认证怎么配

把 shell 交给龙虾，可能出什么事

允许智能体调用 shell，它生成的命令就可能偏离你的意图。光在提示词里要求它谨慎不够，执行权限要靠工具策略、审批和运行环境一起限制。

出事的路径有这几种:

• 它把你的话理解偏了。你说清一下临时文件,它对「临时」的判断和你不一样。
• 它读到的内容可能带有恶意指令。网页、邮件、issue、README 都可能包含提示注入；模型未必能可靠区分任务资料与越权指令。
• 权限范围过宽。可写挂载、宿主 shell 或过大的凭证权限，会让一次错误影响更多资源。

授权之前，拿备份实际恢复一次。文件能从备份恢复，凭证泄露和消息误发却恢复不了，这两样要单独考虑。

OpenClaw 有哪些安全配置项，各在哪个键

全部落在同一个文件 ~/.openclaw/openclaw.json 里：

先运行 openclaw config validate。严格校验会拒绝未知键或错误类型；运行中的无效外部修改不会激活，网关可继续用上一份有效配置。热重载默认 hybrid：有效改动按字段热应用或安排重启；off 仍监听、验证，只将应用延至手动重启。gateway.* 和 channels.* 都是有的字段能热应用、有的要重启，改完回头看新值有没有生效。

沙箱的后端、模式和访问范围

沙箱默认配置在 agents.defaults.sandbox，可按 agent 覆盖。它不只有本地容器：docker、podman 使用容器运行时，ssh 使用远程主机，也有 OpenShell 等后端。各后端的文件与网络限制各不相同。

Docker/Podman 需要容器运行时与可用镜像。官方默认 Docker 镜像 openclaw-sandbox:bookworm-slim 基于 Debian，包含常用工具并以非 root 用户运行；源代码安装可用 scripts/sandbox-setup.sh，npm 包不含该脚本，按镜像准备文档操作。SSH 后端的远端要满足 shell、Python 和文件系统等运行条件，并使用受限账号与可信主机密钥。

模式和作用域：谁被关进去、隔多细

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",        // 本示例让所有会话使用沙箱
        scope: "agent",     // 默认按 agent 复用；也可选 session 或 shared
        backend: "docker",  // 先准备容器运行时与镜像
        workspaceAccess: "none",
      },
    },
  },
}

据模式与作用域文档，off 默认不启用 agent 级沙箱；non-main 排除的是每个 agent 的 main 会话，不是“主 agent 之外的成员”。普通情况下 main 键为 agent:<agentId>:main；全局会话作用域有 global 例外。all 让全部会话使用沙箱。要关紧某个 agent，应给其 agents.entries.*.sandbox.mode 设 "all"。

scope 另管环境复用：默认 agent 按 agent 一份，session 按会话一份，shared 共用环境且忽略部分按 agent 的后端覆盖。角色策略要求沙箱的会话还有更严格的规则，可在 mode off 时仍强制沙箱，并改变复用边界。上面只是沙箱片段，工具策略要另配。

Docker 后端的默认值

下表是 Docker 后端及其工作区访问的默认值；SSH 远端断不断网、根文件系统是否只读，看远端自己的设置。

需要放开的时候,对应关系是这样:

• 工具确实要联网——按需要配置 sandbox.docker.network，只开任务用得到的那部分。浏览器另用 sandbox.browser.network，默认专用网络，不支持 "none"；改命令容器的网络管不到浏览器。详见上述 Docker 文档与浏览器自动化教程。
• 要让它看见你现有的文件——workspaceAccess 设 "ro",agent 工作区以只读挂到 /agent;设 "rw" 则读写挂到 /workspace。能用 "ro" 办成的事,别写 "rw"。
• 要额外挂宿主目录——sandbox.docker.binds,格式 宿主目录:容器目录:ro,或者结尾写 :rw。结尾那两个字母决定它能不能改你的原始文件。

工作区访问文档明确区分本地容器挂载与远程 shell：SSH/OpenShell 的 shell 文件权限依赖远端主机或其策略，单独设置 workspaceAccess 不能保证远程路径只读。workspace 本身也只是默认 cwd。

工具沙箱不会自动隔离网关进程。额外可写挂载扩大了可修改范围；允许 elevated 等宿主执行通道时，还可能在工具沙箱外执行。所以设了 mode all，还要对着工具与 agent 权限文档检查挂载和 elevated。

Skill 列表和工具权限分开设置

agents.defaults.skills 是说明加载的基线，agents.entries.*.skills 显式列表会替换它。[] 表示不加载 skill 说明，也影响技能命令发现等路径，不等于撤销工具权限。官方 Skills 说明明确指出它不是宿主 shell 授权边界。

收紧权限要看 tools.allow/tools.deny 与按 agent 的工具配置，再配合执行审批和沙箱。即使禁用了文件写入工具，仍可用的 exec 也可能写文件，因此应一并检查。安装说明见Skills 入门。

新装的 OpenClaw 默认开哪些工具：2026.9.5 起本地 onboarding 默认选 Full

没设过工具 profile 就跑本地 onboarding，它会替你选 Full 工具，重跑 onboarding 时也一样，这是 2026.9.5 的更新日志改的默认值；Full 包含消息类工具，以及已启用插件带来的可选工具。已经显式设过 profile 的保持原样，普通升级也不会去改一个没设置过的 profile。所以 9.5 之后新装、或者重跑过 onboarding 而没设过 profile 的本地实例，要按 Full 这一档来评估风险。

Full 和 Full Access 是两回事：Full 选的是工具范围，Full Access 管的是执行权限，后者仍是单独的一项，不随工具选择变化。

自己这份是不是 Full，先看 ~/.openclaw/openclaw.json 里有没有 tools.profile: "full"：本地 onboarding 替你选 Full 时写进去的就是这一项，在安全设置里选 Full 也会显式存下来。再到要查的那个会话里发 /tools，看实际生效的工具列表；profile 之后，群组、provider、沙箱和按 agent 的策略还可能再拿掉一些工具。

tools.profile 是排在 tools.allow/tools.deny 之前的基础白名单，有四个取值：

要收窄，把 tools.profile 改成前三档里的一档，例如：

{
  tools: { profile: "coding" },
}

只收某一个 agent，就把 profile 写在 agents.entries.<agentId>.tools 下面。coding 和 messaging 两档都还带着会话工具，换过去并不收窄跨会话的可见范围，那一项由 tools.sessions.visibility 管。配置里没写 profile 的，核心工具同样不过滤，只是不会自动选入插件的可选工具。各档的完整工具清单见官方工具策略文档。改完再发一次 /tools 看生效的列表。

官方配置示例中的 agents.defaults.modelPolicy.allow 限制模型覆盖和选择器，可写精确 ref 或 provider/*；省略或写 [] 表示不限制，含义与 skills 空列表不同。云端与本地的差别见API 与本地模型对比。

同网关多个 agent 还需检查会话访问：2026.9.2 起会话工具默认对全部会话可见，tools.agentToAgent 默认开启，没进沙箱的会话可以跨 agent 读取和搜索其他会话。把 tools.sessions.visibility 设成 agent 或 self 可以收窄，tools.agentToAgent 的 allow 限定允许的 agent 配对。需要严格分离时，使用独立网关及操作系统或主机权限边界。详见多 agent 教程。

白名单：谁能私聊它、群里谁能触发

私聊看 dmPolicy,四个取值:pairing 要先配对,allowlist 只认名单,open 谁都能来,disabled 直接关掉。给了 shell 权限的实例上不要用 open,那等于把一台机器的操作入口挂出去让陌生人试。稳的组合是 allowlist 配合 allowFrom 显式列人。

名单写在各渠道自己的配置下面。官方配置页的最小示例只放行一个 WhatsApp 号码：

// ~/.openclaw/openclaw.json
{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

Telegram 的同名键写在 channels.telegram 下面：dmPolicy、allowFrom、groupPolicy、groupAllowFrom、groups；名单里要填的 Telegram 用户 ID 怎么查，在官方 Telegram 访问控制页。这几项都不写时，Telegram 的私聊按 pairing、群按 allowlist 处理；配了多个账号的，账号上没写的 dmPolicy、groupPolicy、allowFrom、groupAllowFrom 这四项继承渠道根上的设置。

配完这样检查：openclaw config get channels.whatsapp.allowFrom（换成你的渠道）读出配置里写的名单；openclaw pairing list --channel telegram 列出等着批准的私聊配对；再用一个不在名单里的账号给它发一条消息，这条消息不该触发任务。

群聊看 groupPolicy、群组名单和 groupAllowFrom，再看 requireMention 和 agent 的 groupChat.mentionPatterns。各渠道的继承和隐式提及规则不一样，“默认被 @ 才响应”在你用的渠道上成不成立，到官方访问控制和对应渠道文档里查。

群聊文档中的 messages.groupChat.visibleReplies: "message_tool" 控制群聊回复方式，messages.visibleReplies 是更广的默认值。它不是人工批准：消息工具不可用时可回退为自动回复，授权命令仍会可见回复，插件绑定输出也有例外。接入真实群前，用受控群测试触发、上下文与发送行为。

网关认证怎么配，装在云服务器上要查什么

官方网络暴露说明要求非 loopback 监听配合有效认证与防火墙。可用 token/password；正确配置的可信代理也是一种认证路径。默认引导会生成认证 secret。

监听地址是 gateway.bind，认证在 gateway.auth 下面（gateway.auth.mode、gateway.auth.token）。已经在跑的实例，用官方 Gateway 排错页给的这几条命令看现状：

openclaw config get gateway.bind
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow

最后一条会一直跟着输出日志，看完按 Ctrl+C 退出。gateway.bind 写成 lan、tailnet、custom 这类非 loopback 的值而认证没配上时，日志里会出现 refusing to bind gateway ... without auth；客户端报 unauthorized，是地址连得上、凭证不对。旧键 gateway.token 顶替不了 gateway.auth.token。

端口开在共享网络或公网上的，另看一个 2026.9.7 改过的默认值：每个 IP 同时挂着、尚未完成认证的连接，上限从 32 提到了 128，也就是允许更多未认证连接占用服务器资源。要用回旧值，设环境变量 OPENCLAW_MAX_PREAUTH_CONNECTIONS_PER_IP=32 再重启 Gateway，说明在官方限流文档。

优先保留 gateway.bind: "loopback" 及认证，远程通过 SSH 隧道访问，避免直接开放网关端口；SSH 端口与账号仍需保护。涉及配置文件中的 token/password 轮换，只有实际认证模式不变时才可热应用；bind、端口、认证模式、TLS 等变更仍需重启。修改进程环境变量中的凭证，也要以新环境重启进程。云端步骤见云服务器部署教程，改完把上面五条命令再跑一遍。

Webhook 另有两项要配，见官方 webhook 配置：

• hooks.token 是独立的。它不跟着网关认证走。设了网关 token 不等于 webhook 也保护到了,这两处要分开配。
• 外部请求能不能自己指定会话，由 hooks.allowRequestSessionKey 决定。开了它，再用 hooks.allowedSessionKeyPrefixes 限定可指定的会话前缀。

hooks.gmail.allowUnsafeExternalContent 或 hook mapping 中的同名字段会影响外部内容的安全包装，应保持关闭。关着它，消息能触发的工具和凭证范围也还要另外限制。

从最紧的配置起步，按什么顺序放开权限

下面以本地 Docker 为例，SSH 等远程后端按各自文档另排。每放开一项权限，先写清是哪个任务要用它，放开后做右栏那一项验证。

出现非预期的写入或发送，停掉相关的自动任务、留好日志，查出是哪一项权限放出去的，再决定恢复哪些。

权限收紧后工具不可用，按工具调用失败排查定位。

常见问题

龙虾会不会偷偷删我的文件？

有可能误删。误解指令、提示注入或过宽权限都可能造成损失。为相关 agent 配置 mode: all，同时限制工具、可写挂载与宿主执行通道，并保留可恢复备份；workspace 路径本身不限制文件访问。

装在云服务器上安全吗？

看网关怎么配。让网关绑定 loopback 并保留认证，远程访问走 SSH 隧道，不直接开放网关端口；SSH 服务自己的认证和网络保护照样要做。非 loopback 监听必须配有效认证和防火墙，容器沙箱管不到网关的访问控制。

沙箱开到 all 是不是很难用？

mode: all 决定所有会话使用沙箱，实际限制还取决于后端。Docker 默认不出网、根文件系统只读，workspaceAccess 默认 none，但私有沙箱工作区仍可写。要用现有文件、网络或浏览器，分别改挂载、网络和浏览器配置；这些是容器后端的默认值，远程后端另算。

用沙箱是不是必须装 Docker？

不是。Docker 和 Podman 需要准备容器运行时及可用镜像；SSH 后端用的是满足官方工具与文件系统要求的远程主机，shell 文件权限由远端环境控制，workspaceAccess 一项管不了远端只读。其他后端按各自文档准备。

把它拉进群会不会乱说话？

有可能。先看渠道的群名单和提及规则配了没有；messages.groupChat.visibleReplies: message_tool 管的是回复走哪条路，消息工具不可用时会回退为自动回复，授权命令和插件绑定的回复也照常发出。接真实群之前，在受控群里把触发和发送试一遍。

配置写错了会怎么样？

未知键或类型错误会被严格校验拒绝。启动时无效配置可能阻止启动；运行中的无效外部修改会被拒绝激活，网关可继续使用上一份有效配置。改完运行 openclaw config validate，再回头看新值有没有生效。