开源双智能体自动化系统：60秒部署的Orchestrator与Builder协作框架

1. 项目概述：一个开箱即用的双智能体自动化系统

如果你正在寻找一个能快速上手的、可自部署的AI智能体系统，而不是又一个需要你从头开始拼凑的“提示词包”，那么这个OpenClaw Starter Kit可能就是你需要的。它是一个完全免费、开源的入门套件，核心是为你预配置好一个由两个智能体（Orchestrator和Builder）协同工作的自动化系统。你只需要一条命令，就能在60秒内把它跑起来，部署在你自己的机器或服务器上。这听起来可能有点技术性，但别担心，它的设计初衷就是让没有深厚开发背景的人也能轻松驾驭。简单来说，它就像一套为你量身定制的自动化“双人工作组”，一个负责思考和指挥，另一个负责动手执行，帮你处理那些重复性的、基于规则的任务，比如代码生成、文件处理或者工作流编排。

这个项目的核心价值在于它的“开箱即用”和“所有权”。它不是SaaS服务，你不需要注册账号，也不会被绑定在任何第三方平台上。所有代码、配置文件都归你所有，运行在你的本地环境或你完全控制的VPS上。这意味着更高的隐私性、可控性，以及零锁定风险。对于开发者、技术爱好者、小团队或者任何希望用自动化提升效率但又不想依赖黑盒服务的人来说，这是一个非常理想的起点。它基于OpenClaw这个开源框架构建，而Starter Kit则为你做好了最繁琐的初始化工作：智能体角色定义、通信配置、安全基线，全都预设好了。

2. 核心架构与设计思路解析

2.1 双智能体协作模型：分工与制衡

这个入门套件的核心设计哲学是“职责分离”和“简单有效”。它没有一上来就堆砌十几个功能各异的智能体，而是从最经典、最实用的“指挥官-执行者”双人模型开始。这种设计降低了初学者的认知负担，也让系统更稳定、更易于调试。

Orchestrator（协调者）是这个系统的大脑和前台。它的角色类似于一个经验丰富的项目经理或产品经理。所有外部的用户请求首先都会到达它这里。Orchestrator的核心工作不是去亲自写每一行代码，而是进行任务分类、意图理解和路由决策。当它收到一个请求，比如“帮我在项目里添加一个用户登录功能”，它会先分析这个请求的复杂性、所需的技能，并判断是否需要，以及如何调用Builder。它负责维护对话的上下文，确保用户的原始意图在整个执行过程中不被丢失或曲解。在Builder完成工作后，Orchestrator还负责对结果进行综合与润色，以更完整、更人性化的方式将最终结果返回给用户。这种设计确保了系统有一个统一的、智能的交互入口。

Builder（构建者）则是系统的双手，一个专注的执行专家。它的职责非常明确：安全、精准地实现代码变更。它被设计为“最小化变更”和“安全第一”。这意味着，当Orchestrator将一个具体的编码任务分配给它时，Builder会尝试用最简洁、对现有代码影响最小的方式去完成。更重要的是，它被赋予了“早期预警”的职责。如果在执行过程中，它发现任务描述与代码库的实际情况存在冲突（例如，要求修改一个不存在的文件，或者基于错误的理解进行编码），它会立即停止并向上汇报，而不是强行执行可能破坏系统的操作。这种制衡机制是防止AI“幻觉”导致灾难性错误的关键。

这种“Orchestrator-Builder”的二分法，模拟了现实中许多高效的工作流程。它避免了单个智能体既要宏观思考又要微观操作可能带来的混乱，也通过明确的职责边界提升了系统的可靠性和可解释性。当你想扩展系统时，这个模型也提供了清晰的插槽，例如，你可以在两者之间插入一个“Reviewer（审查者）”智能体，专门负责代码审核，从而形成一个更严谨的“规划-执行-检查”流水线。

2.2 技术栈与配置亮点：安全与简洁并重

这个Starter Kit在技术实现上做了大量减法，只保留最核心、最必要的部分，以确保极低的入门门槛和清晰的代码结构。

