⏱️ 执行超时保护机制

执行超时保护（Exec Timeout Protection）是AI Agent系统中防止任务无限运行的核心安全机制。v2026.6.6版本将超时从"建议"升级为"强制"。

📖 定义

执行超时保护确保每个工具调用、脚本执行或Agent任务都有明确的时间边界：

• 硬超时：达到上限后强制终止（fail-closed）
• 软超时：达到阈值后发出警告
• 级联超时：父任务超时自动终止所有子任务

⚙️ 核心原理

1. 超时层级架构

超时配置层级:
├── 全局超时 (Global)
│   └── 默认: 300s (5分钟)
├── 工具超时 (Tool)
│   ├── read: 10s
│   ├── write: 30s
│   ├── exec: 60s
│   └── browser: 120s
├── 任务超时 (Task)
│   └── 自定义: 0-3600s
└── 级联超时 (Cascade)
    └── 子任务继承父任务剩余时间

2. 超时触发流程

# 超时处理流程 (v2026.6.6)
┌─────────────────────────────────────┐
│  任务开始                           │
│  ↓                                  │
│  检查超时配置                       │
│  ↓                                  │
│  执行中... 定期检查剩余时间         │
│  ↓                                  │
│  [正常完成] → 返回结果              │
│  [超时触发] → 执行Fail-Closed策略   │
│      ├── 终止进程 (SIGTERM → SIGKILL)│
│      ├── 清理资源                   │
│      ├── 记录日志                   │
│      └── 返回错误码                 │
└─────────────────────────────────────┘

3. 配置示例

# ~/.openclaw/config.yaml
exec:
  # 全局默认超时
  defaultTimeout: 60s
  
  # Fail-Closed模式
  failClosed: true
  
  # 超时后动作
  onTimeout: kill  # kill | continue | retry
  
  # 工具特定超时
  toolTimeouts:
    read: 10s
    write: 30s
    exec: 120s
    browser: 180s
    web_fetch: 30s
  
  # 资源限制
  limits:
    maxMemory: 512MB
    maxCpu: 80%
    maxProcesses: 10

🔧 OpenClaw实战应用

场景1: 防止npm install无限卡住

# 问题: npm install有时会卡在网络请求
$ openclaw exec "npm install" --timeout 120

# v2026.6.6行为:
# - 120秒后强制终止
# - 返回错误码 ETIMEOUT
# - 清理node_modules残留
# - 日志记录超时原因

# 配置文件方式
exec:
  commands:
    "npm install":
      timeout: 120s
      retries: 1  # 失败后重试1次

场景2: 浏览器自动化超时

# Playwright任务
$ openclaw browser navigate "https://slow-site.com" --timeout 30

# 超时策略:
# - 页面加载: 30s
# - 元素等待: 10s
# - 脚本执行: 15s
# - 总任务: 60s

browser:
  timeouts:
    navigation: 30s
    element: 10s
    script: 15s
    total: 60s

场景3: 子任务级联超时

# 父任务配置
task:
  name: "批量处理"
  timeout: 300s  # 5分钟
  
# 子任务自动继承
subtasks:
  - name: "任务1"
    # 自动获得: min(自定义超时, 父任务剩余时间)
  - name: "任务2"
    timeout: 120s  # 会被限制为 min(120s, 剩余时间)

# 级联终止: 父任务超时 → 所有子任务立即终止

📊 超时策略对比

策略	适用场景	风险
无超时	开发调试	🔴 无限循环风险
软超时	非关键任务	🟡 可能资源泄漏
硬超时(Fail-Closed)	生产环境	🟢 安全可控

💡 最佳实践

🔗 相关概念

• Fail-Closed执行 - 安全执行模式
• 沙箱执行 - 隔离环境
• 资源限制 - 内存/CPU限制

📅 最后更新: 2026-06-13 | 🏷️ 标签: 超时 安全 OpenClaw v2026.6.6