OpenClaw 安全更新：Web Fetch Provider 边界强化详解

OpenClaw 在最新版本中加强了 Web Fetch Provider 的安全边界，通过强化 URL 解析和请求验证，有效防止 SSRF（服务器端请求伪造）等安全攻击。

本文将详细介绍这项安全更新的技术细节和配置方法。

目录

• 什么是 Web Fetch Provider
• 安全风险分析
• 边界强化措施
• 配置与使用
• 最佳实践
• 常见问题

什么是 Web Fetch Provider

Web Fetch Provider 是 OpenClaw 中用于网页内容获取的核心组件。它负责：

• 发送 HTTP/HTTPS 请求
• 解析响应内容
• 处理重定向和超时
• 管理连接池

典型使用场景

在 Skill 中使用 Web Fetch
web_fetch:
  url: "https://api.example.com/data"
  method: GET
  headers:
    Authorization: "Bearer ${API_TOKEN}"

安全风险分析

SSRF（服务器端请求伪造）

攻击原理：
攻击者通过构造特殊 URL，让服务器向内部网络或敏感资源发起请求。

攻击示例：

恶意请求
url: "http://169.254.169.254/latest/meta-data/"  # AWS 元数据服务

或
url: "http://localhost:6379/"  # 本地 Redis 服务

或  
url: "file:///etc/passwd"  # 本地文件读取

URL 解析漏洞

问题场景：

• 不规范的 URL 格式被意外解析
• 特殊字符绕过安全检查
• Unicode 编码混淆

有问题的 URL
http://example.com@evil.com/  # @ 符号混淆
http://example.com%2F..%2Fetc/passwd  # 编码绕过

边界强化措施

1. URL 解析加固

新的 URL 解析器采用更严格的 RFC 3986 标准：

// 严格的 URL 解析
class HardenedURLParser {
  parse(url: string): ParsedURL {
    // 1. 规范化编码
    const normalized = this.normalizeEncoding(url);
    
    // 2. 验证协议白名单
    if (!this.isAllowedProtocol(normalized.protocol)) {
      throw new SecurityError(Protocol ${normalized.protocol} not allowed);
    }
    
    // 3. 验证主机名格式
    if (!this.isValidHostname(normalized.hostname)) {
      throw new SecurityError(Invalid hostname: ${normalized.hostname});
    }
    
    // 4. 检查 IP 范围
    if (this.isPrivateIP(normalized.hostname)) {
      throw new SecurityError(Private IP access not allowed: ${normalized.hostname});
    }
    
    return normalized;
  }
}

2. 请求边界控制

config.yaml
providers:
  web_fetch:
    security:
      # 启用边界强化
      hardened_boundaries: true
      
      # 协议白名单
      allowed_protocols:
        - https
        - http
      
      # 禁止的主机模式
      blocked_host_patterns:
        - "localhost"
        - "127...*"
        - "10...*"
        - "192.168.."
        - "*.internal"
        - "*.local"
      
      # 禁止的端口
      blocked_ports:
        - 22    # SSH
        - 23    # Telnet
        - 25    # SMTP
        - 53    # DNS
        - 110   # POP3
        - 143   # IMAP
        - 3389  # RDP
        - 6379  # Redis
        - 3306  # MySQL
        - 5432  # PostgreSQL
      
      # 最大重定向次数
      max_redirects: 3
      
      # 验证 SSL 证书
      verify_ssl: true

3. 响应边界控制

providers:
  web_fetch:
    response_limits:
      # 最大响应大小 (10MB)
      max_size: 10485760
      
      # 允许的内容类型
      allowed_content_types:
        - "text/html"
        - "text/plain"
        - "application/json"
        - "application/xml"
        - "text/markdown"
      
      # 禁止的内容模式
      blocked_patterns:
        - "]>[\\s\\S]?"  # 脚本标签（可选）

配置与使用

基础配置

config.yaml
providers:
  web_fetch:
    enabled: true
    
    # 安全强化（推荐启用）
    security:
      hardened_boundaries: true
      
    # 超时设置
    timeout:
      connect: 5000      # 连接超时 5秒
      read: 30000        # 读取超时 30秒
      
    # 重试策略
    retry:
      max_attempts: 3
      backoff: exponential

在 Skill 中使用

// 安全的 Web Fetch 调用
export class SafeWebFetchSkill {
  async fetchData(url: string) {
    // OpenClaw 会自动应用安全边界
    const response = await this.webFetch({
      url,
      method: 'GET',
      headers: {
        'User-Agent': 'OpenClaw/1.0'
      }
    });
    
    return response.data;
  }
}

自定义安全策略

为特定 provider 定制安全策略
providers:
  web_fetch:
    # 默认严格模式
    security:
      hardened_boundaries: true
    
    # 特定场景宽松模式（谨慎使用）
    profiles:
      internal_api:
        security:
          hardened_boundaries: true
          blocked_host_patterns:
            # 允许访问内部 API
            - "localhost"
            - "127.0.0.1"
          
      public_only:
        security:
          hardened_boundaries: true
          blocked_host_patterns:
            - "*.internal.company.com"

最佳实践

1. 输入验证

