design-image-prompt-engineer 为什么 spawn 失败？一次 OpenClaw agent 注册机制的深度排查

本文记录了 blog-pipeline 流水线中 design-image-prompt-engineer spawn 失败的完整排查过程。如果你也遇到过"这个 agent 明明配置了、allowAgents 里也有、但 sessions_spawn 就是报 not in registry"的问题，这篇文章会帮你理解 OpenClaw 的 agent 注册机制。

一、背景：blog-pipeline 的一次正常执行

今天的任务是用 blog-pipeline 完整流程写一篇博客。流水线涉及多个专业 agent：

kb-writer（写稿）→ editor-blog-yuntianchen（质检）→ marketing-seo-specialist（SEO）
→ design-image-prompt-engineer（配图提示词）→ design-yuntianguang（生图）

整个流程的前几个阶段（写稿、质检、SEO）都顺利通过了。但在 Phase 3.5（配图提示词生成）阶段，第一个 sessions_spawn 调用就失败了。

二、症状：在 allowAgents 里的 agent spawn 失败

报错信息

"agentId \"design-image-prompt-engineer\" is not in the configured agent registry
(allowed: agents-orchestrator, audio-yuntianlai, chief-yuntian, ...)"

初步检查

按经验，先查 openclaw.json 的 allowAgents 列表：

// ~/.openclaw/openclaw.json → agents.defaults.subagents.allowAgents
// 共 31 个，design-image-prompt-engineer 在第 30 位
{
  "agents-orchestrator", "audio-yuntianlai", "business-strategist",
  ...
  "design-image-prompt-engineer"
}

design-image-prompt-engineer 确实在 allowAgents 里。按常理，它在白名单里应该可以 spawn 才对。

但报错信息的 allowed: 列表只有 16 个 agent，且不包含 design-image-prompt-engineer。

三、排查过程：从 surface error 到源码级分析

第一轮排查：allowAgents ≠ allowed

报错信息的 allowed 列表（16个）和配置中的 allowAgents（31个）不一致。怀疑配置没有正确加载，但验证确认 openclaw.json 中确实有 31 个。

第二轮排查：sessions_spawn 到底检查了什么？

查看 OpenClaw 源码 openclaw-tools-CIBcX9Ku.js：

const allowAgents = resolveAgentConfig(cfg, requesterAgentId)?.subagents?.allowAgents
  ?? cfg?.agents?.defaults?.subagents?.allowAgents;
const configuredAgentIds = resolveConfiguredAgentIds(cfg);
const allowed = resolveSubagentAllowedTargetIds({
  requesterAgentId,
  allowAgents,
  configuredAgentIds
});

关键发现：sessions_spawn 用了 两个参数 做检查：

1. allowAgents（来自配置）
2. configuredAgentIds（来自另一个来源）

第三轮排查：configuredAgentIds 到底是什么？

function resolveConfiguredAgentIds(cfg) {
  return listAgentIds(cfg);
}

function listAgentIds(cfg) {
  const agents = listAgentEntries(cfg);
  // ...
}

function listAgentEntries(cfg) {
  const list = cfg.agents?.list;
  if (!Array.isArray(list)) return [];
  return list.filter((entry) => entry !== null && typeof entry === "object");
}

listAgentEntries 读的是 cfg.agents.list，不是 allowAgents。这是两个不同的列表。

第四轮排查：两个列表的差异

agents.list (27个)       allowAgents (31个)
─────────────────       ─────────────────
main                     agents-orchestrator
chief-yuntian             audio-yuntianlai
academic-narratologist    business-strategist
agents-orchestrator       chief-financial-officer
oc-engineer               chief-yuntian
design-yuntianguang       data-consolidation-agent
writer-yuntianfeng        debt-rebirth-oklife
editor-yuntianyue         design-ux-researcher
fq-short-yuntianmo        design-yuntianguang
scout-yuntianhuo          editor-yuntianyue
marketing-book-co-author  fq-short-yuntianmo
marketing-content-creator kb-manager
pub-yuntianxing           kb-writer
audio-yuntianlai          marketing-book-co-author
kb-manager                marketing-content-creator
kb-writer                 marketing-seo-specialist
debt-rebirth-oklife       oc-engineer
                         pub-yuntianxing
                         scout-yuntianhuo
                         specialized-document-generator
                         writer-yuntianfeng
                         agent-ops
                         search-scout-yuntianyan
                         editor-blog-yuntianchen
                         design-image-prompt-engineer

agents.list 有但不在 allowAgents 的（7个）： main、academic-narratologist、engineering-technical-writer、technical-translator-agent、language-translator、report-distribution-agent、grant-writer

allowAgents 有但不在 agents.list 的（11个）： business-strategist、chief-financial-officer、data-consolidation-agent、design-ux-researcher、marketing-growth-hacker、product-feedback-synthesizer、product-manager、product-trend-researcher、specialized-risk-assessor、support-analytics-reporter、agent-ops

第五轮排查：filterConfiguredAllowedIds 的真相

function filterConfiguredAllowedIds(params) {
  const configuredIds = normalizeConfiguredAgentIds(params.configuredAgentIds);
  // ← 把 configuredAgentIds 转成 Set
  return params.allowedIds.filter((id) => configuredIds.has(id));
  // ← 只保留两边都有的 ID
}

