作者海风 环境阿里云 ECS OpenClaw 2026.3.x 飞书自建 Agent 日期2026年3月前言我用 OpenClaw 飞书搭建了一套 AI 多 Agent 协作系统主 AgentCEO 角色可以根据任务需要自动调度子 Agent研究员、程序员、交易员等分工协作。某天晚上我让主 Agent 带领团队研究一个课题结果发现主 Agent 调用子 Agent 时被拒绝sessions_spawn权限不足修复后子 Agent 能启动了但搜索工具失灵Fiona研究员无法连接搜索引擎这两个问题花了不少时间排查踩了好几个坑。本文完整记录排障过程希望能帮同样在搭建多 Agent 系统的朋友少走弯路。一、环境背景项目配置服务器阿里云 ECS操作系统AliOSCentOS 系OpenClaw 版本2026.3.xAI 模型Kimi-K2.5主力、Claude Sonnet 4.6、GLM-5 等前端渠道飞书自建 Agent搜索方案SearXNG自托管 Jina ReaderAgent 团队构成Agent ID角色职责mainCEO / 总调度理解任务、分配工作、汇总结果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_asciiFalse, indent2) ❌ 第二次尝试加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_asciiFalse, indent2) print(Done) 别忘了清理第二次尝试留下的错误配置openclaw doctor --fix openclaw gateway install --force openclaw gateway restart结果✅sessions_spawn成功主 Agent 能正常调度子 Agent 了。2.4 小结三次尝试对比尝试配置路径结果错误原因第一次agents.allowedAgents❌ Unrecognized keyAgent 自己编的根本不存在第二次agents.defaults.subagents.allowAgents❌ Unrecognized keydefaults 下不支持此字段第三次agents.list[].subagents.allowAgents✅ 成功官方文档确认的正确位置三、问题二子 Agent 搜索工具失灵3.1 现象sessions_spawn修复后主 Agent 成功派 Fiona研究员去搜索信息。但 Fiona 返回说遇到了一点问题无法连接到搜索工具主 Agent 只好自己亲自上阵搜索绕过了子 Agent。3.2 排查思路搜索能力在 OpenClaw 中有两种来源内置web_search工具基于 Brave Search API自定义 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 Skillls -la ~/.openclaw/skills/输出只有画图相关的 SkillSearXNG 和 Jina Reader 的 Skill 文件不见了drwxr-xr-x nano-banana-pro drwxr-xr-x openai-image-gen3.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?qtestformatjson | python3 -c import sys, json r json.load(sys.stdin).get(results, []) print(fSearXNG 返回 {len(r)} 条结果) # ✅ SearXNG 正常返回 18 条结果SearXNG 服务完好只是 Agent 找不到调用它的 Skill 文件。3.4 修复重建共享搜索 Skill按照之前部署时的文档重新创建两个 SkillSearXNG 搜索 Skillmkdir -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?qURL编码的关键词formatjsonlanguagezh-CN 然后用 python3 解析 JSON提取 results 数组中的 title、url、content。 ## 参数 - q关键词必填 - format固定 json - languagezh-CN 或 en - categoriesgeneral、news、images、science - time_rangeday、week、month、year EOFJina Reader Skillmkdir -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 加载新 Skillopenclaw gateway install --force openclaw gateway restart3.5 验证结果在飞书中开启新会话让主 Agent 派研究员搜索新闻用户让 Fiona 搜一下今天虚拟货币市场有什么新闻结果✅ 主 Agent 成功分派任务给 Fiona✅ Fiona 通过 SearXNG 搜索到当天新闻✅ 返回了完整的结构化新闻摘要比特币挖矿难度下调 7.76% 等四、为什么选择 SearXNG 而不是内置搜索很多人可能会问OpenClaw 不是内置了web_search吗为什么要自己搭 SearXNG对比项内置 web_searchBraveSearXNG自托管费用免费 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 无) done5. 修改配置前先备份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 IDAgent 建议的配置位置错误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[ 主 AgentCEO] Main --|sessions_spawnbr需要 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 系统的高级玩法但「能协作」和「能正确协作」之间还有不少配置细节需要注意。这次排障的核心收获权限要显式配置sessions_spawn默认是最小权限原则需要手动开启Skill 共享是关键子 Agent 需要通过共享目录继承基础能力文档优先于 AI 建议AI 的自我诊断可以作为参考但最终要以官方文档为准如果你也在用 OpenClaw 或类似的多 Agent 框架希望这篇踩坑记录能帮你节省几个小时的排障时间。本文所有 IP、Token、路径等敏感信息已脱敏处理。实际部署时请替换为你自己的环境配置。