// 始终验证用户输入的 URL
function validateUserURL(input: string): string {
  // 1. 基本格式检查
  const urlPattern = /^https?:\/\/.+/;
  if (!urlPattern.test(input)) {
    throw new Error('URL must start with http:// or https://');
  }
  
  // 2. 长度限制
  if (input.length > 2048) {
    throw new Error('URL too long');
  }
  
  // 3. 危险字符检查
  const dangerousChars = ['<', '>', '{', '}', '|', '^', ''];
  for (const char of dangerousChars) {
    if (input.includes(char)) {
      throw new Error(URL contains dangerous character: ${char}`);
    }
  }
  
  return input;
}

2. 使用 URL 白名单

对于已知安全的 API
providers:
  web_fetch:
    whitelist:
      enabled: true
      urls:
        - "https://api.github.com/*"
        - "https://api.openai.com/*"
        - "https://docs.openclaw.ai/*"

3. 日志审计

providers:
  web_fetch:
    audit:
      enabled: true
      log_level: info
      log_requests: true
      log_responses: false  # 避免记录敏感数据

4. 监控和告警

monitoring:
  web_fetch:
    alerts:
      - name: "SSRF Attempt Detected"
        condition: "security.blocked_request_count > 0"
        action: "notify_admin"
      
      - name: "High Error Rate"
        condition: "error_rate > 0.1"
        action: "throttle_requests"

测试安全边界

安全测试用例

// tests/security/web-fetch.test.ts
describe('Web Fetch Security Boundaries', () => {
  it('should block private IP access', async () => {
    await expect(
      webFetch('http://192.168.1.1/')
    ).rejects.toThrow('Private IP access not allowed');
  });
  
  it('should block localhost access', async () => {
    await expect(
      webFetch('http://localhost:8080/')
    ).rejects.toThrow('Blocked host pattern: localhost');
  });
  
  it('should block file protocol', async () => {
    await expect(
      webFetch('file:///etc/passwd')
    ).rejects.toThrow('Protocol file not allowed');
  });
  
  it('should block suspicious URL encoding', async () => {
    await expect(
      webFetch('http://example.com%2F..%2Fadmin')
    ).rejects.toThrow('Invalid URL encoding');
  });
});

总结

Web Fetch Provider 边界强化 为 OpenClaw 带来了更强的安全防护：

1. URL 解析加固 — 严格遵循 RFC 标准，防止编码绕过
2. 请求边界控制 — 协议、主机、端口多层次限制
3. 响应边界控制 — 大小、类型双重限制
4. 可观测性 — 完整的审计日志和监控告警

关键配置：

providers:
  web_fetch:
    security:
      hardened_boundaries: true  # 启用安全强化

常见问题

Q: 启用边界强化后，原有功能会受影响吗？

A: 正常的外部 API 调用不会受影响。只有尝试访问内部网络或敏感资源的请求会被阻止。

Q: 如何临时禁用某个安全限制？

A: 不建议禁用，但可以添加例外规则：

security:
  hardened_boundaries: true
  exceptions:
    - host: "internal-api.company.com"
      reason: "Internal API access required"

Q: 误拦截了合法请求怎么办？

A:
1. 检查审计日志确认拦截原因
2. 如果是白名单中的 API，更新白名单配置
3. 如果是配置错误，调整 blocked_host_patterns

Q: 支持自定义安全策略吗？

A: 支持，可以通过配置文件自定义协议、端口、主机模式等限制。

Q: 对性能有影响吗？

A: 影响极小。URL 解析和验证在微秒级完成。

Q: 如何查看被拦截的请求？

A:

查看安全审计日志
tail -f ~/.openclaw/logs/security-audit.log | grep "BLOCKED"

统计拦截情况
openclaw stats web-fetch --security

参考来源

• OpenClaw Web Fetch 文档
• OWASP SSRF 防护指南
• RFC 3986 – URI 标准
• GitHub PR #59646

—

相关阅读：

• OpenClaw 安全加固指南
• Provider 安全配置
• 审计日志分析

OpenClaw 插件安全加固：Runtime Facade 激活保护机制详解

OpenClaw 在最新更新中引入了 Runtime Facade 激活保护机制，有效防止插件在激活过程中的潜在安全风险，提升整体系统稳定性。

本文将详细介绍这项安全加固措施的原理、实现方式以及对现有插件的影响。

目录

• 什么是 Facade 激活保护
• 为什么需要这项保护
• 技术实现细节
• 对现有插件的影响
• 最佳实践
• 常见问题

什么是 Facade 激活保护

Facade（外观模式） 是 OpenClaw 插件架构中的核心概念。它提供了一个统一的接口，让插件能够与 OpenClaw 核心进行交互。

激活过程的风险

在插件加载时，Facade 需要被激活以建立插件与核心的通信。这个过程如果缺乏保护，可能导致：

• 未授权访问 — 恶意插件在激活时执行危险操作
• 资源泄漏 — 激活失败时清理不当
• 系统不稳定 — 激活过程中的异常导致核心服务崩溃

保护机制概览

新的保护机制在 Facade 激活 阶段增加了安全检查：

插件加载 → 安全检查 → Facade 激活 → 受限运行 → 完整功能

为什么需要这项保护

安全场景分析

#### 场景 1: 恶意插件注入

// 恶意插件可能在激活时尝试
module.exports = {
  activate() {
    // 尝试访问受限 API
    const fs = require('fs');
    fs.writeFileSync('/etc/passwd', '...'); // 危险操作
  }
}

保护机制：激活阶段限制文件系统访问，阻止此类操作。

#### 场景 2: 激活失败资源泄漏

// 插件激活时创建资源，失败时未清理
module.exports = {
  activate() {
    this.server = createServer(); // 创建服务器
    throw new Error('激活失败');  // 异常退出，服务器未关闭
  }
}

保护机制：激活守卫确保失败时自动清理资源。

实际安全案例

在 Discord 和浏览器插件中发现的潜在问题：

• Discord 插件：清理线程解绑操作在激活守卫内，可能导致死锁
• 浏览器插件：清理辅助函数被错误地包含在激活守卫中

技术实现细节

1. 激活守卫（Activation Guard）

// plugin-sdk/runtime/facade.ts
export class PluginFacade {
  async activate(plugin: Plugin): Promise {
    // 进入激活守卫
    return await activationGuard(async () => {
      // 验证插件签名
      await this.verifyPluginSignature(plugin);
      
      // 限制环境下的初始化
      await plugin.activate(this.restrictedContext);
      
      // 验证激活结果
      this.validateActivationState();
    });
  }
}

2. 本地化 Facade 加载策略

config.yaml
plugins:
  security:
    facade:
      # 本地加载策略
      load_policy: localized
      
      # 激活守卫配置
      activation_guard:
        enabled: true
        timeout: 30000  # 30秒超时
        
      # 权限限制
      restricted_permissions:
        - fs_write
        - network_outbound
        - process_spawn

3. 清理操作的保护

修复了清理操作被错误包含在激活守卫中的问题：

// 修复前（有问题）
class BrowserPlugin {
  activate() {
    activationGuard(() => {
      this.setupBrowser();
      this.cleanup = () => {  // ❌ 清理不应该在守卫内
        this.browser.close();
      };
    });
  }
}

// 修复后（正确）
class BrowserPlugin {
  activate() {
    activationGuard(() => {
      this.setupBrowser();
    });
    
    // ✅ 清理操作在守卫外
    this.cleanup = () => {
      this.browser.close();
    };
  }
}

4. Discord 插件的修复

// discord/plugin.ts
export class DiscordPlugin {
  async activate() {
    await this.facade.activateGuard(async () => {
      await this.initializeBot();
    });
    
    // 清理操作移出守卫
    this.registerCleanup(() => {
      this.threadUnbind();  // ✅ 在线程外执行
    });
  }
}

5. 非零退出处理

浏览器插件现在能优雅处理清理失败：

async cleanup() {
  try {
    await this.browser.close();
  } catch (error) {
    // 非零退出时提供回退方案
    if (error.exitCode !== 0) {
      logger.warn('浏览器清理异常，使用强制终止');
      await this.browser.kill();
    }
  }
}

对现有插件的影响

需要检查的插件类型

| 插件类型 | 影响程度 | 检查重点 |
|———-|———-|———-|
| 浏览器自动化 | 高 | 清理操作位置 |
| Discord 集成 | 中 | 线程解绑逻辑 |
| 文件系统操作 | 中 | 激活阶段权限 |
| 网络请求 | 低 | 一般无影响 |

迁移检查清单

• [ ] 检查清理操作是否在激活守卫外
• [ ] 验证激活失败时的资源清理
• [ ] 测试插件在受限环境下的行为
• [ ] 更新插件 manifest 声明权限

最佳实践

1. 插件开发规范

// ✅ 推荐的插件结构
export default class MyPlugin {
  // 激活阶段 - 受限环境
  async activate(context: RestrictedContext) {
    // 只进行基本初始化
    this.config = await context.loadConfig();
    this.validateConfig();
  }
  
  // 完全激活后 - 正常环境
  async onReady(context: FullContext) {
    // 此时可以执行完整功能
    await this.initializeServices();
  }
  
  // 清理 - 确保在守卫外
  async deactivate() {
    await this.cleanup();
  }
}

2. 错误处理

async activate(context: Context) {
  try {
    await this.initialize();
  } catch (error) {
    // 激活失败时确保清理
    await this.cleanup();
    throw new ActivationError('插件激活失败', { cause: error });
  }
}

3. 权限声明

{
  "name": "my-plugin",
  "permissions": {
    "activation": ["config_read"],
    "runtime": ["network", "filesystem"]
  }
}

总结

Runtime Facade 激活保护 是 OpenClaw 插件安全的重要加固：

1. 激活阶段隔离 — 限制插件在初始化时的权限
2. 资源清理保证 — 失败时自动清理，防止泄漏
3. 清理操作分离 — 避免死锁和资源竞争
4. 非零退出处理 — 提供优雅的错误回退

下一步行动：
1. 检查你的自定义插件是否符合新规范
2. 更新插件声明权限
3. 测试插件在激活守卫下的行为

常见问题

Q: 这项更新会影响现有插件的运行吗？

A: 大多数插件不会受影响。只有那些在激活阶段执行敏感操作或清理逻辑不当的插件需要调整。

Q: 如何检查我的插件是否需要更新？

A: 运行 OpenClaw 的插件检查工具：

openclaw plugins check --compatibility

Q: 激活守卫的超时可以配置吗？

A: 可以，在 config.yaml 中调整：

plugins:
  security:
    facade:
      activation_guard:
        timeout: 60000  # 60秒

Q: 清理操作应该在什么时候注册？

A: 在 activate() 方法中注册，但确保回调函数在守卫外执行：

activate() {
  // 守卫内的初始化
  activationGuard(() => {
    this.resource = createResource();
  });
  
  // 守卫外的清理注册
  this.onDeactivate(() => {
    this.resource.close();
  });
}

Q: 如果插件在激活时超时怎么办？

A: 系统会自动终止激活过程并清理资源。建议：

• 将耗时操作移到 onReady 阶段
• 优化初始化逻辑
• 增加激活守卫超时时间

参考来源

• OpenClaw 插件 SDK 文档
• OpenClaw 安全加固指南
• Facade 模式设计模式
• GitHub PR #59412

—

相关阅读：

• OpenClaw 插件开发最佳实践
• 插件权限系统详解
• 安全审计指南

OpenClaw 安全更新：Web Fetch Provider 边界强化详解

OpenClaw 在最新版本中加强了 Web Fetch Provider 的安全边界，通过强化 URL 解析和请求验证，有效防止 SSRF（服务器端请求伪造）等安全攻击。

本文将详细介绍这项安全更新的技术细节和配置方法。

目录

• 什么是 Web Fetch Provider
• 安全风险分析
• 边界强化措施
• 配置与使用
• 最佳实践
• 常见问题

什么是 Web Fetch Provider

Web Fetch Provider 是 OpenClaw 中用于网页内容获取的核心组件。它负责：

• 发送 HTTP/HTTPS 请求
• 解析响应内容
• 处理重定向和超时
• 管理连接池

典型使用场景

在 Skill 中使用 Web Fetch
web_fetch:
  url: "https://api.example.com/data"
  method: GET
  headers:
    Authorization: "Bearer ${API_TOKEN}"

安全风险分析

SSRF（服务器端请求伪造）

攻击原理：
攻击者通过构造特殊 URL，让服务器向内部网络或敏感资源发起请求。

攻击示例：

恶意请求
url: "http://169.254.169.254/latest/meta-data/"  # AWS 元数据服务

或
url: "http://localhost:6379/"  # 本地 Redis 服务

或  
url: "file:///etc/passwd"  # 本地文件读取

URL 解析漏洞

问题场景：

• 不规范的 URL 格式被意外解析
• 特殊字符绕过安全检查
• Unicode 编码混淆

有问题的 URL
http://example.com@evil.com/  # @ 符号混淆
http://example.com%2F..%2Fetc/passwd  # 编码绕过

边界强化措施

1. URL 解析加固

新的 URL 解析器采用更严格的 RFC 3986 标准：

// 严格的 URL 解析
class HardenedURLParser {
  parse(url: string): ParsedURL {
    // 1. 规范化编码
    const normalized = this.normalizeEncoding(url);
    
    // 2. 验证协议白名单
    if (!this.isAllowedProtocol(normalized.protocol)) {
      throw new SecurityError(Protocol ${normalized.protocol} not allowed);
    }
    
    // 3. 验证主机名格式
    if (!this.isValidHostname(normalized.hostname)) {
      throw new SecurityError(Invalid hostname: ${normalized.hostname});
    }
    
    // 4. 检查 IP 范围
    if (this.isPrivateIP(normalized.hostname)) {
      throw new SecurityError(Private IP access not allowed: ${normalized.hostname});
    }
    
    return normalized;
  }
}

2. 请求边界控制

config.yaml
providers:
  web_fetch:
    security:
      # 启用边界强化
      hardened_boundaries: true
      
      # 协议白名单
      allowed_protocols:
        - https
        - http
      
      # 禁止的主机模式
      blocked_host_patterns:
        - "localhost"
        - "127...*"
        - "10...*"
        - "192.168.."
        - "*.internal"
        - "*.local"
      
      # 禁止的端口
      blocked_ports:
        - 22    # SSH
        - 23    # Telnet
        - 25    # SMTP
        - 53    # DNS
        - 110   # POP3
        - 143   # IMAP
        - 3389  # RDP
        - 6379  # Redis
        - 3306  # MySQL
        - 5432  # PostgreSQL
      
      # 最大重定向次数
      max_redirects: 3
      
      # 验证 SSL 证书
      verify_ssl: true

3. 响应边界控制

providers:
  web_fetch:
    response_limits:
      # 最大响应大小 (10MB)
      max_size: 10485760
      
      # 允许的内容类型
      allowed_content_types:
        - "text/html"
        - "text/plain"
        - "application/json"
        - "application/xml"
        - "text/markdown"
      
      # 禁止的内容模式
      blocked_patterns:
        - "]>[\\s\\S]?"  # 脚本标签（可选）

配置与使用

基础配置

config.yaml
providers:
  web_fetch:
    enabled: true
    
    # 安全强化（推荐启用）
    security:
      hardened_boundaries: true
      
    # 超时设置
    timeout:
      connect: 5000      # 连接超时 5秒
      read: 30000        # 读取超时 30秒
      
    # 重试策略
    retry:
      max_attempts: 3
      backoff: exponential

在 Skill 中使用

// 安全的 Web Fetch 调用
export class SafeWebFetchSkill {
  async fetchData(url: string) {
    // OpenClaw 会自动应用安全边界
    const response = await this.webFetch({
      url,
      method: 'GET',
      headers: {
        'User-Agent': 'OpenClaw/1.0'
      }
    });
    
    return response.data;
  }
}

自定义安全策略

为特定 provider 定制安全策略
providers:
  web_fetch:
    # 默认严格模式
    security:
      hardened_boundaries: true
    
    # 特定场景宽松模式（谨慎使用）
    profiles:
      internal_api:
        security:
          hardened_boundaries: true
          blocked_host_patterns:
            # 允许访问内部 API
            - "localhost"
            - "127.0.0.1"
          
      public_only:
        security:
          hardened_boundaries: true
          blocked_host_patterns:
            - "*.internal.company.com"

最佳实践

1. 输入验证

// 始终验证用户输入的 URL
function validateUserURL(input: string): string {
  // 1. 基本格式检查
  const urlPattern = /^https?:\/\/.+/;
  if (!urlPattern.test(input)) {
    throw new Error('URL must start with http:// or https://');
  }
  
  // 2. 长度限制
  if (input.length > 2048) {
    throw new Error('URL too long');
  }
  
  // 3. 危险字符检查
  const dangerousChars = ['<', '>', '{', '}', '|', '^', ''];
  for (const char of dangerousChars) {
    if (input.includes(char)) {
      throw new Error(URL contains dangerous character: ${char}`);
    }
  }
  
  return input;
}

