朝廷系统：基于 OpenClaw + Matrix 的多 Agent 协作架构

2026-02-25

字数统计: 3.6k字 | 阅读时长≈ 17分

朝廷系统：基于 OpenClaw + Matrix 的多 Agent 协作架构

一份完整的搭建经验，让其他 AI 也能看懂并复现。

概述

“朝廷”是一个多 Agent 协作系统，核心思路：

用 Matrix（开源即时通讯协议）作为 Agent 之间的通信层
用 OpenClaw（AI Agent 框架）驱动每个 Agent 的大脑
用 Conduit（轻量 Matrix 服务器）作为自托管聊天后端
一个”军师”Agent 作为群聊总管，负责接收用户消息并调度其他部门

最终效果：用户在 Matrix 群聊发一条消息，军师自动分析并派任务给对应部门，部门完成后军师汇总回复。

架构

用户（Element 客户端）
    │
    ▼
Matrix 群聊（朝廷大殿）
    │
    ├── 🧠 军师（总管，autoReply，Opus）
    │     ├── @兵部 → 🗡️ 兵部（写代码，Opus）
    │     ├── @户部 → 💰 户部（财务，Opus）
    │     ├── @礼部 → 📝 礼部（文案，Sonnet）
    │     ├── @工部 → 🔧 工部（运维，Sonnet）
    │     └── @吏部 → 📋 吏部（项目管理，Sonnet）
    │
    ▼
OpenClaw Gateway（多 Agent 引擎）
    ├── Agent 1: junshi  → workspace-junshi/
    ├── Agent 2: bingbu  → workspace-bingbu/
    ├── Agent 3: hubu    → workspace-hubu/
    ├── Agent 4: libu    → workspace-libu/
    ├── Agent 5: gongbu  → workspace-gongbu/
    └── Agent 6: libu-pm → workspace-libu-pm/

所需组件

组件	用途	推荐配置
Conduit	Matrix 服务器（轻量，Rust 写的）	2C/4G 足够
Caddy	反向代理 + HTTPS	和 Conduit 同机
OpenClaw	AI Agent 框架	16C/32G（跑多个 Agent）
Element	Matrix 客户端（Web）	app.element.io
LLM API	大模型接口	Claude Opus + Sonnet 推荐

可以全部装在一台机器上，也可以分开（推荐 Conduit+Caddy 一台，OpenClaw 一台）。

第一步：部署 Conduit（Matrix 服务器）

Docker 部署

mkdir -p /opt/conduit/data
cat > /opt/conduit/conduit.toml << 'EOF'
[global]
server_name = "your.server.ip"  # 或域名，设定后不可更改
database_path = "/var/lib/matrix-conduit/"
database_backend = "rocksdb"
port = 8448
max_request_size = 20000000
allow_registration = true       # 先开，创建完用户后关掉
allow_federation = false
trusted_servers = ["matrix.org"]
address = "0.0.0.0"
EOF

docker run -d --name conduit \
  -v /opt/conduit/data:/var/lib/matrix-conduit/ \
  -v /opt/conduit/conduit.toml:/etc/conduit.toml:ro \
  -e CONDUIT_CONFIG=/etc/conduit.toml \
  -p 8448:8448 \
  --restart unless-stopped \
  ghcr.io/girlbossceo/conduwuit:latest

创建用户

# 管理员
curl -s -X POST "http://localhost:8448/_matrix/client/v3/register" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"YourPassword123!","auth":{"type":"m.login.dummy"}}'

# Bot 用户（重复执行，改 username）
for bot in bingbu hubu junshi libu gongbu libu-pm; do
  curl -s -X POST "http://localhost:8448/_matrix/client/v3/register" \
    -H "Content-Type: application/json" \
    -d "{\"username\":\"$bot\",\"password\":\"BotPassword123!\",\"auth\":{\"type\":\"m.login.dummy\"}}"
done

关闭注册

创建完用户后，修改 conduit.toml：

1	allow_registration = false

然后 docker restart conduit。

设置显示名

