万字解析 OpenClaw 源码架构-安全与权限

引言

本文件系统化阐述 OpenClaw 的安全模型与设计原则，覆盖整体安全架构、信任模型、威胁建模、风险评估、安全边界与攻击面、安全审计与修复、异常检测与入侵防护、安全配置基线、合规与度量指标，以及安全测试方法。目标读者为安全架构师与系统设计人员。

项目结构

OpenClaw 将安全能力贯穿于“网关认证与访问控制”“会话隔离”“工具执行沙箱”“外部内容处理”“安全审计与修复”等模块，并通过 CLI 提供统一的安全运维入口。下图展示与安全相关的核心目录与文件：

graph TB
subgraph "安全文档"
D1["docs/security/README.md"]
D2["docs/security/THREAT-MODEL-ATLAS.md"]
D3["docs/security/CONTRIBUTING-THREAT-MODEL.md"]
D4["docs/cli/security.md"]
end
subgraph "安全策略与政策"
P1["SECURITY.md"]
end
subgraph "运行时安全"
R1["src/gateway/auth.ts"]
R2["src/security/external-content.ts"]
R3["src/agents/sandbox/tool-policy.ts"]
end
subgraph "安全审计与修复"
A1["src/security/audit.ts"]
A2["src/security/fix.ts"]
end
D1 --> D2
D2 --> R1
D2 --> R2
D2 --> R3
D4 --> A1
A1 --> A2
P1 --> D1

核心组件

• 网关认证与访问控制：负责身份鉴别、速率限制、代理信任与设备令牌登录（在受控界面场景启用）。
• 外部内容处理：对外部输入进行标记、警告与清洗，防止提示注入与边界逃逸。
• 工具策略与沙箱：基于允许/拒绝列表与组规则对工具调用进行强约束，保障最小权限与路径安全。
• 安全审计与修复：提供可操作的配置检查、权限加固与自动修复建议，支持 JSON 输出以适配 CI/CD。

架构总览

OpenClaw 的安全架构以“个人助理”信任模型为核心，默认假设单个操作者（用户）可信，多用户共享同一网关实例不在推荐范围。系统通过以下信任边界与控制平面实现纵深防御：

• 边界一：渠道接入（AllowFrom/白名单、配对期保护）
• 边界二：会话隔离（会话键路由、工具策略）
• 边界三：执行沙箱（容器或主机执行、命令审批）
• 边界四：外部内容（抓取/邮件/Webhook 包装与警告）
• 边界五：供应链（ClawHub 技能发布与审核）

graph TB
U["未受信区域<br/>渠道/外部源"] --> B1["边界一：渠道接入<br/>AllowFrom/配对保护"]
B1 --> B2["边界二：会话隔离<br/>会话键/工具策略"]
B2 --> B3["边界三：执行沙箱<br/>容器/主机+命令审批"]
B3 --> B4["边界四：外部内容<br/>包装/警告/模式检测"]
B4 --> B5["边界五：供应链<br/>ClawHub 审核/扫描"]

详细组件分析

组件一：网关认证与访问控制

• 身份模式：支持 token、密码、受信代理转发与 Tailscale 设备令牌；默认优先使用 token 模式。
• 速率限制：可按共享密钥作用域进行失败计数与锁定，缓解暴力破解。
• 受信代理：严格校验代理地址、必要头字段与用户头，支持白名单用户。
• 设备令牌登录：仅在受控界面（WS 控制 UI）场景启用，避免跨网络滥用。
• 防护要点：禁止 loopback 绑定但无认证；严格 Origin 白名单；禁用危险的 Host 头回退；mDNS 全量模式泄露元数据。

sequenceDiagram
participant C as "客户端"
participant GW as "网关"
participant RL as "速率限制器"
participant TS as "Tailscale Whois"
C->>GW : 建立连接/握手
GW->>RL : 查询当前IP是否受限
RL-->>GW : 允许/拒绝并返回重试时间
alt 受信代理模式
GW->>GW : 校验代理地址与必要头
GW-->>C : 返回用户身份或拒绝
else 设备令牌登录
GW->>TS : 校验设备令牌来源与身份
TS-->>GW : 返回身份信息
GW-->>C : 认证成功
else 密码/token
GW-->>C : 要求凭据
C-->>GW : 提交凭据
GW->>RL : 记录失败/重置
GW-->>C : 认证结果
end

组件二：外部内容处理与提示注入防护

• 标记与警告：对外部内容插入唯一边界标记与安全警告，明确不可作为系统指令。
• 模式检测：识别可疑提示注入模式，用于监控与告警。
• 标记清洗：对可能伪造的边界标记进行清洗，降低逃逸风险。
• 包装策略：针对邮件、Webhook、Web 搜索/抓取等不同来源提供统一包装接口。

flowchart TD
Start(["接收外部内容"]) --> Detect["检测可疑模式"]
Detect --> Warn{"是否触发警告?"}
Warn --> |是| Log["记录可疑模式"]
Warn --> |否| Wrap["生成唯一ID并插入边界标记"]
Log --> Sanitize["清洗潜在边界标记"]
Wrap --> Sanitize
Sanitize --> Output["输出带警告与边界的包装内容"]

组件三：工具策略与沙箱

• 策略解析：支持按代理与全局维度合并允许/拒绝列表，展开工具组，形成最终策略。
• 默认策略：未显式允许时视为允许（空允许列表），但会注入必要的基础工具（如图像处理）以满足多模态工作流。
• 沙箱边界：结合容器/主机执行与命令审批，确保工具调用在最小权限范围内执行。

flowchart TD
A["加载代理/全局工具策略"] --> B["展开工具组"]
B --> C["编译拒绝/允许正则"]
C --> D{"工具名匹配拒绝?"}
D --> |是| Deny["拒绝"]
D --> |否| E{"允许列表为空?"}
E --> |是| Allow["允许"]
E --> |否| F{"匹配允许?"}
F --> |是| Allow
F --> |否| Deny

组件四：安全审计与修复

• 审计范围：文件系统权限、网关绑定与认证、受信代理、mDNS 模式、浏览器控制端点、插件与技能安全、Docker 沙箱设置、钩子与会话键覆盖、危险配置标志等。
• 修复能力：自动收紧权限（chmod/ACL）、将通用组策略从开放改为白名单、调整敏感日志脱敏级别、写回安全配置变更。
• 输出格式：支持人类可读报告与 JSON，便于 CI/CD 集成与自动化治理。

sequenceDiagram
participant CLI as "openclaw security"
participant AUD as "审计器"
participant FIX as "修复器"
participant FS as "文件系统/配置"
CLI->>AUD : 运行安全审计
AUD-->>CLI : 生成发现项与严重级别
CLI->>FIX : 请求修复 (--fix)
FIX->>FS : 修改权限/更新配置
FIX-->>CLI : 返回修复动作与结果

依赖关系分析

• 文档层：安全文档与威胁模型指导实现层的设计与落地。
• 实现层：认证模块依赖速率限制与代理信任配置；外部内容模块为所有外部输入提供统一包装；工具策略模块为执行层提供最小权限约束；审计与修复模块贯穿部署与运维生命周期。
• 外部依赖：Node.js 版本安全补丁、Docker 安全运行参数（只读文件系统、丢弃多余能力）。

graph LR
TM["威胁模型<br/>THREAT-MODEL-ATLAS.md"] --> AUTH["认证模块<br/>auth.ts"]
TM --> EXT["外部内容<br/>external-content.ts"]
TM --> TOOL["工具策略<br/>tool-policy.ts"]
CLI["CLI 安全命令<br/>docs/cli/security.md"] --> AUD["审计器<br/>audit.ts"]
AUD --> FIX["修复器<br/>fix.ts"]
AUTH --> AUD
EXT --> AUD
TOOL --> AUD

性能考量

• 审计与修复：采用增量检查与缓存（如代码安全性摘要缓存）减少重复开销；权限修复按需执行，避免不必要的文件系统写入。
• 认证与速率限制：基于 IP 作用域的轻量级状态存储，避免阻塞式同步锁；Tailscale 设备令牌校验仅在受控界面启用。
• 外部内容包装：边界标记与模式检测为常量时间复杂度；内容清洗按出现次数线性处理，整体开销可控。
• 工具策略：策略编译与匹配采用预编译正则与通配符展开，匹配阶段为线性扫描，适合高频调用场景。

故障排查指南

• 审计与修复
  • 使用 JSON 输出在 CI 中定位高危发现项，结合严重级别筛选关键问题。
  • 对于权限修复失败，检查符号链接、缺失文件与平台差异（Windows ACL）。
  • 对于配置写回失败，确认配置文件存在性与解析快照有效性。
• 认证与访问控制
  • 若 loopback 绑定但无认证导致访问异常，检查网关 token 或密码配置。
  • 受信代理模式下，确认代理地址、必要头与用户头配置正确。
  • 浏览器控制端点无认证时，启用网关认证并重启以自动生成 token。
