1. 项目概述：为什么我们需要一个AI代码执行的“安全屋”？

最近在折腾AI智能体开发的朋友，估计没少为“安全”这事儿头疼。你让AI去执行一个 ls 命令，它可能老老实实；但你让它去写个脚本，或者处理一个用户上传的未知文件，心里是不是就开始打鼓了？万一它执行了 rm -rf / ，或者尝试访问敏感的系统文件怎么办？这可不是危言耸听，在赋予AI工具调用能力的同时，如何为它划定一个安全的“活动范围”，是每个严肃的开发者都必须面对的问题。

这就是“安全沙盒”概念的核心价值。你可以把它想象成一个透明的、坚不可摧的玻璃房子。AI智能体（比如OpenClaw）在这个房子里可以自由活动，使用工具、读写文件、运行代码，但它的所有操作都被限制在这个房子内部，无法触及到外部的“真实世界”（也就是你的宿主机）。房子里的任何破坏，都不会影响到房子外的任何东西。OpenClaw项目提供的沙盒架构，正是为了解决这个核心痛点。

而今天我们要深入探讨的，是OpenClaw沙盒架构中一个非常强大且灵活的选项： SSH后端 。与默认的Docker后端不同，SSH后端允许你将这个“安全屋”直接建在另一台远程服务器上。这意味着，你可以将潜在有风险的计算任务完全剥离到一台专用的、隔离的“沙盒服务器”上，从而实现对生产环境或开发主机的绝对保护。结合OpenShell插件，你甚至可以获得一个托管式的、功能更丰富的远程沙盒环境。

接下来的内容，我将以一个资深运维和AI应用开发者的视角，带你彻底拆解OpenClaw的沙盒安全模型，并手把手完成SSH后端，特别是结合OpenShell的实战配置。无论你是想为你的AI应用增加一道坚固的防线，还是希望将计算负载卸载到远程资源，这篇文章都将提供从原理到落地的完整指南。

2. 核心架构解析：OpenClaw沙盒的三层安全哲学

在直接动手配置之前，我们必须先理解OpenClaw沙盒设计背后的逻辑。它不是简单的一堵墙，而是一个由策略、隔离层和逃生通道共同构成的精密系统。理解这些，你才能知道每个配置项究竟在保护什么，以及在什么情况下该如何调整。

2.1 隔离什么？不隔离什么？

这是安全边界定义的第一步。OpenClaw的沙盒隔离有明确的范畴：

会被沙盒隔离的操作（即“关在玻璃房里”的操作）：

• 工具执行 ：这是核心。包括 exec （执行命令）、 read / write / edit / apply_patch （文件操作）、 process （进程管理）等所有通过工具调用触发的行为。
• 沙盒浏览器 ：当AI需要操作浏览器时（例如进行网页抓取或自动化测试），可以启动一个独立的、容器化的浏览器实例。这个浏览器也运行在沙盒内，其网络和文件系统同样受到限制。

不会被沙盒隔离的操作（即“玻璃房外的特权操作”）：

• Gateway网关进程本身 ：负责协调通信和管理的核心进程必须留在主机上，否则整个系统就无法运行了。
• 显式提升的工具 ：这是故意留出的“后门”。通过 tools.elevated 配置显式声明的工具，会绕过沙盒，直接在主机或指定的Node环境中运行。这用于那些必须访问主机资源的高度受信操作。

我的实操心得 ：这个设计非常务实。它承认了“绝对隔离”在现实中有时行不通。比如，你的AI可能需要调用一个只有宿主机上才有的特定硬件驱动或密钥管理服务。这时， tools.elevated 就是一个可控的、审计明确的逃生通道。关键在于，这个通道必须由你手动、显式地打开，而不是默认存在。

2.2 沙盒的三种运行模式：按需启用隔离

不是所有会话都需要同等强度的隔离。OpenClaw通过 sandbox.mode 提供了精细的控制：

• off ：完全关闭沙盒。所有工具都在主机上运行。 仅在完全可信的内部调试环境中使用 。
• non-main （默认） ：仅隔离“非主会话”。这里有个关键概念： session.mainKey ，默认是 "main" 。你与AI的普通一对一聊天通常就是主会话。而群组聊天、特定渠道的会话会被视为非主会话并被隔离。这个模式很适合这样一个场景：你信任自己和AI在主会话中的交互，但对来自外部群组或未知渠道的请求保持警惕。
• all ：最严格的模式。 所有会话 ，包括你的主聊天，都会被扔进沙盒。这是生产环境或面对不可信用户输入时的推荐设置。