TOKEN="admin的access_token"
SERVER="http://localhost:8448"

declare -A NAMES=(
  [bingbu]="🗡️ 兵部"
  [hubu]="💰 户部"
  [junshi]="🧠 军师"
  [libu]="📝 礼部"
  [gongbu]="🔧 工部"
  [libu-pm]="📋 吏部"
)

for bot in "${!NAMES[@]}"; do
  # 先用 bot 自己的 token 登录设置
  BOT_TOKEN=$(curl -s -X POST "$SERVER/_matrix/client/v3/login" \
    -H "Content-Type: application/json" \
    -d "{\"type\":\"m.login.password\",\"user\":\"$bot\",\"password\":\"BotPassword123!\"}" \
    | python3 -c "import json,sys;print(json.load(sys.stdin)['access_token'])")
  
  curl -s -X PUT "$SERVER/_matrix/client/v3/profile/@${bot}:your.server.ip/displayname" \
    -H "Authorization: Bearer $BOT_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"displayname\":\"${NAMES[$bot]}\"}"
done

创建群聊房间

curl -s -X POST "$SERVER/_matrix/client/v3/createRoom" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "朝廷大殿",
    "room_alias_name": "courtroom",
    "preset": "public_chat",
    "initial_state": [
      {"type": "m.room.history_visibility", "content": {"history_visibility": "shared"}}
    ]
  }'

邀请 Bot 加入

ROOM_ID="!创建房间返回的id"
for bot in bingbu hubu junshi libu gongbu libu-pm; do
  # 邀请
  curl -s -X POST "$SERVER/_matrix/client/v3/rooms/$ROOM_ID/invite" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"user_id\":\"@${bot}:your.server.ip\"}"
  
  # 用 bot token 接受邀请
  BOT_TOKEN="对应bot的token"
  curl -s -X POST "$SERVER/_matrix/client/v3/join/$ROOM_ID" \
    -H "Authorization: Bearer $BOT_TOKEN"
done

第二步：配置 Caddy（HTTPS 反向代理）

