OpenClaw Sandbox工作原理解析（一）：Docker容器隔离与沙箱配置入门

1. OpenClaw Sandbox 到底解决了什么问题从一次工具误删说起如果你正在用 OpenClaw 这类 Agent 框架跑自动化任务大概率遇到过这种心跳加速的瞬间让模型执行一条清理命令它顺手把工作目录里不该动的文件删了或者某个 exec 工具跑飞了把宿主机上正在用的端口占满。OpenClaw Sandbox 就是为这类场景设计的——它把 AI 工具的执行过程塞进 Docker 容器里让「爆炸半径」被限制在一个可丢弃的沙箱内。一句话概括OpenClaw Sandbox 是基于 Docker 容器技术的工具执行隔离机制它让 exec、read、write、edit、apply_patch、process 这些工具在容器里跑而不是直接在宿主机上跑。适合谁适合所有把 Agent 接入真实文件系统、真实命令行的开发者尤其是多用户环境或让模型自主决策的场景。它的设计目标有四条我按重要性排一下安全隔离是第一位。限制 AI 工具对主机文件系统、进程和网络的访问默认拒绝一切需要什么显式开什么。最小权限是配套原则不给多余能力。灵活配置让你能在开发期放松、生产期收紧。透明运行则是体验层面的要求——对用户和模型透明工具代码不用改模型也不需要知道自己在沙箱里。需要说清楚边界Gateway 进程本身不沙箱化它是策略决策者显式允许在主机运行的工具比如 tools.elevated也不进沙箱。沙箱化的是那些「模型能直接触发、可能造成副作用」的工具。理解这条边界后面配置才不会拧巴。Docker 能实现隔离靠的是 Linux 内核的 Namespaces 和 Cgroups 两套机制。Namespaces 负责「看不见」PID namespace 让容器内进程独立编号Mount namespace 给独立文件系统视图Network namespace 给独立网络栈UTS 给独立主机名IPC 隔离进程间通信User 做用户 ID 映射。Cgroups 负责「用不多」内存上限、CPU 配额、最大进程数。OpenClaw Sandbox 把这些能力包装成配置项你不需要手写 docker run 的全部参数但理解底层有助于排障。下面我会从架构、配置、可复制参数到验证命令一步步带你搭起来。过程中涉及模型调用和 API Key 的部分我会用 TaoToken 的接入方式演示因为它的 Base URL 和 Key 管理对这类本地 Agent 场景比较顺手。2. 接入前的准备TaoToken 的 Key、Base URL 与模型 ID 三件套在配置沙箱之前先把模型侧的通路打通。OpenClaw 的 Gateway 需要调用模型来做决策而沙箱只是执行层的隔离。很多人卡在第一步不是沙箱配错而是模型请求根本没通。TaoToken 的接入逻辑和主流 OpenAI 兼容接口一致核心是三件套Base URL、API Key、Model ID。Base URL 用https://taotoken.net/api注意这个地址不带任何查询参数是纯 API 端点。API Key 在控制台的 API Keys 页面生成建议按项目分 Key方便后续排查是哪个环境出的问题。Model ID 填你实际要用的模型标识比如claude-sonnet-4-5这类具体以模型对话页面列出的为准。我试过把 Key 直接写进配置文件后来改成环境变量原因是配置文件容易误提交到 Git。推荐做法是在 shell 里 exportexport TAOTOKEN_API_KEYsk-你的实际key export TAOTOKEN_BASE_URLhttps://taotoken.net/api然后在 OpenClaw 的配置里引用环境变量。如果你用的是 Codex 这类需要auth.json的工具结构大致是这样{ openai: { apiKey: sk-你的实际key, baseURL: https://taotoken.net/api } }注意baseURL结尾不要多加/v1TaoToken 的 API 路径已经处理好了多写反而会 404。这一点和某些自建网关的习惯不同踩过一次坑。如果你用的是 Cline 或 Claude Code 这类带 MCP 配置的工具三件套要写全。Cline 的 MCP 配置里Base URL 和 Key 放在 provider 段Model ID 放在 model 段。Claude Code 的 settings 里则是通过环境变量注入。无论哪种缺一个都会表现为请求失败或模型列表为空。验证模型通路是否打通最直接的方式是用模型对话页面发一条测试消息或者用 curl 打一次curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: ping}] }返回里有choices字段就说明通了。如果返回 401先检查 Key 是否有多余空格如果返回local proxy failed通常是本地网络层的问题不是 Key 的问题。这一步通了再往下配沙箱排障范围会小很多。对于长期跑编码任务或 Agent 的场景可以考虑用 Coding Plan它在持续调用下的配额管理比按次计费更省心。但沙箱配置本身和用哪种计费方式无关先把隔离跑通。3. 可复制的沙箱配置mode、scope、workspaceAccess 与 docker 参数OpenClaw Sandbox 的配置集中在agents.defaults.sandbox下。我按「先定策略、再定资源、最后定网络」的顺序给一份可复制的 JSON 片段你可以直接贴进配置文件再按需改。{ agents: { defaults: { sandbox: { mode: non-main, scope: session, workspaceAccess: ro, docker: { image: openclaw-sandbox-common:bookworm-slim, network: none, memory: { limit: 512MB, swap: 0 }, cpu: { quota: 50000, period: 100000 }, pids: { max: 100 }, dangerouslyAllowContainerNamespaceJoin: false } } } } }逐项解释。mode有三个值off完全不启用沙箱适合开发环境或完全信任的场景non-main只对非主会话沙箱化这是推荐值——私聊在主机会话跑群组或自动化会话进沙箱all所有会话都沙箱化适合高安全多用户环境。初次接触建议先用non-main既能体验隔离又不会因为沙箱缺工具导致主流程跑不动。scope决定容器粒度。session是每会话一个容器隔离级别最高资源消耗也最高agent是每代理一个容器中等shared是所有共享一个容器隔离最低、最省资源。如果你在调试阶段频繁重启会话session会不断创建销毁容器日志会比较吵可以临时切agent。workspaceAccess控制主机工作区的挂载方式。none时容器只能访问~/.openclaw/sandboxes完全隔离ro把工作区挂到/agent只读模型能读不能写rw挂到/workspace可读写。生产环境建议ro起步需要写文件时再评估是否放开。注意ro和rw的挂载路径不同写工具代码时如果硬编码了路径切换访问级别会失效。docker.image默认是openclaw-sandbox:bookworm-slim只有基础工具。如果你需要 curl、jq、nodejs、python3、git用openclaw-sandbox-common:bookworm-slim。镜像构建脚本在./scripts/sandbox-setup.sh、./scripts/sandbox-common-setup.sh、./scripts/sandbox-browser-setup.sh按需执行。network默认none这是安全级别最高的选项。需要联网时可选bridge或者浏览器专用的openclaw-sandbox-browser。host和container:id属于低安全级别container命名空间加入还需要dangerouslyAllowContainerNamespaceJoin显式打开默认关闭别轻易动。Cgroups 部分memory.limit给 512MB、swap设 0 是常见组合禁用交换能避免内存超限时拖慢宿主机。cpu.quota50000 配合period100000相当于半个 CPU 核。pids.max100 防止 fork 炸弹。这些值按你的机器规格调小机器上别给太大。如果你用 TOML 风格的配置部分工具链支持等价写法是[agents.defaults.sandbox] mode non-main scope session workspaceAccess ro [agents.defaults.sandbox.docker] image openclaw-sandbox-common:bookworm-slim network none配置改完记得重启 Gateway否则不会生效。这一步很多人忘然后对着旧行为排查半天。4. 启动后验证隔离生效命令、预期输出与结果解读配置写完不等于隔离生效必须验证。我按「容器是否起来、命名空间是否独立、资源限制是否生效、网络是否真的断」四层来验。第一层确认容器在跑。启动 Gateway 后执行docker ps --filter nameopenclaw --format table {{.Names}}\t{{.Image}}\t{{.Status}}预期输出里能看到类似openclaw-sandbox-session-id的容器镜像是你配的openclaw-sandbox-common:bookworm-slim状态是Up。如果列表为空说明沙箱没触发——检查mode是不是off或者当前会话是不是被判定为主会话。第二层验证 PID namespace 独立。进容器看进程docker exec -it 容器名 ps aux预期只看到容器内的少量进程PID 从 1 开始编号看不到宿主机的进程列表。如果你在容器里ps aux看到了宿主机的进程说明 namespace 没隔离通常是容器启动参数被覆盖了。第三层验证文件系统隔离。在容器内尝试读主机工作区docker exec -it 容器名 ls /agentworkspaceAccess为ro时这里能看到工作区文件但尝试写入会失败docker exec -it 容器名 touch /agent/test.txt预期报Read-only file system。如果写入成功了说明挂载权限配错回去检查workspaceAccess是不是被设成了rw。第四层验证网络隔离。network为none时docker exec -it 容器名 curl -s --max-time 5 https://example.com预期是超时或Could not resolve host。如果返回了正常内容说明网络没断检查network配置是否被其他层覆盖。第五层验证资源限制。在容器内跑一个吃内存的命令docker exec -it 容器名 sh -c dd if/dev/zero of/dev/null bs1M count2000配合docker stats 容器名观察内存应该被压在 512MB 附近不会无限涨。如果docker stats显示内存持续攀升超过限制检查 Cgroups 配置是否真的应用到了容器上。验证通过后你可以让模型触发一次 exec 工具然后在宿主机上确认宿主机的工作目录没有被意外修改宿主机进程列表没有多出奇怪进程宿主机网络连接没有异常。这三条都干净说明隔离生效。如果验证过程中容器起不来先看docker logs 容器名常见原因是镜像没构建、镜像名拼错、或者 Docker Daemon 没运行。镜像问题用docker images | grep openclaw确认。5. 常见报错排查401、local proxy failed、reading choices 与 OAuth这一节按真实报错来每个都给出定位路径。401 Unauthorized。这是模型侧最常见的。表现是 Gateway 日志里出现401模型请求被拒。排查顺序先确认TAOTOKEN_API_KEY环境变量在当前 shell 里真的存在echo $TAOTOKEN_API_KEY看有没有值再确认 Key 没有多余空格或换行复制时容易带上然后确认 Base URL 是https://taotoken.net/api没有多写/v1或少了协议头。如果 Key 是从控制台新生成的确认没有把旧 Key 和新 Key 混用。三件套里 Key 和 Base URL 对上了401 基本就消失。local proxy failed。这个报错通常不是 Key 的问题而是本地网络层。表现是请求还没到服务端就失败了。排查确认本机没有配置会拦截请求的本地代理确认 DNS 能解析taotoken.net用curl -v看请求卡在哪一步。如果是容器内发起的请求注意network: none的容器本来就没网模型请求应该由 Gateway 在主机侧发起而不是容器内。如果你把模型调用也塞进了沙箱容器那local proxy failed是预期行为把模型调用移回 Gateway 层。reading choices 报错。典型信息是Cannot read properties of undefined (reading choices)。这说明代码在解析响应时响应体里没有choices字段。原因通常是请求返回了错误结构比如 401 的错误体但代码没先判断状态码就取choices或者 Model ID 写错服务端返回了模型不存在的错误。排查先用 curl 单独打一次看原始响应长什么样确认 Model ID 在模型对话页面列出的清单里在代码里加一层状态码判断非 200 时先打印响应体再解析。OAuth 相关报错。如果你用的是 Claude Code 这类走 OAuth 的工具报错可能表现为 token 过期或授权失败。注意 OAuth 流程和 API Key 是两条路不要混用。用 API Key 接入时确保工具配置里没有残留的 OAuth 配置项。Claude Code 的 settings 里如果同时存在 OAuth token 和 API Key可能优先走 OAuth 导致失败。清理掉 OAuth 相关字段只保留 Base URL 和 Key。容器启动失败。报错可能是image not found或permission denied。前者用docker images确认镜像存在不存在就执行构建脚本后者检查当前用户是否在 docker 组里groups命令看一下没有的话需要加组并重新登录。沙箱内工具找不到。表现是模型触发 exec 时报command not found。这是因为默认镜像只有基础工具。换成openclaw-sandbox-common:bookworm-slim或者自己基于基础镜像加工具。注意换镜像后要重新验证隔离别因为图省事把network也放开。配置不生效。改了 JSON 但行为没变九成是没重启 Gateway。另外检查配置层级agents.defaults.sandbox是默认值如果某个 agent 单独覆盖了 sandbox 配置默认值就不起作用。用配置校验命令或日志确认最终生效的值。排障时建议开 Gateway 的 debug 日志能看到容器创建参数和模型请求的完整链路。日志里容器创建那段会打印实际的 docker 参数对照你的配置看有没有被覆盖。6. 把沙箱接进你的工作流从验证到长期运行沙箱跑通之后下一步是把它接进日常流程。我的建议是分三阶段先在开发环境用mode: non-mainworkspaceAccess: ro跑一周观察模型触发哪些工具、哪些因为隔离失败然后根据失败清单决定是加工具镜像还是放开特定权限最后再考虑上生产。长期运行时容器的生命周期管理要注意。scope: session会频繁创建销毁容器磁盘上可能堆积停止的容器定期docker container prune清理。scope: shared省资源但隔离弱多用户场景别用。模型侧如果调用量大Coding Plan 的配额模式比按次更可控尤其是 Agent 反复试错的场景。但无论用哪种Base URL 和 Key 的管理方式不变三件套写全就不会出岔子。最后提醒一个容易忽略的点沙箱隔离的是工具执行不是模型本身。模型仍然能看到你传给它的上下文所以敏感信息不要放进 prompt。沙箱解决的是「模型决策后执行动作」的爆炸半径不是数据泄露的全部防线。把这两层分开理解配置时就不会指望沙箱做它做不到的事。验证清单再走一遍容器在跑、PID 独立、文件系统只读、网络断开、内存受限。五条都过你的 OpenClaw Sandbox 就算搭好了。接下来可以试着让模型跑一个需要多步 exec 的任务观察它在沙箱里的行为和主机上直接跑有什么不同。