setupCommand（一次性容器设置）

该钩子在沙箱容器创建后仅运行一次，并说明最常导致其失败的默认设置。

setupCommand（一次性容器设置）¶

setupCommand 在沙箱容器创建后仅运行一次（并非每次运行时都运行）。它通过 sh -lc 在容器内执行。

如果访问权限在设置完成前被撤销，OpenClaw 会保留容器及其已保存数据以供检查。后续请求会拒绝该不完整容器，而不是重启它或重放设置。在显式重新创建沙箱之前，请保留任何所需的容器数据。

路径：

常见陷阱

默认 docker.network 为 "none"（无出站网络），因此软件包安装会失败。
docker.network: "container:<id>" 需要 dangerouslyAllowContainerNamespaceJoin: true，且仅限紧急逃生使用。
readOnlyRoot: true 会阻止写入；请设置 readOnlyRoot: false 或构建自定义镜像。
软件包安装要求 user 为 root。Docker 可以省略 user 或设置 user: "0:0"；rootful Podman 必须设置 user: "0:0"，因为其默认行为会保留工作区所有权。Rootless Podman 会拒绝零值用户；请将软件包构建到镜像中，或使用 rootful Podman。
沙箱 exec 不会继承宿主机的 process.env。请使用 agents.defaults.sandbox.docker.env（或自定义镜像）来提供技能 API 密钥。
agents.defaults.sandbox.docker.env 中的值仍可通过容器元数据命令（例如 docker inspect 或 podman inspect）看到。Docker 和 Podman 要求可移植的环境变量名以及单行、非 NUL 值，因为安全引擎的环境文件按行分隔；配置校验和 openclaw doctor 会在沙箱使用前拒绝无效条目。请重命名无效键、使用单行值，或通过挂载文件或自定义镜像传递多行内容；这需要手动修复，因为 doctor --fix 无法安全保留原始值。SSH 和 OpenShell 后端仍支持多行值。如果元数据暴露不可接受，请使用自定义镜像、挂载的密钥文件或其他密钥传递路径。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw