---
title: "Sub-Agent Race Condition"
type: concept
tags: [multi-agent, concurrency, engineering-pitfall]
sources: [overnight-mini-app-builder]
last_updated: 2026-04-22
---

## Definition

多子代理并发编辑共享文件时导致的竞态条件。当主会话和子代理同时尝试修改同一文件（如 AUTONOMOUS.md/Kanban 状态文件）时，由于 `edit` 工具要求精确的 `oldText` 匹配，子代理在主会话读取和编辑之间的窗口期内更新了文件内容，导致 `oldText` 失效，`edit` 操作静默失败。

## Aliases

- Race Condition
- 并发编辑冲突
- Silent Edit Failure

## Root Cause

OpenClaw 的 `edit` 工具依赖精确字符串匹配（exact `oldText` match）。在多 Agent 并发场景下：
1. 主会话读取文件 → 内存中为旧版本
2. 子代理修改同一文件 → 磁盘版本已更新
3. 主会话尝试 `edit(oldText=旧版本)` → 匹配失败 → **静默失败**

## Solution: Git-Style Append-Only Pattern

参考 Git 的"不重写历史"原则，将任务文件分为两类：

| 文件 | 角色 | 谁可写 |
|------|------|--------|
| `AUTONOMOUS.md` | 状态文件（目标 + 开放待办） | **仅主会话** |
| `memory/tasks-log.md` | 追加日志（已完成任务） | **所有子代理（只追加）** |

```markdown
# tasks-log.md — Completed Tasks (append-only)
# Sub-agents: always append to the END. Never edit existing lines.

### 2026-02-24
- ✅ TASK-001: Research competitors → research/competitors.md
- ✅ TASK-002: Draft blog post → drafts/post-1.md
```

子代理 spawn 指令中必须包含：
> "When done, append a ✅ line to `memory/tasks-log.md`. Never edit `AUTONOMOUS.md` directly."

## Key Relationships

- [[GitAsAuditLog]] — 本模式的概念来源，Git 的追加提交哲学
- [[SharedStateCoordination]] — 共享状态协调的通用概念
- [[overnight-mini-app-builder]] — 本模式的来源场景