基于OpenClaw框架：整个系统构建在OpenClaw之上。OpenClaw是一个新兴的开源AI智能体框架，它的优势在于轻量、模块化和对多智能体协作的原生支持。选择它而不是更庞大的框架，意味着这个Starter Kit没有历史包袱，配置更直观，依赖更少，非常适合快速启动和深度定制。

网关安全配置：这是很多自托管AI项目容易忽略，但至关重要的部分。套件中的openclaw.json配置文件预设了非常保守的安全策略。

• Loopback绑定：网关服务默认只绑定在127.0.0.1（本地回环地址）上。这意味着服务只允许本机访问，无法从外部网络直接连接。这是防止服务被意外暴露在公网上的第一道防线。
• 令牌认证：所有通过网关的请求都必须携带一个由环境变量OPENCLAW_GATEWAY_TOKEN定义的令牌。这相当于为你的智能体系统设置了一个密码，即使未来因为配置需要将服务临时暴露，没有令牌也无法调用。
• 并发控制：maxConcurrent参数被设置为4，这限制了同时处理请求的智能体数量。对于入门级的双智能体系统，这个设置既能保证一定的吞吐，又能防止资源被突发的大量请求耗尽，导致服务崩溃。

工作空间隔离：项目中的workspaces/目录为每个智能体创建了独立的工作空间（orchestrator/和builder/）。每个空间内都有定义智能体“灵魂”（SOUL.md，即核心指令与人格）、可用工具（TOOLS.md）和记忆（memory/）的专属文件。这种物理隔离使得每个智能体的行为、知识和能力边界非常清晰，方便单独管理和调试。例如，你可以只修改Builder的SOUL.md，让它变得更谨慎，而不影响Orchestrator的决策逻辑。

注意：这种“一个命令部署”的便利性背后，是项目作者对默认安全设置的深思熟虑。对于生产环境，你至少需要修改默认的令牌，并谨慎评估是否需要以及如何安全地开放网络访问。永远不要使用默认或弱密码作为网关令牌。

3. 从零开始的完整部署与实操指南

3.1 环境准备与一键部署

部署这个系统，你只需要满足最基础的条件：一个安装了Node.js 18+和npm的Linux环境（Windows用户可以通过WSL获得完整的Linux体验）。macOS的支持在付费套件中提供，但Linux是更通用和推荐的选择。

整个部署过程被封装在了一个脚本中，真正做到了一键化。打开你的终端，依次执行以下三条命令：

git clone https://github.com/dropshipit369-blip/openclaw-starter-kit.git cd openclaw-starter-kit bash scripts/bootstrap.sh

我们来拆解一下bootstrap.sh这个脚本背后到底做了什么，这能让你在遇到问题时知道从哪里排查：

1. 环境检查：脚本首先会检查Node.js和npm的版本是否符合要求。如果不符合，它会明确报错并停止，这是为了避免在依赖版本混乱的环境下运行。
2. 依赖安装：它会进入项目目录，运行npm install，安装OpenClaw框架本身以及项目定义的所有Node.js依赖包。
3. 配置部署：将config/目录下的预置配置文件（主要是openclaw.json）复制到OpenClaw框架期望的标准位置。这步是关键，它把我们对智能体、网关、路由的定制化设置“注入”到了框架中。
4. 工作空间初始化：在OpenClaw的数据目录中，创建出orchestrator和builder两个智能体的专属工作空间，并将workspaces/目录下对应的SOUL.md、TOOLS.md等文件拷贝进去。这样，每个智能体启动时就能加载到正确的指令。
5. 运行验证：最后，脚本会尝试启动OpenClaw网关服务，并运行一个简单的健康检查或测试请求，以确保两个智能体都成功加载并可以响应。如果看到成功的提示信息，就说明你的双智能体系统已经就绪，在本地18789端口上监听请求。

