OpenClaw 多 Agent 完整设置与配置教程(2026 最新版)

OpenClaw 多 Agent 架构支持在单一 Gateway 进程中运行多个完全隔离的 AI 智能体，每个 Agent 拥有独立工作区、模型配置、权限、会话记忆与通道绑定，实现工作/生活/专业场景的精准隔离。本文从环境准备、创建、配置、路由、启动到高级优化，提供完整可落地的 MD 教程。

一、核心概念（先看懂再配置）

1.1 关键术语

Agent（智能体）
：独立 AI 大脑，含专属 id、工作区、模型、权限、会话、人设
agentId
：Agent 唯一标识（英文小写，如 main/coding/research）
Workspace
：Agent 本地文件/知识库/工具数据目录（完全隔离）
agentDir
：Agent 状态/认证/配置存储目录（~/.openclaw/agents/<id>）
Channel
：消息通道（Telegram/Discord/WhatsApp/飞书/微信等）
Account
：通道下的独立账号（如 2 个 Telegram Bot、2 个飞书应用）
Binding
：路由规则 → (通道, 账号, 群组/私聊) → 路由到指定 agentId

1.2 多 Agent 核心价值

✅ 记忆隔离：不同 Agent 聊天历史/知识库完全独立 ✅ 权限隔离：工作 Agent 高权限、生活 Agent 只读/低权限 ✅ 模型隔离：编码用 DeepSeek、写作用 Claude、分析用 Kimi ✅ 通道隔离：飞书工作、Telegram 生活、Discord 开发分开响应 ✅ 成本优化：简单任务用廉价模型，复杂任务用高阶模型

二、环境准备（必做）

2.1 系统要求

OS
：Ubuntu 22.04+/macOS 13+/Windows 11 WSL2
内存
：≥4GB（多 Agent 推荐 ≥8GB）
存储
：≥10GB（工作区/向量库占用）
依赖
：Docker & Docker Compose（推荐）/ Node.js 20+（原生）

2.2 安装 OpenClaw

方式 1：Docker（推荐，隔离性强）

# 拉取最新镜像 docker pull openclaw/openclaw:latest

# 初始化配置目录 mkdir -p ~/.openclaw && chmod 777 ~/.openclaw

方式 2：npm 原生安装

# 全局安装 npm install -g agentclaw

# 初始化 openclaw init

### 2.3 目录结构规范（多 Agent 必备）

```

~/.openclaw/ # 主配置目录

├── config.yaml # 主配置（YAML 优先于 JSON）

├── openclaw.json # 备用配置

├── .env # 密钥/API Key（安全存储）

├── agents/ # 所有 Agent 状态目录

│ ├── main/ # 默认主 Agent

│ ├── coding/ # 编码 Agent

│ └── research/ # 研究 Agent

└── workspaces/ # 独立工作区（推荐）

├── main/

├── coding/

└── research/

```

---

## 三、创建多 Agent（2 种方式）

### 3.1 方式 1：CLI 命令（快速创建）

```bash

# 1. 创建编码 Agent

openclaw agents add coding --name "代码开发助手" --workspace ~/.openclaw/workspaces/coding

# 2. 创建研究分析 Agent

openclaw agents add research --name "数据分析研究员" --workspace ~/.openclaw/workspaces/research

# 3. 查看所有 Agent

openclaw agents list

```

执行后自动在 `config.yaml`/`openclaw.json` 生成 `agents.list` 配置。

### 3.2 方式 2：手动配置文件（精准控制）

编辑 `~/.openclaw/config.yaml`（YAML 更易维护多 Agent）：

