安全 · 实战

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

钳叔 · 龙虾AI 编辑部 · 2026-08-24 发布 · 2026-08-24 更新 · 约 7 分钟

先把结论摆出来:龙虾AI 自带的闸不算少——沙箱、Skill 白名单、模型白名单、谁能跟它说话、群里什么时候开口、网关认不认证,这几层都能在 ~/.openclaw/openclaw.json 里配死。但它们能做的是把事故范围缩小,不是把风险归零。这篇不讲通用安全泛论,只讲龙虾实际提供的机制:每道闸叫什么、配在哪个键上、建议从哪一档起步。还没装的先看安装指南。

风险不可能归零,这一点先认下来

你交出去的不是一段脚本的执行权,是一个会自己做决策的程序对 shell 的调用权。这两件事的性质不一样。脚本错了错得一模一样,智能体错了每次错法都不同。

会出事的通常是这三种情况:

• 它把你的话理解偏了。你说清一下临时文件,它对「临时」的判断和你不一样。这类事故不需要它有恶意,只需要指令有歧义。
• 它读到的东西在指挥它。网页、邮件、issue、README 里都可以埋指令。模型看到的是一整片文本,分不清哪句是「要处理的内容」、哪句是「要执行的命令」。
• 你自己把闸开大了。为了少点两下确认,把范围一放,这是最常见的一种。

所以心态别停在「配好了就安全了」,而要落到「配好了,万一出事赔得起」。有个很土但好用的判断标准:假设它现在把授权范围里的东西全删了,你能不能在十分钟内恢复?能,这个范围就可以给;不能,先别给。

龙虾手里有哪几道闸

全部落在同一个文件 ~/.openclaw/openclaw.json 里。先看全貌,再逐条说:

还有一层不用你配的:配置本身走严格 schema 校验,写了未知键、或者类型对不上,启动直接被拒;另外有写保护,能发现关键块被删掉、或者整份配置缩水超过一半这种情况。这层的好消息是配错了它多半起不来,不会带着半截配置默默跑;坏消息是键名拼错不会「降级成默认值」,而是起不来。改完的生效方式分两种:沙箱、skills、模型这些都在热生效的范围里,存盘就算数;但网关那一摊(gateway.*,包括监听地址和认证)必须重启网关才生效——本文第 6 节那些改动,光存盘是不够的。另外,别在没人盯着的时候远程改。

沙箱:先全开,再一格一格往回收

沙箱在 agents.defaults.sandbox。先说清它是什么:容器方案。后端可以是本地的 docker 或 podman,也可以用 ssh 扔到另一台主机上跑,或者交给 openshell 那种托管的远程环境。

启用前要先构建镜像,官方给了现成配方:基于 debian:bookworm-slim,预装 bash、ca-certificates、curl、git、jq、python3、ripgrep 这些常用件,并且建了一个非 root 的 sandbox 用户来跑进程。源码检出后执行 scripts/sandbox-setup.sh 即可,文档也给了等价的 docker build 命令。所以「开个开关就有沙箱」不成立,得先把这一步做掉。

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

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",   // off | non-main | all
        scope: "agent",     // session | agent | shared
      },
    },
  },
}

mode 三档:off 不隔离;non-main 只把主 agent 之外的关进去,适合主 agent 干正事、子 agent 干脏活的分工;all 全关进去,第一周就用这个。scope 决定隔多细:session 一个会话一个,agent 一个 agent 一个,shared 所有的共用一个。粒度越细串味的机会越少,越粗越省资源、也越方便共享中间产物。新手从 session 起步,等你明确需要「上个会话产出的文件下个会话还要用」,再往粗调。

沙箱支持按 agent 覆盖:全局那份写在 agents.defaults.sandbox,单个 agent 的写在 agents.entries.*.sandbox。所以「主 agent 一套、专门干脏活的那个 agent 另一套」是配得出来的。

