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 执行命令的风险矩阵

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

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

二、三层隔离模型总览

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

用户可通过 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 的字符串。

七、三层模型对比总结

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

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

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

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

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

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

您的 AI 助手，从此由您定义。若感兴趣可以浏览本书其他章节内容：

第 1 篇：OpenClaw 是什么？—— 工业级 AI 智能体网关的定位与愿景

第 2 篇：三位一体架构详解 —— 网关层、协议层、智能体系如何协同工作

第 3 篇：ACP 协议设计哲学 —— 为什么 OpenClaw 选择自研 Agent Client Protocol

第 4 篇：启动与配置体系 —— openclaw.mjs、config.yaml 与环境变量管理

第 5 篇：run.ts 上篇 —— 模型调度、账号轮询与上下文守护机制

第 6 篇：run.ts 下篇 —— 故障转移、重试策略与结果封装

第 7 篇：记忆系统基石 —— memory-search.ts 中的 RAG 配置解析与合并逻辑

第 8 篇：向量检索实战 —— OpenClaw 如何实现混合搜索（向量 + 全文）

第 9 篇：长期记忆与会话同步 —— 如何让 AI “记住”跨天对话

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

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

第 12 篇：process.ts —— AI 如何像开发者一样管理后台进程

第 13 篇：安全边界设计 —— OpenClaw 如何防范 AI 滥用系统权限

第 14 篇：server-channels.ts —— 渠道插件生命周期管理器

第 15 篇：WhatsApp 深度集成 —— session.ts 与 Baileys 的健壮连接管理

第 16 篇：消息流入中枢 —— monitor-inbox.ts 如何解析、去重与防抖

第 17 篇：聊天 RPC 接口 —— chat.ts 中的历史查询、发送与中止逻辑

第 18 篇：Skills System —— 为什么“文档即工具”是 OpenClaw 的扩展灵魂

第 19 篇：可观测性工程 —— ws-log.ts 如何让 WebSocket 日志可读可用

第 20 篇：从零部署 OpenClaw —— 实战：接入 WhatsApp + 创建自定义 Skill