实操心得：第一次运行脚本时，建议你在一个干净的终端窗口或屏幕会话（如tmux或screen）中操作，并留意终端的输出信息。如果脚本卡在某个步骤（比如npm安装因网络问题很慢），你可以按Ctrl+C中断，根据错误信息去解决。最常见的问题是Node版本过低或网络超时，前者需要你升级Node，后者可以尝试配置npm的国内镜像源。

3.2 核心配置文件详解与个性化定制

部署完成后，理解并学会修改配置文件，是你从“使用者”变为“掌控者”的关键。所有的魔法都藏在config/openclaw.json和各个工作空间的Markdown文件中。

网关配置 (openclaw.json)：这个文件是系统的大脑和中枢神经系统。我们重点看几个可定制项：

• port: 默认是18789。如果你本地这个端口已被占用（比如另一个开发服务），可以将其修改为任何未被使用的端口，如3000或8080。
• gatewayToken: 这里定义的是认证令牌的名称。实际令牌的值来自环境变量OPENCLAW_GATEWAY_TOKEN。强烈建议你在部署后立即设置一个强密码作为令牌。在终端中执行export OPENCLAW_GATEWAY_TOKEN=你的强密码（临时生效），或将其写入你的shell配置文件（如~/.bashrc）中永久生效。
• heartbeat: 设置为30分钟。这是网关内部健康检查的间隔，对于小型系统保持默认即可。
• agents: 这里定义了Orchestrator和Builder两个智能体。每个智能体的model字段默认是gpt-5.4-mini。这是你需要填入自己OpenAI API密钥的地方。系统运行时，会使用你通过环境变量（如OPENAI_API_KEY）设置的密钥来调用对应的模型。你也可以将其替换为其他兼容OpenAI API的模型端点，如gpt-4o-mini或来自其他提供商的模型。

智能体灵魂文件 (SOUL.md)：这是定义智能体“性格”和“能力边界”的核心文件。以workspaces/orchestrator/SOUL.md为例，它里面可能包含了这样的指令：“你是一个经验丰富的技术协调者，擅长分解复杂任务。你的首要职责是分析用户请求，只有当请求明确涉及代码创建或修改时，才将其路由给Builder…” 你可以像编辑任何文档一样修改这个文件，来改变智能体的行为模式。例如，如果你希望Orchestrator在转发任务给Builder时附上更详细的上下文，就可以在这里补充说明。

工具定义文件 (TOOLS.md)：这个文件列出了该智能体被允许使用的“工具”（可以理解为函数或API）。在Starter Kit中，Builder的TOOLS.md可能包含了读写文件、执行Shell命令（受限）等工具。Orchestrator的TOOLS.md则可能包含了“调用Builder”这个核心工具。修改这个文件需要格外谨慎，因为增加一个不受控的工具（比如无限制的Shell访问）可能会带来安全风险。对于初学者，建议先充分理解现有工具的工作方式，再考虑扩展。

个性化定制步骤：

1. 备份：在修改任何配置文件前，先复制一份备份。
2. 修改配置：用文本编辑器打开config/openclaw.json，按需调整端口、模型等参数。
3. 设置环境变量：在启动服务的终端中，提前设置好OPENCLAW_GATEWAY_TOKEN和OPENAI_API_KEY。
4. 重启服务：任何对openclaw.json或SOUL.md/TOOLS.md的修改，都需要重启OpenClaw网关服务才能生效。

3.3 运行、测试与基础交互

系统部署并配置好后，如何让它真正为你工作？你需要启动服务并学会如何与它通信。

启动服务：在项目根目录下，运行npm start或node gateway.js（具体命令请参考项目根目录的package.json中的scripts定义）。如果一切正常，终端会输出类似“Gateway running on http://127.0.0.1:18789”的信息，并且显示Orchestrator和Builder两个智能体已成功加载。

与服务交互：由于网关默认只绑定在本地且需要令牌认证，你不能直接用浏览器访问。你需要通过HTTP API来调用。最常用的工具是curl命令。下面是一个完整的测试请求示例：

curl -X POST http://127.0.0.1:18789/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \ -d '{ "agent": "orchestrator", "messages": [{"role": "user", "content": "请帮我创建一个简单的Python脚本，用于列出当前目录下的所有文件。"}] }'

