OpenClaw 技术栈与安全管控能力调研

时间：2026-04-15
作用域：梳理 OpenClaw（开源 AI 助手 / Agent 平台）当前的技术实现栈，以及围绕它可以落地的安全管控点，供安全团队评估部署与加固方向。

一、OpenClaw 简介

OpenClaw 是一款开源、自托管、跨平台的个人 AI 助手 / Agent 平台，MIT 协议，支持 200+ LLM 后端（Claude / GPT / Gemini / Llama / Mistral 等）。其核心定位是"单用户、本地优先"——所有凭证与会话都在本机 ~/.openclaw/ 下，而不是集中式多租户 SaaS。这一点直接决定了它的威胁模型：一个 Gateway = 一位受信任操作员，官方明确声明它不是一个面向相互敌对多租户的隔离边界。

二、技术栈总览

2.1 运行时与语言

2.2 进程与架构

OpenClaw 不做微服务，而是以一个常驻的 Node.js Gateway 进程承载 5 个子系统：

1. Gateway — 控制面：会话、channel 路由、工具调度、事件总线，默认监听 127.0.0.1:18789，同时对外提供 Control UI 与 WebChat。
2. Channels — 消息入站/出站适配，官方已支持 50+ 渠道：WhatsApp、Telegram、Slack、Discord、Signal、iMessage、Matrix、Google Chat、Microsoft Teams、Zalo 等。
3. Skills — 技能系统，每个 Skill 是一个带 SKILL.md 的目录（含元信息与调用指令），分三类：bundled（内置）/ managed（ClawHub 下发）/ workspace（本地）。
4. Plugins — 可注册 Tool、HTTP 路由、Gateway RPC、后台服务，官方通过 allowlist 控制。
5. Hooks — 事件驱动钩子（见 Hooks 专题），监听命令 / 会话 / 生命周期 / 消息等 13 个事件。

2.3 存储与配置

