[← 第 07 章](/openclaw-tutorial/07-%E9%A3%9E%E4%B9%A6%E9%9B%86%E6%88%90%E4%B8%8E%E6%B6%88%E6%81%AF%E8%87%AA%E5%8A%A8%E5%8C%96.html) · [📑 目录](/openclaw-tutorial/) · [📋 大纲](/openclaw-tutorial/OUTLINE.html) · [第 09 章 →](/openclaw-tutorial/09-%E6%95%85%E9%9A%9C%E6%8E%92%E6%9F%A5%E4%B8%8E%E6%97%A5%E5%BF%97%E5%88%86%E6%9E%90.html)

第 8 章:单 Gateway 多 Agent 配置与管理

difficulty time chapter

难度: ⭐⭐ 基础 预计阅读: 20 分钟 前置章节: 第 2 章

本章讲解如何在单个 Gateway 下配置和管理多个 Agent,实现多项目隔离、多角色协作。这是 OpenClaw 中高级运维的核心能力。适用于需要在同一台机器或同一集群中运行多个独立 AI 助手的场景,如团队内多角色分工、多项目 DevOps 自动化等。

📑 本章目录


8.1 多 Agent 架构

OpenClaw 支持在单个 Gateway 下运行多个 Agent,每个 Agent 有独立的身份、记忆和技能配置。Gateway 充当统一的消息路由层,负责将来自不同渠道的请求分发到对应的 Agent 进行处理。

8.1.1 整体架构图

Gateway (端口 18789) ─── 统一入口
├── Agent 1: 技术助手 (workspace-1/)
│   ├── IDENTITY.md     → 技术专家身份
│   ├── SOUL.md         → 严谨分析风格
│   ├── skills/         → 编程、调试相关
│   └── memory/         → 技术笔记
├── Agent 2: 运营助手 (workspace-2/)
│   ├── IDENTITY.md     → 运营分析师身份
│   ├── SOUL.md         → 数据驱动风格
│   ├── skills/         → 数据分析相关
│   └── memory/         → 运营报告
└── Agent 3: 项目助手 (workspace-3/)
    ├── IDENTITY.md     → 项目经理身份
    ├── SOUL.md         → 结构化沟通风格
    ├── skills/         → 任务管理相关
    └── memory/         → 项目进展

8.1.2 核心概念一览

概念 说明 存储位置
Gateway 统一消息入口,负责路由和负载均衡 openclaw.json
Agent 独立的 AI 实体,拥有自己的身份和配置 ~/.openclaw/agents/<name>/
Workspace Agent 的工作目录,存放身份、记忆、技能 agents/<name>/workspace/
路由规则 根据渠道/关键词将请求分发到指定 Agent openclaw.jsonrouting 字段
共享记忆 跨 Agent 共用的数据存储区域 ~/.openclaw/workspace/shared-memory/

每个 Agent 拥有完全独立的:

8.1.3 隔离优势

可以通过以下命令快速验证当前 Gateway 下有哪些 Agent:

# 查看已注册的 Agent 列表
openclaw agents list

8.2 Agent 配置与创建

8.2.1 创建新 Agent

下面以创建一个”运营助手”Agent 为例,完整演示创建流程:

# 1. 创建 Agent workspace 目录
mkdir -p ~/.openclaw/agents/agent-2/workspace
cd ~/.openclaw/agents/agent-2/workspace

# 2. 创建身份文件
cat > IDENTITY.md << 'EOF'
---
name: 运营助手
role: 运营数据分析与报告生成
style: 专业严谨,数据驱动
---
# 运营助手

我是一个专注于运营数据分析的 AI 助手。

## 核心能力
- 数据报表自动生成
- 竞品监控与分析
- 用户反馈整理
EOF

# 3. 创建行为准则
cat > SOUL.md << 'EOF'

## 行为准则
- 以数据说话,避免主观判断
- 报告格式清晰、结构化
- 敏感数据脱敏处理
EOF

# 4. 创建记忆和技能目录
mkdir -p memory/ skills/ config/

# 5. 验证 workspace 结构
tree ~/.openclaw/agents/agent-2/workspace/

8.2.2 Agent 配置参数详解

每个 Agent 支持以下配置项,可在 openclaw.jsonagents 字段中定义:

配置项 类型 默认值 说明
workspace string 必填 Agent 的 workspace 目录路径
channels string[] [] 绑定的消息渠道列表
model string 继承全局 使用的 AI 模型名称
maxConcurrent number 5 最大并发请求数
memoryLimit string "256MB" 内存使用上限
timeout number 600 单次请求超时时间(秒)
enabled boolean true 是否启用此 Agent

8.2.3 路由配置

在 Gateway 配置中设置 Agent 路由规则,将不同渠道或用户映射到不同 Agent。

{
  "agents": {
    "agent-1": {
      "workspace": "~/.openclaw/agents/agent-1/workspace",
      "channels": ["feishu:group-tech"],
      "model": "claude-sonnet-4-20250514",
      "enabled": true
    },
    "agent-2": {
      "workspace": "~/.openclaw/agents/agent-2/workspace",
      "channels": ["feishu:group-ops"],
      "model": "gpt-4o",
      "enabled": true
    }
  }
}

配置完成后验证路由是否生效:

# 检查路由配置是否正确
openclaw config validate

# 查看当前生效的路由映射
openclaw agents routes

8.2.4 配置热加载

修改 Agent 配置后,Gateway 支持热加载而不中断服务:

# 发送信号触发重载
openclaw gateway reload

# 或通过 API
curl -X POST http://localhost:18789/admin/reload

# 验证重载结果
openclaw agents list --verbose

[!TIP] 热加载仅更新配置层面的变更(如路由规则、模型切换),Agent 的 workspace 文件变更(如 IDENTITY.md)会在下一次请求时自动读取,无需重载。


8.3 Agent 间通信与协作

多个 Agent 可以通过共享文件或消息通道进行协作。合理设计协作模式可以实现复杂的多步骤自动化流水线。

8.3.1 协作模式对比

协作模式 适用场景 优点 缺点
共享文件 异步数据交换 简单可靠,易于调试 实时性较差
消息转发 请求级联处理 实时性好,链路清晰 配置相对复杂
Cron 定时协作 定期汇总分析 自动化程度高 存在时间延迟
API 直接调用 即时协作 响应最快 耦合度较高

8.3.2 共享记忆目录

~/.openclaw/
├── workspace/shared-memory/     ← 所有 Agent 可访问
│   ├── project-status.json      ← 共享项目状态
│   └── team-notes.md            ← 团队笔记
├── agents/
│   ├── agent-1/workspace/       ← Agent 1 专属
│   └── agent-2/workspace/       ← Agent 2 专属

创建共享记忆目录并初始化:

# 创建共享记忆区
mkdir -p ~/.openclaw/workspace/shared-memory

# 初始化共享状态文件
cat > ~/.openclaw/workspace/shared-memory/project-status.json << 'EOF'
{
  "lastUpdated": "2026-03-06",
  "activeProjects": [],
  "sharedNotes": []
}
EOF

8.3.3 消息转发

Gateway 支持将消息从一个 Agent 转发到另一个 Agent 处理:

{
  "routing": {
    "rules": [
      {"pattern": "技术问题.*", "target": "agent-1"},
      {"pattern": "运营报告.*", "target": "agent-2"},
      {"pattern": "项目进度.*", "target": "agent-3"},
      {"pattern": "default", "target": "agent-1"}
    ]
  }
}

路由规则按照从上到下的顺序匹配,第一条匹配的规则生效。"default" 规则作为兜底,处理所有未匹配的请求。

8.3.4 Agent 协作示例

场景:技术助手生成报告 → 运营助手分析数据 → 项目助手汇总进度

# Step 1: Agent 1 (技术助手) 将技术报告写入共享目录
echo "## 技术周报 - $(date +%Y-%m-%d)
- 完成功能 A 开发
- 修复 Bug #123
- 性能优化提升 20%" > ~/.openclaw/workspace/shared-memory/tech-report.md

# Step 2: Agent 2 (运营助手) 的 Cron 任务定期检查并生成分析
# 在 Agent 2 的 cron/jobs.json 中配置:
cat > ~/.openclaw/agents/agent-2/cron-check.json << 'EOF'
{
  "jobs": [
    {
      "name": "analyze-tech-report",
      "schedule": "0 9 * * 1",
      "command": "分析共享目录中的技术报告并生成运营洞察"
    }
  ]
}
EOF

# Step 3: 查看协作状态
cat ~/.openclaw/workspace/shared-memory/project-status.json

8.4 资源管理与监控

8.4.1 资源限制配置

为每个 Agent 设置合理的资源限制,防止单个 Agent 占用过多系统资源:

{
  "agents": {
    "agent-1": {
      "maxConcurrent": 3,
      "memoryLimit": "512MB",
      "timeout": 300
    },
    "agent-2": {
      "maxConcurrent": 2,
      "memoryLimit": "256MB",
      "timeout": 600
    }
  }
}

8.4.2 监控命令

# 查看所有 Agent 状态
openclaw agents list

# 查看单个 Agent 详情(包含运行状态、活跃会话数等)
openclaw agents status agent-1

# 查看资源占用统计
openclaw agents stats

# 查看 Gateway 整体健康状态
openclaw gateway status

# 实时监控 Agent 日志输出
openclaw logs --agent agent-1 --follow

8.4.3 性能调优建议

场景 建议 命令/操作
Agent 数量 > 5 增加 Gateway 内存限制 修改 openclaw.jsongateway.memoryLimit
高并发请求 设置 maxConcurrent 限制 按 Agent 重要性分配并发配额
大量 Skills 启用懒加载模式 设置 "lazyLoad": true
记忆文件过多 定期归档和清理 openclaw memory archive --agent agent-1
Agent 响应慢 检查模型配置和超时时间 openclaw agents status <name>
磁盘空间不足 清理日志和临时文件 openclaw cleanup --logs --temp

8.5 实操练习

以下练习帮助你从零搭建多 Agent 环境,建议按顺序完成。

练习 1:创建双 Agent 环境

目标:在本机创建两个 Agent(技术助手 + 运营助手),并验证隔离性。

# Step 1: 创建技术助手 Agent
mkdir -p ~/.openclaw/agents/tech-agent/workspace/{memory,skills,config}
cat > ~/.openclaw/agents/tech-agent/workspace/IDENTITY.md << 'EOF'
---
name: 技术助手
role: 代码审查与技术咨询
style: 严谨、逻辑清晰
---
# 技术助手
专注于代码质量和技术架构。
EOF

# Step 2: 创建运营助手 Agent
mkdir -p ~/.openclaw/agents/ops-agent/workspace/{memory,skills,config}
cat > ~/.openclaw/agents/ops-agent/workspace/IDENTITY.md << 'EOF'
---
name: 运营助手
role: 运营数据分析
style: 数据驱动、简洁明了
---
# 运营助手
专注于数据分析与运营洞察。
EOF

# Step 3: 验证目录结构
echo "=== 技术助手 ===" && ls ~/.openclaw/agents/tech-agent/workspace/
echo "=== 运营助手 ===" && ls ~/.openclaw/agents/ops-agent/workspace/

# Step 4: 注册到 Gateway
openclaw agents list

验证要点:确认两个 Agent 目录独立,IDENTITY.md 内容不同。

练习 2:配置路由规则并测试消息分发

目标:设置基于关键词的路由规则,测试消息是否正确分发到对应 Agent。

# Step 1: 编辑路由配置(手动编辑 openclaw.json 或使用命令)
# 在 openclaw.json 中添加 agents 和 routing 配置

# Step 2: 验证配置有效性
openclaw config validate

# Step 3: 重载 Gateway 使配置生效
openclaw gateway reload

# Step 4: 查看路由映射
openclaw agents routes

# Step 5: 通过 API 测试消息分发
curl -s http://localhost:18789/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "技术问题:如何优化数据库查询?"}' | jq .agentId

curl -s http://localhost:18789/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "运营报告:本周用户增长趋势"}' | jq .agentId

验证要点:包含”技术问题”的消息应路由到 tech-agent,包含”运营报告”的消息应路由到 ops-agent。

练习 3:实现跨 Agent 协作流水线

目标:搭建一个从技术报告生成到运营分析的自动化流水线。

# Step 1: 创建共享目录
mkdir -p ~/.openclaw/workspace/shared-memory/reports

# Step 2: 模拟技术助手输出报告
cat > ~/.openclaw/workspace/shared-memory/reports/weekly-tech.md << 'EOF'
# 技术周报 2026-03-06

## 完成事项
- API 接口重构完成,响应时间减少 40%
- 新增 3 个自动化测试用例

## 待处理
- 数据库迁移计划制定
EOF

# Step 3: 配置运营助手的定时检查任务
cat > ~/.openclaw/agents/ops-agent/workspace/config/watch-reports.json << 'EOF'
{
  "watch": {
    "path": "~/.openclaw/workspace/shared-memory/reports/",
    "pattern": "*.md",
    "action": "分析技术报告,提取关键指标,生成运营摘要"
  }
}
EOF