让我们拆解这个命令：

• -X POST: 指定使用POST方法。
• -H "Authorization: Bearer ...": 这是认证头，$OPENCLAW_GATEWAY_TOKEN会被替换成你之前设置的环境变量的值。这是通过网关验证的关键。
• -d '...': 这是请求体，使用JSON格式。
  • "agent": "orchestrator": 指定请求由Orchestrator智能体处理。
  • "messages": 传递对话历史。这里我们发起了一个新的用户请求。

当你执行这个命令后，Orchestrator会分析你的请求，识别出这是一个“创建代码”的任务，于是它会调用Builder工具。Builder接收到具体指令后，会在其工作空间内生成一个Python脚本文件。最后，Orchestrator会将Builder的结果整合，返回一个包含脚本内容和说明的响应。你会在终端看到这个完整的JSON响应。

实操心得：刚开始测试时，可以从非常具体、边界清晰的小任务开始，比如“创建一个名为hello.txt的空文件”或“写一个计算1到10之和的Python函数”。观察Orchestrator是如何描述任务、Builder是如何执行的。使用curl可能对新手不太友好，你可以考虑使用图形化的API测试工具，如Insomnia或Postman。在这些工具中，你可以将请求方法、URL、Headers和Body配置好并保存，以后点击一下就能发送，大大提升了测试效率。同时，务必关注服务运行终端的日志输出，那里会详细记录每个智能体的思考过程、工具调用和可能发生的错误，是调试的最佳信息来源。

4. 进阶扩展：从双智能体到专业工作流

Starter Kit让你轻松入门，但它的真正潜力在于作为一个可扩展的基础。项目文档中提到的付费套件揭示了一个更成熟的智能体生态系统蓝图。即使你不购买付费套件，理解这个蓝图也能指导你如何自定义扩展。

4.1 理解专业套件中的智能体角色

付费套件引入了几个新的专业智能体角色，每一个都解决了双智能体模型下的特定短板：

• Reviewer（审查者）：这是一个“只读”审计员。在Builder完成代码修改后，Orchestrator可以将修改内容发送给Reviewer进行二次检查。Reviewer可以检查代码风格是否符合规范、是否存在明显的安全漏洞（如硬编码密码）、逻辑是否有误。这相当于在“执行”和“交付”之间增加了一个质量关卡，显著降低了错误代码被提交的风险。
• Researcher（研究者）：当Orchestrator遇到一个需要外部知识或数据才能完成的任务时（例如，“总结今天关于AI智能体的主要新闻”），它可以调用Researcher。Researcher可以被授权使用网络搜索工具、读取特定API文档或数据库，收集信息并整理成摘要，再交还给Orchestrator进行综合。这极大地扩展了系统的能力边界，使其不局限于本地代码操作。
• Ops（运维者）：这个智能体专注于系统本身的状态。它可以定期检查服务日志、监控资源使用情况（CPU、内存）、测试网关连通性，甚至在检测到异常时尝试执行预定义的恢复操作（如重启某个服务）。将运维职责剥离给一个专用智能体，可以让Orchestrator更专注于业务逻辑。

4.2 自定义扩展的思路与安全考量

受到付费套件的启发，你可以为自己的Starter Kit添加第三个智能体。假设你想增加一个Translator（翻译者）智能体，专门负责中英文技术文档的互译。

步骤大致如下：

1. 创建工作空间：在workspaces/目录下，新建一个translator/文件夹。
2. 定义灵魂：创建translator/SOUL.md，详细描述其角色：“你是一名专业的科技文档翻译，专注于中英文互译，确保技术术语准确，语言流畅…”
3. 定义工具：创建translator/TOOLS.md。它可能不需要文件操作工具，但可以调用翻译API（如果你有）。最初，可以只让它进行纯文本处理。
4. 修改主配置：在config/openclaw.json的agents数组里，新增一个translator的配置块，指定其模型和工作空间路径。
5. 为Orchestrator扩展工具：修改workspaces/orchestrator/TOOLS.md，增加一个“调用Translator”的工具定义。这需要你了解OpenClaw框架中如何定义跨智能体调用的工具，通常涉及在配置中设置新的工具路由。
6. 更新Orchestrator灵魂：在orchestrator/SOUL.md中补充说明，当用户请求涉及文档翻译时，应调用Translator。