• 外部内容
  • 若提示注入告警频繁，检查外部来源是否包含边界标记或可疑模式文本。
  • 包装后内容仍被误判，可在调用侧关闭详细警告以减少噪声。
• 工具策略
  • 工具调用被拒绝时，检查代理/全局允许/拒绝列表与工具组展开结果。
  • 图像处理等基础工具未生效，确认未被显式拒绝且允许列表非空。

安全设计原则

• 最小权限：工具与会话默认拒绝，除非显式允许。
• 信任模型：单操作者可信，多用户共享不推荐；严格边界隔离。
• 输入不可信：外部内容一律包装与警告，提示注入检测仅作监控。
• 可观测与可修复：审计与修复自动化，JSON 输出便于集成。

威胁缓解策略

• 直接/间接提示注入：包装与警告 + 模式检测 + 命令审批。
• 供应链攻击：ClawHub 审核与扫描（逐步完善）。
• 执行绕过：工具策略 + 沙箱 + 命令审批。
• 外部内容逃逸：多层边界标记 + 清洗 + 安全警告。

安全配置基线

• 网关
  • 绑定：优先 loopback；若非 loopback，必须配置认证与速率限制。
  • 受信代理：严格配置代理地址、必要头与用户白名单。
  • mDNS：优先 minimal/off，避免元数据泄露。
  • 控制界面：Origin 白名单必填；禁用危险 Host 头回退。
• 文件系统
  • 状态目录与配置文件权限收紧至 700/600；凭证目录与会话文件同权限。
  • 插件/钩子安装记录应固定版本与完整性校验。
• 沙箱
  • Docker：只读文件系统、丢弃多余能力；避免 host/容器命名空间共享。
  • 浏览器沙箱：桥接网络需限定来源范围；容器标签一致性校验。
• 外部内容
  • 启用敏感日志脱敏；对 web_fetch 与外部来源实施 URL 白名单与内容包装。

合规与度量指标

• 合规要求
  • Node.js 版本满足安全补丁要求。
  • Docker 运行参数符合最小暴露面原则。
  • 审计与修复流程纳入 CI/CD。
• 度量指标
  • 审计发现数量与严重级别分布（critical/warn/info）。
  • 权限修复成功率与失败原因统计。
  • 提示注入告警频率与模式检测命中率。
  • 工具调用拒绝率与误报率。

安全审计

安全审计体系由“审计引擎 + 报告输出 + 日志与可观测性”三部分构成：

• 审计引擎：集中于 src/security 下，按同步/异步职责拆分，统一汇聚为报告对象。
• 报告输出：CLI 命令 status 中集成安全审计结果展示；支持 JSON 输出用于自动化集成。
• 日志与可观测性：文档化日志位置、格式、级别与导出；提供诊断事件目录与 OTLP 导出能力。

graph TB
subgraph "审计引擎"
A["audit.ts<br/>主审计器"]
B["audit-extra.sync.ts<br/>同步审计收集器"]
C["audit-extra.async.ts<br/>异步审计收集器"]
end
subgraph "报告与CLI"
D["status.command.ts<br/>状态命令集成审计"]
end
subgraph "日志与可观测性"
E["docs/logging.md<br/>日志与导出指南"]
F["src/logging.ts<br/>日志模块入口"]
end
A --> B
A --> C
D --> A
D --> E
E --> F

核心组件

• 审计主控制器
  • 统一选项与上下文构建，汇总各类审计收集器结果，生成带严重性统计的报告对象。
  • 关键类型：SecurityAuditOptions、SecurityAuditReport、SecurityAuditFinding。
• 同步审计收集器
  • 基于配置的静态分析，不涉及 I/O，覆盖攻击面概览、钩子加固、网关 HTTP 无认证、沙箱策略、插件安装与完整性、模型与工具策略等。
• 异步审计收集器
  • 执行文件系统与外部状态检查，如状态目录与配置文件权限、日志文件可读性、扩展插件安装版本漂移、容器端口发布范围、浏览器沙箱标签一致性等。
• 报告与 CLI 集成
  • status 命令运行审计并以人类可读方式输出摘要与修复建议；支持 JSON 输出便于自动化处理。
• 日志与可观测性
  • 文档化文件日志位置、级别、控制台样式、敏感信息脱敏策略；提供诊断事件目录与 OTLP 导出配置。

架构总览

下图展示从 CLI 到审计引擎再到日志系统的调用链路与数据流。

sequenceDiagram
participant CLI as "CLI/用户"
participant Status as "status.command.ts"
participant Audit as "audit.ts 主审计器"
participant Sync as "audit-extra.sync.ts"
participant Async as "audit-extra.async.ts"
participant Logs as "docs/logging.md + src/logging.ts"
CLI->>Status : 执行 openclaw status
Status->>Audit : runSecurityAudit(options)
Audit->>Sync : 调用同步收集器
Audit->>Async : 调用异步收集器
Audit-->>Status : 返回 SecurityAuditReport
Status->>Status : 格式化摘要与修复建议
Status-->>CLI : 输出人类可读/JSON 报告
Status->>Logs : 参考日志配置与导出

详细组件分析

审计主控制器（audit.ts）

• 职责
  • 解析与标准化审计选项，构建执行上下文。
  • 调用同步/异步收集器，合并结果，统计严重性。
  • 可选深探针（deep），对网关可达性与握手进行探测。
• 关键点
  • 通过选项注入测试依赖（execIcacls、execDockerRawFn、probeGatewayFn 等）。
  • 支持预加载配置快照以减少审计时文件读取。
  • 严格区分“文件系统检查”“通道安全检查”“深探针”等维度。

flowchart TD
Start(["进入 runSecurityAudit"]) --> Ctx["构建执行上下文<br/>解析选项/环境/平台"]
Ctx --> Collect["调用同步/异步收集器"]
Collect --> Merge["合并发现项并统计严重性"]
Merge --> Deep{"是否启用 deep 探针？"}
Deep --> |是| Probe["探测网关可达性/握手"]
Deep --> |否| Report["生成报告"]
Probe --> Report
Report --> End(["返回 SecurityAuditReport"])

同步审计收集器（audit-extra.sync.ts）

• 攻击面概览与策略
  • 汇总各通道组策略、工具提升权限、钩子开关、浏览器控制等，形成“攻击面摘要”。
• 钩子加固
  • 检查 hooks.token 是否过短、是否与网关令牌重复、默认会话键是否配置、请求级会话键前缀限制等。
• 网关 HTTP 无认证
  • 当 auth.mode 为 none 且存在启用的 HTTP 端点时，给出严重性提示。
• 沙箱与容器
  • 检查 agents.defaults.sandbox.docker 配置与模式不一致、容器端口发布范围、标签哈希一致性等。
• 插件与安装
  • 检查 plugins.allow 是否缺失、npm 安装规范是否固定、完整性元数据是否存在、版本漂移等。
• 工具策略与模型
  • 分析工具策略、模型选择与回退、小模型风险、最小化配置覆盖等。

异步审计收集器（audit-extra.async.ts）

• 文件系统与状态
  • 检查 stateDir、configPath、auth-profiles.json、sessions.json、日志文件等路径权限与可读性。
• 浏览器沙箱容器
  • 列举并检查沙箱浏览器容器的 configHash 标签、epoch 标签、端口发布范围。
• 插件与安装（续）
  • 读取已安装插件目录、解析允许列表、校验 npm 规范与完整性、版本漂移。
• 代码安全扫描摘要缓存
  • 对工作区技能文件扫描结果进行缓存，降低重复审计成本。

报告与 CLI 集成（status.command.ts）

• 在 status 命令中运行审计，输出摘要与修复建议；支持 JSON 输出。
• 对“重要发现”（critical/warn）进行排序与截断显示，便于快速定位。

日志与可观测性（docs/logging.md + src/logging.ts）

• 日志位置与格式
  • 默认滚动文件日志（JSON Lines），CLI 与 Control UI 实时尾随。
  • 控制台输出支持 pretty/compact/json 三种风格，受 logging.consoleStyle 控制。
• 敏感信息脱敏
  • logging.redactSensitive 控制控制台输出脱敏级别；不影响文件日志。
• 诊断事件与 OTLP 导出
  • 提供模型使用、消息流转、队列与会话等诊断事件目录。
  • 通过 diagnostics-otel 插件导出至任意 OTLP/HTTP 收集器，支持采样与刷新间隔配置。

安全策略与合规要求（SECURITY.md）

• 报告流程与接受标准
  • 明确漏洞报告所需要素、快速通道要求、常见误报场景与范围界定。
• 运营商信任模型
  • 强调“个人助理”信任边界，明确会话键不是多租户授权边界。
• 远程暴露与加固
  • 网关控制 UI 应本地使用；非本地部署需强认证与防火墙/隧道控制。
• 运行时要求与 Docker 安全
  • Node.js 版本安全基线；Docker 运行建议（只读、丢弃能力等）。

