作者：海风 ｜ 环境：阿里云 ECS + OpenClaw 2026.3.x + 飞书自建 Agent ｜ 日期：2026年3月

---

前言

我用 OpenClaw + 飞书搭建了一套 AI 多 Agent 协作系统，主 Agent（CEO 角色）可以根据任务需要，自动调度子 Agent（研究员、程序员、交易员等）分工协作。

某天晚上，我让主 Agent 带领团队研究一个课题，结果发现：

🔴 主 Agent 调用子 Agent 时被拒绝：sessions_spawn 权限不足

🔴 修复后子 Agent 能启动了，但搜索工具失灵：Fiona（研究员）无法连接搜索引擎

这两个问题花了不少时间排查，踩了好几个坑。本文完整记录排障过程，希望能帮同样在搭建多 Agent 系统的朋友少走弯路。

---

一、环境背景

项目	配置
服务器	阿里云 ECS
操作系统	AliOS（CentOS 系）
OpenClaw 版本	2026.3.x
AI 模型	Kimi-K2.5（主力）、Claude Sonnet 4.6、GLM-5 等
前端渠道	飞书自建 Agent
搜索方案	SearXNG（自托管）+ Jina Reader

Agent 团队构成

Agent ID	角色	职责
main	CEO / 总调度	理解任务、分配工作、汇总结果
researcher	研究员	信息搜索、资料收集
coder	程序员	代码编写、脚本开发
writer	作家	文案撰写、内容输出
trader	交易员	模拟炒股、行情分析

---

二、问题一：sessions_spawn 权限被拒绝

2.1 现象

在飞书中让主 Agent 调度子 Agent 执行研究任务，主 Agent 的调度计划很完美——先让研究员搜集资料，再让程序员分析数据，最后让交易员给出建议。

但执行时直接报错：

agentId is not allowed for sessions_spawn (allowed: none)
agents_list returns allowAny: false

翻译：主 Agent 没有权限通过 sessions_spawn 创建子 Agent 的会话。默认配置下，没有任何 Agent 被允许 spawn。

2.2 主 Agent 的自我诊断（错误的）

有趣的是，主 Agent 自己分析了这个报错，并给出了修复建议：

在 openclaw.json 的 agents 节点下添加 allowedAgents 配置...

我没有直接让 Agent 自己改配置（好在没有），而是决定先查官方文档确认正确的配置位置。

2.3 排障过程：三次尝试

❌ 第一次尝试：按 Agent 建议，加 agents.allowedAgents

{
  "agents": {
    "allowedAgents": ["researcher", "coder", "writer", "trader"]
  }
}

结果：Config invalid: agents: Unrecognized key: "allowedAgents"

根本没有这个配置项！Agent 的自我诊断是错的。教训：不要盲目相信 AI 的自我修复建议，尤其是涉及配置文件结构的。

立即清理：

# 用 python3 移除错误的 key
python3 -c "
import json
f = '/path/to/openclaw.json'
c = json.load(open(f))
c['agents'].pop('allowedAgents', None)
json.dump(c, open(f, 'w'), ensure_ascii=False, indent=2)
"

❌ 第二次尝试：加 agents.defaults.subagents.allowAgents

查了部分文档后，我以为 allowAgents 应该放在 defaults 里（全局默认配置），这样所有 Agent 都能 spawn 子 Agent：

{
  "agents": {
    "defaults": {
      "subagents": {
        "allowAgents": ["researcher", "coder", "writer", "trader"]
      }
    }
  }
}

结果：Config invalid: agents.defaults.subagents: Unrecognized key: "allowAgents"

又错了！defaults.subagents 下面不支持 allowAgents。

✅ 第三次尝试：正确位置 agents.list[].subagents.allowAgents

终于找到了官方配置参考文档，明确写着：

agents.list[].subagents.allowAgents — 每个 Agent 单独配置的 spawn 允许列表

• ["*"] 表示允许 spawn 任何 Agent

• 默认：仅允许 spawn 自己

关键区别：这是每个 Agent 单独的配置，不是全局 defaults！只有需要调度其他 Agent 的主 Agent 才需要配置。

正确的配置：

{
  "agents": {
    "list": [
      {
        "id": "main",
        "subagents": {
          "allowAgents": ["researcher", "coder", "writer", "trader"]
        }
      }
    ]
  }
}