```yaml

agents:

# 全局默认配置（所有 Agent 继承）

defaults:

model:

provider: openrouter

model: openrouter/auto

temperature: 0.7

permissions:

- browse:limited

- shell:restricted

memory:

enabled: true

type: vector

size: 10000

# 定义所有 Agent

list:

# 1. 默认主 Agent（必须保留，系统入口）

- id: main

workspace: ~/.openclaw/workspaces/main

agentDir: ~/.openclaw/agents/main/agent

model:

temperature: 0.8 # 覆盖默认

permissions:

- browse:all

- shell:limited

# 2. 编码专用 Agent

- id: coding

workspace: ~/.openclaw/workspaces/coding

agentDir: ~/.openclaw/agents/coding/agent

model:

provider: deepseek

model: deepseek-coder-v2

temperature: 0.3 # 低随机性，精准编码

max_tokens: 4096

permissions:

- shell:restricted:~/dev # 仅允许操作开发目录

- browse:docs:https://docs.openclaw.ai # 仅允许访问官方文档

skills:

- code_exec

- git

- file_edit

# 3. 研究分析 Agent

- id: research

workspace: ~/.openclaw/workspaces/research

agentDir: ~/.openclaw/agents/research/agent

model:

provider: moonshot

model: kimi-v2

temperature: 0.2

context_length: 256000 # 256K 超长上下文

permissions:

- search:limited

- cron:all

skills:

- brave_search

- data_analysis

- report_gen

```

---

四、通道与账号配置（多通道隔离）

4.1 支持通道列表

Telegram、Discord、WhatsApp、飞书（Feishu）、Slack、iMessage、Signal、微信

4.2 配置通道账号（以 Telegram + Discord 为例）

步骤 1：准备通道凭证

Telegram
：@BotFather 创建 Bot → 获取 TELEGRAM_TOKEN
Discord
：开发者平台创建应用 → 启用 Message Content Intent → 获取 DISCORD_TOKEN

#### 步骤 2：写入 .env（密钥安全存储）

```bash

nano ~/.openclaw/.env

```

```env

# OpenRouter API（通用模型）

OPENROUTER_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx

# DeepSeek API（编码专用）

DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx

# Moonshot API（研究专用）

MOONSHOT_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx

# Telegram 账号（2 个独立 Bot）

TELEGRAM_TOKEN_MAIN=xxxxxxxxxx:xxxxxxxxxxxxxxxxxxxx

TELEGRAM_TOKEN_CODING=xxxxxxxxxx:xxxxxxxxxxxxxxxxxxxx

# Discord 账号（2 个独立 Bot）

DISCORD_TOKEN_MAIN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

DISCORD_TOKEN_CODING=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

```

#### 步骤 3：config.yaml 配置通道与账号

```yaml

channels:

telegram:

enabled: true

accounts:

# 主 Telegram 账号（绑定 main Agent）

- id: tg-main

token: ${TELEGRAM_TOKEN_MAIN}

prefix: "/"

# 编码 Telegram 账号（绑定 coding Agent）

- id: tg-coding

token: ${TELEGRAM_TOKEN_CODING}

prefix: "!"

discord:

enabled: true

accounts:

# 主 Discord 账号

- id: discord-main

token: ${DISCORD_TOKEN_MAIN}

prefix: "!"

# 编码 Discord 账号

- id: discord-coding

token: ${DISCORD_TOKEN_CODING}

prefix: "/"

```

五、Binding 路由配置（核心！消息分发）

5.1 路由规则

匹配顺序
：从上到下，第一条匹配立即生效
匹配维度
：channel + accountId + guild/team + peer
默认路由
：未匹配则走 main Agent

### 5.2 完整 Binding 配置