沙箱默认是关的;但你一旦打开,里面的默认值最紧

这两层最容易混,分开说。

第一层:沙箱本身默认不开。官方文档原话是「Sandboxing is off by default」,由 agents.defaults.sandbox(全局)或 agents.entries.*.sandbox(按 agent)控制。也就是说,装完的状态是什么隔离都没有,mode 的出厂值就是 off。把它打开是你要做的第一件事,别以为装完就自带保护。

第二层:打开之后,它内部的默认值确实是最紧的那一档。下面这几个不用你动就已经是保守值。到了这一层,你要操心的才是「什么时候有意识地放开」,而不是「怎么再收紧」:

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

• 要联网——network 从 "none" 改成 "bridge" 或你自建的网络。有个硬性例外:沙箱里跑浏览器不能用 "none",浏览器控制要发布 CDP 端口。浏览器自动化那类活会直接撞上这条。
• 要让它看见你现有的文件——workspaceAccess 设 "ro",agent 工作区以只读挂到 /agent;设 "rw" 则读写挂到 /workspace。能用 "ro" 办成的事,别写 "rw"。
• 要额外挂宿主目录——sandbox.docker.binds,格式 宿主目录:容器目录:ro,或者结尾写 :rw。这是全篇最该抠字眼的地方:结尾那两个字母,决定了它能不能改你的原始文件。

要泼的冷水在这儿,而且是官方自己先泼的。沙箱文档里有一条 Note,原话是「This is not a perfect security boundary, but it materially limits filesystem and process access when the model does something dumb.」——它不是一道完美的安全边界,但当模型干了蠢事的时候,确实能实质性地限制文件系统和进程访问。这句话的两半都别漏掉:既别把沙箱当保险箱,也别因为它不完美就干脆不开。

边界具体在哪,文档也写明了:只有工具执行会进沙箱,网关进程本身仍然跑在宿主机上,没有被隔离。所以沙箱缩小的是「它跑命令时能碰到的东西」,不是「整个龙虾被关起来了」。同理,你亲手用 binds 挂进去、还给了 rw 的那份数据,沙箱一点都不保护——自己开的门,它不会替你关。

能力白名单:从空数组开始加

agents.defaults.skills 是基线,agents.entries.*.skills 可以按 agent 覆盖它。把基线设成空数组 [],就是一个 skill 都不给。

推荐的起步姿势:基线写 [],要用哪个能力,就在具体那个 agent 上单独加。这样默认状态永远是最小的,而不是「装了一堆忘了关」。Skills 入门那篇讲了怎么挑和怎么装,这里只补一句:每加一个 skill,你就多一条它可以自己走的路,加之前先问一句这周真的会用到吗。