审计策略配置与最佳实践

• 审计范围
  • includeFilesystem/includeChannelSecurity/deep 等选项决定审计粒度与深度。
• 修复建议
  • 使用 openclaw security audit --fix 自动收紧权限与策略（如 groupPolicy、logging.redactSensitive、文件权限）。
• 通道安全
  • 文档化常见通道安全问题与缓解措施，结合审计结果进行优先级排序。

依赖关系分析

• 组件耦合
  • audit.ts 作为编排器，依赖同步/异步收集器与文件系统/网络探测能力。
  • status.command.ts 仅负责调用与展示，不直接参与审计逻辑，保持低耦合。
• 外部依赖
  • 日志系统通过 docs/logging.md 与 src/logging.ts 提供统一入口。
  • OTLP 导出依赖 diagnostics-otel 插件与第三方收集器。

graph LR
Status["status.command.ts"] --> Audit["audit.ts"]
Audit --> Sync["audit-extra.sync.ts"]
Audit --> Async["audit-extra.async.ts"]
Status --> Docs["docs/logging.md"]
Docs --> Impl["src/logging.ts"]

性能考量

• 缓存与去重
  • 异步收集器对代码安全扫描摘要使用 Map 缓存，避免重复计算。
• I/O 优化
  • 通过 configSnapshot 预加载配置，减少审计时文件读取。
• 深探针超时
  • deepTimeoutMs 可控，默认约 5 秒，避免阻塞 CLI。
• 日志级别与导出
  • 通过 logging.level 与 diagnostics.otel.sampleRate 控制日志体积与导出压力。

故障排查指南

• 审计未发现问题但怀疑配置不当
  • 使用 --deep 启用深探针，检查网关可达性与握手；关注 critical/warn 发现项。
• 日志为空或不可达
  • 使用 openclaw doctor 排查；确认 logging.file 指向正确路径；必要时提高 logging.level。
• 控制 UI 或远程访问异常
  • 结合 SECURITY.md 的远程暴露与加固建议，确保 gateway.bind 与 auth 配置符合信任模型。
• 插件/钩子安全风险
  • 检查 plugins.allow、npm 规范与完整性、hooks.token 独立性与长度；避免与网关令牌重复。

审计数据保护与隐私考虑

• 敏感信息脱敏
  • 控制台输出可通过 logging.redactSensitive 脱敏；文件日志默认保留原始内容。
• 日志导出与 OTLP
  • OTLP 导出遵循 file log 级别，控制台脱敏不适用于导出日志。
• 通道与会话边界
  • 会话键仅路由控制，非多租户授权边界；跨用户隔离需通过 OS 用户/主机/网关分离实现。

安全与权限

围绕“安全与权限”的关键目录与文件：

• 文档层：安全策略、威胁模型、CLI 安全审计参考
• 核心实现层：网关认证、外部内容包装、安全审计与修复、危险配置检测

graph TB
A["安全策略<br/>SECURITY.md"] --> B["威胁模型<br/>docs/security/THREAT-MODEL-ATLAS.md"]
B --> C["CLI 安全审计参考<br/>docs/cli/security.md"]
D["安全审计实现<br/>src/security/audit.ts"] --> E["安全修复实现<br/>src/security/fix.ts"]
F["危险配置检测<br/>src/security/dangerous-config-flags.ts"] --> D
G["外部内容包装<br/>src/security/external-content.ts"] --> D
H["网关认证<br/>src/gateway/auth.ts"] --> D

核心组件

• 信任模型与边界
  • 个人助理模型（单受信任操作者）与多用户共享边界不被当作多租户隔离边界；会话标识为路由控制而非授权边界。
  • 插件作为可信计算基的一部分，安装即授予与本地主机同等的信任级别。
• 认证与授权
  • 网关支持令牌/密码/受信代理模式；可选 Tailscale 身份验证；HTTP 工具调用默认对危险工具进行限制。
• 外部内容处理
  • 统一封装与安全提示，避免将不受信内容直接作为系统指令或命令。
• 沙箱与工具执行
  • 默认以主机优先（可配置），工具策略与执行审批共同构成第二道防线；建议在多风险场景启用沙箱。
• 安全审计与修复
  • CLI 提供安全审计与可选修复能力，覆盖文件权限、暴露面、危险标志、浏览器控制端点等。

架构总览

下图展示从通道到会话、工具执行、外部内容与供应链的跨边界信任与保护：

graph TB
U["未信任区域<br/>消息通道/外部服务"] --> GW["网关<br/>认证/路由"]
GW --> SESS["会话隔离<br/>会话键/工具策略"]
SESS --> TOOL["工具执行<br/>策略/审批/沙箱"]
TOOL --> EXT["外部内容<br/>包装/警告/标记"]
TOOL --> SUPPLY["供应链<br/>ClawHub/技能发布"]

详细组件分析

组件一：安全审计与修复（CLI）

• 功能要点
  • 审计：检查配置与状态目录权限、暴露面、危险标志、浏览器控制端点、钩子与工具策略、mDNS 元数据泄露、Docker 沙箱网络等。
  • 修复：自动收紧权限（状态目录、配置、凭据、会话日志）、将部分组策略从开放改为白名单、调整敏感信息脱敏级别。
• 关键行为
  • 对非 loopback 绑定且无认证的网关发出严重告警。
  • 对允许在 HTTP 上重新启用危险工具的行为发出严重告警。
  • 对危险标志（如禁用设备认证、Host Header 来源回退）进行汇总与提醒。
• 输出格式
  • 支持 JSON 输出，便于 CI/策略检查；结合 --fix 可输出修复动作与最终报告。

flowchart TD
Start(["开始审计"]) --> FS["检查文件系统权限"]
FS --> GW["检查网关配置与暴露面"]
GW --> BR["检查浏览器控制端点"]
BR --> HK["检查钩子与工具策略"]
HK --> DK["检查 Docker 沙箱与 mDNS"]
DK --> Flags["收集危险配置标志"]
Flags --> Report["生成报告/JSON"]
Report --> Fix{"是否启用 --fix?"}
Fix --> |是| Apply["应用修复动作"]
Fix --> |否| End(["结束"])
Apply --> End

组件二：网关认证与授权

• 模式与解析
  • 支持模式：无、令牌、密码、受信代理；默认令牌模式；可按环境变量与配置解析凭据。
  • 受信代理模式要求明确的用户头、允许用户列表与代理地址范围。
  • Tailscale 身份验证仅在特定场景启用，且需通过反向代理转发的头部校验。
• 授权流程
  • 首先判定受信代理/无认证/令牌/密码路径；失败时记录速率限制；成功后重置速率限制。
  • 对于非本地直连请求，可启用 Tailscale 身份校验。
• 安全注意
  • 非 loopback 绑定且无认证将被标记为高危；速率限制建议开启以抵御暴力破解。

sequenceDiagram
participant C as "客户端"
participant GW as "网关"
participant RL as "速率限制器"
participant TS as "Tailscale Whois"
C->>GW : 建立连接/握手
GW->>RL : 检查速率限制
alt 受信代理模式
GW->>GW : 校验代理与用户头
GW-->>C : 授权结果
else 令牌/密码模式
GW->>GW : 校验凭据
GW-->>C : 授权结果
else Tailscale 身份
GW->>TS : 查询身份
TS-->>GW : 返回身份
GW-->>C : 授权结果
end
RL-->>GW : 成功则重置，失败则记录

组件三：外部内容处理与提示

• 设计原则
  • 不将外部内容视为可信指令；统一使用随机 ID 的边界标记与安全提示文本包裹。
  • 对可能的注入模式进行检测与记录；对已知边界标记进行清洗，防止伪造。
• 使用场景
  • 邮件、Webhook、Web 搜索/抓取等外部输入在进入 LLM 前必须经过封装与上下文提示。
• 会话来源识别
  • 通过会话键前缀识别外部钩子来源（如 gmail/webhook），并据此决定是否包含更严格的警告。

flowchart TD
In(["接收外部内容"]) --> San["清洗边界标记"]
San --> Warn["附加安全提示与元数据"]
Warn --> Mark["生成唯一边界标记"]
Mark --> Out(["返回安全提示后的封装内容"])

组件四：威胁模型与关键风险

• MITRE ATLAS 框架下的威胁分类与风险矩阵
  • 关键威胁：直接/间接提示注入、工具参数注入、执行审批绕过、恶意技能发布、供应链更新投毒、配置篡改、内容包装逃逸、资源耗尽攻击等。
  • 关键攻击链：技能持久化→规避审核→凭据窃取；提示注入→审批绕过→远程命令执行；间接注入→外发数据。
• 建议与优先级
  • 立即（P0）：完善病毒扫描、技能沙箱、敏感动作输出校验；
  • 短期（P1）：速率限制、凭据加密、改进审批 UX 与 URL 白名单；
  • 中期（P2）：通道加密验证、配置完整性校验、更新签名与版本固定。