your.domain.com {
    handle /_matrix/* {
        reverse_proxy localhost:8448
    }
    handle /.well-known/matrix/* {
        reverse_proxy localhost:8448
    }
    handle {
        respond "Server is alive" 200
    }
}

第三步：安装 OpenClaw Matrix 插件

1	openclaw plugin install @openclaw/matrix

⚠️ 关键：禁用 E2EE

Conduit 的 E2EE 和 bot 账号不兼容。需要 stub 掉 crypto 模块：

# 找到插件的 crypto 模块
CRYPTO_PATH="$HOME/.openclaw/extensions/matrix/node_modules/@matrix-org/matrix-sdk-crypto-nodejs/index.js"

# 备份并替换
cp "$CRYPTO_PATH" "${CRYPTO_PATH}.bak"
cat > "$CRYPTO_PATH" << 'EOF'
// Stub: disable E2EE for Conduit compatibility
module.exports = {};
module.exports.OlmMachine = class OlmMachine { static async initialize() { return new OlmMachine(); } };
module.exports.RequestType = {};
module.exports.KeysUploadRequest = class {};
module.exports.KeysQueryRequest = class {};
module.exports.ToDeviceRequest = class {};
module.exports.SignatureUploadRequest = class {};
module.exports.RoomMessageRequest = class {};
module.exports.KeysClaimRequest = class {};
EOF

如果系统自带了 matrix 插件，需要禁用：

1
2
3

# 找到系统插件目录
SYSTEM_PLUGIN=$(find /usr/lib/node_modules/openclaw -name "matrix" -type d | head -1)
mv "$SYSTEM_PLUGIN" "${SYSTEM_PLUGIN}.disabled"

第四步：配置 openclaw.json

这是核心配置，定义了所有 Agent、Matrix 账号、绑定关系和调度规则。

{
  // LLM Provider
  "providers": {
    "your-provider": {
      "type": "openai",
      "url": "https://your-api-endpoint.com",
      "apiKey": "your-api-key",
      "models": {
        "opus-model-id": {},
        "sonnet-model-id": {}
      }
    }
  },

  // Agent 定义
  "agents": {
    "list": [
      {
        "id": "junshi",
        "name": "军师",
        "model": "your-provider/opus-model-id",
        "workspace": "~/.openclaw/workspace-junshi",
        "identity": { "name": "军师" },
        "groupChat": {
          "mentionPatterns": ["@军师", "军师", "@junshi"]
        }
      },
      {
        "id": "bingbu",
        "name": "兵部",
        "model": "your-provider/opus-model-id",
        "workspace": "~/.openclaw/workspace-bingbu",
        "identity": { "name": "兵部" },
        "groupChat": {
          "mentionPatterns": ["@兵部", "兵部", "@bingbu"]
        }
      },
      {
        "id": "hubu",
        "name": "户部",
        "model": "your-provider/opus-model-id",
        "workspace": "~/.openclaw/workspace-hubu",
        "identity": { "name": "户部" },
        "groupChat": {
          "mentionPatterns": ["@户部", "户部", "@hubu"]
        }
      },
      {
        "id": "libu",
        "name": "礼部",
        "model": "your-provider/sonnet-model-id",
        "workspace": "~/.openclaw/workspace-libu",
        "identity": { "name": "礼部" },
        "groupChat": {
          "mentionPatterns": ["@礼部", "礼部", "@libu"]
        }
      },
      {
        "id": "gongbu",
        "name": "工部",
        "model": "your-provider/sonnet-model-id",
        "workspace": "~/.openclaw/workspace-gongbu",
        "identity": { "name": "工部" },
        "groupChat": {
          "mentionPatterns": ["@工部", "工部", "@gongbu"]
        }
      },
      {
        "id": "libu-pm",
        "name": "吏部",
        "model": "your-provider/sonnet-model-id",
        "workspace": "~/.openclaw/workspace-libu-pm",
        "identity": { "name": "吏部" },
        "groupChat": {
          "mentionPatterns": ["@吏部", "吏部", "@libu-pm"]
        }
      }
    ]
  },

  // Matrix 多账号配置
  "channels": {
    "matrix": {
      "homeserver": "https://your.domain.com",
      "accounts": {
        "junshi": {
          "userId": "@junshi:your.server.ip",
          "accessToken": "junshi的token",
          "groups": {
            "*": { "autoReply": true }
          }
        },
        "bingbu": {
          "userId": "@bingbu:your.server.ip",
          "accessToken": "bingbu的token"
        },
        "hubu": {
          "userId": "@hubu:your.server.ip",
          "accessToken": "hubu的token"
        },
        "libu": {
          "userId": "@libu:your.server.ip",
          "accessToken": "libu的token"
        },
        "gongbu": {
          "userId": "@gongbu:your.server.ip",
          "accessToken": "gongbu的token"
        },
        "libu-pm": {
          "userId": "@libu-pm:your.server.ip",
          "accessToken": "libu-pm的token"
        }
      }
    }
  },

  // 绑定：accountId → agentId
  "bindings": [
    { "agentId": "junshi", "match": { "channel": "matrix", "accountId": "junshi" } },
    { "agentId": "bingbu", "match": { "channel": "matrix", "accountId": "bingbu" } },
    { "agentId": "hubu", "match": { "channel": "matrix", "accountId": "hubu" } },
    { "agentId": "libu", "match": { "channel": "matrix", "accountId": "libu" } },
    { "agentId": "gongbu", "match": { "channel": "matrix", "accountId": "gongbu" } },
    { "agentId": "libu-pm", "match": { "channel": "matrix", "accountId": "libu-pm" } }
  ]
}

配置要点

只有军师设 autoReply: true：军师自动回复群聊所有消息
其他部门不设 groups：默认 requireMention，只有被 mention 才回复
mentionPatterns 在 agent 级别配置：定义触发关键词
bindings 一一对应：每个 Matrix accountId 绑定到对应的 agentId

第五步：创建 Workspace 和 SOUL.md

每个 Agent 需要自己的 workspace 目录和 SOUL.md（定义人格和行为规则）。

军师（总管）

mkdir -p ~/.openclaw/workspace-junshi
cat > ~/.openclaw/workspace-junshi/SOUL.md << 'EOF'
# 🧠 军师（朝廷总管）

你是朝廷首席军师，同时也是朝廷大殿的总管。

## 职责
- 项目战略规划与路线图
- 复杂问题拆解与分析
- **调度其他部门**：当任务需要其他部门协助时，在群聊中点名对方

## 朝廷大殿群聊规则
- 你是群聊的主要回复者，用户发的所有消息你都要回复
- 需要其他部门协助时，在消息中明确点名，格式：`@兵部` `@户部` `@礼部` `@工部` `@吏部`
- 你负责汇总各部门的回复，给用户最终建议

## 其他部门
- 🗡️ 兵部：写代码、架构设计、技术决策
- 💰 户部：财务分析、成本优化、预算管理
- 📝 礼部：文案、营销、社交媒体
- 🔧 工部：运维、部署、监控
- 📋 吏部：项目管理、日报周报

## 风格
- 全局视角，高屋建瓴
- 先分析再建议，逻辑清晰
- 用中文沟通
EOF

其他部门（模板）

for bot_info in \
  "bingbu:🗡️ 兵部:写代码、架构设计、技术决策" \
  "hubu:💰 户部:财务分析、成本优化、预算管理" \
  "libu:📝 礼部:文案、营销、社交媒体" \
  "gongbu:🔧 工部:运维、部署、监控" \
  "libu-pm:📋 吏部:项目管理、日报周报"; do
  
  bot=$(echo "$bot_info" | cut -d: -f1)
  name=$(echo "$bot_info" | cut -d: -f2)
  duty=$(echo "$bot_info" | cut -d: -f3)
  short_name="${name#* }"
  
  mkdir -p "$HOME/.openclaw/workspace-${bot}"
  cat > "$HOME/.openclaw/workspace-${bot}/SOUL.md" << INNEREOF
# ${name}

你是朝廷${short_name}，专精${duty}。

## 朝廷大殿群聊规则
- **只有被点名时才回复**（军师或用户在消息中提到你的部门名）
- 被点名的判断：消息中包含"${short_name}"或"@${bot}"
- 如果消息没有点你的名，保持沉默，回复 NO_REPLY
- 回复时简洁专业，直接给方案

## 风格
- 专业、简洁、直接
- 用中文沟通
- 给出可执行的具体方案

## 原则
- 被点名才说话，不抢话
- 做好本职工作，不越界
INNEREOF
done

第六步：修补 Matrix 插件（关键！）

问题

OpenClaw 的 Matrix 插件在初始化 monitor 时调用 buildMentionRegexes(cfg) 但不传 agentId。这导致多 Agent 场景下，每个 bot 的 groupChat.mentionPatterns 不生效 — 所有非 autoReply 的 bot 都无法被文本 mention 触发。

原因

buildMentionRegexes(cfg, agentId) 需要 agentId 才能从 agents.list[].groupChat.mentionPatterns 读取对应 agent 的 mention 配置。不传 agentId 时，只会读全局的 messages.groupChat.mentionPatterns。

修复

找到 Matrix 插件的 src/matrix/monitor/index.ts，定位这一行：

1	const mentionRegexes = core.channel.mentions.buildMentionRegexes(cfg);

替换为：

// Resolve agentId from bindings for this accountId (multi-agent mention support)
const _accountId = opts.accountId ?? null;
const _agentId = _accountId
  ? (cfg.bindings ?? []).find(
      (b: any) => b.match?.channel === "matrix" && b.match?.accountId === _accountId
    )?.agentId ?? _accountId
  : undefined;
const mentionRegexes = core.channel.mentions.buildMentionRegexes(cfg, _agentId);

自动化修补脚本

import re

plugin_path = "~/.openclaw/extensions/matrix/src/matrix/monitor/index.ts"
# 展开 ~ 为实际路径
import os
plugin_path = os.path.expanduser(plugin_path)

with open(plugin_path) as f:
    content = f.read()

old = "  const mentionRegexes = core.channel.mentions.buildMentionRegexes(cfg);"
new = """  // Resolve agentId from bindings for this accountId (multi-agent mention support)
  const _accountId = opts.accountId ?? null;
  const _agentId = _accountId
    ? (cfg.bindings ?? []).find(
        (b: any) => b.match?.channel === "matrix" && b.match?.accountId === _accountId
      )?.agentId ?? _accountId
    : undefined;
  const mentionRegexes = core.channel.mentions.buildMentionRegexes(cfg, _agentId);"""

if old in content:
    content = content.replace(old, new)
    with open(plugin_path, "w") as f:
        f.write(content)
    print("patched successfully")
else:
    print("already patched or target not found")

踩坑记录

1. E2EE 导致插件加载失败

现象：Matrix 插件启动时报 Cannot find module '@matrix-org/matrix-sdk-crypto-nodejs'
原因：native binding 在某些平台编译失败
解决：stub 替换 crypto 模块（见第三步）

2. 所有 Bot 一窝蜂回复

现象：群聊发一条消息，6 个 bot 全部回复了一样的内容
原因：所有 bot 都设了 autoReply: true
解决：只有军师设 autoReply，其他 bot 靠 mentionPatterns 触发

3. mentionPatterns 不生效

现象：军师回复 @兵部写个代码，但兵部没反应
原因：Matrix 插件的 buildMentionRegexes 没传 agentId
解决：修补 monitor/index.ts（见第六步）

4. Conduit Room ID 格式问题

现象：per-room config 报 Matrix homeserver is required
原因：Conduit 返回的 room ID 可能缺少 :server 后缀
解决：不用 per-room config，改用 groups: {"*": {...}} 通配符

5. DNS 解析问题

现象：OpenClaw 连不上 Matrix 服务器
原因：域名未备案，国内 DNS 可能解析异常
解决：在 OpenClaw 所在机器的 /etc/hosts 添加域名→IP 映射

6. systemctl restart 旧进程残留

现象：restart 后报 port already in use
原因：旧 OpenClaw 进程没完全退出
解决：kill -9 <旧PID> 后再 start

调度流程图

用户: "帮我写一个 REST API"
    │
    ▼
军师 (autoReply): "这个交给兵部。@兵部 帮用户写一个 REST API。"
    │
    ▼ (mentionPatterns 匹配 "兵部")
兵部: "```python\nfrom flask import Flask\n..."
    │
    ▼
军师 (看到兵部回复): "兵部交活了。代码在这：..."
    │
    ▼
用户看到完整对话流

扩展思路

跨 Agent 通信：除了群聊 mention，还可以用 OpenClaw 的 sessions_send 让 Agent 之间直接发消息
私聊通道：用户可以在 Element 里直接私聊各部门，绕过军师
记忆系统：每个 Agent 的 workspace 里可以放 MEMORY.md，实现跨会话记忆
工具权限：通过 agents.list[].tools.allow/deny 限制各部门的工具权限
沙箱隔离：通过 agents.list[].sandbox 给不同 Agent 配置不同的沙箱策略

最低配置参考

场景	服务器	配置
最小化（1台）	Conduit + OpenClaw	8C/16G
推荐（2台）	Conduit+Caddy 一台 + OpenClaw 一台	4C/8G + 16C/32G
省钱版	Conduit+Caddy 一台 + OpenClaw 一台	2C/4G + 4C/8G（用 Sonnet）

这套系统的核心价值：用 Matrix 作为 Agent 通信总线，用户在聊天界面就能看到 Agent 之间的协作过程，透明可控。军师作为调度中心，避免了多 Agent 抢答的混乱。

本文作者： Wynne Yin
本文链接： https://wynneyin.github.io/2026/02/25/朝廷系统搭建指南(1)/
版权声明： 本博客所有文章除特别声明外，均采用 MIT 许可协议。转载请注明出处！