2.3 三大后端选型：Docker、SSH与OpenShell

这是架构的核心选择，决定了你的“玻璃房”用什么材料建成，以及建在哪里。

特性	Docker 后端	SSH 后端	OpenShell 后端
运行位置	本地容器	任何SSH可达的主机	OpenShell托管的远程沙盒
设置复杂度	中等（需Docker环境）	低（只需SSH访问）	低（需启用插件）
工作区同步模型	绑定挂载或复制	远程为规范（初始播种）	mirror （本地规范）或 remote （远程规范）
网络控制	通过 docker.network 配置	取决于远程主机网络	取决于OpenShell服务
浏览器沙盒	支持	不支持	暂不支持
绑定挂载	支持 ( docker.binds )	不适用	不支持 ( docker.binds 不生效)
最佳适用场景	本地开发、需要最强隔离、需用浏览器工具	将计算卸载到远程机器、资源隔离	需要远程托管沙盒，且希望有可选双向同步

选择逻辑：

1. 追求极致本地隔离和功能完整性（含浏览器） ：选 Docker后端 。
2. 希望利用现有远程服务器资源，实现物理级隔离 ：选 SSH后端 。
3. 希望使用托管服务，并需要灵活的工作区同步策略 ：选 OpenShell后端 。

我们今天的重点，是 SSH后端 及其增强形态—— OpenShell后端 。它们代表了将安全边界从“本地进程隔离”扩展到“远程物理隔离”的进阶思路。

3. SSH后端实战：构建你的远程安全堡垒

SSH后端的核心思想很简单：让OpenClaw通过SSH协议，在一台远程机器上执行所有沙盒化的操作。这台远程机器就是你的专属“沙盒服务器”。

3.1 准备工作：配置SSH免密登录

这是所有操作的基础。如果SSH连接还需要手动输入密码，自动化就无从谈起。

1. 在OpenClaw主机生成密钥对 （如果还没有）：

   ssh-keygen -t ed25519 -f ~/.ssh/id_openclaw_sandbox
   

   这会在 ~/.ssh/ 下生成私钥 id_openclaw_sandbox 和公钥 id_openclaw_sandbox.pub 。

2. 将公钥部署到沙盒服务器 ： 假设你的沙盒服务器用户是 sandbox-user ，地址是 sandbox-host 。

   # 将公钥内容复制到沙盒服务器的authorized_keys文件中
   ssh-copy-id -i ~/.ssh/id_openclaw_sandbox.pub sandbox-user@sandbox-host
   

   执行后，尝试登录验证：

   ssh -i ~/.ssh/id_openclaw_sandbox sandbox-user@sandbox-host
   

   如果无需密码即可登录，说明配置成功。

重要注意事项 ：出于安全考虑，强烈建议为沙盒服务器创建一个专用、低权限的系统用户（如 openclaw-sandbox ），而不是使用 root 或你的个人账户。这个用户应该只拥有运行必要命令和在其工作目录（如 /tmp/openclaw-sandboxes ）下读写的权限。

3.2 核心配置详解与示例

下面是一个完整的SSH后端配置示例，我们将逐项拆解其含义。

// openclaw.json 或你的配置文件
{
  agents: {
    defaults: {
      sandbox: {
        mode: "all", // 所有会话都进沙盒
        backend: "ssh", // 指定使用SSH后端
        scope: "session", // 每个会话独立一个沙盒目录，隔离性最好
        workspaceAccess: "rw", // 沙盒内可以读写Agent的工作区
        ssh: {
          target: "sandbox-user@sandbox-host:22", // SSH连接目标
          workspaceRoot: "/tmp/openclaw-sandboxes", // 远程服务器上的沙盒根目录
          strictHostKeyChecking: true, // 必须为true，验证主机密钥防止中间人攻击
          updateHostKeys: true, // 自动更新known_hosts
          identityFile: "~/.ssh/id_openclaw_sandbox", // 私钥路径
          // certificateFile: "~/.ssh/id_openclaw_sandbox-cert.pub", // 如果有证书则配置
          knownHostsFile: "~/.ssh/known_hosts", // 已知主机密钥文件
        },
      },
    },
  },
}

关键参数解析：