依赖关系分析

• 审计模块依赖
  • 配置解析与路径解析、网关认证解析、Docker 执行、浏览器配置解析、通道插件清单、Windows ACL 工具等。
• 危险配置检测
  • 从配置中扫描危险标志位，用于审计报告与修复建议。
• 外部内容模块
  • 与审计模块配合，确保外部输入在进入系统前被安全封装。

graph LR
Audit["audit.ts"] --> Auth["gateway/auth.ts"]
Audit --> Fix["fix.ts"]
Audit --> Flags["dangerous-config-flags.ts"]
Audit --> Ext["external-content.ts"]
Audit --> Paths["配置/路径解析"]
Audit --> Docker["Docker 执行"]
Audit --> Browser["浏览器配置"]
Audit --> Plugins["通道插件"]

性能考量

• 审计与修复
  • 文件系统权限检查、Docker 标签检查、Windows ACL 重置等操作可能涉及磁盘与进程调用，建议在 CI/自动化中合理缓存与批量化执行。
• 认证与授权
  • 速率限制器应避免对缺失凭据的请求计为失败尝试，减少误判与资源消耗。
• 外部内容处理
  • 标记清洗与正则匹配成本可控，但应避免对超大文本重复执行；可在上游做分块或采样。

凭证管理

凭证管理相关能力主要分布在以下模块：

• 配置与类型：定义SecretRef契约、默认提供者、解析与校验逻辑
• 网关凭据解析：统一处理本地/远程模式、环境变量优先级、显式覆盖与错误提示
• 凭据矩阵与表面：声明支持/不支持的凭据路径，指导配置与审计
• 文档与CLI：提供Secrets管理指南、命令参考与审计流程
• 认证语义：对令牌有效期、未解析引用等进行稳定语义定义

graph TB
subgraph "配置与类型"
T1["src/config/types.secrets.ts<br/>SecretRef契约/解析/默认提供者"]
M1["src/secrets/credential-matrix.ts<br/>凭据矩阵/排除项"]
end
subgraph "网关凭据解析"
C1["src/gateway/credentials.ts<br/>凭据来源/优先级/错误模型"]
P1["src/gateway/credential-precedence.parity.test.ts<br/>用例验证优先级一致性"]
end
subgraph "文档与CLI"
D1["docs/gateway/secrets.md<br/>Secrets管理指南"]
CLI["docs/cli/secrets.md<br/>CLI命令参考"]
SURF["docs/reference/secretref-credential-surface.md<br/>凭据表面清单"]
SEM["docs/auth-credential-semantics.md<br/>认证语义"]
end
subgraph "认证状态"
CS["src/agents/auth-profiles/credential-state.ts<br/>令牌有效期/可解析性评估"]
end
T1 --> C1
M1 --> D1
SURF --> D1
D1 --> CLI
C1 --> P1
CS --> D1
SEM --> CS

核心组件

• SecretRef契约与解析
  • 定义三类来源：环境变量(env)、文件(file)、执行(exec)，并提供默认提供者别名与校验规则
  • 支持从字符串模板或对象形式解析SecretRef，并在配置阶段进行合法性检查
• 运行时凭据解析与优先级
  • 统一处理本地/远程网关模式、显式覆盖、环境变量与配置文件优先级
  • 对不可解析的SecretRef抛出明确错误，避免“占位符”被误认为有效值
• 凭据矩阵与表面
  • 明确列出支持与不支持的凭据路径，指导配置与审计；排除运行时生成/轮换/会话类凭据
• CLI与审计工作流
  • 提供reload、audit、configure、apply四大命令，配合计划文件实现可审计的一次性变更
• 认证语义与有效期
  • 对令牌型凭据定义稳定的reason code（如缺失、过期、无效）与解析规则

架构总览

系统采用“只读外部SecretRef解析 + 运行时快照”的设计，确保：

• 解析在激活阶段一次性完成，热路径只读内存快照
• 启动/重载失败快速中止，避免部分激活导致的不一致
• 原子替换快照，失败保留上一次已知良好状态
• 仅对“有效表面”进行严格校验，非活跃面允许降级诊断

sequenceDiagram
participant Operator as "操作者"
participant CLI as "CLI(secrets)"
participant Gateway as "网关RPC"
participant Resolver as "Secret解析器"
participant Providers as "提供者(env/file/exec)"
Operator->>CLI : 执行 "secrets reload/audit/configure/apply"
CLI->>Gateway : 调用 secrets.reload 或触发重载
Gateway->>Resolver : 解析所有SecretRef(激活前)
Resolver->>Providers : 并发拉取(受并发/批次限制)
Providers-->>Resolver : 返回键值映射
Resolver-->>Gateway : 返回完整快照或错误
alt 成功
Gateway->>Gateway : 原子交换快照
Gateway-->>CLI : 返回成功(含警告计数)
else 失败
Gateway->>Gateway : 保持上次已知良好快照
Gateway-->>CLI : 返回错误(不含部分激活)
end

组件详解

SecretRef契约与解析

• 结构与默认提供者
  • SecretRef由三元组(source/provider/id)组成，支持env/file/exec三种来源
  • 默认提供者别名用于兼容旧格式与简化配置
• 字符串模板与对象解析
  • 支持从形如"${ENV_VAR}"的模板推导SecretRef
  • 对象形式要求字段齐全且满足正则约束
• 解析与断言
  • 在读取前断言SecretRef已解析；未解析时抛出带路径信息的错误
  • 对空字符串与残留占位符进行过滤，避免误判为有效值

flowchart TD
Start(["开始"]) --> Parse["解析输入(字符串/对象/模板)"]
Parse --> Coerce{"是否为合法SecretRef?"}
Coerce --> |否| Normalize["标准化字符串(去空白)"]
Normalize --> HasValue{"是否有非空值?"}
HasValue --> |否| AssertRef["断言: 必须已解析"]
HasValue --> |是| Done(["返回值"])
Coerce --> |是| Done

网关凭据解析与优先级

• 来源与优先级
  • 显式参数优先于配置与环境变量
  • 本地/远程模式下，token与password的优先顺序不同
  • 服务端网关运行时对token采用“配置优先”，其他路径采用“环境优先”
• 错误模型
  • 当SecretRef在当前命令路径不可用时，抛出明确错误并给出修复建议
  • 对残留占位符进行拒绝，防止“看起来像值”的文本被接受
• 兼容性
  • 保留对历史环境变量的支持，但探测/状态等路径忽略历史变量

sequenceDiagram
participant Cmd as "命令路径"
participant Cfg as "配置/默认"
participant Env as "环境变量"
participant Err as "错误模型"
Cmd->>Cfg : 读取显式参数/配置
Cmd->>Env : 读取OPENCLAW_*与历史变量
Cmd->>Cmd : 按优先级选择(token/password)
alt 任一SecretRef未解析
Cmd->>Err : 抛出不可用错误(含修复指引)
else 全部可用
Cmd-->>Cmd : 返回最终凭据
end

凭据矩阵与表面

• 支持范围
  • 明确列出可在openclaw.json与auth-profiles.json中使用SecretRef的目标路径
  • 包括模型提供商apiKey、工具搜索key、网关认证与远端凭据、各渠道令牌/密钥等
• 不支持范围
  • 排除运行时生成/轮换/会话类凭据(OAuth刷新材料、access token、会话密钥等)
• Google Chat兼容例外
  • 允许通过兄弟字段serviceAccountRef覆盖serviceAccount

classDiagram
class MatrixEntry {
+id : string
+configFile : "openclaw.json"|"auth-profiles.json"
+path : string
+refPath? : string
+when? : {type}
+secretShape : "secret_input"|"sibling_ref"
+optIn : true
+notes? : string
}
class Excluded {
+列表 : 排除项数组
}
MatrixEntry --> Excluded : "受排除规则约束"

CLI与审计工作流

• 命令角色
  • reload：重新解析并原子交换快照
  • audit：扫描明文残留、未解析引用、优先级遮蔽与遗留数据
  • configure：交互式构建提供者与目标映射，预演后应用
  • apply：执行保存的计划，一次性清理明文残留
• 退出码与报告
  • audit --check在发现问题时返回非零；未解析引用有更高优先级
  • apply不写回滚备份，采用原子替换与尽力恢复策略

flowchart TD
A["开始"] --> B["secrets audit --check"]
B --> C{"发现明文/未解析/遮蔽/遗留?"}
C --> |是| D["secrets configure"]
C --> |否| E["secrets reload"]
D --> F["secrets apply --dry-run"]
F --> G{"确认执行?"}
G --> |是| H["secrets apply(无回滚备份)"]
G --> |否| I["终止"]
H --> J["secrets audit --check 再验证"]
J --> K["结束"]

认证语义与有效期

• 稳定reason code
  • ok、missing_credential、invalid_expires、expired、unresolved_ref