```yaml

agents:

# ... 省略 agents.list 与 defaults ...

# 核心：路由绑定（消息 → Agent）

bindings:

# 1. 主 Telegram 账号 → main Agent（所有消息）

- channel: telegram

accountId: tg-main

agentId: main

# 2. 编码 Telegram 账号 → coding Agent（所有消息）

- channel: telegram

accountId: tg-coding

agentId: coding

# 3. 主 Discord 私聊 → main Agent

- channel: discord

accountId: discord-main

type: dm # 仅私聊

agentId: main

# 4. Discord 开发服务器（ID:123456789）→ coding Agent

- channel: discord

accountId: discord-coding

guildId: "123456789" # 服务器 ID

agentId: coding

# 5. 飞书工作群 → research Agent（数据分析）

- channel: feishu

accountId: feishu-work

chatId: "oc_xxxxxx"

agentId: research

# 6. 默认兜底：所有未匹配 → main Agent

- channel: "*"

accountId: "*"

agentId: main

```

---

六、Agent 人设与工作区配置（个性化）

6.1 每个 Agent 独立人设文件

在对应 workspace 创建 3 个核心文件：

1. SOUL.md（Agent 核心人设/指令）

~/.openclaw/workspaces/coding/SOUL.md

# 身份 你是专业的代码开发助手，精通 Python/Go/JavaScript/Rust，专注高质量、可维护、安全的代码实现。  # 核心规则 - 输出代码必须带完整注释、类型提示、错误处理 - 优先提供最优实践与性能优化方案 - 禁止生成不安全/漏洞代码 - 仅回答编程相关问题，拒绝无关内容 - 严格遵守权限：仅操作 ~/dev 目录

2. AGENTS.md（子 Agent/协作配置）

~/.openclaw/workspaces/research/AGENTS.md

# 协作规则 允许调度：main、coding 禁止调度：无  # 数据共享 仅共享非敏感分析结果，不共享原始数据

3. USER.md（用户偏好/历史）

~/.openclaw/workspaces/main/USER.md

# 用户偏好 - 喜欢简洁、直接的回答 - 常用工具：Docker、Git、VS Code - 时区：Asia/Shanghai - 禁止话题：政治、暴力、色情

6.2 工作区权限设置

# 编码 Agent 工作区权限（仅用户读写） chmod 700 ~/.openclaw/workspaces/coding chmod 700 ~/.openclaw/agents/coding

七、启动与验证

7.1 启动 Gateway（多 Agent 模式）

Docker 方式

docker run -d \   --name openclaw-multi \   -v ~/.openclaw:/root/.openclaw \   -p 8080:8080 \   openclaw/openclaw:latest \   gateway start --verbose

原生方式

openclaw gateway restart --verbose

7.2 验证多 Agent 加载成功

查看日志：

# Docker docker logs -f openclaw-multi  # 原生 openclaw logs

成功标志：

[INFO] loaded config.yaml [INFO] registered agents: main, coding, research [INFO] bindings loaded: 6 rules [INFO] channels started: telegram(2), discord(2) [INFO] multi-agent gateway ready

7.3 功能测试

向 主 Telegram 发消息 → main Agent 响应
向 编码 Telegram 发消息 → coding Agent 响应
在 Discord 开发服务器 发消息 → coding Agent 响应
编码 Agent 尝试访问非 ~/dev 目录 → 权限拒绝

八、高级配置（生产级优化）

### 8.1 资源分配（CPU/内存隔离）

```yaml

# config.yaml 添加

resource:

enabled: true

agents:

main:

cpu: 20%

memory: 512MB

coding:

cpu: 40%

memory: 1GB

research:

cpu: 30%

memory: 2GB

```

### 8.2 模型降级/ fallback（成本优化）

```yaml

agents:

list:

- id: research

# ... 其他配置

model:

provider: moonshot

model: kimi-v2

fallback:

- provider: openrouter

model: anthropic/claude-3-haiku

reason: cost

- provider: deepseek

model: deepseek-chat

reason: latency

```

### 8.3 安全策略（权限最小化）

```yaml

agents:

defaults:

permissions:

- browse:limited:https://*.com,https://*.cn

- shell:deny # 默认禁止 Shell

list:

- id: coding

permissions:

- shell:restricted:~/dev

- browse:docs:https://docs.openclaw.ai,https://github.com

```

