沙箱里找不到宿主机已安装的命令怎么办？

容器镜像与宿主机是两套根文件系统；要么把工具做进沙箱镜像，要么通过配置暴露额外路径/挂载。不要把「我 SSH 进机器有」与「沙箱内 PATH 有」混为一谈。

退出码 137 是否一定等于 OOM？

在 Docker/容器场景里 137 常表示 SIGKILL，OOM killer 是常见原因但不是唯一原因；应结合 dmesg、container exit、构建阶段一起判断。

何时应关掉沙箱？

在可信环境、仅只读操作为主的场景可评估关闭或换 SSH/OpenShell 后端；需要隔离任意命令执行时仍应保留沙箱并收紧镜像与网络。

2026 OpenClaw Agent 沙箱（Sandbox）实操：Docker 镜像、`docker.user` 与卷权限、工具不可见与 OOM/137 分诊

你已经能用 Docker / Compose 跑 OpenClaw Gateway，但一打开 Agent 沙箱就出现：容器起不来、工作区只读/不可写、沙箱里明明缺命令、一构建就 OOM 退出 137。本文把 2026 年主流落地路径压成可执行顺序：关→开→验→排障，用配置键位、卷权限与 `docker.user` 对齐、镜像构建与 OOM 分诊表和站内已有「Docker 安装/卷权限/doctor」类文章明确分工。读完你应能判断：是镜像问题、挂载 UID 问题、还是资源上限与日志关键字问题。

痛点：为什么沙箱一开会变成「我本地明明有，容器里就是找不到」

根因往往不在「OpenClaw 装坏了」，而在进程边界：

根文件系统不是宿主机：沙箱是独立镜像；你在宿主机 brew install 的东西不会自动出现在沙箱的 PATH，除非进镜像或额外挂载/层。
工作区是 bind mount 进来的：如果宿主机上目录属主是 501:20、容器里进程是 1000:1000 跑，常出现只读失败或写拒绝，日志里以 Permission denied 或 EROFS 呈现。
沙箱是另一套安全边界：即便 Gateway 有网络，沙箱内 DNS、出站策略与工具集仍应单独设计；和「能 SSH 进机器装软件」是两条运维路径。

与 SSH/OpenShell/无沙箱：一屏对照，避免选错后端

模式	适合什么	你付出的成本	常见误判
Docker 沙箱	要对不可信命令/脚本做硬隔离，复现「干净环境」	镜像体积、拉取/构建、UID/GID/卷要对齐	以为宿主机工具自动继承
SSH / 远端 shell	在你信任的远程 Mac上直接跑（例如独占构建机），需要完整工具链	暴露面与账户模型变大	把本机当沙箱、忘记审计
无沙箱 / 全本地	内网、低危、可快速排障	任一代码被模型执行时风险高	在 CI/生产也长期关闭

配置入口：`agents.defaults.sandbox.docker` 与 `sandbox-setup.sh` 怎么配合

概念上分两层：用哪个沙箱实现（Docker 镜像/运行时）和镜像从哪来。官方仓库通常提供 scripts/sandbox-setup.sh（名称以你本地克隆版本为准）来预构建/拉取作为宿主机上 docker CLI 能识别的镜像。配置里 agents.defaults.sandbox.docker.image 指向要运行会话的那个镜像；两者不一致时，典型症状是「Gateway 认为沙箱已启用，但 docker run 报 manifest not found 或 pull access denied」。

info

和已有文章怎么分工？ 若你卡在 OPENCLAW_IMAGE 或 Control UI 入口，先按官方 Docker 一键与 GHCR 镜像；若你卡在数据卷、权限、持久化与 Skills 路径，对照 Docker 卷与权限检查表。本篇只盯 沙箱子系统 + OOM/137。

`docker.user` 与 `OPENCLAW_HOME` 挂载：按症状对齐，而不是乱 `chmod 777`

推荐顺序：

在宿主机上确认要挂载的 workspace 目录属主/属组，以及 Gateway 进程实际以何身份运行；
在配置里设置 docker.user 为 与卷可写性一致的 UID:GID（以文档键名为准，若你版本用嵌套表结构则对应到 sandbox.docker 下）；
若公司策略禁止对仓库根目录大面 chown，优先调整挂载到容器内的子目录，而不是放开整个磁盘。