• Agent 由 Markdown 配置文件定义（身份、记忆、权限）。
• 会话与历史以 JSONL 存储在本机 ~/.openclaw/agents/<agentId>/sessions/*.jsonl。
• 凭证存在 ~/.openclaw/credentials/<channel>/…，明文（官方承认这是已知取舍）。
• 推荐 ~/.openclaw/ 权限 700，openclaw.json 权限 600。

2.4 对外协议与互通

• WebSocket：Gateway ↔ 本地 / 远端客户端。
• MCP：openclaw mcp serve 启动一个 stdio MCP server，让 Claude / 其他 MCP 客户端接入；同时也有社区实现的 openclaw-mcp-bridge，反向把任意 MCP server 注册成 OpenClaw 的 Tool。
• ClawHub：公开的 Skill 市场，3500+ Skill，只要一周龄的 GitHub 账号即可投递（供应链风险点）。

2.5 一张图

┌──────────────────────── Gateway (Node.js, :18789) ─────────────────────┐
│                                                                        │
│   ┌───────────┐    ┌─────────┐    ┌───────┐    ┌────────┐   ┌────────┐ │
│   │ Channels  │ -> │ Session │ -> │ LLM   │ -> │ Tools  │ - │ Hooks  │ │
│   │ 50+ IM    │    │ Router  │    │ 200+  │    │ /Skills│   │ Events │ │
│   └───────────┘    └─────────┘    └───────┘    └────────┘   └────────┘ │
│         ▲                ▲             ▲           ▲             │     │
│         │ Pairing/DM     │ dmScope     │ profile   │ sandbox     │     │
│         │ Allowlist      │ isolation   │ allow/deny│ Docker      │     │
│         └─── Control UI / WebChat ──── MCP stdio ──┴── Plugins ──┘     │
└────────────────────────────────────────────────────────────────────────┘
                            ▲
                            │  ~/.openclaw/  (明文凭证 + JSONL 会话)

三、官方已提供的安全管控原语

OpenClaw 把安全做成了"多层闸门"的组合，调研它能在内部做的管控，本质就是看这些原语是否够用、能否被 Hooks/Plugin 扩展。

3.1 Gateway 认证与暴露面

3.2 DM 接入策略（对抗 Prompt Injection 的第一道闸）

CLI：openclaw pairing list <channel> / openclaw pairing approve <channel> <code>。

3.3 会话隔离

session.dmScope：

• main（默认）— 所有 DM 共享一个 session（易串号）；
• per-peer — 按发送者隔离；
• per-channel-peer — 按 channel+sender 隔离（推荐）；
• per-account-channel-peer — 多账号变体。

3.4 工具策略与执行审批

{
  "tools": {
    "profile": "messaging",                 // 预置画像
    "deny": [
      "group:automation", "group:runtime", "group:fs",
      "sessions_spawn", "sessions_send"
    ],
    "fs":   { "workspaceOnly": true },
    "exec": {
      "security": "deny",                   // full / moderate / deny
      "ask":      "always",                 // always / off
      "applyPatch": { "workspaceOnly": true },
      "strictInlineEval": true,             // 内联求值强制再审批
      "safeBins": ["ls","cat","rg"]
    }
  }
}

关键点：

• security: full = 受信操作员模型，等于给 Agent 主机 root 等价权限；
• moderate = 执行前审批，且审批绑定具体请求上下文 + 直接文件操作数，避免被"重放"；
• 审批粒度足够精细，适合做分级授权。

3.5 沙箱（Docker）

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all",                 // non-main / all
        "scope": "agent",
        "workspaceAccess": "ro",        // none / ro / rw
        "network": "none"               // 默认 none
      }
    }
  }
}

硬性禁止的"危险开关"（被 security audit 列为 critical）：

• dangerouslyAllowContainerNamespaceJoin
• dangerouslyAllowReservedContainerTargets
• dangerouslyAllowExternalBindSources
• 低强度 seccomp / AppArmor profile
• 相对路径 / 符号链接穿越 / 绑定 /etc /var/run /sys 等敏感目录

3.6 浏览器 SSRF 策略

{
  "browser": {
    "ssrfPolicy": {
      "dangerouslyAllowPrivateNetwork": false,
      "hostnameAllowlist": ["*.example.com"],
      "allowedHostnames": ["localhost"]
    }
  }
}

官方警告：浏览器内登录态 = 完整账号权限，建议独立 profile。

3.7 插件与供应链

{
  "plugins": {
    "allowlist": ["@scope/plugin-id@1.2.3"]
  }
}

• 安装时自动做 dangerous-code 扫描，critical 默认拒绝；
• npm lifecycle script 会执行（安装即代码执行，这是供应链高危点）；
• 校验 npm pack hash、符号链接逃逸；
• Skill 层有 ClawHub + VirusTotal 扫描，但投递门槛仅"一周龄 GitHub 账号"。

3.8 日志与脱敏

{
  "logging": {
    "redactSensitive": "tools",
    "redactPatterns": [
      "api_key: [\\w-]+",
      "token: \\w{20,}"
    ]
  }
}

默认会脱敏 tool 参数，支持自定义正则；但会话 transcript 是明文 JSONL——磁盘访问即信任边界。

3.9 安全审计命令

openclaw security audit           # 基础检查
openclaw security audit --deep    # 活探针 + 扩展分析
openclaw security audit --fix     # 自动修复：权限 / 日志 / 白名单
openclaw security audit --json    # 机读输出（可接 CI）

高优先级检出项：

四、安全能在 OpenClaw 里落地的管控点清单

下表把"能做什么"映射到具体的扩展位置，方便评估哪些靠官方配置即可、哪些需要 Plugin/Hooks 扩展、哪些需要外部系统联动。

4.1 Hooks 作为安全切面的价值

OpenClaw 的 Hook 事件覆盖面非常完整：

• 命令域：command:new / reset / stop / command
• 会话域：session:compact:before / after, session:patch
• 消息域：message:received / transcribed / preprocessed / sent
• 生命周期：agent:bootstrap, gateway:startup

这意味着无需 fork 源码，就可以通过一个 TypeScript handler.ts 文件实现：

1. 输入过滤（message:received）
2. 输出 DLP（message:sent）
3. 命令行风控（command:new）
4. 会话合规归档（session:compact:before）
5. 启动基线检查（gateway:startup 上触发 security audit）

这是在不动 Gateway 主干的前提下，安全团队能拿到的最大空间。

4.2 剩余高风险项（Hook 解决不了的）

1. 凭证明文：~/.openclaw/ 仍是主要取舍点，需要系统层补位（磁盘加密 / keychain 代理 / LUKS）。
2. Skill 供应链：ClawHub 门槛低 + npm lifecycle script = 典型"安装即 RCE"场景，plugins.allowlist 是唯一硬闸，强烈建议打开。
3. 浏览器登录态：一旦授权，泄漏即等同于账号被盗，Hook 无法追溯，只能用"专用独立 profile + 独立用户态"的物理隔离。
4. exec.security = full 的默认"受信模式"：一旦开放到非本地暴露面，Prompt Injection → 主机 RCE 是最短路径。建议在任何非本地部署里强制 moderate 起步。

五、一份 60 秒安全基线（摘自官方并增补）

{
  "gateway": {
    "mode": "local",
    "bind": "loopback",
    "auth": { "mode": "token", "token": "long-random-token" },
    "tailscale": { "mode": "off" }
  },
  "discovery": { "mdns": { "mode": "minimal" } },
  "session":   { "dmScope": "per-channel-peer" },
  "tools": {
    "profile": "messaging",
    "deny": [
      "group:automation", "group:runtime", "group:fs",
      "sessions_spawn", "sessions_send"
    ],
    "fs":   { "workspaceOnly": true },
    "exec": { "security": "deny", "ask": "always",
              "applyPatch": { "workspaceOnly": true },
              "strictInlineEval": true }
  },
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all", "scope": "agent",
        "workspaceAccess": "ro", "network": "none"
      }
    }
  },
  "browser": {
    "ssrfPolicy": { "dangerouslyAllowPrivateNetwork": false }
  },
  "plugins": { "allowlist": [/* 明确枚举 */] },
  "logging": { "redactSensitive": "tools" },
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing",
      "groups": { "*": { "requireMention": true } }
    }
  }
}