安全考量：在扩展时，必须牢记“最小权限原则”。给Translator智能体赋予它完成工作所必需的最小权限。例如，如果它只做文本翻译，就绝对不要给它文件系统写入权限。在TOOLS.md中明确定义工具的使用范围和限制。同时，像网关令牌、API密钥这类敏感信息，永远不要写在配置文件里，必须通过环境变量传入。

4.3 成本控制与生产环境部署建议

当你的智能体系统开始处理真实任务时，成本（主要是大模型API调用费用）和稳定性就成为核心关切。

成本控制策略：

• 模型选择：gpt-5.4-mini是一个假设的模型名。在实际中，你可以根据任务难度选择不同价位的模型。例如，让Orchestrator使用能力更强的模型（如GPT-4）来保证复杂的任务分解和路由准确，而让Builder使用更经济的小模型（如GPT-3.5-Turbo）来执行具体的、模式化的编码任务。这需要在每个智能体的配置中分别指定model参数。
• 心跳与超时：付费套件提到了“55m heartbeat”。心跳间隔会影响智能体在空闲状态下维持会话的成本。更短的心跳意味着更频繁的上下文保持（可能产生费用），更长的心跳则可能在长时间无交互后丢失上下文。你需要根据使用频率找到平衡点。在openclaw.json中可以调整相关超时设置。
• 任务批处理：设计工作流时，可以考虑让Orchestrator积累一些类似的小任务，再一次性提交给Builder处理，减少频繁调用带来的开销。

生产环境部署建议：

1. 使用进程守护：不要让服务仅仅运行在终端前台。使用systemd(Linux) 或launchd(macOS) 将其配置为系统服务，实现开机自启、崩溃重启、日志集中管理。付费套件提供了模板，你可以自行搜索“systemd service file example”来创建。
2. 日志与监控：确保OpenClaw的日志输出被重定向到文件（如/var/log/openclaw.log），并定期检查。可以搭配简单的监控脚本，检查服务端口是否存活。
3. 网络暴露：如果需要在内部网络让其他机器访问，可以修改网关绑定地址为0.0.0.0，但必须同时设置强网关令牌，并考虑配置防火墙规则，只允许特定的IP段访问。
4. 版本控制：将你自定义的workspaces/和config/目录纳入Git版本控制，方便回滚和协作。
5. 备份：定期备份智能体的memory/目录（如果其中存储了重要的对话记忆）和你的自定义配置文件。

5. 常见问题与故障排查实录

在实际部署和运行过程中，你几乎一定会遇到一些问题。下面是我在搭建和测试类似系统时遇到的一些典型情况及其解决方法，希望能帮你少走弯路。

5.1 部署与启动问题

问题1：运行bash scripts/bootstrap.sh时提示node: command not found或npm: command not found。

• 原因：Node.js环境没有安装，或者没有正确添加到系统的PATH环境变量中。
• 解决：
  1. 确认安装：在终端输入node --version和npm --version看是否有版本号输出。
  2. 如果没有，去Node.js官网下载并安装LTS版本。对于Linux，通常使用包管理器更简单，例如 Ubuntu/Debian 用sudo apt update && sudo apt install nodejs npm。
  3. 安装后，可能需要重新打开终端或执行source ~/.bashrc使环境变量生效。

问题2：npm install步骤卡住或报网络错误。

• 原因：npm默认源在国内访问可能较慢或不稳定。
• 解决：可以临时切换为国内镜像源。在项目目录下执行：

  npm config set registry https://registry.npmmirror.com

  然后重新运行bash scripts/bootstrap.sh。安装完成后，如果想切回官方源，执行npm config set registry https://registry.npmjs.org。

