你的subagent明明跑成功了，结果文件却消失了？这不是你的问题——6月14日社区刚修了一个导致subagent结果静默丢失的bug。本文给你完整的修复方案、配置模板和排障清单。

问题背景：Subagent 的「幽灵成功」

多Agent协作是2026年AI工具链的核心能力。OpenClaw 的 subagent 机制让你可以派生子任务给独立Agent执行，大幅提升复杂任务的处理效率。

但有一个坑困扰了不少用户：subagent 返回 success，输出文件路径也正常，但打开文件一看——空的，或者根本没有。

6月14日，社区贡献者 @zhang-guiping 提交了 fix #92642，精准定位了这个bug：

"Subagent run reports success but fails to write output file"

issue编号 #86872，修复提交 #92642。问题的根因是：subagent 在 session 隔离环境下执行时，文件写入路径解析存在竞态条件——subagent 认为写入成功了，但实际文件落到了错误的 session 目录下，主Agent完全看不到。

这个修复已在 OpenClaw 最新提交中合并。如果你在使用 OpenClaw 的多Agent协作，请确保你的版本包含此修复。

快速检查：你的版本有没有这个问题？

在终端执行：

# 检查 OpenClaw 版本
openclaw --version

# 查看最近的提交日志（如果是源码构建）
cd /path/to/openclaw
git log --oneline --since="2026-06-13" | grep -i "subagent\|92642\|86872"

如果看到类似以下提交，说明修复已包含：

d0851435 fix #86872: Subagent run reports success but fails to write output file (#92642)

如果是二进制安装或 Docker 部署，检查版本号 ≥ v2026.6.8-beta.1 即可。

Subagent 配置模板（可直接复制）

以下是经过实战验证的 OpenClaw subagent 配置模板。保存为 subagent-config.yaml：

# OpenClaw Subagent 配置模板 v1.0
# 适用版本: OpenClaw ≥ v2026.6.8-beta.1

subagents:
  # === 代码审查 Subagent ===
  code-reviewer:
    description: "审查代码变更，检查安全漏洞和最佳实践"
    tools:
      - read_file
      - search_files
      - shell  # 允许运行 linter
    timeout: 300  # 5分钟超时
    max_iterations: 10
    output:
      path: "/tmp/openclaw/outputs/code-review-{timestamp}.md"
      format: markdown
    context:
      max_tokens: 8000
      system_prompt: |
        你是一个代码审查专家。请检查以下代码的：
        1. 安全漏洞（SQL注入、XSS、路径遍历）
        2. 性能问题（N+1查询、内存泄漏）
        3. 最佳实践偏离
        输出格式：每个问题标注严重程度（🔴/🟡/🟢）和修复建议。

  # === 数据研究 Subagent ===
  data-researcher:
    description: "搜索和汇总外部数据"
    tools:
      - web_search
      - web_extract
      - write_file
    timeout: 600  # 10分钟（网络请求较慢）
    max_iterations: 15
    output:
      path: "/tmp/openclaw/outputs/research-{task_id}.md"
      format: markdown
    context:
      max_tokens: 16000
      system_prompt: |
        你是数据研究员。请完成以下任务：
        1. 搜索指定主题的最新信息
        2. 从至少3个独立来源交叉验证数据
        3. 输出结构化报告，包含：核心发现、数据来源、可信度评估

  # === 内容排版 Subagent ===
  content-formatter:
    description: "将原始内容格式化为目标输出格式"
    tools:
      - read_file
      - write_file
      - patch
    timeout: 180
    max_iterations: 5
    output:
      path: "/tmp/openclaw/outputs/formatted-{timestamp}.html"
      format: raw
    context:
      max_tokens: 4000

在 OpenClaw 中调用 Subagent

方式一：CLI 直接调用

# 启动代码审查 subagent
openclaw subagent run code-reviewer \
  --input "审查 ./src/api/ 目录下的所有Python文件" \
  --output "/tmp/openclaw/outputs/code-review-$(date +%s).md"

# 检查输出是否成功写入
ls -la /tmp/openclaw/outputs/
cat /tmp/openclaw/outputs/code-review-*.md

方式二：在 OpenClaw Skill 中调用

# ~/.openclaw/skills/multi-agent-workflow.yaml
name: multi-agent-workflow
description: 多Agent协作工作流——研究→审查→格式化

steps:
  - name: research
    subagent: data-researcher
    prompt: "搜索 {topic} 的最新信息和数据"
    output_var: research_result

  - name: review
    subagent: code-reviewer
    input: "{research_result}"
    prompt: "审查研究报告的准确性和完整性"
    output_var: review_result

  - name: format
    subagent: content-formatter
    input: "{review_result}"
    prompt: "将审核后的报告格式化为公众号文章HTML"
    output_file: "/tmp/openclaw/outputs/final-article.html"

方式三：Python SDK 调用

import openclaw
import time

client = openclaw.Client()

# 启动 subagent 任务
task = client.subagent.run(
    name="data-researcher",
    prompt="搜索2026年6月AI Agent工具的最新发展",
    output_path="/tmp/openclaw/outputs/research-20260614.md",
    timeout=600
)