用 Python 脚本修改配置文件：

python3 -c "
import json
f = '/path/to/openclaw.json'
c = json.load(open(f))

# 在 main agent 的配置中添加 allowAgents
for agent in c.get('agents', {}).get('list', []):
    if agent['id'] == 'main':
        if 'subagents' not in agent:
            agent['subagents'] = {}
        agent['subagents']['allowAgents'] = ['researcher', 'coder', 'writer', 'trader']
        break

json.dump(c, open(f, 'w'), ensure_ascii=False, indent=2)
print('Done')
"

别忘了清理第二次尝试留下的错误配置：

openclaw doctor --fix
openclaw gateway install --force && openclaw gateway restart

结果：✅ sessions_spawn 成功！主 Agent 能正常调度子 Agent 了。

2.4 小结：三次尝试对比

尝试	配置路径	结果	错误原因
第一次	agents.allowedAgents	❌ Unrecognized key	Agent 自己编的，根本不存在
第二次	agents.defaults.subagents.allowAgents	❌ Unrecognized key	defaults 下不支持此字段
第三次	agents.list[].subagents.allowAgents	✅ 成功	官方文档确认的正确位置

---

三、问题二：子 Agent 搜索工具失灵

3.1 现象

sessions_spawn 修复后，主 Agent 成功派 Fiona（研究员）去搜索信息。但 Fiona 返回说：

"遇到了一点问题，无法连接到搜索工具"

主 Agent 只好自己亲自上阵搜索，绕过了子 Agent。

3.2 排查思路

搜索能力在 OpenClaw 中有两种来源：

1. 内置 web_search 工具（基于 Brave Search API）
2. 自定义 Skill（我部署的 SearXNG + Jina Reader）

逐一排查：

检查内置搜索

python3 -c "
import json
c = json.load(open('/path/to/openclaw.json'))
web = c.get('tools', {}).get('web', {}).get('search', {})
print('web_search enabled:', web.get('enabled', 'not set'))
"

输出：web_search enabled: false

内置搜索被禁用了——这是我之前故意关掉的，因为 Brave Search 每月只有 2000 次免费额度，我改用了自托管的 SearXNG（完全免费、无限制）。

检查 SearXNG Skill

ls -la ~/.openclaw/skills/

输出只有画图相关的 Skill，SearXNG 和 Jina Reader 的 Skill 文件不见了！

drwxr-xr-x  nano-banana-pro
drwxr-xr-x  openai-image-gen

3.3 根因分析

OpenClaw 的 Skill 目录结构：

~/.openclaw/
├── skills/              ← 共享 Skills（所有 Agent 可见）
│   ├── nano-banana-pro/
│   ├── openai-image-gen/
│   ├── searxng-search/   ← 丢失！
│   └── jina-reader/      ← 丢失！
├── workspace/           ← 主 Agent workspace
│   └── skills/          ← 主 Agent 专属 Skills
├── workspace-researcher/ ← 研究员 workspace（无 skills 目录）
├── workspace-coder/      ← 程序员 workspace（无 skills 目录）
└── ...

搜索 Skill 之前放在共享目录 ~/.openclaw/skills/ 下，在某次升级操作中被清理掉了，只保留了新装的画图 Skill。

而且更关键的是：即使 Skill 存在，子 Agent 也有独立的 workspace。共享 ~/.openclaw/skills/ 对所有 Agent 可见，但各子 Agent 自己的 workspace 里没有 skills/ 目录。所以搜索 Skill 必须放在共享目录才能被子 Agent 使用。

验证 SearXNG 服务本身还在运行：

docker ps | grep searxng
# ✅ 容器正常运行，9 天了

curl -s "<http://localhost:8080/search?q=test&format=json>" | python3 -c "
import sys, json
r = json.load(sys.stdin).get('results', [])
print(f'SearXNG 返回 {len(r)} 条结果')
"
# ✅ SearXNG 正常，返回 18 条结果

SearXNG 服务完好，只是 Agent 找不到调用它的 Skill 文件。

3.4 修复：重建共享搜索 Skill

按照之前部署时的文档，重新创建两个 Skill：

SearXNG 搜索 Skill：

