OpenClaw 这个名字，最近在技术社区里出现的频率相当高——它是一个把大模型能力搬进终端的 Agent 工具，图标是一只举着钳子的龙虾。很多人装好之后，跑一个会话发现好像也就那样：让一个 Agent 从头到尾干完一件事，经常干到一半就跑偏，或者上下文越滚越长，越到后面越糊涂。真正的玩法，是把它从“光杆司令”变成“龙虾大军”，也就是多 Agent 编排。这篇就来聊聊 OpenClaw 多 Agent 的架构、部署、配置和排坑，适合已经装过终端 Agent 但不知道怎么往上进阶的人，也适合刚听说 OpenClaw、想从零开始搭一套的朋友。
1. 概念拆解：多 Agent 到底在编排什么？
1.1 单 Agent 的边界在哪里
一个 Agent 本质上就是一个会调用外部工具的会话上下文。它的问题不是“不够聪明”，而是“上下文太挤”。你让它又查资料、又写代码、又做检查，一份长对话里塞满了目标完全不同的指令，模型很容易顾此失彼：写文档的时候还惦记着查来的数据，调代码的时候又想着上一步的报错。这就好比让一个人既当产品经理又当开发又当测试，短时间能扛，任务一复杂就全面崩盘。
多 Agent 的思路恰恰相反：把一个大任务拆成边界清晰的多个小任务，每个小任务交给一个独立的 Agent 上下文去完成，最后再由主 Agent 汇总。每个子 Agent 只需要关心自己那一段，上下文干净、目标单一、工具集中，出错的概率大幅下降。
OpenClaw 把这种编排做成了开箱即用的能力，这也是“龙虾大军”这个说法的由来——每拉起一个子 Agent，就像多了一只虾兵。单打独斗的“光杆司令”变成了有分工、有协作、有把关的团队，处理的复杂度一下子就能上一个台阶。
1.2 OpenClaw 的多 Agent 架构：主 Agent、子 Agent 与 Skill
OpenClaw 的编排模型可以简化成三层，理解这三层就够了：
- 主 Agent（主管）：接收你的总任务，做规划，把任务拆解成若干子任务，然后按顺序或并行调用子 Agent，最后汇总结果、向你汇报。
- 子 Agent：各自拥有独立的系统提示词、模型参数、工具集和工作目录，只负责被分配的那一小块任务，不关心全局。
- Skill（技能）：一组预置的指令和脚本，相当于给 Agent 配的“外挂工具库”，让它在特定任务上有更专业、更稳定的表现。
主 Agent 的“大脑”里存着每个子 Agent 的说明，包括它们的职责、擅长什么、用什么模型。规划的时候，它会像项目经理一样读这些描述，然后决定“这个任务应该派给谁”。
一个最简化的配置文件长这样：
agents: research: system_prompt: 你是一名信息收集员，负责检索资料并输出结构化笔记 tools: [web_search, web_fetch] writer: system_prompt: 你是一名技术写作者，负责将笔记扩写成完整文章 reviewer: system_prompt: 你是一名严谨的编辑，负责审校事实、逻辑和措辞主 Agent 会读这份配置，然后按照任务阶段把活派出去。注意，research 只配了搜索和抓取工具，没有写作工具；writer 只配了写作工具，没有联网工具。这让每个 Agent 的能力边界非常清楚，不会出现“写着写着又跑去搜资料”这种上下文混乱的情况。
2. 地基先打好：环境准备与安装
2.1 WSL2 环境检查：最常见的翻车点
如果你在 Windows 上跑 OpenClaw，大概率会遇到下面这个报错：
OpenClaw 无法安全验证 wsl2 环境。请在 powershell 中运行 wsl -- status第一次看到这个提示，很多人会以为是软件坏了。其实不是，这是 OpenClaw 的 Windows 环境检测机制在起作用：它会调用 wsl.exe 并解析输出来判断当前 WSL 环境是否可用。如果命令超时、输出为空、WSL 服务没启动，或者根本没有安装发行版，它就会报出这个安全验证失败的错误。说白了，它不信任你的 WSL 环境，宁可停下来也不瞎跑。
解决方法分四步走：
- 打开 PowerShell，执行
wsl --status和wsl --version，看看 WSL 本身有没有响应、内核版本是不是新的。 - 如果提示版本太老，执行
wsl --update更新内核。 - 执行
wsl -l -v确认至少有一个发行版，且 Version 列显示为 2。如果显示 1，需要执行wsl --set-version <发行版名> 2转换。 - 如果还没有任何发行版，直接
wsl --install -d Ubuntu-22.04装一个，首次进入设置好用户名和密码。
这里有个我踩过的坑：很多人以为自己装了 WSL，其实只装了 WSL 1，或者装完从未初始化过发行版。wsl --status一跑，输出里写着“默认发行版: 无”，那 OpenClaw 当然没法验证。先把上面四步走完，再重新启动 OpenClaw，这个报错基本就消失了。
另外，如果你的 WSL 服务卡死，可以执行wsl --shutdown强制重启整个 WSL 子系统，这一步能解决 80% 的“WSL 神秘异常”。
2.2 Node.js 环境与 OpenClaw 安装
OpenClaw 本体是用 Node.js 构建的，所以第一步是把 Node 环境准备好。建议直接用 LTS 版本，去 nodejs.org 官网下载，或者用 nvm-windows 管理版本。
提示：不要在 Windows 上把 Node 装进系统目录后用 sudo 或管理员权限强行改全局路径，后面 npm 全局安装会经常报 EPERM 或 EACCES 权限错误。用 nvm-windows 装 Node，天然绕开这个问题。
装完验证一下：
node -v npm -v我建议 Node 版本不低于 18，最好直接用 20 以上的 LTS。有些老版本在解析某些依赖时会有兼容性问题，排查起来非常费劲。
然后安装 OpenClaw：
npm install -g openclaw openclaw --version注意：不同分支、不同发行渠道的包名可能不一样。如果你从 GitHub 仓库直接读的安装文档，包名可能是
@openclaw/cli之类的变体。以官方仓库 README 里写的为准，不要盲抄网上的命令。
如果 npm 拉包很慢，可以先把 registry 切成国内镜像源，比如：
npm config set registry https://registry.npmmirror.com装完之后，第一次运行会进入交互式初始化，它会问你用哪个模型服务商、填什么 API Key。先随便填一个能跑通的，后面再慢慢改配置。
2.3 算力选择：本地 Ollama 与 API 混合
“OpenClaw 是不是只能用接入 API 的方式使用算力？”这是很多人在社区里问的问题。答案是：不是。OpenClaw 对接的是 OpenAI 兼容接口，任何提供这类接口的推理服务都能接进来。最常见的免费选项就是用 Ollama 跑本地模型。
Ollama 的配置分三步：
- 安装 Ollama，然后拉一个模型，比如
ollama pull qwen2.5:14b。 - 启动服务
ollama serve，确认接口监听在127.0.0.1:11434。 - 在 OpenClaw 配置里把模型服务商指到 Ollama：
OPENCLAW_MODEL_PROVIDER=ollama OPENCLAW_MODEL=qwen2.5:14b OPENCLAW_API_BASE=http://127.0.0.1:11434/v1这里注意，OpenAI 兼容接口的路径一般是/v1/chat/completions，所以API_BASE一定要带/v1，漏掉这个后缀是最常见的连接失败原因。
API 和本地模型各有各的用处，我实测下来的对比大致是这样：
| 对比项 | 本地 Ollama | 云端 API |
|---|---|---|
| 成本 | 免费，只消耗电 | 按 Token 计费 |
| 速度 | 看显卡，人多卡顿 | 稳定，但受网络影响 |
| 隐私 | 数据不出机器 | 数据出网 |
| 长文本 | 显存有限，容易爆 | 上下文大，更从容 |
| 适用场景 | 简单任务、子 Agent | 复杂推理、内容生成 |
我的习惯是混合用：整理资料、提取摘要这些机械活派给本地小模型，真正需要创造力的写作和综合分析走云端 API。这样既省钱又稳定，子 Agent 之间的成本也能拉开差距。
3. 从光杆司令到龙虾大军：多 Agent 编排实战
3.1 定义你的第一个子 Agent
子 Agent 的本质，就是一个独立的模型会话加上一组专属配置。OpenClaw 里定义一个子 Agent，核心字段大概有这几个：
- name：子 Agent 的名字，调度时用。
- description：它的职责描述，这一栏非常重要，主 Agent 靠它来决定什么时候派活。
- model：该子 Agent 用的模型，可以和主 Agent 不同。
- temperature：温度，控制输出的确定性。
- tools：允许它调用的工具列表。
- system_prompt：系统提示词，定义它的角色和行为准则。
- cwd：工作目录，让它在指定目录下执行命令。
一个写代码审查子 Agent 的例子：
agents: code_reviewer: description: 专门审查代码质量、找 bug、提改进建议的资深工程师 model: qwen2.5:14b temperature: 0.2 tools: [bash, read_file] system_prompt: | 你是一名代码审查工程师。收到代码后先指出致命问题， 再按严重程度列出改进建议。输出格式：问题列表 + 建议。这里有一个很容易忽略的点：description 一定要写得像招聘启事，越具体越好。主 Agent 不会读你的 system_prompt 全文，它主要靠 description 判断“这个活该派给谁”。如果你写“负责处理代码”，主 Agent 可能把查资料的活也派给它；如果你写“审查代码质量、找 bug、提改进建议”，它就能精准地对号入座。
3.2 分工与调度：主 Agent 怎么派活
配置好子 Agent 之后，剩下的事情就是给主 Agent 下命令。比如你输入：
请对“终端 AI Agent 的工程实践”这个话题写一份 2000 字左右的深度分析。 先让 research 收集素材，再由 writer 撰写初稿，最后交给 reviewer 审校。主 Agent 会先做规划（plan），把任务拆解成三段：收集素材、写初稿、审校。然后它会依次调用子 Agent，并把上一步的产出作为下一步的输入。你在日志里可以看到类似这样的流程：
[plan] 任务拆解完成，共 3 个子任务 [dispatch] -> research [result] research 返回 6 条素材 [dispatch] -> writer [result] writer 返回 2100 字初稿 [dispatch] -> reviewer [result] reviewer 返回修改意见 8 条，已合并子任务之间没有依赖关系的，可以并行跑。比如让两个子 Agent 分别调研两个不同的方向，可以让主 Agent 同时调度它们。并行能大幅缩短总耗时，但也要注意别一下子铺太开——你的模型服务扛不扛得住并发，上下文窗口够不够汇总，都需要权衡。
如果某个子 Agent 失败了，比如联网检索工具报错，主 Agent 会尝试换一种方式重试，或者把失败原因写进问题描述再派给别人。我在实际使用中发现，给主 Agent 的指令里加上“如果某个环节失败，告诉我原因并重试一次”这句话，比默认行为要稳得多。
3.3 用 Skill 给龙虾“装武器”
子 Agent 解决了“分工”的问题，Skill 解决的是“专业能力”的问题。一个 Skill 就是一小组预置指令和脚本，放在指定的技能目录里，比如：
~/.config/openclaw/skills/pdf-summary/SKILL.md文件内容可以是这样：
--- name: pdf-summary description: 提取 PDF 文件内容并输出结构化摘要 --- 当用户要求总结 PDF 时使用此技能： 1. 先用 python 运行 utils/pdf_extract.py 提取全文 2. 将全文按段落切块，分段总结 3. 合并段落总结，输出层级标题Skill 的价值在于把“经验”固化成流程。你不用每次都在对话里重新描述“怎么解析 PDF、怎么切块、怎么合并”，Agent 一碰到对应场景就会自动加载技能说明，按照既定步骤执行。这就像给龙虾装上钳子以外的武器，让它对付特定目标时又快又准。
我强烈建议凡是重复三次以上的操作，都封装成 Skill。比如“周报生成”“会议纪要整理”“日志分析”，封装之后，子 Agent 的稳定性和执行速度都会明显提升。
4. 实操记录：搭建一个三 Agent 内容流水线
4.1 场景与配置清单
下面用一个我实际搭过的场景举例：三个 Agent 协作写一篇技术分析文章。配置如下：
| Agent | 职责 | 模型 | 温度 |
|---|---|---|---|
| research | 检索资料，输出结构化素材 | qwen2.5:14b（本地 Ollama） | 0.2 |
| writer | 根据素材撰写文章 | 云端 API 的长上下文模型 | 0.7 |
| reviewer | 审校事实与逻辑，修改措辞 | qwen2.5:14b（本地 Ollama） | 0.2 |
对应的 YAML 配置：
agents: research: description: 负责检索技术资料、整理事实性素材的调研员 model: qwen2.5:14b temperature: 0.2 tools: [web_search, web_fetch] system_prompt: | 你是一名调研员。针对给定主题，检索 5 篇以上资料， 输出带来源链接的分点笔记，不要写结论，不要写文章。 writer: description: 负责把调研笔记扩写成完整文章的技术写作者 model: claude-sonnet temperature: 0.7 system_prompt: | 你是一名资深技术博主。根据调研笔记撰写结构清晰、 观点明确的技术文章，保留技术细节，避免空话套话。 reviewer: description: 负责审校文章事实、逻辑、措辞的编辑 model: qwen2.5:14b temperature: 0.2 system_prompt: | 你是一名严谨的编辑。检查文章的事实错误、逻辑漏洞、 以及过于浮夸的表述，输出修改建议清单。这里把 research 和 reviewer 放在本地模型，writer 放在云端 API，是为了让最简单、最模式化的环节不花钱，同时把最有创造力的环节留给更强的模型。
4.2 跑起来：从提问到产出
启动 OpenClaw，输入：
请用三 Agent 流水线完成一篇关于“本地大模型在终端工具中的应用”的 2000 字文章。 分工：research 收集素材 -> writer 撰写 -> reviewer 审校并合并修改。实际跑下来的流程是：research 先检索了 6 个来源，输出了 800 字的笔记；writer 拿到笔记后写出了 2200 字的初稿；reviewer 检查后提了 5 条修改建议，包括两处事实表述不严谨、一处引用链接过旧，以及建议把某段结论前置。主 Agent 汇总后，把这些修改直接合并进文章，最后我拿到手的已经是一份比较干净、可以直接用的稿子。
整个过程大概 8 分钟，我全程没有插手，只需要看日志。如果发现哪一步跑偏，可以随时打断，单独给某个子 Agent 重新下指令，而不需要重跑整条流水线——这是多 Agent 相比单 Agent 在可控性上最大的优势。
调优的小技巧是：让子 Agent 输出摘要而不是原文。比如 research 阶段，明确要求“只输出分点笔记，不要写结论，不要写文章”。如果不加这句，调研 Agent 很容易顺手写出一堆半成品段落，白白占掉下一步的上下文窗口。
4.3 调度策略调优：什么时候并行、什么时候串行
多 Agent 不是越多并行越好，关键要看任务之间的依赖关系。我的经验是：
- 子任务之间没有依赖，比如同时调研多个独立方向，可以并行。
- 后一步强依赖前一步的产出，比如 writer 必须等 research 的结果，就串行。
- 串行流水线更稳，因为每一步的产出都有上下文延续；并行省时间，但主 Agent 汇总时容易丢失细节。
执行顺序：
- 先跑通一条极简的串行流水线，确认每个 Agent 都能完成自己的环节。
- 再加并行分支，同时观察主 Agent 的调度日志，确认它没有把有依赖的任务也并行掉。
- 最后做成本控制，把高频率的简单环节换到本地小模型。
我记得第一次搭并行的时候，两个子 Agent 同时去检索资料，结果主 Agent 汇总时发现两份素材大量重复。后来我在分工指令里加了“research 负责技术文档类资料，另一个专门负责社区讨论类资料”，重复率一下就降下来了。说白了，分工描述写得越细，并行就越安全。
5. 常见问题与排查实录
5.1 Windows 侧问题：WSL2、PowerShell 与 Companion
把我在 Windows 上遇到的和朋友求助的问题整理成一个速查表：
| 症状 | 原因 | 解法 |
|---|---|---|
| OpenClaw 无法安全验证 wsl2 环境 | WSL 服务未启动 / 无发行版 / WSL 内核过旧 | PowerShell 跑wsl --status、wsl --update，确认有发行版且为 Version 2 |
wsl --status报 0x800706ba | Windows Update 服务或 WSL 服务异常 | 重启 LxssManager 服务，或执行wsl --shutdown后重开终端 |
| WSL 显示 Version 1 | 发行版未转换或默认版本未设为 2 | wsl --set-default-version 2，再wsl --set-version <发行版> 2 |
| npm 全局安装报 EPERM/EACCES | Node 装进系统目录，权限不足 | 改用 nvm-windows 管理 Node，避免踩系统目录 |
| PowerShell 拒绝执行 npm 脚本 | 执行策略默认 Restricted | Set-ExecutionPolicy -Scope CurrentUser RemoteSigned |
Windows Companion 是 OpenClaw 在 Windows 侧的一个辅助壳，负责提供右键菜单、文件关联之类的原生体验。它的运行前提是 WSL 环境本身完全健康，所以如果你在配置 Companion 的时候遇到卡住，先别折腾 Companion，回到上一节把wsl --status跑通再说。
Companion 的配置文件一般会生成在用户目录下，路径形如%APPDATA%\OpenClaw\config.json。常见问题无非两类：一是 WSL 环境检测不过，二是 PATH 里找不到 node 和 openclaw 的可执行文件。确认 PowerShell 里能直接执行openclaw --version，Companion 大概率也能正常启动。
5.2 模型接入问题：Ollama 与 API
模型相关的问题，九成集中在三个地方：
| 症状 | 原因 | 解法 |
|---|---|---|
| 连接被拒绝 / connection refused | Ollama 服务没启动，或 OLLAMA_HOST 配错 | 执行ollama serve；确保地址是127.0.0.1:11434而不是localhost（IPv6 解析容易踩坑） |
| 模型不存在 / model not found | 模型没拉下来或名字拼错 | ollama list确认模型名，再ollama pull <模型名> |
| 请求 401 / API key 无效 | API Key 没写入环境变量或填错 | 检查OPENCLAW_API_KEY等环境变量，确认服务商账户有余额 |
额外提醒一点：如果你的 Ollama 和 OpenClaw 跑在同一台机器上，API_BASE用127.0.0.1而不是localhost。某些 Windows 环境下localhost会被解析成 IPv6 的::1，而 Ollama 默认只监听 IPv4，这个原因排查起来非常隐蔽。
5.3 手机端 Termux 部署的注意事项
用 Termux 在手机上装 OpenClaw 也是可行的，步骤是：
pkg update && pkg upgrade pkg install nodejs-lts npm install -g openclaw termux-setup-storage重点提醒三条：
- Android 对后台进程限制很严，跑长任务前先执行
termux-wake-lock，否则屏幕一锁，会话就可能被杀掉。 - 手机的内存和显存都有限，本地模型别拉太大的，14B 模型在手机上基本就是灾难，要么用 API，要么只跑 3B 级别的小模型做简单分类和摘要。
- Termux 的 npm 全局安装目录默认在
../usr/bin，一般不需要额外配 PATH，但如果你手动改过环境变量，装完记得which openclaw检查一下。
手机端更适合的场景是“远程随手改配置、启动一个简单任务”，而不是跑完整的多 Agent 流水线。真做重活，还是回到桌面端。
6. 最后说点实在的：我的几条经验
多 Agent 编排不是越复杂越好。任务太小，直接单 Agent 一次性对话反而省事；任务一复杂，才值得拆流水线。我个人的底线是：如果这个活儿我一个人瞎聊两句就能搞定，就绝不开三个子 Agent 去折腾。
真正让我觉得“龙虾大军”有价值的，是它把任务边界固定住了。子 Agent 不会因为上下文太长而忘记自己的职责，主 Agent 负责全局思维，调研、写作、审查各司其职。配置好一轮之后，下次再遇到类似任务，几乎不用改动就能复用，这种积累感是单 Agent 给不了的。
还有两个小技巧可以说说。一是子 Agent 的 description 值得花时间打磨，它直接决定了主 Agent 的调度准确性，我见过太多人把 description 写成一个词，结果调度一塌糊涂。二是日志不要关，把 log_level 调到 debug，多跑几次流水线，你会慢慢看懂主 Agent 的规划思路，然后反过来微调提示词，效果立竿见影。
最后提醒一句：别一次并行太多。几个子 Agent 同时跑确实壮观，但你的本地模型可能直接爆显存，按量计费的 API 也可能在不知不觉中烧掉不少余额。从两个三个开始，稳定运行后再慢慢加，这是最稳妥的路。