• 令牌有效期规则
  • expires必须为有限正数；无效或已过期的令牌视为不可用
  • tokenRef不会绕过expires校验
• 兼容性消息
  • 为脚本兼容保留首行不变的消息，后续追加人类可读细节与稳定reason code

flowchart TD
S(["开始"]) --> T["判断类型(api_key/token/oauth)"]
T --> |api_key| K{"是否存在key或keyRef?"}
K --> |否| R1["reason=missing_credential"]
K --> |是| OK["eligible=true"]
T --> |token| TK{"是否存在token或tokenRef?"}
TK --> |否| R2["reason=missing_credential"]
TK --> |是| EXP["校验expires(有限正数)"]
EXP --> |无效| R3["reason=invalid_expires"]
EXP --> |已过期| R4["reason=expired"]
EXP --> |有效| OK
T --> |oauth| ACC{"是否存在access或refresh?"}
ACC --> |否| R5["reason=missing_credential"]
ACC --> |是| OK

依赖关系分析

• 类型层依赖
  • 网关凭据解析依赖SecretRef契约与默认提供者配置
  • 凭据矩阵为文档与CLI提供“支持/不支持”清单
• 行为一致性
  • 测试用例覆盖调用/探测/状态/认证四条路径的优先级一致性
• 运行时契约
  • CLI命令与网关RPC共同保证“预检通过再提交、失败保留上次快照”

graph LR
Types["types.secrets.ts"] --> Creds["gateway/credentials.ts"]
Matrix["secrets/credential-matrix.ts"] --> Docs["gateway/secrets.md"]
Docs --> CLI["cli/secrets.md"]
Creds --> Test["gateway/credential-precedence.parity.test.ts"]
Sem["auth-credential-semantics.md"] --> State["agents/auth-profiles/credential-state.ts"]

性能考量

• 并发与批处理
  • 解析器支持最大提供者并发、每提供者最大引用数与批量字节上限，避免资源耗尽
• 路径安全
  • 文件提供者与执行提供者对路径所有权/权限进行严格校验；Windows与包管理器路径需显式信任
• 启动与重载
  • 激活阶段一次性解析，热路径只读内存快照，减少IO与解析开销

认证与授权

OpenClaw 在不同层面实现了认证与授权能力：

• 设备侧认证：设备令牌、角色与作用域、元数据规范化与签名载荷构建
• 网关侧认证：WebSocket 连接鉴权、速率限制、方法级授权
• 渠道侧授权：直接消息（DM）与群组的访问控制、命令授权门禁
• 凭据与令牌：OAuth 令牌交换与存储、API 密钥解析与轮换
• 会话与审计：会话存储、缓存与维护、会话键映射与重置

graph TB
subgraph "设备侧"
DA["设备认证载荷构建<br/>device-auth.ts"]
DS["设备认证数据结构<br/>shared/device-auth.ts"]
end
subgraph "网关侧"
RP["角色策略<br/>role-policy.ts"]
AC["WS 鉴权上下文<br/>ws-connection/auth-context.ts"]
end
subgraph "渠道侧"
DM["DM/群组访问策略<br/>dm-policy-shared.ts"]
CMD["命令授权门禁<br/>plugin-sdk/command-auth.ts"]
end
subgraph "凭据与令牌"
OA["OAuth 与令牌存储<br/>concepts/oauth.md + authentication.md"]
MA["模型认证解析<br/>agents/model-auth.ts"]
OH["OAuth 实现细节<br/>agents/auth-profiles/oauth.ts"]
end
subgraph "会话与审计"
SS["会话存储与缓存<br/>config/sessions/store.ts"]
SM["会话键映射<br/>acp/session-mapper.ts"]
ST["会话工具解析<br/>agents/tools/session-status-tool.ts"]
end
DA --> AC
DS --> AC
RP --> AC
DM --> CMD
CMD --> AC
OA --> MA
OH --> MA
SS --> SM
SS --> ST

核心组件

• 设备认证与令牌管理
  • 设备认证载荷构建与版本化（v2/v3），包含设备 ID、客户端标识、角色、作用域、时间戳、可选令牌与随机数，并对平台与设备家族字段进行规范化
  • 设备认证条目与本地存储结构，支持角色与作用域的标准化与去重排序
• 角色与方法授权
  • 网关角色集合与解析，角色是否可跳过设备身份校验的判定，以及基于方法的授权规则（节点角色仅允许节点相关方法，操作员角色仅允许管理相关方法）
• 渠道访问控制与命令授权
  • DM/群组访问策略：根据策略类型（禁用/开放/需要配对/白名单）与允许列表计算有效允许列表，决定放行、需要配对或阻断
  • 命令授权门禁：结合“是否启用访问组”“文本命令”“是否存在控制命令”等参数，评估命令授权结果
• 凭据与令牌管理
  • OAuth 令牌交换与存储：集中式凭据存储、刷新与过期处理、多账户（配置文件）路由
  • API 密钥解析与轮换：环境变量优先级、速率限制下的备用密钥重试
• 会话管理与审计
  • 会话存储：原子写入、缓存（TTL）、磁盘预算、归档与清理、锁队列与并发控制
  • 会话键映射与重置：标签/键解析、按需重置会话

架构总览

下图展示从设备到网关、再到渠道与会话的整体认证与授权流程。

sequenceDiagram
participant Dev as "设备"
participant GW as "网关"
participant Role as "角色策略"
participant Rate as "速率限制"
participant Auth as "设备令牌验证"
participant DM as "DM/群组策略"
participant Cmd as "命令授权门禁"
participant Sess as "会话存储"
Dev->>GW : "建立连接并携带设备令牌"
GW->>Rate : "检查设备速率限制"
Rate-->>GW : "允许/拒绝"
GW->>Auth : "验证设备令牌与角色/作用域"
Auth-->>GW : "通过/失败"
GW->>Role : "方法级授权判定"
Role-->>GW : "允许/拒绝"
GW->>DM : "评估 DM/群组访问策略"
DM-->>GW : "放行/需要配对/阻断"
GW->>Cmd : "命令授权门禁评估"
Cmd-->>GW : "授权/阻断"
GW->>Sess : "记录会话元数据/更新"
Sess-->>GW : "持久化完成"
GW-->>Dev : "建立会话并返回状态"

详细组件分析

设备认证与令牌管理

• 载荷构建
  • v2：设备 ID、客户端 ID、客户端模式、角色、作用域列表、签名时间戳、令牌、随机数
  • v3：在 v2 基础上增加平台与设备家族字段的规范化
• 本地存储
  • 条目包含令牌、角色、作用域与更新时间；支持角色与作用域的标准化（去空白、去重、排序）
• 平台与设备家族规范化
  • 统一为 ASCII 小写形式，确保跨平台一致性
• 测试与兼容
  • 单测覆盖载荷向量与元数据规范化；Android 侧同样实现一致逻辑

flowchart TD
Start(["开始"]) --> BuildV2["构建 v2 载荷<br/>设备ID|客户端ID|模式|角色|作用域|时间戳|令牌|随机数"]
BuildV2 --> BuildV3["构建 v3 载荷<br/>在 v2 基础上附加平台与设备家族"]
BuildV3 --> Normalize["规范化平台/设备家族为 ASCII 小写"]
Normalize --> Store["本地存储条目<br/>令牌+角色+作用域+更新时间"]
Store --> End(["结束"])

角色权限模型与方法授权

• 角色集合与解析：支持 operator 与 node
• 设备身份豁免：仅当共享认证可用时，operator 可跳过设备身份
• 方法授权：节点方法仅允许 node 角色，管理方法仅允许 operator 角色

classDiagram
class 角色策略 {
+解析角色(raw)
+可跳过设备身份(role, sharedAuthOk)
+按方法授权(role, method)
}
角色策略 <|.. 网关角色 : "operator/node"

渠道访问控制与命令授权

• DM/群组访问策略
  • 决策依据：策略类型（禁用/开放/需要配对/白名单）、允许列表、存储中的允许列表
  • 结果：放行、需要配对、阻断，并附带原因码
• 命令授权门禁
  • 结合“是否启用访问组”“文本命令”“是否存在控制命令”，评估命令授权与是否阻断控制命令

flowchart TD
A["输入: 是否群组/策略类型/允许列表/发送者"] --> B["计算有效允许列表"]
B --> C{"策略类型"}
C --> |禁用| D["阻断"]
C --> |开放| E["放行"]
C --> |需要配对| F{"是否在允许列表?"}
F --> |是| E
F --> |否| G["需要配对"]
C --> |白名单| F
E --> H["命令授权门禁评估"]
G --> H
D --> H
H --> I["授权/阻断"]

凭据与令牌管理（OAuth 与 API 密钥）

• OAuth
  • 令牌交换（PKCE）、集中式凭据存储（auth-profiles.json）、刷新与过期处理、多账户（配置文件）路由
  • 支持提供商插件自带 OAuth 或 API 密钥流程