mkdir -p ~/.openclaw/skills/searxng-search
cat > ~/.openclaw/skills/searxng-search/SKILL.md << 'EOF'
---
name: searxng-search
description: "使用本地 SearXNG 进行网页搜索，免费且无限制"
author: "YourName"
version: "1.0.0"
tags:
  - search
  - web
triggers:
  - "搜索"
  - "查一下"
  - "search"
  - "帮我找"
---

# SearXNG Web Search

## 功能
使用本地 SearXNG 元搜索引擎进行网页搜索，聚合多个搜索引擎的结果。

## 使用方法
使用 exec 工具执行：

curl -s "<http://localhost:8080/search?q=URL编码的关键词&format=json&language=zh-CN>"

然后用 python3 解析 JSON，提取 results 数组中的 title、url、content。

## 参数
- q：关键词（必填）
- format：固定 json
- language：zh-CN 或 en
- categories：general、news、images、science
- time_range：day、week、month、year
EOF

Jina Reader Skill：

mkdir -p ~/.openclaw/skills/jina-reader
cat > ~/.openclaw/skills/jina-reader/SKILL.md << 'EOF'
---
name: jina-reader
description: "使用 Jina Reader API 将网页转为 Markdown"
author: "YourName"
version: "1.0.0"
tags:
  - reader
  - web
triggers:
  - "阅读"
  - "读取网页"
  - "read"
  - "获取网页内容"
---

# Jina Reader

## 阅读网页
使用 exec 工具执行：

curl -s "<https://r.jina.ai/目标URL>" -H "Accept: text/markdown"

## 搜索模式
curl -s "<https://s.jina.ai/搜索关键词>" -H "Accept: application/json"

## 规则
1. 阅读网页：URL 前加 <https://r.jina.ai/>
2. 搜索：关键词前加 <https://s.jina.ai/>
3. r.jina.ai 不可用时改用 SearXNG
EOF

重启 Gateway 加载新 Skill：

openclaw gateway install --force && openclaw gateway restart

3.5 验证结果

在飞书中开启新会话，让主 Agent 派研究员搜索新闻：

用户：让 Fiona 搜一下今天虚拟货币市场有什么新闻

结果：

• ✅ 主 Agent 成功分派任务给 Fiona
• ✅ Fiona 通过 SearXNG 搜索到当天新闻
• ✅ 返回了完整的结构化新闻摘要（比特币挖矿难度下调 7.76% 等）

---

四、为什么选择 SearXNG 而不是内置搜索？

很多人可能会问：OpenClaw 不是内置了 web_search 吗，为什么要自己搭 SearXNG？

对比项	内置 web_search（Brave）	SearXNG（自托管）
费用	免费 2000 次/月，超出付费	完全免费，无限制
搜索次数	有限	无限
隐私	搜索记录发送到第三方	数据留在自己服务器
国内可用性	可能需要代理	直接聚合百度/Bing，无需代理
搭配	无深度阅读	• Jina Reader 深度阅读

对于日常高频使用（每天自动推送 + 手动搜索 + 多 Agent 并行搜索），Brave 的免费额度完全不够。SearXNG 是更经济的选择。

---

五、踩坑总结

5.1 核心教训

1. 不要盲信 AI 的自我诊断

主 Agent 分析报错后给出的修复建议是错误的（agents.allowedAgents 根本不存在）。AI 擅长推理但不一定了解具体软件的配置结构。永远以官方文档为准。

2. 区分「全局默认」和「单 Agent 配置」

OpenClaw 的很多配置有两个层级：

• agents.defaults.* — 所有 Agent 的默认配置
• agents.list[].* — 单个 Agent 的专属配置

不是所有字段在两个层级都支持。subagents.allowAgents 只在 list[] 层级有效，因为「谁能 spawn 谁」本质上是每个 Agent 独立的权限控制。

3. 共享 Skill 目录是多 Agent 协作的关键

子 Agent 有独立的 workspace，但共享 ~/.openclaw/skills/ 目录对所有 Agent 可见。搜索、阅读等基础能力应该放在共享目录，而不是某个 Agent 的专属 workspace 里。

4. 升级/操作后检查 Skill 完整性

每次升级或大幅修改配置后，都应该检查 Skills 目录是否完整。一个简单的检查命令：

