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

默认路由：未匹配则走mainAgent

### 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发消息 →mainAgent 响应

向编码 Telegram发消息 →codingAgent 响应

在Discord 开发服务器发消息 →codingAgent 响应

编码 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 模型调用失败

检查.envAPI 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. 配置定时任务与自动化工作流

众力资讯网

OpenClaw 多 Agent 完整设置与配置教程（2026 最新版）

热门分类