2. 使用 URL 白名单

对于已知安全的 API
providers:
  web_fetch:
    whitelist:
      enabled: true
      urls:
        - "https://api.github.com/*"
        - "https://api.openai.com/*"
        - "https://docs.openclaw.ai/*"

3. 日志审计

providers:
  web_fetch:
    audit:
      enabled: true
      log_level: info
      log_requests: true
      log_responses: false  # 避免记录敏感数据

4. 监控和告警

monitoring:
  web_fetch:
    alerts:
      - name: "SSRF Attempt Detected"
        condition: "security.blocked_request_count > 0"
        action: "notify_admin"
      
      - name: "High Error Rate"
        condition: "error_rate > 0.1"
        action: "throttle_requests"

测试安全边界

安全测试用例

// tests/security/web-fetch.test.ts
describe('Web Fetch Security Boundaries', () => {
  it('should block private IP access', async () => {
    await expect(
      webFetch('http://192.168.1.1/')
    ).rejects.toThrow('Private IP access not allowed');
  });
  
  it('should block localhost access', async () => {
    await expect(
      webFetch('http://localhost:8080/')
    ).rejects.toThrow('Blocked host pattern: localhost');
  });
  
  it('should block file protocol', async () => {
    await expect(
      webFetch('file:///etc/passwd')
    ).rejects.toThrow('Protocol file not allowed');
  });
  
  it('should block suspicious URL encoding', async () => {
    await expect(
      webFetch('http://example.com%2F..%2Fadmin')
    ).rejects.toThrow('Invalid URL encoding');
  });
});

