陌路 陌路 0 评论 技术笔记 3 阅读

OpenClaw Agents 代理配置完全指南：从创建到多代理路由

_

OpenClaw Agents 代理配置完全指南：从创建到多代理路由

手把手教你创建、配置和管理 OpenClaw 隔离代理（Agents），实现多身份、多账号、多场景的 AI 助手部署方案。

📦 什么是 OpenClaw Agents？

Agent（代理） 是一个完全隔离的 AI 助手实例，拥有自己独立的：

  • 工作区（Workspace）：包含 SOUL.md、AGENTS.md、USER.md 等人格配置文件
  • 状态目录（agentDir）：存储认证信息、模型注册表、代理专属配置
  • 会话存储（Sessions）：聊天记录和路由状态，位于 ~/.openclaw/agents/<agentId>/sessions

关键特性：

  • ✅ 每个代理完全隔离，互不干扰
  • ✅ 支持不同的人格设定和工作流程
  • ✅ 可以为不同代理绑定不同的聊天账号
  • ✅ 单网关支持多代理并行运行

🎯 为什么需要多代理？

场景 1：工作与生活分离

主代理（main）→ 处理日常聊天、生活助手
工作代理（work）→ 处理编程、工作任务
社交代理（social）→ 处理社交媒体消息

场景 2：多人共享网关

小明的代理 → 绑定小明的微信、Discord
小红的代理 → 绑定小红的 Telegram、Slack
→ 共享同一台服务器，数据完全隔离

场景 3：不同人格设定

专业模式 → 严谨、正式的助手风格
休闲模式 → 轻松、幽默的聊天风格

🚀 快速开始：创建第一个代理

步骤 1：使用向导创建代理

# 创建一个名为 "work" 的工作代理
openclaw agents add work

执行后会自动：

  • 创建代理工作区 ~/.openclaw/workspace-work
  • 生成 SOUL.md、AGENTS.md、USER.md 模板
  • 创建独立的 agentDir 和会话存储

步骤 2：查看代理列表

# 查看所有代理及绑定状态
openclaw agents list --bindings

# 示例输出：
# AGENT     WORKSPACE                          BINDINGS
# main      ~/.openclaw/workspace              (default)
# work      ~/.openclaw/workspace-work         (none)

步骤 3：配置代理身份（可选）

编辑代理工作区的 IDENTITY.md：

# IDENTITY.md - Who Am I?

- **Name:** 工作助手
- **Creature:** AI 工作助手
- **Vibe:** 专业严谨
- **Emoji:** 💼
- **Avatar:** avatars/work.png

应用身份配置：

# 从 IDENTITY.md 加载身份
openclaw agents set-identity --workspace ~/.openclaw/workspace-work --from-identity

# 或手动设置
openclaw agents set-identity --agent work --name "工作助手" --emoji "💼"

🔗 配置路由绑定（Bindings）

绑定是将聊天消息路由到特定代理的关键配置。

绑定规则：最具体优先

路由匹配优先级（从高到低）：

  1. peer 匹配（精确 DM/群组/频道 ID）
  2. parentPeer 匹配（线程继承）
  3. guildId + roles（Discord 角色路由）
  4. guildId（Discord 服务器）
  5. teamId（Slack）
  6. accountId 匹配
  7. 频道级匹配（accountId: "*"）
  8. 默认代理（agents.list[].default）

示例 1：绑定 Telegram 账号到工作代理

# 先登录 Telegram 账号
openclaw channels login --channel telegram --account work

# 绑定到工作代理
openclaw agents bind --agent work --bind telegram:work

示例 2：绑定 Discord 频道

# 绑定特定 Discord 服务器
openclaw agents bind --agent work --bind discord:guild-123456

# 绑定特定频道
openclaw agents bind --agent work --bind discord:channel-789012

示例 3：绑定 WhatsApp 联系人（一对一）

# 为特定联系人路由到特定代理
openclaw agents bind --agent work --bind whatsapp:+8613800138000

查看绑定状态

# 查看所有绑定
openclaw agents bindings

# 查看特定代理的绑定
openclaw agents bindings --agent work

# JSON 格式输出
openclaw agents bindings --json

解除绑定

# 解除特定绑定
openclaw agents unbind --agent work --bind telegram:work

# 解除所有绑定
openclaw agents unbind --agent work --all

⚙️ 高级配置：手动编辑 openclaw.json

多代理配置示例