加上一条定时任务：

openclaw security audit --deep --json > /var/log/openclaw-audit-$(date +%F).json

六、结论

1. 技术栈很"朴素"：Node.js 单进程 Gateway + Markdown/JSON/JSONL 本地存储 + 50+ Channel 适配 + 插件化 Skill/MCP/Plugin。优点是轻量、可审计、易部署；缺点是凭证明文与供应链敞口。
2. 安全能力已经形成纵深：Auth / DM pairing / 会话隔离 / 工具白名单 / 执行审批 / Docker 沙箱 / SSRF / 插件 allowlist / 日志脱敏 / 安全审计一条龙，对"单用户受信模型"而言够用。
3. 真正能被安全团队放大的扩展点是 Hook + Plugin：事件面完整、注册方式简单，能把 OpenClaw 当作一个可观测、可拦截的 Agent 运行时对待——日志外发、输入扫描、出站 DLP、命令行风控、外部审批联动都可以在不 fork 源码的前提下落地。
4. 高风险仍需系统层补位：凭证明文、ClawHub 供应链、浏览器登录态、exec.security=full 默认，这四项是 OpenClaw 自身配置解决不了的，需要磁盘加密、主机隔离、组织级 allowlist、部署形态约束共同兜底。

七、参考资料

• OpenClaw 官方文档 — Security
• OpenClaw 官方文档 — Hooks
• OpenClaw 官方文档 — MCP CLI
• OpenClaw 2026 架构与部署指南 — Valletta
• GitHub: openclaw/openclaw
• GitHub: freema/openclaw-mcp
• GitHub: AIWerk/openclaw-mcp-bridge
• Snyk Labs — Escaping the Agent: Bypassing OpenClaw's Sandbox
• Nebius — OpenClaw security architecture & hardening
• Auth0 — Securing OpenClaw: A Developer's Guide
• DigitalOcean — What is OpenClaw