• scope: “session” ：这意味着每个独立的AI会话都会在远程服务器的 workspaceRoot 下创建一个唯一的子目录。这提供了最强的隔离性，会话A无法干扰会话B的文件。代价是会有更多的目录和初始播种开销。如果追求资源复用，可以考虑 “agent” （每个智能体一个目录）或 “shared” （所有共享一个目录）。
• workspaceAccess: “rw” ：将Agent的工作区以读写模式“映射”到沙盒内的 /workspace 路径。AI在沙盒内对 /workspace 的修改，实际上会作用到远程服务器的沙盒目录里。如果设为 “ro” ，则只能读不能写；设为 “none” ，则完全看不到主工作区，只能看到沙盒临时目录。
• workspaceRoot ： 务必确保远程服务器上的这个路径存在，并且SSH用户有完整的读写权限。 例如： ssh sandbox-user@sandbox-host “mkdir -p /tmp/openclaw-sandboxes” 。
• 身份验证的另一种方式（更安全） ：上面的例子使用了本地文件。但在容器化或CI/CD环境中，更推荐使用 *Data 字段内联密钥内容或引用环境变量Secret，避免密钥文件落地。

  ssh: {
    target: "sandbox-user@sandbox-host:22",
    workspaceRoot: "/tmp/openclaw-sandboxes",
    strictHostKeyChecking: true,
    // 从环境变量中读取私钥、证书和known_hosts内容
    identityData: { source: "env", provider: "default", id: "SANDBOX_SSH_KEY" },
    certificateData: { source: "env", provider: "default", id: "SANDBOX_SSH_CERT" },
    knownHostsData: { source: "env", provider: "default", id: "SANDBOX_KNOWN_HOSTS" },
  }
  

  这样，私钥等敏感信息只存在于内存或安全的Secret管理器中。

3.3 SSH后端的工作原理与数据流

理解以下流程，对调试问题至关重要：

1. 沙盒创建 ：当一个新的会话需要沙盒时，OpenClaw会在远程服务器的 /tmp/openclaw-sandboxes/<scope-id> 目录下创建专属目录。
2. 初始播种 ： 仅第一次创建时发生 。OpenClaw会将本地Agent工作区的内容，通过SSH的SCP/SFTP复制到远程的沙盒目录中。此后，这个远程目录就成为该沙盒的“规范”工作区。
3. 工具执行 ：此后，该会话所有的 exec 、 read 、 write 等操作，都会通过SSH通道直接针对这个远程目录执行。
4. 无反向同步 ： 这是一个关键点！ SSH后端采用“远程规范”模型。在初始播种之后，AI在远程沙盒里创建或修改的文件， 不会自动同步回你本地OpenClaw主机的工作区 。远程沙盒的状态是独立的。
5. 沙盒销毁与重建 ：当你执行 openclaw sandbox recreate 命令时，会删除远程的沙盒目录。下次使用时，会重新从本地工作区播种，创建一个全新的远程沙盒。

我的踩坑记录 ：曾经误以为SSH后端会双向同步，在远程沙盒里调试好的脚本，回头在本地找不到，排查了半天。务必记住，SSH后端下，远程是“工作副本”，本地是“初始模板”。如果你需要将远程的修改拿回来，需要手动通过SCP或其他方式同步，或者考虑使用下文要讲的OpenShell的 mirror 模式。

4. OpenShell后端进阶：托管沙盒与灵活同步

OpenShell是OpenClaw生态中的一个插件，它提供了一个专门为AI智能体优化的托管沙盒服务。你可以把它理解为一个“加强版的SSH后端”，它管理了沙盒容器的生命周期，并提供了更智能的工作区同步策略。

4.1 启用与基础配置

首先，确保OpenShell插件已启用并正确配置。

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell", // 切换到OpenShell后端
        scope: "session",
        workspaceAccess: "rw", // 这个设置对OpenShell依然有效，但含义因模式而异
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true, // 必须启用插件
        config: {
          from: "openclaw", // 标识来源
          mode: "remote", // 核心选择：`mirror` 或 `remote`
          remoteWorkspaceDir: "/sandbox", // 远程沙盒内的工作区路径
          remoteAgentWorkspaceDir: "/agent", // 远程沙盒内Agent工作区的挂载点（当workspaceAccess为ro时）
        },
      },
    },
  },
}

4.2 核心抉择： mirror 模式 vs remote 模式

这是OpenShell后端最精髓的部分，直接决定了你的工作流。

mode: “mirror” (镜像模式，本地为权威)

