exec.ts 上篇 —— OpenClaw 安全执行 Shell 命令的三层隔离模型

关键词：安全执行｜沙箱隔离｜Docker｜权限提升｜用户审批｜环境注入

在 AI 智能体系统中，工具调用（Tool Calling）是实现“行动能力”的核心。而其中最强大也最危险的能力，莫过于执行任意 Shell 命令——它能让 AI 重启服务、部署代码、分析日志，但也可能被滥用为“删库跑路”的入口。

OpenClaw 的 src/agents/bash-tools.exec.ts 模块，正是为解决这一矛盾而生。它没有简单地暴露 child_process.exec，而是构建了一套三层隔离模型（Three-Layer Isolation Model），在提供强大功能的同时，将风险控制在可接受范围内。

本文将详解这三层模型的设计原理、实现机制与安全边界。

一、为什么需要隔离？AI 执行命令的风险矩阵

image

信任 AI 的推理，不等于信任它的输出。

OpenClaw 的哲学是：AI 可以“提议”执行命令，但人类必须保留“否决权”。

二、三层隔离模型总览

OpenClaw 将命令执行环境分为三个层级，按安全强度递增：

image

用户可通过 host 参数指定执行位置：

tools:
  - name: "list_files"
    command: "ls -l {{path}}"
    host: "sandbox"   # ← 关键配置

默认即安全：若未指定，一律使用 L1 沙箱。

三、第一层：Docker 沙箱（Sandbox）—— 默认且最安全

核心思想

• 每条命令在一个临时、无状态、最小化的 Docker 容器中运行
• 容器启动后立即执行命令，完成后销毁
• 无网络、无持久存储、无特权

实现细节

// exec.ts
async function runInSandbox(cmd: string, args: string[]): Promise<ExecResult> {
  const image = "openclaw/sandbox:latest"; // 基于 alpine + coreutils
  
  const container = await docker.createContainer({
    Image: image,
    Cmd: [cmd, ...args],
    HostConfig: {
      NetworkMode: "none",        // 禁用网络
      AutoRemove: true,          // 执行完自动删除
      Memory: 128 * 1024 * 1024, // 128MB 内存限制
      CpuPeriod: 100000,
      CpuQuota: 50000,           // 限制 50% 单核 CPU
      Binds: [],                 // 不挂载任何主机目录
      CapDrop: ["ALL"],          // 放弃所有 Linux 能力
      SecurityOpt: ["no-new-privileges"]
    }
  });

  await container.start();
  const logs = await container.logs({ stdout: true, stderr: true });
  await container.wait(); // 等待退出

  return parseLogs(logs);
}

安全特性

• 文件系统隔离：无法读写主机任何文件
• 网络隔离：curl、wget 等命令无效
• 资源限制：防 DoS
• 无持久性：每次都是干净环境

适合：纯计算、文本处理、代码 lint 等无副作用操作。

四、第二层：网关宿主（Gateway Host）—— 受控的本地执行

当命令需要访问本地资源（如项目目录、Docker Daemon），可降级到 L2。

启用条件（必须同时满足）

1. 智能体配置显式声明 host: "gateway"
2. 命令在 权限提升白名单（Elevated Whitelist）中
3. 用户通过手机端手动审批

权限提升白名单示例

# config.yaml
bashTools:
  elevatedWhitelist:
    - "git status"
    - "npm run build"
    - "docker ps"
    - "kubectl get pods"

若命令不在白名单（如 rm -rf），即使指定 host: gateway 也会被拒绝。

执行环境加固

工作目录限制：仅允许在 allowedPaths 下操作

allowedPaths:
  - "/home/user/projects"
  - "/opt/openclaw/data"

PATH 注入：仅包含安全命令（/usr/bin:/bin，排除 /usr/local/bin）

环境变量清理：移除 SSH_AUTH_SOCK、AWS_SECRET_ACCESS_KEY 等敏感变量

用户审批流程

1. AI 生成 tool_call: bash_exec(cmd="npm run deploy")
2. 网关检测到需 elevated 权限
3. 通过 WhatsApp/Telegram 发送确认卡片： “AI 请求执行：npm run deploy 路径：/home/user/my-app 确认 拒绝”
4. 用户点击“确认”后，命令才执行

人类是最后一道防线。

五、第三层：远程节点（Remote Node）—— 企业级扩展

在多服务器环境中，命令可能需在特定机器执行（如“在 staging 服务器上重启服务”）。

架构

• OpenClaw 网关作为调度中心
• 远程机器运行轻量 openclaw-agent 守护进程
• 通过 mTLS 加密通道通信

配置示例

remoteNodes:
  staging:
    host: "10.0.1.100"
    user: "deployer"
    allowedCommands: ["systemctl restart app"]
  prod-db:
    host: "10.0.2.200"
    user: "dbadmin"
    allowedCommands: ["pg_dump --dbname=mydb"]

安全保障

• 每个节点独立权限策略
• 命令在远程沙箱中执行（同样支持 L1/L2）
• 所有操作记录审计日志

适合：DevOps 自动化、跨环境部署等企业场景。

六、输入消毒与输出截断

即使在沙箱中，仍需防御命令构造漏洞。

输入消毒

所有参数经 shellEscape() 处理：

function shellEscape(str: string): string {
  if (/^[a-zA-Z0-9._/-]+$/g.test(str)) return str;
  throw new Error("Unsafe characters in parameter");
}

禁止 ;, |, &, $(), ` 等 shell 元字符

输出截断

• 标准输出 > 10KB 自动截断
• 二进制数据（如图片）被过滤，防止终端污染

不信任任何来自 LLM 的字符串。

七、三层模型对比总结

image

结语：安全不是功能开关，而是设计基底

exec.ts 的三层隔离模型，体现了 OpenClaw 对“AI 行动力”的审慎态度：

• 默认最安全（沙箱）
• 可控降级（白名单 + 审批）
• 可扩展（远程节点）

它不阻止 AI 做事，而是确保每一步都在人类知情与授权下进行。

在下一篇中，我们将继续深入 exec.ts 的下半部分，解析后台任务管理、权限提升控制与实时交互机制。

下一篇预告： 第 11 篇：exec.ts 下篇 —— 用户审批、后台任务与权限提升控制