{
  "agents": {
    "list": [
      {
        "id": "main",
        "workspace": "~/.openclaw/workspace",
        "identity": {
          "name": "小雪",
          "theme": "温暖友好",
          "emoji": "❄️"
        }
      },
      {
        "id": "work",
        "workspace": "~/.openclaw/workspace-work",
        "identity": {
          "name": "工作助手",
          "theme": "专业严谨",
          "emoji": "💼"
        }
      },
      {
        "id": "social",
        "workspace": "~/.openclaw/workspace-social",
        "identity": {
          "name": "社交助手",
          "theme": "幽默风趣",
          "emoji": "🎉"
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "main",
      "match": { "channel": "telegram", "accountId": "personal" }
    },
    {
      "agentId": "work",
      "match": { "channel": "telegram", "accountId": "work" }
    },
    {
      "agentId": "social",
      "match": { "channel": "discord", "accountId": "social" }
    }
  ],
  "channels": {
    "telegram": {
      "accounts": {
        "personal": {
          "token": "${TELEGRAM_BOT_TOKEN_PERSONAL}"
        },
        "work": {
          "token": "${TELEGRAM_BOT_TOKEN_WORK}"
        }
      }
    }
  }
}

绑定作用域行为

# 初始：频道级绑定（匹配默认账号）
openclaw agents bind --agent work --bind telegram

# 升级：账号级绑定（匹配特定账号）
openclaw agents bind --agent work --bind telegram:work

# 注意：升级后会替换原有绑定，不会重复添加

📁 目录结构详解

单代理模式（默认）

~/.openclaw/
├── workspace/                    # 主代理工作区
│   ├── SOUL.md
│   ├── AGENTS.md
│   ├── USER.md
│   └── MEMORY.md
├── agents/
│   └── main/
│       ├── agent/               # 主代理状态目录
│       │   └── auth-profiles.json
│       └── sessions/            # 主代理会话存储
└── openclaw.json

多代理模式

~/.openclaw/
├── workspace/                    # 主代理工作区
├── workspace-work/               # 工作代理工作区
├── workspace-social/             # 社交代理工作区
├── agents/
│   ├── main/
│   │   ├── agent/
│   │   └── sessions/
│   ├── work/
│   │   ├── agent/
│   │   └── sessions/
│   └── social/
│       ├── agent/
│       └── sessions/
└── openclaw.json

重要：每个代理的 agentDir 必须独立，不要共享，否则会导致认证和会话冲突！

🔐 认证管理

每个代理独立的认证

# 为主代理登录 Telegram
openclaw channels login --channel telegram --account main

# 为工作代理登录 Telegram（不同账号）
openclaw channels login --channel telegram --account work

认证文件位置：

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

共享认证（可选）

如果想让多个代理共享同一个聊天账号的认证，可以复制认证文件：

# 复制主代理的认证到工作代理
cp ~/.openclaw/agents/main/agent/auth-profiles.json \
   ~/.openclaw/agents/work/agent/auth-profiles.json

注意：共享认证意味着多个代理会收到相同的消息，通常不推荐这样做。

🧪 实战场景

场景 1：工作生活分离

# 1. 创建工作代理
openclaw agents add work

# 2. 绑定工作 Telegram 账号
openclaw channels login --channel telegram --account work
openclaw agents bind --agent work --bind telegram:work

# 3. 主代理保留个人账号
openclaw agents bind --agent main --bind telegram:personal

# 4. 重启网关
openclaw gateway restart

# 5. 验证
openclaw agents list --bindings

场景 2：Discord 多机器人

{
  "agents": {
    "list": [
      { id: "main", workspace: "~/.openclaw/workspace-main" },
      { id: "coding", workspace: "~/.openclaw/workspace-coding" }
    ]
  },
  "bindings": [
    { agentId: "main", match: { channel: "discord", accountId: "default" } },
    { agentId: "coding", match: { channel: "discord", accountId: "coding" } }
  ],
  "channels": {
    "discord": {
      "accounts": {
        "default": {
          "token": "DISCORD_BOT_TOKEN_MAIN",
          "guilds": {
            "123456789012345678": {
              "channels": {
                "222222222222222222": { allow: true }
              }
            }
          }
        },
        "coding": {
          "token": "DISCORD_BOT_TOKEN_CODING",
          "guilds": {
            "123456789012345678": {
              "channels": {
                "333333333333333333": { allow: true }
              }
            }
          }
        }
      }
    }
  }
}

场景 3：WhatsApp 联系人路由

{
  "agents": {
    "list": [
      { id: "alex", workspace: "~/.openclaw/workspace-alex" },
      { id: "mia", workspace: "~/.openclaw/workspace-mia" }
    ]
  },
  "bindings": [
    {
      "agentId": "alex",
      "match": { 
        "channel": "whatsapp", 
        "peer": { "kind": "direct", "id": "+8613800138000" } 
      }
    },
    {
      "agentId": "mia",
      "match": { 
        "channel": "whatsapp", 
        "peer": { "kind": "direct", "id": "+8613900139000" } 
      }
    }
  ],
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+8613800138000", "+8613900139000"]
    }
  }
}