总结

Web Fetch Provider 边界强化 为 OpenClaw 带来了更强的安全防护：

1. URL 解析加固 — 严格遵循 RFC 标准，防止编码绕过
2. 请求边界控制 — 协议、主机、端口多层次限制
3. 响应边界控制 — 大小、类型双重限制
4. 可观测性 — 完整的审计日志和监控告警

关键配置：

providers:
  web_fetch:
    security:
      hardened_boundaries: true  # 启用安全强化

常见问题

Q: 启用边界强化后，原有功能会受影响吗？

A: 正常的外部 API 调用不会受影响。只有尝试访问内部网络或敏感资源的请求会被阻止。

Q: 如何临时禁用某个安全限制？

A: 不建议禁用，但可以添加例外规则：

security:
  hardened_boundaries: true
  exceptions:
    - host: "internal-api.company.com"
      reason: "Internal API access required"

Q: 误拦截了合法请求怎么办？

A:
1. 检查审计日志确认拦截原因
2. 如果是白名单中的 API，更新白名单配置
3. 如果是配置错误，调整 blocked_host_patterns

Q: 支持自定义安全策略吗？

A: 支持，可以通过配置文件自定义协议、端口、主机模式等限制。

Q: 对性能有影响吗？

A: 影响极小。URL 解析和验证在微秒级完成。

Q: 如何查看被拦截的请求？

A:

查看安全审计日志
tail -f ~/.openclaw/logs/security-audit.log | grep "BLOCKED"

统计拦截情况
openclaw stats web-fetch --security

参考来源

• OpenClaw Web Fetch 文档
• OWASP SSRF 防护指南
• RFC 3986 – URI 标准
• GitHub PR #59646

—

相关阅读：

• OpenClaw 安全加固指南
• Provider 安全配置
• 审计日志分析

OpenClaw 安全更新：Web Fetch Provider 边界强化详解

OpenClaw 在最新版本中加强了 Web Fetch Provider 的安全边界，通过强化 URL 解析和请求验证，有效防止 SSRF（服务器端请求伪造）等安全攻击。

本文将详细介绍这项安全更新的技术细节和配置方法。

目录

• 什么是 Web Fetch Provider
• 安全风险分析
• 边界强化措施
• 配置与使用
• 最佳实践
• 常见问题

什么是 Web Fetch Provider

Web Fetch Provider 是 OpenClaw 中用于网页内容获取的核心组件。它负责：

• 发送 HTTP/HTTPS 请求
• 解析响应内容
• 处理重定向和超时
• 管理连接池

典型使用场景

在 Skill 中使用 Web Fetch
web_fetch:
  url: "https://api.example.com/data"
  method: GET
  headers:
    Authorization: "Bearer ${API_TOKEN}"

安全风险分析

SSRF（服务器端请求伪造）

攻击原理：
攻击者通过构造特殊 URL，让服务器向内部网络或敏感资源发起请求。

攻击示例：

恶意请求
url: "http://169.254.169.254/latest/meta-data/"  # AWS 元数据服务

或
url: "http://localhost:6379/"  # 本地 Redis 服务

或  
url: "file:///etc/passwd"  # 本地文件读取

URL 解析漏洞

问题场景：

• 不规范的 URL 格式被意外解析
• 特殊字符绕过安全检查
• Unicode 编码混淆

有问题的 URL
http://example.com@evil.com/  # @ 符号混淆
http://example.com%2F..%2Fetc/passwd  # 编码绕过

边界强化措施

1. URL 解析加固

新的 URL 解析器采用更严格的 RFC 3986 标准：

// 严格的 URL 解析
class HardenedURLParser {
  parse(url: string): ParsedURL {
    // 1. 规范化编码
    const normalized = this.normalizeEncoding(url);
    
    // 2. 验证协议白名单
    if (!this.isAllowedProtocol(normalized.protocol)) {
      throw new SecurityError(Protocol ${normalized.protocol} not allowed);
    }
    
    // 3. 验证主机名格式
    if (!this.isValidHostname(normalized.hostname)) {
      throw new SecurityError(Invalid hostname: ${normalized.hostname});
    }
    
    // 4. 检查 IP 范围
    if (this.isPrivateIP(normalized.hostname)) {
      throw new SecurityError(Private IP access not allowed: ${normalized.hostname});
    }
    
    return normalized;
  }
}

2. 请求边界控制

config.yaml
providers:
  web_fetch:
    security:
      # 启用边界强化
      hardened_boundaries: true
      
      # 协议白名单
      allowed_protocols:
        - https
        - http
      
      # 禁止的主机模式
      blocked_host_patterns:
        - "localhost"
        - "127...*"
        - "10...*"
        - "192.168.."
        - "*.internal"
        - "*.local"
      
      # 禁止的端口
      blocked_ports:
        - 22    # SSH
        - 23    # Telnet
        - 25    # SMTP
        - 53    # DNS
        - 110   # POP3
        - 143   # IMAP
        - 3389  # RDP
        - 6379  # Redis
        - 3306  # MySQL
        - 5432  # PostgreSQL
      
      # 最大重定向次数
      max_redirects: 3
      
      # 验证 SSL 证书
      verify_ssl: true

3. 响应边界控制

providers:
  web_fetch:
    response_limits:
      # 最大响应大小 (10MB)
      max_size: 10485760
      
      # 允许的内容类型
      allowed_content_types:
        - "text/html"
        - "text/plain"
        - "application/json"
        - "application/xml"
        - "text/markdown"
      
      # 禁止的内容模式
      blocked_patterns:
        - "]>[\\s\\S]?"  # 脚本标签（可选）

配置与使用

基础配置

config.yaml
providers:
  web_fetch:
    enabled: true
    
    # 安全强化（推荐启用）
    security:
      hardened_boundaries: true
      
    # 超时设置
    timeout:
      connect: 5000      # 连接超时 5秒
      read: 30000        # 读取超时 30秒
      
    # 重试策略
    retry:
      max_attempts: 3
      backoff: exponential

在 Skill 中使用

// 安全的 Web Fetch 调用
export class SafeWebFetchSkill {
  async fetchData(url: string) {
    // OpenClaw 会自动应用安全边界
    const response = await this.webFetch({
      url,
      method: 'GET',
      headers: {
        'User-Agent': 'OpenClaw/1.0'
      }
    });
    
    return response.data;
  }
}

自定义安全策略

为特定 provider 定制安全策略
providers:
  web_fetch:
    # 默认严格模式
    security:
      hardened_boundaries: true
    
    # 特定场景宽松模式（谨慎使用）
    profiles:
      internal_api:
        security:
          hardened_boundaries: true
          blocked_host_patterns:
            # 允许访问内部 API
            - "localhost"
            - "127.0.0.1"
          
      public_only:
        security:
          hardened_boundaries: true
          blocked_host_patterns:
            - "*.internal.company.com"