模型也该白名单,键是 agents.defaults.modelPolicy.allow,可以写精确的模型 ref,也可以 provider/* 通配整个供应商。这条容易被忽略:换大脑等于换行为方式,一个你没验过的模型接管同一套权限,判断风格完全不同。把 allow 写死,它就跑不到清单外的模型上。要在云端 API 和本地模型之间切,先看这篇的对比再决定 allow 里放谁。

谁有资格指挥它

这块比沙箱更容易被忽视——沙箱管的是它能干什么,这里管的是谁能让它干。

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

群聊看 groupPolicy。默认行为已经是保守的:必须被 @ 才响应。mentionPatterns 能用正则自定义触发词,方便,但正则写太宽等于它随时在听——比如把公司简称写进去,群里聊到业务它就插话。

还有个开关值得单独提:visibleReplies 设成 message_tool 之后,它必须显式决定才发言,而不是有话就说。把龙虾拉进任何有别人的群之前,先把这个设上,能省掉一半尴尬场面。

装在云服务器上:网关不许裸奔

这一条单独拎出来,因为它是最容易出人命的地方:网关一旦绑到 loopback 之外,就必须设认证——OPENCLAW_GATEWAY_TOKEN 或者 OPENCLAW_GATEWAY_PASSWORD,二选一。这是官方 .env.example 里写明的要求。

事故是怎么发生的:本机跑的时候一切正常,搬到云服务器上想远程访问,把监听地址从 127.0.0.1 改成 0.0.0.0,认证那步忘了。这时候你在公网上挂着的,是一个能执行 shell 的接口。更省心的做法是继续只绑本机,远程访问走 SSH 隧道,端口一个都不用对外开。云上部署的整套步骤在这篇,里面的安全组那节配合着看。

另外两个和外部请求有关的键:

• hooks.token 是独立的。它不跟着网关认证走。设了网关 token 不等于 webhook 也保护到了,这两处要分开配。
• allowedSessionKeyPrefixes 限制请求能申领哪些 session key 前缀。没有它,一个外部请求可能钻进它本不该进的会话上下文。写窄一点,只留 webhook 真正需要的那一类前缀。

最后是 allowUnsafeExternalContent。它默认关闭,官方的定位是给窄范围调试用的。翻译成人话:打开它,外部内容就能绕过那道防护。真要调试就临时开,调完当场关掉,别让它在配置里过夜。

一份可以照着走的放开顺序

不想一上来就研究每个字段的,直接按下面四档走,每档跑顺了再进下一档。

往回收的信号也给一条:只要出现一次你没预期的写操作,不管有没有造成损失,退回上一档待一周。这比事后补备份便宜得多。

上面这些键名和取值,是 2026-08-24 对着官方文档整理的。这个项目迭代很快,配置项改名、加取值都发生过,动手前请以你装的那个版本的配置文档为准,对着网关配置文档和沙箱文档再核一眼。某个字段的实际行为拿不准,去 GitHub 仓库翻源码和 issue,比猜快。配置改完它调不动工具了,按工具调用失败排查那套顺序过一遍——权限收紧之后最常见的报错就出在这儿。

常见问题

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

它不会「偷偷」干什么,但确实可能因为理解偏了你的指令而删掉不该删的东西。防的办法是三层:沙箱开到 all、只授权一个专用工作目录、重要数据先备份或者拿副本练手。别图省事把家目录整个交给它。

装在云服务器上安全吗?

可以做到能接受的程度,前提是网关别裸奔。官方要求很明确:网关绑到 loopback 之外就必须设 OPENCLAW_GATEWAY_TOKEN 或 OPENCLAW_GATEWAY_PASSWORD。更省心的做法是继续只绑 127.0.0.1,远程访问走 SSH 隧道,一个对外端口都不开。

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

先说个前提:沙箱默认是关的,得自己把 mode 从 off 改成 all,不改就谈不上难用不难用。打开之后确实会损失一点方便,因为内部默认值最紧——不出网、根文件系统只读、也不挂 agent 工作区。真正会卡住的是要联网、要读你现有文件、要在沙箱里跑浏览器的活,按需一项项放开即可。

用沙箱是不是必须装 Docker?

不是只有 Docker 这一条路。本地后端可以用 docker 或 podman,也可以走 ssh 把沙箱扔到另一台主机上,或者用 openshell 那种托管的远程环境。但有一步跑不掉:启用前要先构建镜像,官方给了现成配方,默认镜像基于 debian:bookworm-slim,并以非 root 的 sandbox 用户运行。

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

默认已经是被 @ 才响应,不会有话就插。想更保守就把 visibleReplies 设成 message_tool,这样它必须显式决定才发言。还有一点:mentionPatterns 的正则别写太宽,写宽了等于它随时在听。

配置写错了会怎么样?

多半是起不来,而不是带着半截配置默默跑。配置走严格 schema 校验,未知键或类型不对启动就被拒;另有写保护,能发现关键块被删或整份配置缩水超过一半。所以键名拼错不会降级成默认值,别在没人盯着的时候远程改配置。