echo "=== 共享 Skills ==="
ls ~/.openclaw/skills/
echo "=== 各 Agent workspace Skills ==="
for d in ~/.openclaw/workspace-*/; do
    echo "$d: $(ls $d/skills/ 2>/dev/null || echo '无')"
done

5. 修改配置前先备份

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d%H%M)

这次我们犯了两次配置错误，好在每次都及时清理了。如果没有备份习惯，连续的错误修改可能导致配置混乱到无法恢复。

5.2 完整排障清单

问题	根因	修复
sessions_spawn 被拒	主 Agent 未配置子 Agent 的 spawn 允许列表	在 agents.list[main].subagents.allowAgents 中添加子 Agent ID
Agent 建议的配置位置错误	AI 不了解具体的配置结构	查阅官方配置参考文档
defaults.subagents.allowAgents 无效	该字段只在 list[] 层级支持	移到 agents.list[].subagents.allowAgents
子 Agent 无法搜索	SearXNG/Jina Reader 的共享 Skill 文件丢失	重建 Skill 到 ~/.openclaw/skills/ 共享目录
内置 web_search 不可用	被故意禁用（节省 Brave API 额度）	不需要修复，使用 SearXNG 替代

---

六、OpenClaw 多 Agent 协作架构图

flowchart TB
    User["👤 用户（飞书）"] -->|发送指令| Main["🦞 主 Agent（CEO）"]
    
    Main -->|"sessions_spawn<br>需要 allowAgents 配置"| Researcher["🔍 研究员 Fiona"]
    Main -->|sessions_spawn| Coder["💻 程序员 Owen"]
    Main -->|sessions_spawn| Writer["✍️ 作家 Iris"]
    Main -->|sessions_spawn| Trader["📈 交易员 Grant"]
    
    subgraph SharedSkills["📂 共享 Skills (~/.openclaw/skills/)"]
        S1["🔎 SearXNG 搜索"]
        S2["📖 Jina Reader"]
        S3["🎨 Nano Banana 画图"]
    end
    
    Researcher -.->|调用| S1
    Researcher -.->|调用| S2
    Main -.->|调用| S1
    Main -.->|调用| S3
    
    S1 -->|"curl localhost:8080"| SearXNG["🐳 SearXNG Docker"]
    S2 -->|"curl r.jina.ai"| Jina["☁️ Jina Reader API"]
    SearXNG -->|聚合| Baidu["百度"]
    SearXNG -->|聚合| Bing["Bing"]

---

七、相关配置参考

sessions_spawn 允许列表配置

{
  "agents": {
    "list": [
      {
        "id": "main",
        "subagents": {
          "allowAgents": ["researcher", "coder", "writer", "trader"]
        }
      },
      { "id": "researcher" },
      { "id": "coder" },
      { "id": "writer" },
      { "id": "trader" }
    ]
  }
}

• allowAgents: ["*"] 表示允许 spawn 任何 Agent
• 默认（不设置）：只允许 spawn 自己
• 只需要在发起调度的 Agent（通常是主 Agent）上配置

Skill 目录优先级

~/.openclaw/skills/          ← 共享（所有 Agent 可见）✅ 推荐
~/.openclaw/workspace/skills/ ← 仅主 Agent 可见
~/.openclaw/workspace-xxx/skills/ ← 仅对应子 Agent 可见

基础能力型 Skill（搜索、阅读）放共享目录；专业型 Skill（如 TuShare 金融数据）可以放特定 Agent 的 workspace。

---

结语

多 Agent 协作是 AI Agent 系统的高级玩法，但「能协作」和「能正确协作」之间还有不少配置细节需要注意。这次排障的核心收获：

1. 权限要显式配置：sessions_spawn 默认是最小权限原则，需要手动开启
2. Skill 共享是关键：子 Agent 需要通过共享目录继承基础能力
3. 文档优先于 AI 建议：AI 的自我诊断可以作为参考，但最终要以官方文档为准

如果你也在用 OpenClaw 或类似的多 Agent 框架，希望这篇踩坑记录能帮你节省几个小时的排障时间。

---

本文所有 IP、Token、路径等敏感信息已脱敏处理。实际部署时请替换为你自己的环境配置。