• API 密钥
  • 解析顺序：单值覆盖、环境变量列表、备用键、Google 额外回退键；仅在速率限制错误时重试下一个密钥

sequenceDiagram
participant User as "用户/CLI"
participant Wizard as "向导/命令"
participant OAuth as "OAuth 实现"
participant Store as "凭据存储"
participant Provider as "模型提供方"
User->>Wizard : "选择 OAuth/设置令牌"
Wizard->>OAuth : "发起 PKCE 登录/粘贴令牌"
OAuth->>Provider : "交换令牌/获取账户信息"
Provider-->>OAuth : "返回访问/刷新令牌与过期时间"
OAuth->>Store : "写入/更新凭据"
Store-->>Wizard : "确认状态"
Wizard-->>User : "完成"

会话管理与审计

• 会话存储
  • 原子写入、缓存（TTL）、磁盘预算、归档与清理、锁队列与并发控制
  • 键规范化、迁移、维护（修剪、封顶、轮转）
• 会话键映射与重置
  • 支持标签/键解析、存在性校验、按需重置

flowchart TD
L["加载会话存储"] --> N["规范化条目/键"]
N --> M{"维护模式"}
M --> |告警| W["仅警告不强制执行"]
M --> |执行| P["修剪过期/封顶数量/轮转文件/磁盘预算"]
P --> A["归档/清理历史会话"]
W --> R["报告维护统计"]
A --> S["序列化并原子写入"]
R --> S
S --> Done(["完成"])

依赖关系分析

• 设备认证与网关鉴权
  • 设备认证载荷与本地存储被网关用于 WS 连接鉴权与速率限制
• 角色策略与方法授权
  • 角色策略为方法级授权提供基础，确保最小权限
• 渠道策略与命令门禁
  • DM/群组策略与命令门禁共同构成渠道访问控制闭环
• 凭据与令牌
  • OAuth 与 API 密钥解析贯穿模型调用链路，影响认证与授权决策
• 会话与审计
  • 会话存储为审计与追踪提供持久化基础

graph LR
DA["设备认证载荷"] --> AC["WS 鉴权"]
DS["设备认证存储"] --> AC
RP["角色策略"] --> AC
DM["DM/群组策略"] --> CMD["命令门禁"]
CMD --> AC
OA["OAuth/令牌"] --> MA["模型认证解析"]
MA --> AC
SS["会话存储"] --> AC

性能考量

• 会话存储缓存
  • 默认 TTL 为约 45 秒，可通过环境变量调整；缓存命中可显著降低磁盘 IO
• 并发与锁队列
  • 会话存储采用写锁队列，避免竞态；Windows 下具备重试与退避策略
• 速率限制
  • 设备令牌鉴权前先检查速率限制，失败即快速拒绝，降低无效验证开销

沙箱安全

围绕沙箱安全的关键目录与文件如下：

• 镜像构建：Dockerfile.sandbox、Dockerfile.sandbox-browser、Dockerfile.sandbox-common 及其构建脚本
• 运行时沙箱：src/agents/sandbox 下的安全校验、网络模式、主机路径处理、文件系统边界检查、Docker 容器编排等
• 文档：docs/gateway/sandboxing.md（沙箱使用与配置）、docs/cli/sandbox.md（CLI 管理）
• 测试：src/agents/bash-tools.exec.path.test.ts（工具执行权限测试）

graph TB
subgraph "镜像与构建"
A["Dockerfile.sandbox"]
B["Dockerfile.sandbox-browser"]
C["Dockerfile.sandbox-common"]
D["scripts/sandbox-setup.sh"]
E["scripts/sandbox-browser-setup.sh"]
F["scripts/sandbox-common-setup.sh"]
end
subgraph "运行时沙箱"
G["docker.ts<br/>容器编排与创建"]
H["validate-sandbox-security.ts<br/>安全校验"]
I["network-mode.ts<br/>网络模式判定"]
J["host-paths.ts<br/>主机路径归一化"]
K["fs-bridge-path-safety.ts<br/>文件边界检查"]
L["constants.ts<br/>默认值与常量"]
M["types.ts<br/>类型定义"]
end
subgraph "文档与测试"
N["docs/gateway/sandboxing.md"]
O["docs/cli/sandbox.md"]
P["bash-tools.exec.path.test.ts"]
end
A --> D
B --> E
C --> F
D --> G
E --> G
F --> G
G --> H
H --> I
H --> J
G --> K
G --> L
G --> M
N --> G
O --> G
P --> G

核心组件

• 镜像与运行时
  • 基础镜像：debian:bookworm-slim，分别构建 openclaw-sandbox、openclaw-sandbox-browser、openclaw-sandbox-common
  • 构建脚本：scripts/sandbox-*.sh 负责镜像构建与缓存优化
• 安全校验
  • 绑定挂载安全：禁止危险源路径、保留目标路径、允许根外挂载的受控开关
  • 网络模式安全：禁用 host 与 container:* 命名空间加入
  • 安全选项：禁用 unconfined seccomp/apparmor
• 文件系统边界
  • 通过边界读取与符号链接解析，确保宿主路径在限定挂载内
• 容器编排
  • 创建/启动/重启/重建策略；配置哈希一致性校验；注册表记录状态
• 类型与常量
  • 默认镜像、前缀、端口、工作目录、工具白名单/黑名单、修剪策略

架构总览

下图展示从配置到容器运行、再到安全校验与文件系统边界的整体流程。

graph TB
CFG["配置<br/>agents.defaults.sandbox"] --> HASH["计算配置哈希"]
HASH --> REG["注册表<br/>containers.json"]
CFG --> IMG["镜像选择<br/>openclaw-sandbox(-common/-browser)"]
IMG --> BUILD["构建脚本<br/>sandbox-*.sh"]
CFG --> DOCKER["docker.ts<br/>构建创建参数"]
DOCKER --> SEC["validate-sandbox-security.ts<br/>安全校验"]
SEC --> NET["network-mode.ts<br/>网络模式判定"]
SEC --> HOST["host-paths.ts<br/>主机路径归一化"]
DOCKER --> RUN["创建/启动容器"]
RUN --> FS["fs-bridge-path-safety.ts<br/>文件边界检查"]
FS --> MON["执行监控/日志"]

详细组件分析

组件A：容器编排与生命周期（docker.ts）

• 关键职责
  • 解析 Docker 可执行程序（含 Windows 兼容）
  • 执行 docker 原子命令并处理错误码与超时/中止信号
  • 构建容器创建参数（标签、只读根、tmpfs、网络、用户、环境变量、能力集、安全选项、DNS、主机、PID/内存/CPU/ulimit、绑定挂载）
  • 确保镜像存在或拉取默认镜像
  • 容器存在性/运行态检查与自动启动
  • 基于配置哈希的热容器提示与重建策略
  • 注册表更新与修剪策略
• 安全要点
  • 在构建参数阶段即调用 validateSandboxSecurity，阻断危险配置
  • 环境变量清洗，阻断敏感变量注入
  • 默认 no-new-privileges、drop cap、可选 seccomp/apparmor
  • PID/内存/CPU/ulimit 限制
• 生命周期
  • ensureSandboxContainer：按作用域（会话/代理/共享）命名与查找容器
  • 若配置哈希不一致且容器近期活跃，输出重建提示；否则删除旧容器并重建
  • 启动后可执行 setupCommand（需网络与写权限）

sequenceDiagram
participant Cfg as "配置"
participant Hash as "配置哈希"
participant Reg as "注册表"
participant Img as "镜像"
participant Args as "构建参数"
participant Sec as "安全校验"
participant Dkr as "Docker"
participant FSB as "文件边界"
Cfg->>Hash : 计算配置哈希
Hash->>Reg : 读取/比较当前哈希
Reg-->>Cfg : 哈希匹配/不匹配
Cfg->>Img : 确认镜像存在
Img-->>Cfg : 不存在则拉取默认镜像
Cfg->>Args : 生成创建参数
Args->>Sec : validateSandboxSecurity
Sec-->>Args : 通过/抛错
Args->>Dkr : docker create/start
Dkr-->>FSB : 启动后执行工具命令
FSB-->>Dkr : 边界检查通过

组件B：安全校验（validate-sandbox-security.ts）

• 绑定挂载安全
  • 字符串级快速检查：非绝对源路径、覆盖系统根、命中黑名单路径
  • 允许根外挂载的受控开关
  • 保留目标路径检测（如 /workspace、/agent）
  • 符号链接逃逸硬化工序：通过现有祖先解析真实路径再校验
• 网络模式安全
  • 禁止 host
  • 禁止 container:*（除非显式允许）
• 安全选项
  • 禁止 unconfined seccomp/apparmor
• 错误信息明确指出违规原因与修复建议