对 Linux 与远程 Mac 的细微差别是：命名卷、绑定挂载、SELinux 标签（在部分发行版上）会放大「在 compose 里看着对、进容器就错」的现象。此时要在 Gateway/沙箱容器的启动日志中抓首条 I/O 错误行，而不是在模型对话里试运气。

「工具在宿主机有、沙箱里无」的最短分诊 4 问

该可执行文件是否在**镜像 PATH 的目录**中？docker exec 到沙箱里跑 command -v 比口述可靠。
是否依赖**动态库或解释器**路径（例如特定 Node/Python minor）而镜像中不存在？
是否需要只读绑定宿主机的 ~/.cache 之类路径才能跑？若是，要评估把缓存放进镜像/公共层，而不是从宿主随意穿越。
该工具是否与 Gateway 同网络策略，需要额外 HTTP(S)_PROXY？网络失败常被误报成 command not found。

OOM 与 `exit 137`：在 Docker 里如何读「被杀」与「不够内存」

137 = 128 + 9 (SIGKILL) 在实践里常和 OOM killer 相关，但你也可能看到 人为 docker kill 或 cgroup 内存限制 触顶。分诊上至少做三件事：看 构建阶段是 docker build 还是 docker run；在引擎侧看 concurrent build 是否让 Docker Desktop / VM 内存打满；对远程 Mac/专用机则看系统真实可用内存与 swap 压力，而不是只盯单容器 limits。另有一类易混信号是退出码 1 或 2却伴随大量 Cannot allocate memory 文本，也要并入「内存/磁盘临时空间」同一张表，避免在模型侧反复调参却不动容器。

对「构建时 OOM」的通用减负顺序：关并行层（--parallel 等）、用多阶段构建减少编译峰、提高 Docker VM 分配、换带更多内存的 独占远程 Mac 档位 作为稳定基座。这与「在笔记本上开多个 IDE + 本地大模型 + Docker」的偶然成功不是一类事件。若团队已上共享存储，额外关注inode 与元数据小文件爆发导致的「像 OOM 一样卡死」现象，必要时分卷或改清理策略。

落地 6 步：从 0 到能稳定开沙箱跑一轮工具

确认 Docker/Compose 健康 与 Gateway 能启动（参考 Gateway/模型层分诊与 doctor 衔接）。
跑官方/随仓库的 sandbox-setup 构建或拉取镜像，记录**镜像名与 ID** 与配置一致。
在测试 workspace 上启用沙箱，刻意运行「只写小文件」与「读大目录」各一次，抓权限错误。
对 docker.user 与挂载做 A/B：只改一个变量、保留 diff，避免同时改三处后无法回滚。
压一个中等强度构建，同时观察宿主机与容器内存，记录是否 137。
把 Runbook 写进团队 Wiki：含最小复现、日志片段、与「何时关沙箱/何时必须开」的边界。

config 片段（示意键名，以你版本 openclaw.json/文档为准）

{
  "agents": {
    "defaults": {
      "sandbox": { "mode": "docker" },
      "docker": { "user": "1000:1000" }
    }
  }
}
// 实际项目可能为嵌套在 sandbox.docker 下，请先 openclaw doctor / 对照官方文档

可引用技术信息：3 条写进评审/容量笔记的参数量级

exit 137 与 128+信号：在排障单里**同时记录** docker events 或引擎日志、宿主机 memory pressure，避免把业务 OOM 与 docker build 并行 OOM 混为同一类事故。
用户命名空间/UID 映射：在 bind mount 场景，chown -R 1000:1000 单个项目目录 与「动整个家目录」风险不同，变更要有工单与回滚点。
沙箱冷启动时延：大镜像的 extract 层、首次 pip 索引、以及无持久层时的重复下载，会把「能跑通一次」和「能跑通一百次」的成本拉开，应在容量评审里给首启时间一个数字。

为何「笔记本临时配 Docker + 大模型 + Xcode」常撑不住企业级沙箱节奏

这类替代拓扑通常输在内存与 I/O 的同时峰值与可重复的环境边界上：你昨天能构建，是侥幸没有并发；而生产 Agent 在高峰会稳定触发 137 与写放大。对需要7×24 Gateway + 沙箱的团队，更可控的组合是 独占的 Apple Silicon 云主机、清晰磁盘与日志策略、可预期的租期。在这种前提下，MACCOME 的远程 Mac 云算力更适合作为 OpenClaw 的常驻基座——你减少的是与随机本地环境搏斗的时间，把精力放回工具链与产品交付。