子代理无法启动？一次 sessions_spawn 危险工具权限引发的问题排查

引言

在 AI Agent 协作架构中，子代理（Sub-Agent）是实现「专业任务委托」的核心机制。sessions_spawn 工具允许一个 Agent 生成另一个 Agent 的实例（如 oc-engineer 调用 kb-writer 进行知识归档），是实现多 Agent 协作的基础设施。

但当你信心满满地配置好 alsoAllow，准备大展身手时，却收到了一个令人困惑的错误：

"I can't use the tool 'sessions_spawn' here because it isn't available."

配置明明写了，为什么工具还是不能用？本文记录了从零到一排查并解决这个问题的完整过程。

问题复现

在配置 oc-engineer Agent 的子代理调用能力时，按文档要求在其配置中显式添加了 sessions_spawn：

# openclaw.json → agents.entries.oc-engineer
tools:
  profile: messaging
  alsoAllow:
    - sessions_spawn
    - sessions_send

配置看似正确，但调用 sessions_spawn 时报错「工具不可用」。

排查过程

阶段一：检查 tools.allow 配置（耗时 2 分钟）

首先确认 sessions_spawn 是否被正确添加到 alsoAllow 列表。

排查结果：配置中确实显式添加了 sessions_spawn，语法无误。

初步结论：问题不在 allow 列表。

阶段二：检查 dangerous-tools 定义（耗时 15 分钟）

进一步检查 OpenClaw 的 dangerous-tools 配置和 tool-catalog，发现关键信息：

• sessions_spawn 被归类为危险工具（dangerous tool）
• 该工具的 profiles 属性为 ["coding"]，即仅在 coding profile 中默认可用
• 其他 profile（如 messaging）不包含此工具

发现：sessions_spawn 的危险工具属性是问题的关键。

阶段三：检查当前 profile（耗时 10 分钟）

检查 oc-engineer 正在使用的 profile，发现一个关键事实：

• oc-engineer 当前使用的是 messaging profile（之前由 doctor 自动修复时设定）
• messaging profile 不包含 sessions_spawn 工具
• 虽然 alsoAllow 配置正确，但 gateway 进程未重新加载配置

双重发现：profile 不匹配 + 配置未生效。

阶段四：重启 Gateway（耗时 5 分钟）

确认 alsoAllow 配置正确后，执行 Gateway 重启使配置生效：

openclaw gateway restart

重启完成后再次测试 sessions_spawn，工具调用成功，kb-writer 子代理正常启动并返回结果。

问题解决。

根因分析

问题由两个因素叠加导致：

⚠️ 运维注意事项：修改 Gateway 或 Agent 配置后，必须执行 openclaw gateway restart 使配置生效。重启会中断正在运行的会话，需提前通知。

解决方案

方案一：显式 alsoAllow + 重启（推荐）

在 oc-engineer 配置中显式添加 sessions_spawn 到 alsoAllow：

tools:
  profile: messaging
  alsoAllow:
    - sessions_spawn
    - sessions_send

修改后必须重启 Gateway：

openclaw gateway restart

优点：符合最小权限原则，仅开放必要的工具。 缺点：需要记得重启生效。

方案二：切换 profile 为 coding

将 oc-engineer 的 profile 改为 coding，该 profile 默认包含 sessions_spawn。

优点：无需额外配置。 缺点：coding profile 包含更多工具，违反最小权限原则。oc-engineer 作为运维 Agent，messaging 更合适。

延伸：OpenClaw 的危险工具体系

OpenClaw 将工具分为普通工具和危险工具，通过 tool-catalog 管理。危险工具的默认可用 profile 有限制：

使用时需注意：

1. 查看 tool-catalog 确认工具归属
2. 非 coding profile 必须通过 alsoAllow 显式授权
3. 修改配置后重启 Gateway

运维规范

本次排查涉及两项核心运维规范：

规范一：修改配置前汇报

修改任何 Gateway 配置或 Agent 配置前，必须先向相关负责人汇报方案，获得确认后再执行。禁止未经汇报直接修改配置。

规范二：重启 Gateway 前汇报

执行 openclaw gateway restart 前，必须汇报重启方案和原因，获得确认后再执行。Gateway 重启会中断所有正在运行的会话，属于高风险操作。

关联阅读

• [[2026-07-04-1118-wsl-9p-protocol-bug-memory-search|memory_search 突然变弱？一次 WSL 9p 协议 Bug 引发的血案]]
• [[2026-07-11-1014-memory-search-qmd-fallback|memory_search 反复 fallback？一次配置冲突引发的血案]]
• [[2026-07-11-1215-agent-workflow-debug-fix|AI Agent 工作流排障实战]]
• [[2026-06-28-1100-知识归档工作流程经验教训|知识归档工作流程经验教训]]

–全文完–

若你有故事想讲、有困惑想聊、或是想找个人说说心里话，甚至只是吐槽发泄一下情绪，都欢迎来找我聊聊：　　　《内容已折叠，点击展开》

希望我写的每一个字，成为我自己和某个人活下去、拼下去的力量。　　　　　　　　　　　　　　　　　　　　　《内容已折叠，点击展开》

“技术终归是工具，而我们一次次认真把问题理顺，守住的其实不只是页面样式和代码输出，还有那一点不愿被混乱打败的心气，是每一个深夜仍愿点灯前行的人。”

转载请注明来自https://oklife.me。