### 8.4 日志与监控

```yaml

logging:

level: info

file: ~/.openclaw/logs/gateway.log

rotation: daily

max_size: 100MB

monitoring:

enabled: true

prometheus:

port: 9090

alert:

email: admin@example.com

threshold:

cpu: 80%

memory: 85%

```

---

九、常见问题与排错

9.1 Agent 未加载

检查 agentId 是否重复、格式是否为英文小写
确认 workspace/agentDir 目录存在且权限正确
日志搜索 registered agents 确认数量

9.2 消息路由错误

检查 bindings 顺序（从上到下匹配）
确认 channel/accountId/guildId 拼写正确
用 openclaw bindings test 命令测试路由

9.3 权限拒绝

检查 permissions 配置是否正确
确认目录路径与权限匹配
日志查看 permission denied 详情

9.4 模型调用失败

检查 .env API Key 是否正确
确认模型 provider/model 名称拼写无误
验证 API Key 余额与权限

十、完整配置文件示例（可直接复制）

## 十、完整配置文件示例（可直接复制）

```yaml

# ~/.openclaw/config.yaml（2026 多 Agent 生产配置）

agents:

defaults:

model:

provider: openrouter

model: openrouter/auto

temperature: 0.7

max_tokens: 2048

permissions:

- browse:limited

- shell:deny

memory:

enabled: true

type: vector

size: 10000

list:

- id: main

workspace: ~/.openclaw/workspaces/main

agentDir: ~/.openclaw/agents/main/agent

model:

temperature: 0.8

permissions:

- browse:all

- shell:limited

- id: coding

workspace: ~/.openclaw/workspaces/coding

agentDir: ~/.openclaw/agents/coding/agent

model:

provider: deepseek

model: deepseek-coder-v2

temperature: 0.3

max_tokens: 4096

permissions:

- shell:restricted:~/dev

- browse:docs:https://docs.openclaw.ai,https://github.com

skills:

- code_exec

- git

- file_edit

- id: research

workspace: ~/.openclaw/workspaces/research

agentDir: ~/.openclaw/agents/research/agent

model:

provider: moonshot

model: kimi-v2

temperature: 0.2

context_length: 256000

fallback:

- provider: openrouter

model: anthropic/claude-3-haiku

permissions:

- search:limited

- cron:all

skills:

- brave_search

- data_analysis

- report_gen

bindings:

- channel: telegram

accountId: tg-main

agentId: main

- channel: telegram

accountId: tg-coding

agentId: coding

- channel: discord

accountId: discord-main

type: dm

agentId: main

- channel: discord

accountId: discord-coding

guildId: "123456789"

agentId: coding

- channel: "*"

accountId: "*"

agentId: main

channels:

telegram:

enabled: true

accounts:

- id: tg-main

token: ${TELEGRAM_TOKEN_MAIN}

prefix: "/"

- id: tg-coding

token: ${TELEGRAM_TOKEN_CODING}

prefix: "!"

discord:

enabled: true

accounts:

- id: discord-main

token: ${DISCORD_TOKEN_MAIN}

prefix: "!"

- id: discord-coding

token: ${DISCORD_TOKEN_CODING}

prefix: "/"

resource:

enabled: true

agents:

main: { cpu: 20%, memory: 512MB }

coding: { cpu: 40%, memory: 1GB }

research: { cpu: 30%, memory: 2GB }

logging:

level: info

file: ~/.openclaw/logs/gateway.log

rotation: daily

```

---

十一、总结与下一步

OpenClaw 多 Agent 核心是 agents.list 定义大脑 + channels 定义入口 + bindings 定义路由，实现完全隔离、灵活调度、安全可控的 AI 多智能体体系。

下一步： 1. 按本文配置运行测试 2. 为每个 Agent 完善 SOUL.md 人设 3. 接入更多通道（飞书/微信） 4. 配置定时任务与自动化工作流