# 等待完成并验证输出
result = client.subagent.wait(task.id, timeout=600)
if result.status == "success":
    # 🆕 修复后的验证逻辑
    output = client.subagent.get_output(task.id)
    if output and len(output) > 50:
        print(f"✅ Subagent 输出验证通过: {len(output)} 字符")
    else:
        print("⚠️ 输出文件为空或不存在，检查路径和权限")
else:
    print(f"❌ Subagent 失败: {result.error}")

Subagent 最佳实践（5条硬核经验）

1. 输出路径必须使用绝对路径

❌ 错误做法：

output:
  path: "./outputs/result.md"  # 相对路径，subagent的pwd可能不同

✅ 正确做法：

output:
  path: "/tmp/openclaw/outputs/result.md"  # 绝对路径，session透明可见

原因：subagent 运行在独立 session 中，其工作目录可能与主Agent不同。相对路径会导致文件写入subagent的session临时目录，主Agent无法访问。

2. 输出完成后必须显式验证

不要信任 subagent 的 "success" 返回码。在 v2026.6.8-beta.1 之前，subagent 可能返回 success 但文件未写入。养成这个习惯：

def verify_subagent_output(path, min_bytes=50):
    """验证 subagent 输出文件是否实际存在且内容充足"""
    import os
    if not os.path.exists(path):
        raise FileNotFoundError(f"输出文件不存在: {path}")
    size = os.path.getsize(path)
    if size < min_bytes:
        raise ValueError(f"输出文件过小: {size} 字节（预期 ≥ {min_bytes}）")
    with open(path, 'r') as f:
        content = f.read()
    print(f"✅ 输出验证通过: {path} ({size} 字节)")
    return content

3. 合理设置超时：task复杂度 × 工具调用预算

任务类型	建议超时	原因
文件读写	120s	本地操作，快速完成
代码审查	300s	需要阅读多个文件
网络搜索	600s	外部API调用耗时不稳定
多步推理	900s	可能有多轮工具调用

经验公式：timeout ≥ (max_iterations × 30s) + 缓冲60s

4. Subagent 的工具集越小越好

❌ 错误：给所有 subagent 开放全部工具

tools:
  - "*"  # 危险！subagent可能执行意外操作

✅ 正确：只给完成特定任务所需的最少工具

tools:
  - read_file
  - write_file
  - search_files
  # 不给 shell、web_search 等不需要的工具

安全原则：subagent 是"最小权限原则"的最佳实践场景。每个 subagent 只能做它被指定要做的事。

5. 输出格式尽量简单

❌ 复杂输出结构：

output:
  path: "/tmp/{task_id}/{timestamp}/{format}/result.{ext}"
  format: structured_json_with_metadata

✅ 简单可靠：

output:
  path: "/tmp/openclaw/outputs/{task_name}-{timestamp}.md"
  format: markdown

原因：复杂的输出路径和格式增加了文件系统操作的失败概率。保持简单——你可以在主Agent中对markdown输出进行后处理。

常见排障清单

症状	可能原因	解决方案
subagent success，文件为空	#86872 bug	升级到 ≥ v2026.6.8-beta.1
subagent success，文件不存在	相对路径问题	改用绝对输出路径
subagent超时但文件部分存在	timeout设置过低	增大timeout，参考公式
主Agent读不到subagent的输出	session隔离	输出到`/tmp/openclaw/outputs/`共享目录
subagent报权限错误	输出目录不可写	`mkdir -p /tmp/openclaw/outputs && chmod 777`
多次调用同一subagent结果互相覆盖	文件名冲突	使用`{timestamp}`或`{task_id}`变量

验证你的修复是否生效

运行以下测试脚本，确认你的 OpenClaw 版本已包含修复：

#!/bin/bash
# subagent-output-test.sh — 验证 #92642 修复是否生效

OUTPUT_DIR="/tmp/openclaw/outputs"
mkdir -p "$OUTPUT_DIR"
OUTPUT_FILE="$OUTPUT_DIR/test-subagent-$(date +%s).md"

echo "🧪 测试 OpenClaw Subagent 输出修复..."

openclaw subagent run data-researcher \
  --prompt "写一句话：Subagent输出测试通过" \
  --output "$OUTPUT_FILE" \
  --timeout 120

if [ -f "$OUTPUT_FILE" ] && [ -s "$OUTPUT_FILE" ]; then
    echo "✅ 修复验证通过！输出文件存在且非空"
    echo "📄 内容预览:"
    head -3 "$OUTPUT_FILE"
else
    echo "❌ 输出文件不存在或为空——你的版本可能仍有 #86872 bug"
    echo "💡 解决方案: 升级 OpenClaw 到最新版本"
fi

# 清理
rm -f "$OUTPUT_FILE"

总结

OpenClaw 的 subagent 机制是多Agent协作的核心能力，但输出丢失问题一直是个隐雷。6月14日的 #92642 修复解决了一个关键的竞态条件bug。

三个关键行动：
1. 立即检查版本：确保 ≥ v2026.6.8-beta.1
2. 应用配置模板：使用绝对路径 + 验证逻辑
3. 养成验证习惯：永远不要假设 subagent 的 success 返回码等于输出文件可用

你的 subagent 工作流越复杂，输出验证就越重要。花5分钟加上验证逻辑，能省下几小时的排障时间。

AI创业 #Agent工坊 #OpenClaw #Subagent #多Agent协作