flowchart TD
Start(["开始"]) --> Parse["解析 bind 规范"]
Parse --> CheckAbs{"源路径绝对？"}
CheckAbs --> |否| ErrAbs["报错：非绝对路径"]
CheckAbs --> |是| Normalize["归一化主机路径"]
Normalize --> Blocked{"命中黑名单路径？"}
Blocked --> |是| ErrBlocked["报错：黑名单路径"]
Blocked --> |否| AllowedRoots{"允许根外挂载？"}
AllowedRoots --> |否| Outside{"是否在允许根内？"}
Outside --> |否| ErrOutside["报错：超出允许根"]
Outside --> |是| Reserved{"是否保留目标路径？"}
AllowedRoots --> |是| Reserved
Reserved --> |是| ErrReserved["报错：保留目标路径"]
Reserved --> |否| Symlink["通过现有祖先解析真实路径"]
Symlink --> Recheck["再次强制策略校验"]
Recheck --> Done(["结束"])

组件C：网络访问控制（network-mode.ts）

• 归一化网络模式字符串
• 判定 host 与 container:* 命名空间加入风险
• 提供 isDangerousNetworkMode 快速判断

组件D：主机路径处理（host-paths.ts）

• 归一化 POSIX 主机路径（兼容 Windows 前缀）
• 通过现有祖先解析路径，避免末级不存在导致的绕过

组件E：文件系统边界与权限（fs-bridge-path-safety.ts）

• 依据容器内路径解析挂载点，确保操作在限定挂载范围内
• 使用边界读取工具进行宿主路径合法性检查
• 支持可选别名策略（如允许最终符号链接用于 unlink）
• 写入权限要求与只读挂载校验
• 解析规范化的容器路径，避免符号链接逃逸

组件F：镜像与构建（Dockerfile 与脚本）

• 基础镜像：debian:bookworm-slim
• 浏览器镜像：包含 Chromium、VNC、noVNC、Xvfb 等
• 通用镜像：预装 curl、wget、jq、nodejs、python3、git、pnpm、bun、brew 等
• 构建脚本支持缓存优化与多平台构建

组件G：类型与常量（types.ts、constants.ts）

• 类型：工具策略、作用域、工作区访问、浏览器配置、修剪策略、上下文
• 常量：默认镜像、前缀、端口、工作目录、工具白/黑名单、注册表路径

依赖关系分析

• docker.ts 依赖 validate-sandbox-security.ts（安全校验）、network-mode.ts（网络模式）、host-paths.ts（路径处理）、fs-bridge-path-safety.ts（文件边界）、constants.ts（默认值）、types.ts（类型）
• 文档 sandboxing.md 与 cli/sandbox.md 为使用与运维参考
• 测试 bash-tools.exec.path.test.ts 验证工具执行权限与沙箱主机策略

graph LR
docker_ts["docker.ts"] --> validate_ts["validate-sandbox-security.ts"]
docker_ts --> network_ts["network-mode.ts"]
docker_ts --> hostpaths_ts["host-paths.ts"]
docker_ts --> fsbridge_ts["fs-bridge-path-safety.ts"]
docker_ts --> constants_ts["constants.ts"]
docker_ts --> types_ts["types.ts"]
docs_md["docs/gateway/sandboxing.md"] --> docker_ts
cli_md["docs/cli/sandbox.md"] --> docker_ts
test_ts["bash-tools.exec.path.test.ts"] --> docker_ts

性能考量

• 镜像构建缓存
  • 使用 buildx 与 cache-from/cache-to 降低重复构建时间
  • 多阶段构建与包管理器缓存（apt cache、lists）提升安装效率
• 容器复用与修剪
  • 热容器窗口内延迟重建，减少频繁创建开销
  • 闲置/最大年龄修剪策略平衡资源占用
• 资源限制
  • PID/内存/CPU/ulimit 显式设置，防止资源滥用
• 网络隔离
  • 默认无网络或专用桥接网络，降低出站流量与暴露面

威胁防护

OpenClaw 将“路由/认证”“会话隔离”“工具执行”“外部内容”“供应链”等环节划分为多道信任边界，围绕这些边界构建了安全控制点与检测/阻断逻辑。关键安全相关模块包括：

• 外部内容包装与检测：src/security/external-content.ts
• 执行审批与白名单：src/infra/exec-approvals.ts
• 主机环境变量安全：src/infra/host-env-security.ts
• 路径规范化与保护：src/gateway/security-path.ts
• 沙箱工具策略：src/agents/sandbox-tool-policy.ts
• 沙箱能力导出与类型：src/agents/sandbox.ts
• 安全策略与范围：SECURITY.md 与 docs/security/THREAT-MODEL-ATLAS.md

graph TB
subgraph "外部域"
U["用户/攻击者"]
end
subgraph "网关层"
GW["Gateway 认证/路由"]
SEC_PATH["路径规范化/保护"]
end
subgraph "会话层"
SES["会话隔离<br/>工具策略"]
end
subgraph "执行层"
APPR["执行审批/白名单"]
SBPOL["沙箱工具策略"]
SB["沙箱运行时"]
end
subgraph "外部内容"
EC["外部内容包装/检测"]
end
U --> GW
GW --> SEC_PATH
GW --> SES
SES --> APPR
SES --> EC
APPR --> SBPOL
SBPOL --> SB
EC --> SES

核心组件

• 外部内容过滤与异常模式检测：对来自邮件、Webhook、网页抓取等来源的内容进行边界标记、元数据注入与安全提示，同时检测可疑指令模式（如“忽略先前指令”“system:”等），作为监控与阻断依据。
• 执行审批与白名单：通过可配置的安全级别（deny/allowlist/full）与“询问策略”（off/on-miss/always），在命令执行前进行人工确认或自动放行；支持持久化存储与套接字交互。
• 主机环境变量安全：对危险环境变量键/前缀进行拦截，限制 PATH 覆盖，仅允许受控的终端/语言类变量，降低注入与提权风险。
• 路径规范化与保护：对输入路径进行多轮解码、规范化、点段解析与大小写/分隔符处理，生成候选路径集合，用于判定是否命中受保护前缀，阻断路径遍历。
• 沙箱工具策略：基于全局与代理级配置合并策略，计算最终工具允许/拒绝集合，遵循“最小授权”原则。
• 威胁建模与风险矩阵：基于 MITRE ATLAS 的威胁识别、影响与缓解建议，明确关键攻击链与优先级。

架构总览

下图展示从“外部输入”到“工具执行”的关键安全控制点，以及各威胁场景下的阻断路径。

sequenceDiagram
participant U as "用户/攻击者"
participant GW as "Gateway"
participant SEC as "外部内容过滤"
participant APPR as "执行审批"
participant POL as "工具策略"
participant SB as "沙箱运行时"
U->>GW : 发送消息/触发工具调用
GW->>SEC : 包装并检测外部内容
SEC-->>GW : 返回带边界标记与警告的内容
GW->>APPR : 解析命令与参数
APPR-->>GW : 决策允许/询问/拒绝
GW->>POL : 计算工具可用性
POL-->>GW : 最终工具集
GW->>SB : 在沙箱中执行受限工具
SB-->>GW : 输出结果
GW-->>U : 安全响应

详细组件分析

组件A：外部内容过滤与异常行为识别

• 功能要点
  • 可疑模式检测：内置正则集合识别提示注入迹象（如“忽略先前指令”“system:”等），记录匹配模式用于监控与审计。
  • 边界标记与元数据：为外部内容注入唯一随机 ID 的起止边界标记，附加来源、发件人、主题等元信息；对常见同形异体字符进行折叠处理，防止绕过。
  • 安全提示：在包装后的内容中加入安全声明，明确不可将其视为系统指令或命令。
  • Web 工具包装：针对 web_search/web_fetch 提供差异化包装策略，后者额外包含安全提示。
• 异常行为识别
  • 检测到可疑模式时，仍进行安全包装与处理，避免直接信任外部输入；同时保留日志以便进一步分析。
• 自动响应机制
  • 该模块本身不直接阻断，但其输出被后续审批与策略模块消费，构成“先包装、再决策”的闭环。

flowchart TD
Start(["接收外部内容"]) --> Detect["检测可疑模式"]
Detect --> HasSuspicion{"是否匹配可疑模式？"}
HasSuspicion --> |是| Log["记录匹配模式"]
HasSuspicion --> |否| Wrap["包装内容边界标记+元数据+安全提示"]
Log --> Wrap
Wrap --> Return["返回安全内容"]

组件B：执行审批与白名单（含路径与参数校验）

• 功能要点
  • 安全级别：deny（默认拒绝）、allowlist（白名单放行）、full（完全开放）。
  • 询问策略：off（不询问）、on-miss（未命中白名单时询问）、always（每次询问）。
  • 命令分析与计划：记录 argv、cwd、原始命令、会话标识、节点信息等，便于审计与回溯。
  • 允许列表：支持按模式匹配的条目，持久化存储于专用文件，具备去重与 ID 自动生成。
  • 套接字交互：通过命名套接字与令牌进行请求/决策通信，支持超时控制。
