Matrix 多账号配置完整教程：从单 Agent 到多 Agent 协作

摘要：本文详细讲解如何在 OpenClaw 中配置多个 Matrix 账号，实现多 Agent 协作系统。包含账号创建、凭证管理、路由配置、权限设置等完整流程，所有配置均可直接复制使用。

封面图:

作者：江神
邮箱: jiangyayun72@gmail.com
发布时间：2026-03-04
阅读时间：20 分钟

一、为什么需要多账号配置？

在《30 天实战》中，我记录了搭建 AI 助手"戴蒙"的全过程。但单个 Agent 能力有限，无法胜任复杂任务。

多账号配置的价值：

专业化分工 - 每个 Agent 专注特定领域（编程、写作、测试等）
独立上下文 - 避免不同任务的上下文相互污染
权限隔离 - 不同 Agent 访问不同资源和房间
负载均衡 - 分散请求压力，提高响应速度
可追溯性 - 每个操作都有明确的责任 Agent

我的多账号架构：

用户消息 → Matrix 服务器 → OpenClaw Gateway → 路由到对应 Agent
                                      ├─ @agent-name:matrix.server.com (主 Agent)
                                      ├─ @coding-agent:matrix.server.com (编程专家)
                                      ├─ @novel-agent:matrix.server.com (网文作家)
                                      ├─ @tech-blog:matrix.server.com (技术博主)
                                      ├─ @reviewer:matrix.server.com (代码审查)
                                      └─ @tester:matrix.server.com (测试员)

二、准备工作

2.1 前置条件

✅ 已部署 Matrix 服务器（参考 Matrix Conduit 部署教程）
✅ 已安装 OpenClaw（参考 OpenClaw 快速开始）
✅ 有 Matrix 服务器管理员权限（用于创建账号）

2.2 规划账号体系

在开始之前，先规划好需要的 Agent 账号：

Agent ID	Matrix 账号	职责	使用场景
main	@agent-name:matrix.server.com	主 Agent，任务协调	私聊问答、任务分发
coding	@coding-agent:matrix.server.com	编程专家	代码开发、调试
novel	@novel-agent:matrix.server.com	网文作家	小说创作、故事编写
tech-blog	@tech-blog:matrix.server.com	技术博主	技术文章撰写
reviewer	@reviewer:matrix.server.com	代码审查	代码审查、安全检查
tester	@tester:matrix.server.com	测试员	单元测试、集成测试
planner	@planner:matrix.server.com	任务规划	任务分解、进度跟踪
coordinator	@coordinator:matrix.server.com	协调员	多 Agent 协作协调

三、创建 Matrix 账号

3.1 方法 1：通过 Matrix 客户端创建

步骤：

打开 Matrix 客户端（Element、FluffyChat 等）
注册新账号
用户名格式：Agent 名称（如damon、coding）
设置强密码（建议 16 位以上，包含大小写、数字、特殊字符）
完成邮箱验证（可选）

示例：

用户名：damon
密码：YourStrongPassword123!@#
完整账号：@agent-name:matrix.server.com

3.2 方法 2：通过 API 批量创建

适合需要创建大量 Agent 账号的场景：

#!/bin/bash

# Matrix 服务器地址
HOMESERVER="https://matrix.example.com"

# 账号列表
AGENTS=("damon" "coding" "novel" "tech-blog" "reviewer" "tester")

# 统一密码（生产环境建议每个账号不同密码）
PASSWORD="YourStrongPassword123!@#"

for agent in "${AGENTS[@]}"; do
    echo "创建账号：@$agent:conduit.local"

    curl -X POST "$HOMESERVER/_matrix/client/v3/register" \
      -H "Content-Type: application/json" \
      -d "{
        \"username\": \"$agent\",
        \"password\": \"$PASSWORD\",
        \"auth\": {
          \"type\": \"m.login.dummy\"
        }
      }"

    echo ""
done