# Step 4: 验证共享文件可被两个 Agent 读取
cat ~/.openclaw/workspace/shared-memory/reports/weekly-tech.md

# Step 5: 查看协作状态
openclaw agents stats

验证要点:共享目录中的文件可以被两个 Agent 正常读写,流水线数据传递正常。


8.6 常见问题 (FAQ)

Q1: 多个 Agent 之间如何保证数据隔离?

A: 每个 Agent 拥有完全独立的 workspace 目录,包括 IDENTITY.mdSOUL.mdmemory/skills/ 等。Gateway 通过唯一路由规则将请求分发到指定 Agent,不会出现跨 Agent 的数据泄露。你可以通过以下命令检查隔离状态:

# 确认每个 Agent 的 workspace 路径独立
openclaw agents list --verbose

Q2: Gateway 资源占用过高怎么办?

A: 当多个 Agent 同时处理请求时,Gateway 的内存和 CPU 占用会增加。建议从以下几方面优化:

  1. 降低 maxConcurrent 限制每个 Agent 的并发请求数
  2. 启用 "lazyLoad": true 让不活跃的 Agent 自动卸载技能
  3. 定期清理低活跃 Agent 的缓存:openclaw cleanup --cache
  4. 使用 openclaw agents stats 定位消耗最高的 Agent

Q3: 如何在飞书中切换不同的 Agent?

A: 有两种方式切换 Agent:

Q4: Agent 配置修改后必须重启 Gateway 吗?

A: 不需要。OpenClaw Gateway 支持热加载机制,执行 openclaw gateway reload 即可应用新配置。Agent workspace 中的文件变更(如修改 IDENTITY.md)在下一次请求时自动生效,甚至不需要 reload。

Q5: 单个 Gateway 最多能管理多少个 Agent?

A: 没有硬性上限,但建议根据服务器资源合理规划:

超过 5 个 Agent 时建议启用懒加载模式。使用 openclaw agents stats 持续监控资源使用情况。


8.7 外部参考



注意事项与常见错误

多 Agent 配置中以下错误最易被忽视:

常见错误 后果 正确做法
Agent 名称重复 路由混乱,消息发错 确保每个 Agent 有唯一标识
共享同一 workspace 记忆和配置互相覆盖 每个 Agent 使用独立 workspace 目录
未设置资源限制 单个 Agent 占满内存 使用 NODE_OPTIONS 限制内存上限

注意事项与常见错误

多 Agent 配置中常见错误:

常见错误 后果 正确做法
Agent 名称重复 路由混乱 确保唯一标识
共享同一 workspace 配置覆盖 使用独立 workspace
未设置资源限制 内存占满 设置 NODE_OPTIONS


常见问题 (FAQ)

Q: 本章内容是否需要前置知识?

A: 建议先完成前面的章节,确保理解 OpenClaw 的基础概念和安装方式。

Q: 遇到命令执行错误怎么办?

A: 请检查 OpenClaw 是否正确安装,运行 openclaw --version 确认版本。如问题持续,请参考故障排查章节或提交 GitHub Issue。

Q: 如何获取更多帮助?

A: 可以通过以下渠道获取帮助:


参考来源

来源 链接 可信度 说明
OpenClaw 官方文档 https://docs.OpenClaw.ai A 安装, 配置, 命令
OpenClaw GitHub 仓库 https://github.com/OpenClaw/OpenClaw A 源码, Issues, Release
ClawHub Skills 平台 https://hub.OpenClaw.ai A Skills, 市场, 安装
Docker 官方文档 https://docs.docker.com A Docker, 容器, 部署
systemd 管理文档 https://www.freedesktop.org/wiki/Software/systemd/ A systemd, 服务管理, 后台运行

本章小结


[← 上一章:飞书集成与消息自动化](/openclaw-tutorial/07-%E9%A3%9E%E4%B9%A6%E9%9B%86%E6%88%90%E4%B8%8E%E6%B6%88%E6%81%AF%E8%87%AA%E5%8A%A8%E5%8C%96.html) · [📑 返回目录](/openclaw-tutorial/) · [下一章:故障排查与日志分析 →](/openclaw-tutorial/09-%E6%95%85%E9%9A%9C%E6%8E%92%E6%9F%A5%E4%B8%8E%E6%97%A5%E5%BF%97%E5%88%86%E6%9E%90.html)