OpenClaw Agent 配置排障：sessions_spawn 工具权限问题的根因分析与修复

背景

在运行博客生产流水线（blog-pipeline）时，oc-engineer 尝试通过 sessions_spawn 委托 kb-writer 执行 Mode B 会话归档任务，但 kb-writer 返回 "Tool not found" 错误——sessions_spawn 工具不可用。

这导致整个博客流水线无法启动。经过多层排查，最终定位到根因：手动添加的 tools.subagents.tools.deny 配置意外收紧了子代理的工具权限列表。

问题现象

排查路径

第 1 层：检查全局 tools.profile

"tools": {
  "profile": "full",
  "agentToAgent": { "enabled": true },
  "sessions": { "visibility": "all" }
}

full profile 包含所有工具组（group:sessions），sessions_spawn 应该在列。✅

第 2 层：检查 kb-writer 的 tools 配置

"tools": {
  "profile": "coding",
  "alsoAllow": ["message"],
  "deny": ["gateway"]
}

根据 OpenClaw 官方文档：

coding profile 应该包含 sessions_spawn。配置本身没有问题。✅

第 3 层：检查 tools.subagents.tools 配置

这里发现了问题所在。此前为精细控制子代理权限，手动添加了：

"tools": {
  "subagents": {
    "tools": {
      "deny": ["gateway", "cron", "browser", ...]
    }
  }
}

这个配置的本意是：禁止子代理使用某些高风险工具（gateway 配置修改、cron 定时任务等）。

但实际效果是：tools.subagents.tools.deny 不仅拒绝了指定工具，还覆盖了子代理的工具继承链。OpenClaw 的工具解析逻辑是：

当 tools.subagents.tools 存在时，子代理不再从父级 profile 继承完整工具列表，而是以 deny 列表为基准重新计算可用工具集。

这意味着：coding profile 原本包含的 sessions_spawn 因为不在显式白名单中，被 deny 逻辑意外排除。

修复方案

立即修复：移除 tools.subagents.tools

# 移除 tools.subagents.tools 整个节点
cat ~/.openclaw/openclaw.json | jq 'del(.tools.subagents.tools)' > /tmp/openclaw_fix.json && mv /tmp/openclaw_fix.json ~/.openclaw/openclaw.json

验证修复结果：

openclaw config get "tools.subagents.tools"
# 输出：Not set (good)

当前正确的全局配置

{
  "tools": {
    "profile": "full",
    "agentToAgent": { "enabled": true },
    "sessions": { "visibility": "all" },
    "subagents": {}
  }
}

subagents 为空对象表示：子代理继承父级完整工具列表，不做额外限制。

重启 Gateway 使配置生效

# 重启 gateway 进程
openclaw gateway restart

⚠️ 注意：配置修改后必须重启 gateway 才能生效。部分工具策略在 gateway 启动时加载到内存，热加载可能不覆盖工具列表变更。

验证结果

修复后新建 kb-writer 会话测试：

sessions_spawn(agentId="kb-writer", task="...", mode="run", context="isolated")
→ 返回 childSessionKey: "agent:kb-writer:subagent:7be78288-..."
→ resolvedModel: "sapiens/agnes-2.5-flash"
✅ sessions_spawn 正常可用

经验教训

1. tools.subagents.tools.deny 是"双刃剑"

tools.subagents.tools.deny 的设计意图是在白名单基础上拒绝特定工具，而不是在黑名单基础上工作。当 tools.subagents.tools 对象存在时：

• ✅ 正确用法：配合 allow 列表使用，只允许子代理访问特定工具
• ❌ 错误用法：只设置 deny 而不设置 allow，会触发工具继承链断裂

2. 配置变更的验证闭环

每次修改 openclaw.json 后，必须执行以下验证：

# 1. 配置语法检查
openclaw config validate

# 2. 确认目标配置已变更
openclaw config get "tools.subagents.tools"

# 3. 重启 gateway
openclaw gateway restart

# 4. 新建会话测试关键工具
# （用 sessions_spawn 或目标工具实际测试）

3. 文档是最好的防御

本次问题的完整排查过程已记录在本文，后续遇到类似"工具突然不可用"的问题，可以按以下优先级排查：

1. 检查 tools.profile（是否被意外改为 minimal）
2. 检查 tools.subagents.tools（是否有 deny/allow 覆盖）
3. 检查 agents.<id>.tools.deny（agent 级别 deny）
4. 重启 gateway 使配置生效
5. 新建会话验证（旧会话可能缓存过时策略）

附录：OpenClaw 工具 Profile 对照表

来源：~/.nvm/versions/node/v24.16.0/lib/node_modules/openclaw/docs/tools/index.md

常见问题

Q: tools.subagents.tools.deny 的正确用法是什么？ A: 必须配合 allow 白名单一起使用。例如：

"tools": {
  "subagents": {
    "tools": {
      "allow": ["sessions_spawn", "sessions_yield", "read", "exec"],
      "deny": ["gateway", "cron"]
    }
  }
}

这样既限制了高风险工具，又不会意外断开工具继承链。

Q: sessions_spawn 报错 “Tool not found” 还可能是哪些原因？ A: 除了 tools.subagents.tools 配置问题外，还可能因为：

• tools.profile 被设为 minimal（不含 group:sessions）
• agent 级别 tools.deny 包含了 sessions_spawn
• 旧 session 缓存了过时策略，需要新建会话

Q: 修改配置后不重启 gateway 会怎样？ A: 工具策略在 gateway 启动时加载到内存，运行时不热重载。不重启的话，即使 JSON 文件已修改，实际生效的还是旧策略。

关联阅读

• [[OpenClaw Agent 工具权限配置指南]]
• [[blog-pipeline HITL 门控事故复盘]]

参考来源

• OpenClaw Tools Documentation
• OpenClaw Subagents Documentation
• OpenClaw Config Tools Documentation