最佳实践

1. 输入验证

// 始终验证用户输入的 URL
function validateUserURL(input: string): string {
  // 1. 基本格式检查
  const urlPattern = /^https?:\/\/.+/;
  if (!urlPattern.test(input)) {
    throw new Error('URL must start with http:// or https://');
  }
  
  // 2. 长度限制
  if (input.length > 2048) {
    throw new Error('URL too long');
  }
  
  // 3. 危险字符检查
  const dangerousChars = ['<', '>', '{', '}', '|', '^', ''];
  for (const char of dangerousChars) {
    if (input.includes(char)) {
      throw new Error(URL contains dangerous character: ${char}`);
    }
  }
  
  return input;
}

2. 使用 URL 白名单

对于已知安全的 API
providers:
  web_fetch:
    whitelist:
      enabled: true
      urls:
        - "https://api.github.com/*"
        - "https://api.openai.com/*"
        - "https://docs.openclaw.ai/*"

3. 日志审计

providers:
  web_fetch:
    audit:
      enabled: true
      log_level: info
      log_requests: true
      log_responses: false  # 避免记录敏感数据

4. 监控和告警

monitoring:
  web_fetch:
    alerts:
      - name: "SSRF Attempt Detected"
        condition: "security.blocked_request_count > 0"
        action: "notify_admin"
      
      - name: "High Error Rate"
        condition: "error_rate > 0.1"
        action: "throttle_requests"

测试安全边界

安全测试用例

// tests/security/web-fetch.test.ts
describe('Web Fetch Security Boundaries', () => {
  it('should block private IP access', async () => {
    await expect(
      webFetch('http://192.168.1.1/')
    ).rejects.toThrow('Private IP access not allowed');
  });
  
  it('should block localhost access', async () => {
    await expect(
      webFetch('http://localhost:8080/')
    ).rejects.toThrow('Blocked host pattern: localhost');
  });
  
  it('should block file protocol', async () => {
    await expect(
      webFetch('file:///etc/passwd')
    ).rejects.toThrow('Protocol file not allowed');
  });
  
  it('should block suspicious URL encoding', async () => {
    await expect(
      webFetch('http://example.com%2F..%2Fadmin')
    ).rejects.toThrow('Invalid URL encoding');
  });
});

总结

Web Fetch Provider 边界强化 为 OpenClaw 带来了更强的安全防护：

1. URL 解析加固 — 严格遵循 RFC 标准，防止编码绕过
2. 请求边界控制 — 协议、主机、端口多层次限制
3. 响应边界控制 — 大小、类型双重限制
4. 可观测性 — 完整的审计日志和监控告警

关键配置：

providers:
  web_fetch:
    security:
      hardened_boundaries: true  # 启用安全强化

常见问题

Q: 启用边界强化后，原有功能会受影响吗？

A: 正常的外部 API 调用不会受影响。只有尝试访问内部网络或敏感资源的请求会被阻止。

Q: 如何临时禁用某个安全限制？

A: 不建议禁用，但可以添加例外规则：

security:
  hardened_boundaries: true
  exceptions:
    - host: "internal-api.company.com"
      reason: "Internal API access required"

Q: 误拦截了合法请求怎么办？

A:
1. 检查审计日志确认拦截原因
2. 如果是白名单中的 API，更新白名单配置
3. 如果是配置错误，调整 blocked_host_patterns

Q: 支持自定义安全策略吗？

A: 支持，可以通过配置文件自定义协议、端口、主机模式等限制。

Q: 对性能有影响吗？

A: 影响极小。URL 解析和验证在微秒级完成。

Q: 如何查看被拦截的请求？

A:

查看安全审计日志
tail -f ~/.openclaw/logs/security-audit.log | grep "BLOCKED"

统计拦截情况
openclaw stats web-fetch --security

参考来源

• OpenClaw Web Fetch 文档
• OWASP SSRF 防护指南
• RFC 3986 – URI 标准
• GitHub PR #59646

—

相关阅读：

• OpenClaw 安全加固指南
• Provider 安全配置
• 审计日志分析

OpenClaw 插件安全加固：Runtime Facade 激活保护机制详解

OpenClaw 在最新更新中引入了 Runtime Facade 激活保护机制，有效防止插件在激活过程中的潜在安全风险，提升整体系统稳定性。

本文将详细介绍这项安全加固措施的原理、实现方式以及对现有插件的影响。

目录

• 什么是 Facade 激活保护
• 为什么需要这项保护
• 技术实现细节
• 对现有插件的影响
• 最佳实践
• 常见问题

什么是 Facade 激活保护

Facade（外观模式） 是 OpenClaw 插件架构中的核心概念。它提供了一个统一的接口，让插件能够与 OpenClaw 核心进行交互。

激活过程的风险

在插件加载时，Facade 需要被激活以建立插件与核心的通信。这个过程如果缺乏保护，可能导致：

• 未授权访问 — 恶意插件在激活时执行危险操作
• 资源泄漏 — 激活失败时清理不当
• 系统不稳定 — 激活过程中的异常导致核心服务崩溃

保护机制概览

新的保护机制在 Facade 激活 阶段增加了安全检查：

插件加载 → 安全检查 → Facade 激活 → 受限运行 → 完整功能

为什么需要这项保护

安全场景分析

#### 场景 1: 恶意插件注入

// 恶意插件可能在激活时尝试
module.exports = {
  activate() {
    // 尝试访问受限 API
    const fs = require('fs');
    fs.writeFileSync('/etc/passwd', '...'); // 危险操作
  }
}

保护机制：激活阶段限制文件系统访问，阻止此类操作。

#### 场景 2: 激活失败资源泄漏

// 插件激活时创建资源，失败时未清理
module.exports = {
  activate() {
    this.server = createServer(); // 创建服务器
    throw new Error('激活失败');  // 异常退出，服务器未关闭
  }
}

保护机制：激活守卫确保失败时自动清理资源。

实际安全案例

在 Discord 和浏览器插件中发现的潜在问题：

• Discord 插件：清理线程解绑操作在激活守卫内，可能导致死锁
• 浏览器插件：清理辅助函数被错误地包含在激活守卫中

技术实现细节

1. 激活守卫（Activation Guard）

// plugin-sdk/runtime/facade.ts
export class PluginFacade {
  async activate(plugin: Plugin): Promise {
    // 进入激活守卫
    return await activationGuard(async () => {
      // 验证插件签名
      await this.verifyPluginSignature(plugin);
      
      // 限制环境下的初始化
      await plugin.activate(this.restrictedContext);
      
      // 验证激活结果
      this.validateActivationState();
    });
  }
}

2. 本地化 Facade 加载策略

config.yaml
plugins:
  security:
    facade:
      # 本地加载策略
      load_policy: localized
      
      # 激活守卫配置
      activation_guard:
        enabled: true
        timeout: 30000  # 30秒超时
        
      # 权限限制
      restricted_permissions:
        - fs_write
        - network_outbound
        - process_spawn

3. 清理操作的保护

修复了清理操作被错误包含在激活守卫中的问题：

// 修复前（有问题）
class BrowserPlugin {
  activate() {
    activationGuard(() => {
      this.setupBrowser();
      this.cleanup = () => {  // ❌ 清理不应该在守卫内
        this.browser.close();
      };
    });
  }
}

// 修复后（正确）
class BrowserPlugin {
  activate() {
    activationGuard(() => {
      this.setupBrowser();
    });
    
    // ✅ 清理操作在守卫外
    this.cleanup = () => {
      this.browser.close();
    };
  }
}

4. Discord 插件的修复

// discord/plugin.ts
export class DiscordPlugin {
  async activate() {
    await this.facade.activateGuard(async () => {
      await this.initializeBot();
    });
    
    // 清理操作移出守卫
    this.registerCleanup(() => {
      this.threadUnbind();  // ✅ 在线程外执行
    });
  }
}

5. 非零退出处理

浏览器插件现在能优雅处理清理失败：

async cleanup() {
  try {
    await this.browser.close();
  } catch (error) {
    // 非零退出时提供回退方案
    if (error.exitCode !== 0) {
      logger.warn('浏览器清理异常，使用强制终止');
      await this.browser.kill();
    }
  }
}

对现有插件的影响

需要检查的插件类型

| 插件类型 | 影响程度 | 检查重点 |
|———-|———-|———-|
| 浏览器自动化 | 高 | 清理操作位置 |
| Discord 集成 | 中 | 线程解绑逻辑 |
| 文件系统操作 | 中 | 激活阶段权限 |
| 网络请求 | 低 | 一般无影响 |

迁移检查清单

• [ ] 检查清理操作是否在激活守卫外
• [ ] 验证激活失败时的资源清理
• [ ] 测试插件在受限环境下的行为
• [ ] 更新插件 manifest 声明权限

最佳实践

1. 插件开发规范

// ✅ 推荐的插件结构
export default class MyPlugin {
  // 激活阶段 - 受限环境
  async activate(context: RestrictedContext) {
    // 只进行基本初始化
    this.config = await context.loadConfig();
    this.validateConfig();
  }
  
  // 完全激活后 - 正常环境
  async onReady(context: FullContext) {
    // 此时可以执行完整功能
    await this.initializeServices();
  }
  
  // 清理 - 确保在守卫外
  async deactivate() {
    await this.cleanup();
  }
}

2. 错误处理

async activate(context: Context) {
  try {
    await this.initialize();
  } catch (error) {
    // 激活失败时确保清理
    await this.cleanup();
    throw new ActivationError('插件激活失败', { cause: error });
  }
}

3. 权限声明

{
  "name": "my-plugin",
  "permissions": {
    "activation": ["config_read"],
    "runtime": ["network", "filesystem"]
  }
}

总结

Runtime Facade 激活保护 是 OpenClaw 插件安全的重要加固：

1. 激活阶段隔离 — 限制插件在初始化时的权限
2. 资源清理保证 — 失败时自动清理，防止泄漏
3. 清理操作分离 — 避免死锁和资源竞争
4. 非零退出处理 — 提供优雅的错误回退

下一步行动：
1. 检查你的自定义插件是否符合新规范
2. 更新插件声明权限
3. 测试插件在激活守卫下的行为

常见问题

Q: 这项更新会影响现有插件的运行吗？

A: 大多数插件不会受影响。只有那些在激活阶段执行敏感操作或清理逻辑不当的插件需要调整。

Q: 如何检查我的插件是否需要更新？

A: 运行 OpenClaw 的插件检查工具：

openclaw plugins check --compatibility

Q: 激活守卫的超时可以配置吗？

A: 可以，在 config.yaml 中调整：

plugins:
  security:
    facade:
      activation_guard:
        timeout: 60000  # 60秒

Q: 清理操作应该在什么时候注册？

A: 在 activate() 方法中注册，但确保回调函数在守卫外执行：

activate() {
  // 守卫内的初始化
  activationGuard(() => {
    this.resource = createResource();
  });
  
  // 守卫外的清理注册
  this.onDeactivate(() => {
    this.resource.close();
  });
}

Q: 如果插件在激活时超时怎么办？

A: 系统会自动终止激活过程并清理资源。建议：

• 将耗时操作移到 onReady 阶段
• 优化初始化逻辑
• 增加激活守卫超时时间

参考来源

• OpenClaw 插件 SDK 文档
• OpenClaw 安全加固指南
• Facade 模式设计模式
• GitHub PR #59412

—

相关阅读：

• OpenClaw 插件开发最佳实践
• 插件权限系统详解
• 安全审计指南

OpenClaw 2026.3.31-beta.1 升级指南：6个破坏性变更与9项安全增强详解

OpenClaw 2026.3.31-beta.1 是一次重大安全更新，包含6个破坏性变更和多项功能增强，显著提升了系统的安全性和可靠性。

本文将详细解析这些变更的影响，并提供完整的迁移指南，帮助你顺利升级。

目录

• 破坏性变更（Breaking Changes）
• 安全增强
• 功能改进
• 迁移指南
• 常见问题

破坏性变更（Breaking Changes）

1. 节点执行方式重构 ⚠️

变更内容：移除了 nodes.run shell 包装器，节点 shell 执行现在统一通过 exec host=node。

#### 影响

• 之前使用 nodes.run 执行 shell 命令的脚本需要修改
• 节点特定功能保留在 nodes invoke 和专用媒体/位置/通知操作中

#### 迁移方案

旧方式（已弃用）
nodes.run "ls -la"


新方式
exec host=node ls -la

#### 何时使用哪个命令？

• exec host=node — 在节点上执行 shell 命令
• nodes invoke — 调用节点特定功能（相机、位置、通知）

—

2. 插件 SDK 弃用警告 ⚠️

变更内容：弃用旧版提供程序兼容子路径和旧版捆绑提供程序设置。

#### 影响

• 使用旧版 SDK 路径的插件将看到迁移警告
• 未来主要版本将完全移除这些兼容层

#### 迁移方案

// 旧方式（已弃用）
import { ... } from 'openclaw/legacy-compat';


// 新方式
import { ... } from 'openclaw/plugin-sdk';
// 或本地 barrel
import { ... } from './api';
import { ... } from './runtime-api';

—

3. 危险代码扫描默认阻止 ⚠️

变更内容：内置危险代码 critical 发现和安装时扫描失败现在默认阻止安装。

#### 影响

• 之前可能成功安装的不安全插件现在会被阻止
• 需要显式覆盖才能继续安装

#### 迁移方案

如果遇到安装失败，显式覆盖（谨慎使用！）
openclaw skills install  --dangerously-force-unsafe-install


openclaw plugins install  --dangerously-force-unsafe-install

⚠️ 警告：仅在信任代码来源时使用此选项！

—

4. 可信代理认证强化 ⚠️

变更内容：trusted-proxy 现在拒绝混合共享令牌配置，本地直接回退需要配置令牌。

#### 影响

• 混合共享令牌配置将不再工作
• 同主机调用也需要显式配置令牌

#### 迁移方案

config.yaml
gateway:
  auth:
    trusted-proxy:
      - 127.0.0.1
      - 10.0.0.0/8
    tokens:
      - name: local
        token: ${LOCAL_TOKEN}  # 使用环境变量

—

5. 节点命令权限收紧 ⚠️

变更内容：节点命令现在保持禁用状态，直到节点配对被批准。

#### 影响

• 仅设备配对不再足以暴露声明的节点命令
• 需要在 OpenClaw Control UI 中明确批准

#### 迁移方案
1. 完成设备配对
2. 访问 OpenClaw Control UI
3. 在「节点管理」中批准该节点
4. 节点命令将自动启用

—

6. 节点事件权限限制 ⚠️

变更内容：节点发起的运行现在保持在减少的信任表面上。

#### 影响

• 通知驱动或节点触发的流程可能需要调整
• 之前依赖更广泛主机/会话工具访问的流程可能无法工作

#### 迁移方案

为节点触发的工作流显式配置权限
nodes:
  :
    permissions:
      tools:
        - notify
        - camera_snap
      sessions:
        - read

安全增强

7. ACPX 插件工具 MCP 桥接

新增显式默认关闭的 ACPX 插件工具 MCP 桥接配置：

acp:
  mcp-bridge:
    enabled: false  # 默认关闭，需显式启用
    trust-boundary: strict

8. 代码安装安全扫描强化

• 危险代码扫描现在失败关闭
• 安装时安全检查更加严格
• 新增 --dangerously-force-unsafe-install 覆盖选项

9. 可信代理认证安全

• 拒绝混合共享令牌配置
• 本地回退需要显式令牌
• 防止同主机隐式认证绕过

功能改进

10. Agent 空闲流超时

新增可配置的空闲流超时，防止模型流挂起：

agents:
  llm:
    idle-stream-timeout: 30000  # 30秒

11. MCP 工具增强

• 工具名称使用提供程序安全格式（serverName__toolName）
• 支持可选的 streamable-http 传输选择
• 每个服务器可配置连接超时
• 保留中止/错误轮次的真实工具结果

#### 配置示例

mcp:
  servers:
    my-server:
      transport: streamable-http
      timeout: 30000
      tools:
        naming: provider-safe  # serverName__toolName

12. Android 通知转发控制

新增通知转发控制功能：

• 包名过滤
• 安静时段设置
• 速率限制
• 更安全的选择器行为

nodes:
  android:
    notifications:
      forwarding:
        enabled: true
        package-filter:
          - com.whatsapp
          - com.telegram
        quiet-hours:
          start: "22:00"
          end: "08:00"
        rate-limit: 10  # 每分钟最大转发数

13. 后台任务控制平面重构

重大改进：将任务转变为真正的共享后台运行控制平面：

• 统一 ACP、子代理、cron 和后台 CLI 执行
• SQLite 支持的账本
• 分离生命周期更新路由
• 审计/维护/状态可见性
• 自动清理和丢失运行恢复
• 改进的任务感知

#### 查看任务状态

查看所有任务
openclaw tasks list


查看任务详情
openclaw tasks status 

任务审计日志
openclaw tasks audit

迁移指南

升级前检查清单

• [ ] 备份当前配置
• [ ] 检查是否有使用 nodes.run 的脚本
• [ ] 确认插件 SDK 导入路径
• [ ] 记录当前节点配对状态
• [ ] 检查是否有自定义安全覆盖

升级步骤

1. 备份配置
cp ~/.openclaw/config.yaml ~/.openclaw/config.yaml.backup

2. 更新 OpenClaw
docker pull openclaw/openclaw:2026.3.31-beta.1

3. 重启服务
docker restart openclaw

4. 检查日志
docker logs openclaw | grep -i "breaking\|deprecat\|warning"

5. 验证节点状态
openclaw nodes list

常见迁移问题

| 问题 | 原因 | 解决方案 |
|——|——|———-|
| 节点命令不工作 | 未批准配对 | 在 Control UI 中批准节点 |
| 插件安装失败 | 安全扫描 | 检查代码或显式覆盖 |
| shell 命令失败 | nodes.run 已移除 | 改用 exec host=node |
| 本地 API 401 | 可信代理变更 | 配置显式令牌 |

总结

OpenClaw 2026.3.31-beta.1 是一次以安全为核心的重大更新：

1. 6个破坏性变更 — 强化安全边界，减少攻击面
2. 后台任务重构 — 统一控制平面，提升可靠性
3. MCP 增强 — 更好的工具管理和传输支持
4. Android 通知 — 更细粒度的控制
5. 安装安全 — 默认阻止危险代码

下一步行动：
1. 在测试环境验证所有工作流
2. 按迁移指南逐步升级
3. 在 Control UI 中重新批准节点
4. 更新使用旧 SDK 路径的插件

常见问题

Q: 为什么节点命令突然不工作了？

A: 2026.3.31-beta.1 要求节点配对后显式批准才能使用节点命令：
1. 打开 OpenClaw Control UI（通常是 http://localhost:5678）
2. 进入「节点」页面
3. 找到你的设备，点击「批准」
4. 节点命令将自动恢复

Q: 如何安全地安装被阻止的插件？

A: 如果你有充分理由信任该插件，可以使用覆盖选项：

openclaw skills install  --dangerously-force-unsafe-install

⚠️ 仅在以下情况使用：

• 你自己开发的插件
• 来自官方或可信源的插件
• 已在隔离环境测试过

Q: nodes.run 和 exec host=node 有什么区别？

A:

• nodes.run — 已移除，旧版包装器
• exec host=node — 标准 shell 执行，推荐方式
• nodes invoke — 调用节点特定功能（相机、位置等）

Q: 后台任务重构对我有什么影响？

A: 主要改进：

• 更可靠的任务状态跟踪
• 统一的任务管理界面
• 更好的失败恢复
• 审计日志支持

使用 openclaw tasks 命令管理任务，之前通过 ACP 或 cron 启动的任务会自动迁移。

Q: 如何回退到之前的版本？

A:

停止当前容器
docker stop openclaw

启动旧版本（替换为之前的标签）
docker run -d --name openclaw \
  -v ~/.openclaw:/root/.openclaw \
  openclaw/openclaw:2026.3.30

恢复配置
cp ~/.openclaw/config.yaml.backup ~/.openclaw/config.yaml

Q: MCP 工具命名变更会影响现有配置吗？

A: 新的 serverName__toolName 格式是附加功能，不影响现有配置。但如果你希望使用显式服务器选择，可以更新配置：

mcp:
  naming: provider-safe  # 启用新格式

参考来源

• OpenClaw 官方文档
• OpenClaw GitHub Releases
• Model Context Protocol 规范
• OpenClaw 插件 SDK 文档
• 节点管理指南

—

相关阅读：

• OpenClaw 安全配置最佳实践
• 插件开发入门指南
• 后台任务管理详解
• MCP 集成教程

OpenClaw 2026.3.31-beta.1 升级指南：6个破坏性变更与9项安全增强详解

OpenClaw 2026.3.31-beta.1 是一次重大安全更新，包含6个破坏性变更和多项功能增强，显著提升了系统的安全性和可靠性。

本文将详细解析这些变更的影响，并提供完整的迁移指南，帮助你顺利升级。

目录

• 破坏性变更（Breaking Changes）
• 安全增强
• 功能改进
• 迁移指南
• 常见问题

破坏性变更（Breaking Changes）

1. 节点执行方式重构 ⚠️

变更内容：移除了 nodes.run shell 包装器，节点 shell 执行现在统一通过 exec host=node。

#### 影响

• 之前使用 nodes.run 执行 shell 命令的脚本需要修改
• 节点特定功能保留在 nodes invoke 和专用媒体/位置/通知操作中

#### 迁移方案

旧方式（已弃用）
nodes.run "ls -la"


新方式
exec host=node ls -la

#### 何时使用哪个命令？

• exec host=node — 在节点上执行 shell 命令
• nodes invoke — 调用节点特定功能（相机、位置、通知）

—

2. 插件 SDK 弃用警告 ⚠️

变更内容：弃用旧版提供程序兼容子路径和旧版捆绑提供程序设置。

#### 影响

• 使用旧版 SDK 路径的插件将看到迁移警告
• 未来主要版本将完全移除这些兼容层

#### 迁移方案

// 旧方式（已弃用）
import { ... } from 'openclaw/legacy-compat';


// 新方式
import { ... } from 'openclaw/plugin-sdk';
// 或本地 barrel
import { ... } from './api';
import { ... } from './runtime-api';

—

3. 危险代码扫描默认阻止 ⚠️

变更内容：内置危险代码 critical 发现和安装时扫描失败现在默认阻止安装。

#### 影响

• 之前可能成功安装的不安全插件现在会被阻止
• 需要显式覆盖才能继续安装

#### 迁移方案

如果遇到安装失败，显式覆盖（谨慎使用！）
openclaw skills install  --dangerously-force-unsafe-install


openclaw plugins install  --dangerously-force-unsafe-install

⚠️ 警告：仅在信任代码来源时使用此选项！

—

4. 可信代理认证强化 ⚠️

变更内容：trusted-proxy 现在拒绝混合共享令牌配置，本地直接回退需要配置令牌。

#### 影响

• 混合共享令牌配置将不再工作
• 同主机调用也需要显式配置令牌

#### 迁移方案

config.yaml
gateway:
  auth:
    trusted-proxy:
      - 127.0.0.1
      - 10.0.0.0/8
    tokens:
      - name: local
        token: ${LOCAL_TOKEN}  # 使用环境变量

—

5. 节点命令权限收紧 ⚠️

变更内容：节点命令现在保持禁用状态，直到节点配对被批准。

#### 影响

• 仅设备配对不再足以暴露声明的节点命令
• 需要在 OpenClaw Control UI 中明确批准

#### 迁移方案
1. 完成设备配对
2. 访问 OpenClaw Control UI
3. 在「节点管理」中批准该节点
4. 节点命令将自动启用

—

6. 节点事件权限限制 ⚠️

变更内容：节点发起的运行现在保持在减少的信任表面上。

#### 影响

• 通知驱动或节点触发的流程可能需要调整
• 之前依赖更广泛主机/会话工具访问的流程可能无法工作

#### 迁移方案

为节点触发的工作流显式配置权限
nodes:
  :
    permissions:
      tools:
        - notify
        - camera_snap
      sessions:
        - read

安全增强

7. ACPX 插件工具 MCP 桥接

新增显式默认关闭的 ACPX 插件工具 MCP 桥接配置：

acp:
  mcp-bridge:
    enabled: false  # 默认关闭，需显式启用
    trust-boundary: strict

8. 代码安装安全扫描强化

• 危险代码扫描现在失败关闭
• 安装时安全检查更加严格
• 新增 --dangerously-force-unsafe-install 覆盖选项

9. 可信代理认证安全

• 拒绝混合共享令牌配置
• 本地回退需要显式令牌
• 防止同主机隐式认证绕过

功能改进

10. Agent 空闲流超时

新增可配置的空闲流超时，防止模型流挂起：

agents:
  llm:
    idle-stream-timeout: 30000  # 30秒

11. MCP 工具增强

• 工具名称使用提供程序安全格式（serverName__toolName）
• 支持可选的 streamable-http 传输选择
• 每个服务器可配置连接超时
• 保留中止/错误轮次的真实工具结果

#### 配置示例

mcp:
  servers:
    my-server:
      transport: streamable-http
      timeout: 30000
      tools:
        naming: provider-safe  # serverName__toolName

12. Android 通知转发控制

新增通知转发控制功能：

• 包名过滤
• 安静时段设置
• 速率限制
• 更安全的选择器行为

nodes:
  android:
    notifications:
      forwarding:
        enabled: true
        package-filter:
          - com.whatsapp
          - com.telegram
        quiet-hours:
          start: "22:00"
          end: "08:00"
        rate-limit: 10  # 每分钟最大转发数

13. 后台任务控制平面重构

重大改进：将任务转变为真正的共享后台运行控制平面：

• 统一 ACP、子代理、cron 和后台 CLI 执行
• SQLite 支持的账本
• 分离生命周期更新路由
• 审计/维护/状态可见性
• 自动清理和丢失运行恢复
• 改进的任务感知

#### 查看任务状态

查看所有任务
openclaw tasks list


查看任务详情
openclaw tasks status 

任务审计日志
openclaw tasks audit

迁移指南

升级前检查清单

• [ ] 备份当前配置
• [ ] 检查是否有使用 nodes.run 的脚本
• [ ] 确认插件 SDK 导入路径
• [ ] 记录当前节点配对状态
• [ ] 检查是否有自定义安全覆盖

升级步骤

1. 备份配置
cp ~/.openclaw/config.yaml ~/.openclaw/config.yaml.backup

2. 更新 OpenClaw
docker pull openclaw/openclaw:2026.3.31-beta.1

3. 重启服务
docker restart openclaw

4. 检查日志
docker logs openclaw | grep -i "breaking\|deprecat\|warning"

5. 验证节点状态
openclaw nodes list

常见迁移问题

| 问题 | 原因 | 解决方案 |
|——|——|———-|
| 节点命令不工作 | 未批准配对 | 在 Control UI 中批准节点 |
| 插件安装失败 | 安全扫描 | 检查代码或显式覆盖 |
| shell 命令失败 | nodes.run 已移除 | 改用 exec host=node |
| 本地 API 401 | 可信代理变更 | 配置显式令牌 |

总结

OpenClaw 2026.3.31-beta.1 是一次以安全为核心的重大更新：

1. 6个破坏性变更 — 强化安全边界，减少攻击面
2. 后台任务重构 — 统一控制平面，提升可靠性
3. MCP 增强 — 更好的工具管理和传输支持
4. Android 通知 — 更细粒度的控制
5. 安装安全 — 默认阻止危险代码

下一步行动：
1. 在测试环境验证所有工作流
2. 按迁移指南逐步升级
3. 在 Control UI 中重新批准节点
4. 更新使用旧 SDK 路径的插件

常见问题

Q: 为什么节点命令突然不工作了？

A: 2026.3.31-beta.1 要求节点配对后显式批准才能使用节点命令：
1. 打开 OpenClaw Control UI（通常是 http://localhost:5678）
2. 进入「节点」页面
3. 找到你的设备，点击「批准」
4. 节点命令将自动恢复

Q: 如何安全地安装被阻止的插件？

A: 如果你有充分理由信任该插件，可以使用覆盖选项：

openclaw skills install  --dangerously-force-unsafe-install

⚠️ 仅在以下情况使用：

• 你自己开发的插件
• 来自官方或可信源的插件
• 已在隔离环境测试过

Q: nodes.run 和 exec host=node 有什么区别？

A:

• nodes.run — 已移除，旧版包装器
• exec host=node — 标准 shell 执行，推荐方式
• nodes invoke — 调用节点特定功能（相机、位置等）

Q: 后台任务重构对我有什么影响？

A: 主要改进：

• 更可靠的任务状态跟踪
• 统一的任务管理界面
• 更好的失败恢复
• 审计日志支持

使用 openclaw tasks 命令管理任务，之前通过 ACP 或 cron 启动的任务会自动迁移。

Q: 如何回退到之前的版本？

A:

停止当前容器
docker stop openclaw

启动旧版本（替换为之前的标签）
docker run -d --name openclaw \
  -v ~/.openclaw:/root/.openclaw \
  openclaw/openclaw:2026.3.30

恢复配置
cp ~/.openclaw/config.yaml.backup ~/.openclaw/config.yaml

Q: MCP 工具命名变更会影响现有配置吗？

A: 新的 serverName__toolName 格式是附加功能，不影响现有配置。但如果你希望使用显式服务器选择，可以更新配置：

mcp:
  naming: provider-safe  # 启用新格式

参考来源

• OpenClaw 官方文档
• OpenClaw GitHub Releases
• Model Context Protocol 规范
• OpenClaw 插件 SDK 文档
• 节点管理指南

—

相关阅读：

• OpenClaw 安全配置最佳实践
• 插件开发入门指南
• 后台任务管理详解
• MCP 集成教程