• 行为 ：
  1. 执行前同步 ：每次AI执行工具前，OpenClaw会将 本地工作区 的全部内容同步到OpenShell远程沙盒。
  2. 执行 ：AI在远程沙盒中操作。
  3. 执行后同步 ：执行完成后，OpenClaw会将 远程沙盒的修改同步回本地工作区 。
• 优点 ：本地工作区始终是“真理之源”。你在本地IDE里修改代码，下次AI执行时自动就能用上。AI在沙盒里生成的结果，也会自动带回本地。行为最接近Docker后端，符合直觉。
• 缺点 ：每次执行都有同步开销，对于大工作区或频繁执行，可能会有性能影响。
• 适用场景 ： 开发调试阶段 。你主要在本地编码，希望AI在干净的沙盒中测试，并将结果带回本地。

mode: “remote” (远程模式，远程为权威)

• 行为 ：
  1. 初始播种 ：仅在沙盒 首次创建时 ，将本地工作区内容复制到远程。
  2. 后续执行 ：之后所有的操作都直接针对 远程沙盒工作区 进行。 没有反向同步 。
• 优点 ：执行速度最快，无同步延迟。远程沙盒状态持久化，适合长时间、多轮次的交互任务。
• 缺点 ：本地和远程状态可能脱节。在本地修改文件，远程沙盒感知不到，除非重建沙盒。
• 适用场景 ： 生产或持续运行环境 。你将沙盒视为一个独立的、长期存在的执行环境。或者，你明确希望将AI的工作产物保留在远程，而不污染本地。

4.3 OpenShell的工作机制

OpenShell后端在底层复用了SSH的传输协议，但增加了管理层：

1. 沙盒生命周期管理 ：OpenClaw通过OpenShell插件的API（如 openshell sandbox create ）来创建、获取、销毁沙盒，而不是直接操作SSH服务器。
2. 动态SSH配置 ：OpenClaw通过 openshell sandbox ssh-config <name> 命令，向OpenShell服务请求一个临时的、针对特定沙盒的SSH连接配置（包括主机、端口、密钥等）。
3. 连接与桥接 ：OpenClaw Core拿到这个配置，写入临时文件，然后像普通的SSH后端一样建立连接和文件系统桥接。
4. 模式化同步 ：根据 mode 是 mirror 还是 remote ，决定在执行前后是否进行 rsync 或类似的文件同步操作。

4.4 配置示例与选择建议

场景一：个人开发项目，本地为主

{
  agents.defaults.sandbox: { mode: "all", backend: "openshell", scope: "session" },
  plugins.entries.openshell: {
    enabled: true,
    config: { from: "openclaw", mode: "mirror", remoteWorkspaceDir: "/sandbox" }
  }
}

解读 ：你写代码，AI在干净的远程沙盒里测试并返回结果，完美闭环。

场景二：部署在服务器的AI客服，沙盒即工作区

{
  agents.defaults.sandbox: { mode: "all", backend: "openshell", scope: "agent", workspaceAccess: "rw" },
  plugins.entries.openshell: {
    enabled: true,
    config: { from: "openclaw", mode: "remote", remoteWorkspaceDir: "/sandbox" }
  }
}

解读 ： scope: “agent” 让同一个智能体的所有会话共享一个沙盒，保持上下文。 mode: “remote” 让所有交互数据都留在远程沙盒，本地主机无状态，易于扩展和重置。

5. 安全加固与生产环境配置要点

将AI代码执行放到远程，安全更是重中之重。以下是我总结的几条生产级配置建议：

1. 最小权限原则 ：

   • SSH用户权限必须严格限制。禁止 sudo ， shell 最好限制为 rbash （受限bash）。
   • 远程的 workspaceRoot 目录权限应为 0700 （仅属主可读写执行）。
   • 在OpenClaw配置中，除非必要，将 workspaceAccess 设为 “ro” 甚至 “none” ，防止AI意外覆盖重要文件。

2. 网络隔离 ：

   • 沙盒服务器应该部署在独立的网络分区或VPC中，严格限制其出站和入站连接。只允许来自OpenClaw Gateway主机的SSH入站连接。
   • 在沙盒服务器内部，可以考虑使用 firewalld 或 iptables 进一步限制容器或进程的网络访问，例如禁止访问内部数据库或管理网段。

3. 审计与日志 ：

   • 确保远程服务器上的 auditd 或系统日志记录了所有SSH会话的建立和用户命令（通过 pam_tty_audit 或类似模块）。
   • 在OpenClaw Gateway端，启用详细的工具执行日志，记录谁、在哪个会话、何时、执行了什么命令。

