配置 — 智能体沙箱化

agents.defaults.sandbox 的完整配置：嵌入式 Agent 的镜像选择、工作区模式、挂载项和网络策略。

`agents.defaults.sandbox`¶

嵌入式 Agent 的可选沙箱机制。完整指南请参阅沙箱。

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off (default) | non-main | all
        backend: "docker", // docker (default) | openshell | podman | ssh
        scope: "agent", // session | agent (default) | shared
        workspaceAccess: "none", // none (default) | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          containerPrefix: "openclaw-sbx-",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          gpus: "all",
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
          binds: ["/home/user/source:/source:rw"],
        },
        ssh: {
          target: "user@gateway-host:22",
          command: "ssh",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
          updateHostKeys: true,
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
          // SecretRefs / inline contents also supported:
          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
        browser: {
          enabled: false,
          image: "openclaw-sandbox-browser:bookworm-slim",
          network: "openclaw-sandbox-browser",
          cdpPort: 9222,
          cdpSourceRange: "172.21.0.1/32",
          vncPort: 5900,
          noVncPort: 6080,
          headless: false,
          noVncEnabled: true,
          allowHostControl: false,
          autoStart: true,
          autoStartTimeoutMs: 12000,
        },
        prune: {
          idleHours: 24,
          maxAgeDays: 7,
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "apply_patch",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

上面展示的默认值（off/docker/agent/none/bookworm-slim 镜像/none 网络等）是 OpenClaw 的实际默认值，而不仅仅是示例值。

沙箱详情

后端：

docker：本地 Docker 运行时（默认）
openshell：由 OpenShell 管理的本地或远程运行时
podman：使用 Docker 兼容设置的本地 Podman 运行时
ssh：基于 SSH 的通用远程运行时

由插件管理的后端会将运行时专属设置保存在各自的插件条目下：

OpenShell：plugins.entries.openshell.config；请参阅 OpenShell

SSH 后端配置：

target：user@host[:port] 形式的 SSH 目标
command：SSH 客户端命令（默认：ssh）
workspaceRoot：用于各作用域工作区的远程绝对根路径（默认：/tmp/openclaw-sandboxes）
identityFile / certificateFile / knownHostsFile：传递给 OpenSSH 的现有本地文件
identityData / certificateData / knownHostsData：内联内容或 SecretRef，OpenClaw 会在运行时将它们物化为临时文件
strictHostKeyChecking / updateHostKeys：OpenSSH 主机密钥策略开关（两者默认均为 true）

SSH 认证优先级：

identityData 优先于 identityFile
certificateData 优先于 certificateFile
knownHostsData 优先于 knownHostsFile
由 SecretRef 支持的 *Data 值会在沙箱会话启动前，从当前生效的 secrets 运行时快照中解析

SSH 后端行为：

在创建或重新创建后，对远程工作区执行一次初始化（seed）
随后以远程 SSH 工作区为权威（canonical）状态
通过 SSH 转发 exec、文件工具和媒体路径
不会自动将远程更改同步回主机
不支持沙箱浏览器容器

工作区访问：

none：~/.openclaw/sandboxes 下按作用域划分的沙箱工作区（默认）
ro：沙箱工作区位于 /workspace，Agent 工作区以只读方式挂载在 /agent
rw：Agent 工作区以读写方式挂载在 /workspace

作用域：

session：每个会话一个容器 + 工作区
agent：每个 Agent 一个容器 + 工作区（默认）
shared：共享容器和工作区（不提供跨会话隔离）

OpenShell 插件配置：

{
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          mode: "mirror", // mirror (default) | remote
          command: "openshell",
          from: "openclaw",
          remoteWorkspaceDir: "/sandbox",
          remoteAgentWorkspaceDir: "/agent",
          gateway: "lab", // optional
          gatewayEndpoint: "https://lab.example", // optional
          workspace: "research", // optional existing OpenShell workspace
          policy: "/etc/openclaw/openshell-policy.yaml", // optional host-side YAML file
          providers: ["openai"], // optional
          gpu: false,
          autoProviders: true,
          timeoutSeconds: 120,
        },
      },
    },
  },
}

OpenShell 模式：