问题3：脚本执行成功，但服务启动失败，端口被占用。

• 原因：默认的18789端口可能被其他程序占用。
• 解决：
  1. 找出占用端口的进程：sudo lsof -i :18789或sudo netstat -tulpn | grep 18789。
  2. 停止该进程，或者修改config/openclaw.json中的port为其他空闲端口（如3000）。
  3. 重启服务。

5.2 运行时与交互问题

问题4：使用curl调用API时，返回401 Unauthorized错误。

• 原因：请求头中缺少有效的Authorization令牌，或令牌值错误。
• 解决：
  1. 确保你已设置环境变量：echo $OPENCLAW_GATEWAY_TOKEN，看看是否有输出。
  2. 如果没有，请设置：export OPENCLAW_GATEWAY_TOKEN=你的强密码。
  3. 在curl命令中，Bearer $OPENCLAW_GATEWAY_TOKEN会自动使用变量。如果变量未设置，你需要写死令牌（不推荐）：-H "Authorization: Bearer your_token_here"。
  4. 检查网关配置中gatewayToken字段的名字是否与你设置的环境变量名完全一致（默认是OPENCLAW_GATEWAY_TOKEN）。

问题5：请求成功，但Orchestrator没有调用Builder，或者返回错误说找不到Builder工具。

• 原因：智能体配置或工具定义可能有问题，或者智能体没有正确理解任务。
• 排查：
  1. 查看日志：服务运行终端的日志是最重要的信息源。仔细阅读Orchestrator收到请求后的“思考”过程，看它是否识别出这是编码任务，以及尝试调用Builder时具体报什么错。
  2. 检查工具定义：确认workspaces/orchestrator/TOOLS.md文件中正确定义了调用Builder的工具，并且工具名称在SOUL.md的指令中被正确引用。
  3. 简化测试：发送一个极其明确的任务，如“调用Builder工具，创建一个名为test.txt的空文件”，看Orchestrator如何响应。

问题6：Builder执行写文件操作失败，提示权限不足。

• 原因：Builder智能体运行进程的用户身份可能没有对目标目录的写权限。
• 解决：
  1. 检查OpenClaw服务进程是以哪个用户运行的（如ps aux | grep openclaw）。
  2. 确保该用户对你希望操作的文件和目录有读写权限。在开发环境，一个简单但不安全的方法是让服务以你的当前用户运行。在生产环境，则需要精心规划用户和目录权限。

5.3 性能与稳定性问题

问题7：处理复杂任务时响应非常慢，或者超时。

• 原因：可能是大模型API响应慢，或者是智能体陷入了复杂的循环思考。
• 优化：
  1. 设置超时：在openclaw.json的网关或智能体配置中，增加请求超时（timeout）设置，避免无限等待。
  2. 任务拆解：让Orchestrator学会将过大的任务拆分成多个子任务，分批交给Builder处理。
  3. 模型降级：对于执行步骤明确、创造性要求不高的任务，尝试让Builder使用更快、更便宜的模型。

问题8：智能体的“记忆”似乎不持久，重启服务后忘了之前的对话。

• 原因：默认配置下，智能体的对话记忆可能仅保存在内存（RAM）中，服务重启后丢失。
• 解决：这取决于OpenClaw框架和你的配置。检查workspaces/agent_name/memory/目录，看是否有文件生成。有些框架需要显式配置将记忆持久化到数据库或向量库。Starter Kit可能只提供了基础的、基于文件的短期记忆。对于需要长期记忆的场景，你可能需要研究OpenClaw框架的文档，集成像SQLite或Chroma这样的持久化存储方案。

核心排查心法：当遇到任何问题时，遵循“从外到内，从日志开始”的原则。首先检查环境、网络、权限等外部因素；然后，仔细阅读服务终端和控制台输出的每一条日志，AI智能体的“思考链”通常会在日志中完整呈现，这是定位问题根源最直接的方式。不要害怕修改SOUL.md文件，用更清晰、更严格的指令去约束智能体的行为，往往是解决其行为异常的最有效方法。