4. 定期清理与重置 ：

   • 对于 scope: “session” ，会话结束后的沙盒目录残留需要清理。可以配置一个定时任务（cron job），定期删除 /tmp/openclaw-sandboxes 下超过一定时间的目录。
   • 对于 scope: “agent” 或 “shared” ，定期使用 openclaw sandbox recreate 命令来重置沙盒状态，避免状态累积导致不可预知的行为。

5. 密钥管理 ：

   • 绝对不要 使用永久性的、高权限的SSH密钥。考虑使用：
     • 证书认证 ：配置 certificateFile ，使用短期有效的SSH证书。
     • 动态密钥 ：通过HashiCorp Vault、AWS Secrets Manager等系统动态获取临时密钥，并通过 identityData 字段注入。
   • 将私钥内容存储在环境变量或Secret管理器中，如前面示例所示，避免密钥文件泄露风险。

6. 常见问题排查与调试技巧

即使配置正确，在实际运行中也可能遇到各种问题。这里记录一些典型的“坑”和解决方法。

问题1：SSH连接失败，提示 Connection timed out 或 Permission denied 。

• 排查步骤 ：
  1. 网络可达 ：从OpenClaw主机手动执行 ssh -v -i <私钥路径> <target> ，观察详细输出。检查防火墙、安全组规则。
  2. 密钥权限 ：确保本地私钥文件权限为 600 ( -rw------- )。过宽的权限SSH会拒绝使用。
  3. 用户与路径 ：确认 target 中的用户名和主机名正确，且远程 workspaceRoot 目录存在且用户有权限。
  4. Known Hosts ：如果是第一次连接，且 strictHostKeyChecking 为 true ，需要先手动连接一次将主机密钥加入 known_hosts ，或者临时设为 false （不推荐生产环境）进行测试。

问题2：工具执行失败，错误提示文件不存在或权限错误。

• 排查步骤 ：
  1. 检查工作区路径 ：登录沙盒服务器，查看 workspaceRoot 下的会话目录是否成功创建，内部文件是否与本地一致。
  2. 检查 workspaceAccess ：如果AI尝试写入文件失败，检查配置是 “rw” 还是 “ro” 。在SSH后端下，还要确认远程目录的文件系统是否只读（如 /tmp 被挂载为 noexec ）。
  3. 查看OpenClaw日志 ：使用 openclaw logs --level debug 查看详细的工具调用和沙盒桥接日志，里面通常会有更具体的错误信息。

问题3：OpenShell模式下，文件修改没有同步回本地（ mirror 模式）。

• 排查步骤 ：
  1. 确认模式 ：首先检查 plugins.entries.openshell.config.mode 确实是 mirror 。
  2. 检查同步日志 ：OpenClaw在同步文件时会有日志输出。检查是否有同步错误（如网络中断、磁盘满）。
  3. 手动触发同步 ：可以尝试手动重建沙盒( openclaw sandbox recreate )，这会触发一次完整的重新播种，帮助你判断是同步过程出错，还是配置理解有误。

问题4：性能缓慢，尤其是文件操作。

• 可能原因与优化 ：
  1. 网络延迟 ：OpenClaw主机与沙盒服务器之间的网络延迟过高。考虑将它们部署在同一可用区或内网。
  2. SSH加密开销 ：对于大量小文件传输，SSH的加密/解密会有开销。可以尝试在OpenShell或SSH服务器端启用压缩（SSH的 -C 选项），但需要测试是否真的提升性能。
  3. scope 选择 ： scope: “session” 会为每个会话创建独立目录并播种，开销最大。如果会话间不需要强隔离，可以尝试 scope: “agent” 。
  4. 工作区大小 ：避免将巨大的、AI不需要的目录（如 node_modules , .git ）放入工作区。使用 .openclawignore 文件忽略它们，减少同步数据量。

调试利器： openclaw sandbox explain 命令 当你搞不清为什么某个工具被阻止，或者沙盒没有按预期工作时，一定要用这个命令。它会清晰地展示当前会话生效的沙盒模式、后端、工具策略以及所有相关的配置项，是诊断配置问题的第一选择。

配置AI代码执行沙盒，尤其是远程沙盒，是一个在“功能”、“安全”和“便利性”之间寻找平衡点的过程。没有一劳永逸的银弹配置，最好的配置总是源于对业务场景的深刻理解和对底层原理的清晰把握。希望这篇从架构到实战的深度解析，能帮你构建起既强大又安全的AI智能体执行环境。