• 风险控制
  • 对高危命令采用“白名单+询问”策略，降低误执行风险；支持记录最近使用与解析路径，辅助审计。
  • 默认 deny 与 on-miss 策略在未命中白名单时触发人工确认，有效阻断路径操纵与命令混淆。

flowchart TD
Req["收到执行请求"] --> Analyze["分析命令与参数"]
Analyze --> Resolve["解析安全级别与询问策略"]
Resolve --> Decision{"是否命中白名单且满足安全级别？"}
Decision --> |是| Allow["允许执行"]
Decision --> |否| Ask{"询问策略触发？"}
Ask --> |是| Socket["通过套接字请求决策"]
Socket --> Decide{"决策：允许/拒绝"}
Decide --> |允许| Allow
Decide --> |拒绝| Deny["拒绝执行"]
Ask --> |否| Deny

组件C：主机环境变量安全（阻断注入与提权）

• 功能要点
  • 危险键/前缀拦截：对敏感环境变量键与前缀进行黑名单管理，避免注入 PATH、LD_PRELOAD 等高危变量。
  • Shell 包装器变量白名单：仅允许 TERM、LANG、LC_* 等终端/本地化变量，减少副作用。
  • 合并与过滤：从进程环境与覆盖变量中合并，剔除危险项，严格禁止 PATH 覆盖。
• 风险控制
  • 通过严格的键名规范化与前缀匹配，阻断提示注入与动态链接劫持；仅在必要时允许有限变量覆盖，降低提权与逃逸风险。

flowchart TD
Env["读取进程环境"] --> Merge["合并基础环境与覆盖变量"]
Merge --> Filter["过滤危险键/前缀与覆盖键"]
Filter --> BlockPath{"是否覆盖 PATH？"}
BlockPath --> |是| Drop["丢弃覆盖"]
BlockPath --> |否| Keep["保留变量"]
Drop --> Output["输出安全环境"]
Keep --> Output

组件D：路径规范化与保护（阻断路径遍历）

• 功能要点
  • 多轮解码：对输入路径进行最多 N 次解码尝试，记录解码轮次与是否达到上限。
  • 规范化：统一分隔符、去除尾随斜杠、小写化；生成候选路径集合。
  • 点段解析：使用 URL 解析消除相对路径段，确保规范化结果稳定。
  • 前缀匹配：对受保护前缀（如特定 API 路由）进行匹配判断，若命中则判定为受保护。
  • 异常判定：当出现畸形编码或解码轮次达到上限时，采取“关闭”策略（即判定为受保护/异常）。
• 风险控制
  • 通过候选集与异常判定，有效阻断“../..”“%2e%2e%2f”等路径遍历变种；在边界不明确时倾向保守处理。

flowchart TD
In["输入路径"] --> Decode["多轮解码并记录状态"]
Decode --> Normalize["规范化分隔符/大小写/点段解析"]
Normalize --> Candidates["生成候选路径集合"]
Candidates --> Protect{"是否命中受保护前缀？"}
Protect --> |是| Block["判定为受保护/阻断"]
Protect --> |否| CheckAnomaly{"是否畸形编码/达到解码上限？"}
CheckAnomaly --> |是| Block
CheckAnomaly --> |否| Allow["允许访问"]

组件E：沙箱工具策略（最小授权与策略合并）

• 功能要点
  • 配置来源：支持全局与代理级 allow/deny/alsoAllow 组合；alsoAllow 在无显式 allow 时视作在隐式“全部”基础上累加。
  • 合并规则：代理策略优先于全局策略，最终策略取交集（更严格者胜）。
  • 导出与类型：统一导出策略解析函数与类型定义，便于上层工具调用与审计。
• 风险控制
  • 通过“代理覆盖 > 全局 > 默认”的层级合并，确保细粒度策略落地；拒绝集合优先，避免过度授权。

classDiagram
class SandboxToolPolicyConfig {
+allow? : string[]
+alsoAllow? : string[]
+deny? : string[]
}
class SandboxToolPolicy {
+allow : string[]
+deny : string[]
}
class pickSandboxToolPolicy {
+(config?) : SandboxToolPolicy|undefined
}
SandboxToolPolicyConfig --> pickSandboxToolPolicy : "输入"
pickSandboxToolPolicy --> SandboxToolPolicy : "输出"

组件F：威胁情报集成、实时监控与告警

• 威胁情报集成
  • ClawHub 供应链扫描：计划引入 VirusTotal 行为分析与社区举报/审计日志，逐步替代简单正则模式。
• 实时监控与告警
  • 外部内容可疑模式检测：记录匹配模式，作为异常事件上报与趋势分析依据。
  • 执行审批：通过套接字与持久化文件记录决策与使用情况，支持审计与回溯。
• 建议
  • 结合外部威胁情报源（如 VT、开源情报）对已发布技能进行扫描与评分；在网关层增加速率限制与成本预算，降低资源耗尽风险。

组件G：自动响应机制（阻断与降级）

• 外部内容：包装并注入安全提示，降低注入指令的可执行性。
• 执行审批：deny 策略直接阻断；allowlist 策略在未命中时触发询问；always 策略强制人工确认。
• 沙箱策略：拒绝集合优先，最小授权暴露工具集；代理策略可叠加 alsoAllow，但最终以更严格为准。
• 路径保护：异常判定与前缀匹配导致的阻断，避免路径遍历与越权访问。

依赖关系分析

• 组件耦合
  • 外部内容过滤与执行审批：前者提供“安全内容”，后者据此做“是否允许”的决策，耦合度中等。
  • 路径保护与沙箱策略：路径保护用于边界判定，沙箱策略用于工具可用性控制，二者共同决定访问与执行面。
  • 主机环境变量安全：在系统命令执行前对环境进行清洗，降低注入风险，与执行审批形成互补。
• 依赖可视化

graph LR
EC["external-content.ts"] --> APPR["exec-approvals.ts"]
SEC_PATH["security-path.ts"] --> APPR
SEC_PATH --> SBPOL["sandbox-tool-policy.ts"]
SBPOL --> SB["sandbox.ts"]
ENV["host-env-security.ts"] --> APPR

性能考量

• 外部内容包装：多轮解码与候选集生成存在时间复杂度，建议在高频路径上缓存标准化结果与标记替换。
• 执行审批：套接字交互与文件读写带来延迟，可通过批量决策与本地缓存优化；同时注意文件权限与时钟同步。
• 路径保护：URL 解析与候选集生成开销可控，建议在网关入口集中处理，避免重复计算。
• 沙箱策略：策略合并与类型检查为纯内存操作，性能影响较小；建议在配置变更时进行一次性校验。

故障排查指南

• 外部内容告警过多
  • 检查可疑模式正则是否过于宽泛；结合业务场景调整 includeWarning 与元数据注入策略。
  • 关注边界标记折叠逻辑，确保同形异体字符被正确归一化。
• 执行审批误判
  • 核对 allowlist 条目是否命中；检查 ask 与 security 策略组合；确认持久化文件权限与格式。
  • 使用套接字交互时，确认令牌与路径配置正确，超时设置合理。
• 路径遍历失败
  • 检查输入路径是否包含畸形编码或过多点段；确认受保护前缀配置是否覆盖目标路由。
• 沙箱工具不可用
  • 核对代理策略与全局策略合并结果；确认 alsoAllow 是否导致意外放行或被更严格策略覆盖。
• 环境变量异常
  • 检查危险键/前缀是否被错误放行；确认 PATH 是否被覆盖；核对 shell 包装器白名单。

威胁建模与攻击链

• 关键攻击链
  • 技能型数据窃取：发布恶意技能 → 绕过审核 → 技能执行时窃取凭据。
  • 提示注入到远程命令执行：直接提示注入 → 绕过执行审批 → 在宿主或沙箱中执行命令。
  • 间接注入 via 外部内容：污染 URL 内容 → Agent 获取并执行 → 数据外泄。
• 风险矩阵（部分）
  • T-EXEC-001、T-PERSIST-001、T-EXFIL-003：高影响/高概率，优先处置。
  • T-EXEC-002、T-EXEC-004、T-ACCESS-003：中高风险，需强化审批与白名单。
  • T-IMPACT-002：高概率/中影响，需引入速率限制与成本预算。

漏洞评估与加固清单

• 外部内容
  • 引入 AST/行为分析替代简单正则；增强边界标记的抗同形异体攻击能力。
• 执行审批
  • 默认 deny + on-miss；对高危命令启用 always；完善套接字交互与持久化文件权限。
• 路径保护
  • 明确受保护前缀清单；对异常路径采取保守阻断策略。
• 沙箱策略
  • 代理策略优先；拒绝集合优先；定期审计工具暴露面。
• 环境变量
  • 严格拦截危险键/前缀；禁止 PATH 覆盖；仅允许必要变量。
• 运维与合规
  • 定期安全审计与修复；实施最小权限与只读根文件系统；容器运行时限制能力与网络。