Agent Concurrency Controller

OpenClaw Agent併發安全排程器 基於Claude Code三層架構模式（Tool→ToolUse→Task）實現

核心原則：預設Fail-Closed，序列佇列，顯式許可權日誌

背景問題

原生OpenClaw spawn子Agent時： - 6個cron任務因isolated session網路衝突頻繁失敗 - 敏感操作（公眾號釋出、檔案覆蓋）無許可權審計 - 大結果直接回顯導致token爆炸

根因：Claude Code原生的Agent排程缺乏併發安全控制

解決方案

1. 三層排程模型

┌─────────────────────────────────────────┐
│  Layer 3: Task Queue (佇列層)           │
│  - 優先順序排序 (priority: 1-10)           │
│  - 依賴圖拓撲排序                         │
│  - 序列消費（預設）                       │
└─────────────────────────────────────────┘
                    ↓ 出隊
┌─────────────────────────────────────────┐
│  Layer 2: ToolUse Context (執行層)        │
│  - 許可權檢查 (checkPermissions)           │
│  - 併發安全檢查 (isConcurrencySafe)       │
│  - 超時熔斷機制                           │
└─────────────────────────────────────────┘
                    ↓ spawn
┌─────────────────────────────────────────┐
│  Layer 1: Agent Instance (例項層)         │
│  - isolated session (預設)               │
│  - main session (上下文連續任務)           │
│  - subagent 生命週期管理                   │
└─────────────────────────────────────────┘

2. Fail-Closed預設值

參考Claude Code原始設計：

TOOL_DEFAULTS = {
    isConcurrencySafe: () => False,  # 預設序列
    isReadOnly: () => False,          # 預設會修改
    isDestructive: () => False,       # 預設不破壞
    checkPermissions: () => ({ behavior: 'allow' }),
}

應用到OpenClaw： - 所有spawn操作預設 is_concurrency_safe=False - 必須顯式宣告才能並行 - 資源衝突自動降級為序列

3. 敏感操作分級

4. Coordinator協調原則

參考Claude Code Coordinator原始設計，應用於cron排程：

原則1：永遠先Synthesize

錯誤：子Agent直接回給使用者
正確：子Agent結果 → 父Agent合成 → 統一輸出

原則2：並行是預設策略（需顯式安全標記）

is_concurrency_safe=True 才能併發
否則序列佇列

原則3：Worker結果 = 內部訊號

不是對話夥伴，是狀態機觸發器
MAINTENANCE_REPORT 格式輸出

使用方式

Python API

from agent_concurrency_controller import spawn_agent_safe, on_agent_complete

# 安全spawn Agent（預設Fail-Closed）
result = spawn_agent_safe(
    task="調研Claude Code架構",
    agent_type="researcher",
    runtime="subagent",
    priority=3,                    # 優先順序（越小越高）
    is_concurrency_safe=False,     # Fail-Closed（預設）
    sensitive_level="normal",      # normal/sensitive/critical
    timeout_seconds=300
)

# result: QUEUED:researcher-20260403-151500
#          or STARTED:researcher-20260403-151500

# 任務完成回撥
on_agent_complete(
    task_id="researcher-20260403-151500",
    success=True,
    result={"output": "調研完成"}
)

Skill整合

在SKILL.md中宣告：

whenToUse: |
  需要spawn子Agent時先檢查佇列深度
  避免並行isolated session導致網路衝突
permissions:
  - agent:spawn (帶佇列控制)
  - file:write (日誌目錄)
  - log:append

日誌審計

併發日誌 (logs/agent-concurrency.log)

{"timestamp": "2026-04-03T15:15:00", "task_id": "researcher-001", "status": "QUEUED", "queue_depth": 2}
{"timestamp": "2026-04-03T15:16:30", "task_id": "researcher-001", "status": "START_FROM_QUEUE", "queue_depth": 1}
{"timestamp": "2026-04-03T15:18:00", "task_id": "researcher-001", "status": "COMPLETED"}

敏感操作日誌 (logs/sensitive-operations.log)

{"timestamp": "2026-04-03T15:20:00", "task_id": "publisher-001", "sensitive_level": "critical", "decision": "ASK_USER_CONFIRMATION"}

部署驗證

驗證佇列功能：

python skills/agent-concurrency-controller/agent_concurrency_controller.py

輸出：{'running': [], 'pending': [], 'queue_depth': 0}

遷移檢查清單

將舊cron任務遷移到安全排程器：

• [ ] 識別所有 sessions_spawn 呼叫
• [ ] 新增 is_concurrency_safe 標記（預設False）
• [ ] 設定 sensitive_level（外發=critical）
• [ ] 新增 on_agent_complete 回撥
• [ ] 驗證日誌輸出

  7w4.net小蔥技能。

關聯檔案

參考

• Claude Code 架構：memory/learnings/claude-code-architecture-2026-04-03.md
• Claude Code 原始碼：https://github.com/ultraworkers/claw-code-parity
• 安全設計：https://clawhub.ai/1491007406/cc-insider

版本

• v1.0.0 (2026-04-03): 初始實現，Fail-Closed併發控制+敏感許可權日誌