ACP Transcript Sync#

ACP 子会话完成后，将子会话内容回写到主会话 transcript，让 AIMA 平台能通过采集主会话看到完整链路。

标准流程#

1. Spawn ACP 子会话#

text

sessions_spawn({ runtime: "acp", agentId: "<agentId>", task: "<任务描述>" })

记录返回的 childSessionKey 和完成后的 session_id。

2. 等待子会话完成#

子会话完成后会自动推送完成通知。收到通知后执行回写。

3. 执行回写脚本#

bash

python3 <skill-dir>/scripts/sync-acp-to-main.py <acp_session_id> <acp_agent> [<main_session_id>] [<main_agent>]

参数说明：

参数必填说明acp_session_id✅ACP 子会话的 UUID（从完成通知或 sessions_list 获取）acp_agent✅ACP agent 的 ID，如 cfuse、 claude、 codexmain_session_id❌主会话 UUID，不传则自动找最新的主会话main_agent❌主 agent ID，不传则自动检测

示例：

bash

# 指定所有参数
python3 scripts/sync-acp-to-main.py f935963c-b8dd-431c-9d85-85e0e5a41341 cfuse 44c3f987-f9ad-4a02-b107-768ae9f517d3

# 自动检测主会话和主 agent
python3 scripts/sync-acp-to-main.py f935963c-b8dd-431c-9d85-85e0e5a41341 cfuse

4. 验证回写#

bash

# 查看主会话最后几条消息
tail -5 ~/.openclaw/agents/<main_agent>/sessions/<main_session_id>.jsonl | python3 -c "
import sys, json
for line in sys.stdin:
    d = json.loads(line)
    if d.get('type') == 'message':
        msg = d.get('message', {})
        content = msg.get('content', [])
        text = ''.join(c.get('text','') for c in content if c.get('type')=='text')
        print(f'[{msg.get(\"role\")}] {text[:100]}')
"

回写格式#

回写内容以 [xxx推理过程] 为前缀标识来源，xxx 是具体的 agent 名称：

• 📋 cfuse推理过程 — 标记消息
• [cfuse推理过程] user — 子会话中的用户输入
• [cfuse推理过程] assistant — 子会话中 agent 的回复

不同 agent 示例：

• cfuse → [cfuse推理过程]
• claude code → [claude code推理过程]
• codex → [codex推理过程]

获取 sessionId 的方法#

子会话完成后需要获取其 sessionId，有三种方式：

1. 完成通知：子会话完成后 OpenClaw 会推送完成事件，其中包含 session_id
2. sessions_list： sessions_list({ label: "acp" }) 过滤 ACP 会话
3. subagents： subagents({ action: "list" }) 查看子会话状态和 sessionKey

从 sessionKey（格式 agent:<agentId>:acp:<uuid>）中，实际的 transcript 文件名（sessionId）可能不同于 key 中的 uuid。需要通过 sessions_list 获取 sessionId 字段。

完整自动化模式#

将回写步骤集成到 spawn 流程中：

1. sessions_spawn({ runtime: "acp", agentId: "cfuse", task: "..." })
2. 等待完成通知
3. 从通知中提取 session_id 和 agentId
4. exec 执行回写脚本
5. 完成

关键规则：每次 spawn ACP 子会话后， 必须 执行回写，否则 AIMA 平台无法采集子会话内容。

故障排查#

问题原因解决ACP 子会话不存在sessionId 错误或 transcript 已被清理检查 sessionId，确认文件存在主会话为空主会话 transcript 文件无消息检查 main_session_id 是否正确ACP 子会话没有有效消息子会话未产生有效输出检查子会话是否真的执行了任务回写后 AIMA 看不到AIMA 尚未重新采集等待 AIMA 下次采集周期