注意：
- 需要关闭 Matrix 服务器的注册限制
- 或者使用管理员账号批量创建

3.3 方法 3：使用 Conduit 管理命令

如果使用 Conduit 作为 Matrix 服务器：

# 进入 Conduit 容器
docker exec -it conduit bash

# 使用 conduit-cli 创建用户
conduit-cli user create @agent-name:matrix.server.com --password "YourStrongPassword123!@#"
conduit-cli user create @coding-agent:matrix.server.com --password "YourStrongPassword123!@#"
# ... 继续创建其他账号

四、获取访问令牌（Access Token）

OpenClaw 使用 Access Token 认证，而不是密码。

4.1 方法 1：通过 Element 客户端获取

步骤：

登录要获取 Token 的账号
设置 → 帮助与关于 → 访问令牌
复制 Token（格式类似：YOUR_ACCESS_TOKEN_HERE）

4.2 方法 2：通过 API 获取

curl -X POST "https://matrix.example.com/_matrix/client/v3/login" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "m.login.password",
    "identifier": {
      "type": "m.id.user",
      "user": "damon"
    },
    "password": "YourStrongPassword123!@#",
    "initial_device_display_name": "OpenClaw-Damon"
  }'

返回示例：

{
  "access_token": "YOUR_ACCESS_TOKEN_HERE",
  "device_id": "OpenClaw-Damon",
  "home_server": "conduit.local",
  "user_id": "@agent-name:matrix.server.com"
}

4.3 保存凭证

将获取的 Token 保存到安全位置：

# 创建凭证目录
mkdir -p /root/.openclaw/credentials/matrix

# 保存每个账号的凭证
cat > /root/.openclaw/credentials/matrix/credentials-damon.json << 'EOF'
{
  "homeserver": "https://matrix.example.com",
  "userId": "@agent-name:matrix.server.com",
  "accessToken": "YOUR_ACCESS_TOKEN_HERE",
  "deviceId": "OpenClaw-Damon",
  "createdAt": "2026-03-01T07:45:00.000Z"
}
EOF

# 设置权限（仅 root 可读）
chmod 600 /root/.openclaw/credentials/matrix/credentials-*.json

五、配置 OpenClaw

5.1 配置 Matrix 渠道

编辑 openclaw.json：

{
  "channels": {
    "matrix": {
      "enabled": true,
      "encryption": false,
      "threadReplies": "inbound",
      "homeserver": "https://matrix.example.com",
      "dm": {
        "policy": "open",
        "allowFrom": ["*"],
        "enabled": true
      },
      "groups": {
        "*": {
          "requireMention": true,
          "allow": true,
          "enabled": true
        },
        "#tech-blog-working:conduit.local": {
          "name": "技术博客工作群",
          "enabled": true,
          "requireMention": true
        }
      }
    }
  }
}

关键配置说明：

配置项	说明	推荐值
`homeserver`	Matrix 服务器地址	`https://matrix.example.com`
`encryption`	端到端加密	`false`（生产环境建议 `true`）
`dm.policy`	私聊策略	`open`（开放）或 `allowlist`（白名单）
`groups.*.requireMention`	群聊是否需要 @提及	`true`（避免误触发）

5.2 配置多 Agent 路由

在 openclaw.json 中添加路由规则：

{
  "routing": {
    "rules": [
      {
        "agentId": "main",
        "match": {
          "channel": "matrix",
          "accountId": "damon"
        }
      },
      {
        "agentId": "coding",
        "match": {
          "channel": "matrix",
          "accountId": "coding"
        }
      },
      {
        "agentId": "web-novel-writer",
        "match": {
          "channel": "matrix",
          "accountId": "novel",
          "peer": {
            "kind": "channel",
            "id": "#novel:conduit.local"
          }
        }
      },
      {
        "agentId": "tech-blog-writer",
        "match": {
          "channel": "matrix",
          "accountId": "tech-blog"
        }
      },
      {
        "agentId": "hf-chat",
        "match": {
          "channel": "matrix",
          "accountId": "hf-chat",
          "peer": {
            "kind": "direct",
            "id": "@user:matrix.server.com"
          }
        }
      }
    ]
  }
}