sessions_spawn 实际的可用 agent 列表 = allowAgents ∩ agents.list

design-image-prompt-engineer 在 allowAgents（31个）里，但 不在 agents.list（27个） 里。所以被 filterConfiguredAllowedIds 静默过滤掉了。

四、根因：OpenClaw 的 agent 注册机制

OpenClaw 的 agent 系统由两个列表共同控制：

关键机制：sessions_spawn 对这两个列表取交集。只有同时出现在两个列表中的 agent 才能被 spawn。

可 spawn 的 agent = agents.list ∩ allowAgents

design-image-prompt-engineer 只被添加到了 allowAgents，但没添加到 agents.list，所以虽然白名单里有它，实际 spawn 时被过滤掉了。

**根本原因是: 我忘记把 design-image-prompt-engineer 添加到当下使用的写作场景的/home/oklife/.openclaw/scenes/writing.json文件的agent列表里了。 导致使用python3 ~/.openclaw/scenes/switch-scene.py writing切换场景命令时，openclaw.json → agents.list没有design-image-prompt-engineer

五、修复方案

实际修复方案：

将 design-image-prompt-engineer 添加到 /home/oklife/.openclaw/scenes/writing.json文件的agent列表里， 然后在终端执行：

python3 ~/.openclaw/scenes/switch-scene.py writing

重新生成agents.list包含design-image-prompt-engineer的openclaw.json文件，重启网关即可。

正确的/home/oklife/.openclaw/scenes/writing.json文件的agent列表：

[
  "kb-writer",
  "search-scout-yuntianyan",
  "editor-blog-yuntianchen",
  "marketing-seo-specialist",
  "design-image-prompt-engineer",
  "design-yuntianguang",
  "pub-yuntianxing",
  "main",
  "chief-yuntian",
  "debt-rebirth-oklife",
  "oc-engineer",
  "writer-yuntianfeng",
  "editor-yuntianyue",
  "fq-short-yuntianmo",
  "scout-yuntianhuo",
  "audio-yuntianlai",
  "agents-orchestrator",
  "kb-manager",
  "marketing-book-co-author",
  "marketing-content-creator",
  "academic-narratologist",
  "grant-writer",
  "engineering-technical-writer",
  "specialized-document-generator",
  "report-distribution-agent",
  "technical-translator-agent",
  "language-translator"
]

方案（仅适用全场景情况）：补全 agents.list

将 design-image-prompt-engineer 添加到 openclaw.json 的 agents.list 中：

{
  "id": "design-image-prompt-engineer",
  "name": "配图提示词工程师",
  "workspace": "/home/oklife/.openclaw/agency-agents/design-image-prompt-engineer",
  "agentDir": "/home/oklife/.openclaw/agents/design-image-prompt-engineer/agent"
}

修复后验证

$ openclaw agents list | grep design-image-prompt-engineer
  design-image-prompt-engineer (配图提示词工程师)
    Workspace: ~/.openclaw/agency-agents/design-image-prompt-engineer

$ sessions_spawn(agentId="design-image-prompt-engineer", task="测试")
→ ✅ accepted

六、延伸思考：还有谁躺枪？

修复后检查发现，allowAgents 与 agents.list 存在系统性错配：

只进 allowAgents、没进 agents.list 的 11 个 agent

只进 agents.list、没进 allowAgents 的 7 个 agent

实际是因为当下在写作场景的问题。

七、踩坑经验总结

❌ 我以前犯的错误

1. 直接读 agents.list 确认 agent 存在，就以为能 spawn

   • 以为 agents.list 和 allowAgents 是同一件事
   • 实际上 OpenClaw 对两者取交集，两边都要有才能 spawn

2. 报错信息不仔细读

   • “not in the configured agent registry” 的 allowed 列表只有 16 个
   • 对比后发现和配置的 31 个不同，但没有立刻追查为什么

3. 查到 allowAgents 有它就以为问题解决了

   • 没有继续查 agents.list 是否有它

✅ 正确排查路径

sessions_spawn 报错 "not in the configured agent registry"
  → 检查 allowAgents 是否有 → 有，继续
  → 检查 agents.list 是否有 → 没有，根因找到
  → 补入 agents.list → 修复

🔑 核心知识点

OpenClaw agent spawn 权限 = agents.list ∩ allowAgents

• 只有同时出现在 agents.list 和 allowAgents 中的 agent 才能被 sessions_spawn
• 只加 allowAgents 不加 agents.list → agent 被静默过滤
• 只加 agents.list 不加 allowAgents → agent 存在但无法被 spawn
• 两个都要加 → agent 可正常 spawn

关联阅读

• [[2026-07-11-1430-sessions-spawn-tools-permission-fix]]
• [[2026-07-25-1930-博客生图pipeline排障实战]]
• [[2026-08-03-1706-openclaw-gateway-restart-troubleshooting-auditd-memory-pressure]]

参考来源

• OpenClaw 源码：openclaw-tools-CIBcX9Ku.js（sessions_spawn 权限检查逻辑）
• OpenClaw 源码：subagent-spawn-plan-CyPIM_UV.js（filterConfiguredAllowedIds 实现）
• OpenClaw 源码：agent-scope-config-BxAUeF6t.js（listAgentIds / listAgentEntries 实现）
• ~/.openclaw/openclaw.json（本地配置）