mirror：在执行前从本地向远程进行 seed（初始同步），执行后同步回本地；本地工作区保持权威（canonical）。
remote：在沙箱创建时对远程进行一次 seed，然后保持远程工作区为权威。

在 remote 模式下，seed 步骤之后，在 OpenClaw 外部对主机本地所做的编辑不会自动同步到沙箱中。传输方式为通过 SSH 进入 OpenShell 沙箱，但插件负责沙箱的生命周期以及可选的镜像同步（mirror sync）。 workspace 为整个插件选择一个现有的 OpenShell 控制面（control-plane）工作区；它与 agent 的文件系统工作区分开。policy 必须指向一个 OpenClaw Gateway 可读取的 YAML 文件，而不是一个命名策略 ID。有关设置、前提条件和故障排除，请参阅 OpenShell。

setupCommand 在容器创建后运行一次（通过 sh -lc）。需要网络出口（network egress）、可写的根文件系统、root 用户。

容器默认 network: "none" — 如果代理需要出站访问，请将其设置为 "bridge"（或自定义桥接网络）。 "host" 被阻止。"container:<id>" 默认也被阻止，除非你显式设置 sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true（break-glass）。在活跃的 OpenClaw 沙箱中运行的 Codex app-server，其原生 code-mode 网络访问使用相同的出口设置。

入站附件会暂存到活动工作区的 media/inbound/* 目录中。

docker.binds 挂载额外的主机目录；全局与每个代理（per-agent）的 binds 会合并。

沙箱浏览器（sandbox.browser.enabled，默认 false）：容器内的 Chromium + CDP。不需要在 openclaw.json 中设置 browser.enabled。 noVNC 观察者访问受密码保护，并通过一次性、已认证的 bootstrap URL 进行代理。观察者 URL 被有意从模型可见的系统提示上下文中省略。

allowHostControl: false（默认）阻止沙箱会话以主机浏览器为目标。
network 默认为 openclaw-sandbox-browser（专用桥接网络）。仅当你明确需要全局桥接连接时，才设置为 bridge。不支持 "none"，因为必须将 CDP 端口发布到主机；"host" 同样被阻止。升级时，openclaw doctor --fix 会禁用受持久化 "none" 值影响的 sidecar，并恢复专用网络，而不会静默启用出口。
cdpSourceRange 可选地将容器边缘的 CDP 入站流量限制为 CIDR 范围（例如 172.21.0.1/32）。
sandbox.browser.binds 仅将额外的主机目录挂载到沙箱浏览器容器中。一旦设置（包括 []），它会替换浏览器容器的 docker.binds。
沙箱浏览器容器中的 Chromium 始终以 --no-sandbox --disable-setuid-sandbox 启动（容器不具备 Chrome 自身沙箱所需的内核原语）；没有对应的配置开关。
启动默认值定义在 scripts/sandbox-browser-entrypoint.sh 中，并针对容器主机进行了调优：
--remote-debugging-address=127.0.0.1
--remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>
--user-data-dir=${HOME}/.chrome
--no-first-run
--no-default-browser-check
--disable-dev-shm-usage
--disable-background-networking
--disable-breakpad
--disable-crash-reporter
--no-zygote
--metrics-recording-only
--password-store=basic
--use-mock-keychain
--disable-3d-apis、--disable-gpu 和 --disable-software-rasterizer 默认启用；如果 WebGL/3D 使用需要，可以通过 OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 禁用。
--disable-extensions（默认启用）；如果你的工作流依赖扩展，OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 会重新启用扩展。
--renderer-process-limit=2 是默认值；可通过 OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N> 更改，设置为 0 则使用 Chromium 的默认进程限制。
--headless=new 仅在启用 headless 时使用。
默认值是容器镜像基线；要更改容器默认值，请使用带有自定义 entrypoint 的自定义浏览器镜像。

浏览器沙箱需要 Docker 引擎。sandbox.docker.binds 同时适用于 Docker 和 Podman 后端。

构建镜像（从源码检出）：

scripts/sandbox-setup.sh           # main sandbox image
scripts/sandbox-browser-setup.sh   # optional browser image

对于没有源码检出的 npm 安装，请参阅沙箱 § 镜像与设置了解内联的 docker build 命令。

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

配置 — 智能体沙箱化

agents.defaults.sandbox¶

`agents.defaults.sandbox`¶