路由规则说明：

基础路由 - 根据账号 ID 匹配（如 damon、coding）
群聊路由 - 限定特定群聊（如 #novel:conduit.local）
私聊路由 - 限定特定用户（如 @user:matrix.server.com）

5.3 配置 Agent 工作空间

为每个 Agent 创建独立的工作空间：

# 创建 Agent 工作空间
mkdir -p /root/.openclaw/agents/coding
mkdir -p /root/.openclaw/agents/novel
mkdir -p /root/.openclaw/agents/tech-blog
mkdir -p /root/.openclaw/agents/reviewer
mkdir -p /root/.openclaw/agents/tester

# 复制基础配置
cp /root/.openclaw/agents/main/openclaw.json /root/.openclaw/agents/coding/
# ... 复制其他 Agent

每个 Agent 的独立配置：

{
  "agentId": "coding",
  "workspace": "/root/.openclaw/agents/coding",
  "model": {
    "primary": "qwen3-coder-plus"
  },
  "identity": {
    "name": "编程大师",
    "emoji": "💻"
  },
  "skills": [
    "coding-assistant",
    "code-reviewer",
    "test-generator"
  ]
}

六、权限管理

6.1 配置允许列表

创建 /root/.openclaw/credentials/matrix-allowFrom.json：

{
  "version": 1,
  "allowFrom": [
    "@admin:matrix.server.com",
    "@user:matrix.server.com"
  ]
}

权限策略：

["*"] - 允许所有用户（开发环境）
["@user1:server.com", "@user2:server.com"] - 白名单（生产环境）

6.2 群聊权限管理

在 openclaw.json 中配置群聊权限：

{
  "channels": {
    "matrix": {
      "groups": {
        "#public:conduit.local": {
          "name": "公共群聊",
          "enabled": true,
          "requireMention": true
        },
        "#private:conduit.local": {
          "name": "私密群聊",
          "enabled": true,
          "requireMention": false,
          "allowFrom": [
            "@admin:matrix.server.com",
            "@admin:conduit.local"
          ]
        }
      }
    }
  }
}

七、实战场景

7.1 场景 1：私聊问答

配置：

{
  "agentId": "main",
  "match": {
    "channel": "matrix",
    "accountId": "damon"
  }
}

使用方式：
- 用户私聊 @agent-name:matrix.server.com
- 戴蒙直接回答，无需 @提及

7.2 场景 2：群聊协作

配置：

{
  "agentId": "coding",
  "match": {
    "channel": "matrix",
    "accountId": "coding",
    "peer": {
      "kind": "channel",
      "id": "#dev-team:conduit.local"
    }
  }
}

使用方式：
- 在 #dev-team:conduit.local 群聊中
- @coding 帮我写个 Python 脚本
- 编程大师接收任务并执行

7.3 场景 3：多 Agent 协作

配置：

{
  "routing": {
    "rules": [
      {
        "agentId": "main",
        "match": {"channel": "matrix", "accountId": "damon"}
      },
      {
        "agentId": "coding",
        "match": {"channel": "matrix", "accountId": "coding"}
      },
      {
        "agentId": "reviewer",
        "match": {"channel": "matrix", "accountId": "reviewer"}
      }
    ]
  }
}

协作流程：

用户 → @agent-name:matrix.server.com（主 Agent）
        ↓ 任务分解
        ├─ @coding-agent:matrix.server.com（编写代码）
        └─ @reviewer:matrix.server.com（代码审查）
              ↓ 汇总结果
        @agent-name:matrix.server.com → 用户

八、监控与调试

8.1 查看 Agent 状态

# 查看所有 Agent 状态
openclaw agents list

# 查看特定 Agent 详情
openclaw agents describe coding