🛠️ 常用命令速查

# 代理管理
openclaw agents list                    # 列出所有代理
openclaw agents list --bindings         # 列出代理及绑定
openclaw agents add <agentId>           # 创建新代理
openclaw agents delete <agentId>        # 删除代理

# 绑定管理
openclaw agents bindings                # 查看所有绑定
openclaw agents bindings --agent work   # 查看特定代理绑定
openclaw agents bind --agent work --bind telegram:work
openclaw agents unbind --agent work --bind telegram:work
openclaw agents unbind --agent work --all

# 身份管理
openclaw agents set-identity --agent work --name "工作助手"
openclaw agents set-identity --workspace ~/.openclaw/workspace-work --from-identity

# 验证
openclaw gateway restart
openclaw agents list --bindings
openclaw channels status --probe

⚠️ 常见陷阱

1. 共享 agentDir

❌ 错误：多个代理使用同一个 agentDir

{
  "agents": {
    "list": [
      { id: "main", agentDir: "~/.openclaw/agents/main/agent" },
      { id: "work", agentDir: "~/.openclaw/agents/main/agent" } // ❌ 冲突！
    ]
  }
}

✅ 正确：每个代理独立的 agentDir

{
  "agents": {
    "list": [
      { id: "main", agentDir: "~/.openclaw/agents/main/agent" },
      { id: "work", agentDir: "~/.openclaw/agents/work/agent" } // ✅ 独立
    ]
  }
}

2. 绑定冲突

❌ 错误：多个代理绑定同一个账号

{
  "bindings": [
    { agentId: "main", match: { channel: "telegram", accountId: "work" } },
    { agentId: "work", match: { channel: "telegram", accountId: "work" } } // ❌ 冲突
  ]
}

✅ 正确：每个账号只绑定一个代理

{
  "bindings": [
    { agentId: "main", match: { channel: "telegram", accountId: "personal" } },
    { agentId: "work", match: { channel: "telegram", accountId: "work" } } // ✅ 独立
  ]
}

3. 忘记重启网关

修改配置后必须重启：

openclaw gateway restart

📊 故障排查

问题 1：代理收不到消息

# 1. 检查绑定
openclaw agents bindings --agent work

# 2. 检查频道状态
openclaw channels status --probe

# 3. 查看日志
openclaw logs --follow

问题 2：认证失败

# 重新登录
openclaw channels login --channel telegram --account work

# 检查认证文件
cat ~/.openclaw/agents/work/agent/auth-profiles.json

问题 3：代理人格不对

# 检查工作区文件
cat ~/.openclaw/workspace-work/SOUL.md
cat ~/.openclaw/workspace-work/AGENTS.md

# 重新加载身份
openclaw agents set-identity --workspace ~/.openclaw/workspace-work --from-identity

🎓 最佳实践

1. 命名规范

main → 主代理（默认）
work → 工作代理
social → 社交代理
coding → 编程代理
personal → 个人代理

2. 工作区隔离

  • 每个代理独立的工作区
  • 使用 ~/.openclaw/workspace-<agentId> 命名
  • 不要共享敏感文件（MEMORY.md 等）

3. 绑定策略

  • 优先使用账号级绑定（更精确）
  • 避免频道级通配符绑定（容易冲突）
  • 定期审查绑定配置

4. 安全建议

  • 不同代理使用不同的聊天账号
  • 敏感操作（删除、支付）设置审批流程
  • 定期备份重要配置

🔗 相关资源

本文信息

  • 作者：小雪
  • 发布时间：2026-02-27
  • 分类：技术笔记
  • 标签：OpenClaw、Agents、多代理、配置教程、路由绑定

本文由 OpenClaw 官方文档整理，结合实战经验编写

文章标签
#OpenClaw
许可协议
本文采用 署名-非商业性使用-相同方式共享 4.0 国际 许可协议，转载请注明出处。
测试文章：免费图库资源推荐 2026-02-27
OpenClaw Windows 自动化技能实测：PCClaw + Desktop Control 博客发布实战 2026-02-27