# 查看活跃会话
openclaw sessions list

8.2 查看日志

# 查看 Gateway 日志
tail -f /root/.openclaw/logs/gateway.log

# 查看特定 Agent 日志
tail -f /root/.openclaw/agents/coding/logs/agent.log

# 查看 Matrix 渠道日志
tail -f /root/.openclaw/logs/channels/matrix.log

8.3 常见问题排查

问题 1：Agent 不响应

# 检查 Agent 是否运行
openclaw agents status

# 检查路由配置
openclaw routing describe

# 重启 Agent
openclaw agents restart coding

问题 2：无法连接 Matrix 服务器

# 测试连接
curl -I https://matrix.example.com

# 检查凭证
cat /root/.openclaw/credentials/matrix/credentials-coding.json

# 重新登录
openclaw matrix login --account coding

问题 3：权限错误

# 检查 allowFrom 配置
cat /root/.openclaw/credentials/matrix-allowFrom.json

# 检查群聊权限
openclaw matrix groups list

九、生产环境最佳实践

9.1 安全加固

使用强密码 - 每个账号不同密码，16 位以上
启用端到端加密 - "encryption": true
限制私聊 - "dm.policy": "allowlist"
定期轮换 Token - 每月更新一次
审计日志 - 记录所有 Agent 操作

9.2 性能优化

会话隔离 - 每个 Agent 独立工作空间
消息队列 - 启用 debounce 和 cap 限制
缓存策略 - 常用响应缓存
负载均衡 - 多个 Agent 实例分担请求

9.3 监控告警

# Prometheus 配置示例
scrape_configs:
  - job_name: 'openclaw'
    static_configs:
      - targets: ['localhost:18789']
    metrics_path: '/metrics'

# 告警规则
groups:
  - name: openclaw
    rules:
      - alert: AgentDown
        expr: up{job="openclaw"} == 0
        for: 5m
        annotations:
          summary: "Agent {{ $labels.agent_id }} 已下线"

十、总结

10.1 核心要点

账号规划 - 根据职责划分 Agent 账号
凭证管理 - 安全存储 Access Token
路由配置 - 精确匹配消息路由
权限控制 - 白名单 + 群聊限制
监控调试 - 日志 + 告警 + 健康检查

10.2 后续优化方向

[ ] 启用端到端加密
[ ] 配置 Prometheus 监控
[ ] 实现自动 Token 轮换
[ ] 添加更多专业 Agent

附录：完整配置示例

A.1 openclaw.json 完整配置

{
  "channels": {
    "matrix": {
      "enabled": true,
      "encryption": false,
      "threadReplies": "inbound",
      "homeserver": "https://matrix.example.com",
      "dm": {
        "policy": "open",
        "allowFrom": ["*"],
        "enabled": true
      },
      "groups": {
        "*": {
          "requireMention": true,
          "allow": true,
          "enabled": true
        },
        "#tech-blog-working:conduit.local": {
          "name": "技术博客工作群",
          "enabled": true,
          "requireMention": true
        }
      }
    }
  },
  "routing": {
    "rules": [
      {
        "agentId": "main",
        "match": {
          "channel": "matrix",
          "accountId": "damon"
        }
      },
      {
        "agentId": "coding",
        "match": {
          "channel": "matrix",
          "accountId": "coding"
        }
      },
      {
        "agentId": "tech-blog-writer",
        "match": {
          "channel": "matrix",
          "accountId": "tech-blog"
        }
      }
    ]
  }
}

A.2 账号凭证模板

{
  "homeserver": "https://matrix.example.com",
  "userId": "@AGENT_ID:conduit.local",
  "accessToken": "YOUR_ACCESS_TOKEN",
  "deviceId": "OpenClaw-AGENT_NAME",
  "createdAt": "2026-03-04T00:00:00.000Z"
}

欢迎交流讨论。如果你在配置过程中遇到问题，或者有相关问题，欢迎在评论区留言或私信我。

📑 目录