多代理配置与管理指南

2025-07-10 · 7 分钟基础配置

概述

OpenClaw 的多代理系统允许你在同一个网关实例中运行多个相互隔离的 AI 代理。每个代理拥有独立的工作空间、会话历史、认证凭据和工具权限，互不干扰。这一特性适合需要在工作与生活之间保持隔离、或为不同渠道配置不同 AI 人格的使用场景。

代理的隔离范围

每个代理在以下维度完全独立：

工作空间：独立的文件目录（SOUL.md、AGENTS.md、USER.md）
会话历史：存储在 ~/.openclaw/agents/<agentId>/sessions
认证凭据：独立的 API Key 和 OAuth 配置
工具权限：各自的 allow/deny 策略

添加新代理

通过交互式向导快速添加代理：

# 添加工作用代理
openclaw agents add work

# 添加生活用代理
openclaw agents add home

# 查看所有代理及其渠道绑定
openclaw agents list --bindings

代理配置详解

在 ~/.openclaw/openclaw.json5 中手动配置代理列表：

{
  agents: {
    list: [
      {
        id: "main",           // 代理唯一标识符
        default: true,        // 是否为默认代理
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
        model: {
          primary: "anthropic/claude-opus-4-6",
          fallbacks: ["anthropic/claude-sonnet-4-6"]
        }
      },
      {
        id: "work",
        default: false,
        workspace: "~/.openclaw/workspace-work",
        agentDir: "~/.openclaw/agents/work/agent",
        model: {
          primary: "kilocode/anthropic/claude-opus-4.6"
        },
        // 工作代理限制危险工具
        tools: {
          deny: ["exec", "browser"]
        }
      },
      {
        id: "coding",
        default: false,
        workspace: "~/projects",
        agentDir: "~/.openclaw/agents/coding/agent",
        model: {
          primary: "anthropic/claude-opus-4-6"
        },
        // 为编程代理启用沙箱
        sandbox: {
          mode: "all",
          docker: {
            setupCommand: "apt-get install -y git nodejs python3"
          }
        }
      }
    ]
  }
}

渠道路由绑定

通过 bindings 配置将不同渠道的消息路由到指定代理。路由按优先级从高到低匹配：

{
  agents: {
    bindings: [
      // 微信消息路由到生活代理
      {
        agentId: "home",
        match: { channel: "wechat", accountId: "personal" }
      },
      // 飞书消息路由到工作代理
      {
        agentId: "work",
        match: { channel: "feishu", accountId: "default" }
      },
      // 钉钉群组路由到工作代理
      {
        agentId: "work",
        match: { channel: "dingtalk" }
      },
      // 默认代理处理其余所有消息
      {
        agentId: "main",
        match: { accountId: "*" }
      }
    ]
  }
}

子代理配置

子代理（Sub-Agent）允许主代理将任务派发给后台独立运行的子代理，实现并行任务处理：

{
  agents: {
    defaults: {
      subagents: {
        model: "anthropic/claude-sonnet-4-6",  // 子代理使用更轻量的模型降低成本
        thinking: "low",
        runTimeoutSeconds: 600,       // 子代理最长运行时间（秒）
        archiveAfterMinutes: 60,      // 完成后自动归档的等待时间
        maxSpawnDepth: 2,             // 最大嵌套深度（2 = 支持编排者模式）
        maxChildrenPerAgent: 5,       // 每个代理最多同时运行的子代理数
        maxConcurrent: 8             // 全局最大并发子代理数
      }
    }
  }
}

手动派发子代理任务：

/subagents spawn coding "分析 ~/projects/api 目录下所有 TypeScript 文件的类型覆盖率"

代理间消息（谨慎使用）

代理间相互发送消息默认处于关闭状态，需要显式启用：

{
  tools: {
    agentToAgent: {
      enabled: true,
      allow: ["main", "work", "coding"]  // 仅允许列表中的代理互发消息
    }
  }
}

实用技巧

工作空间隔离最佳实践：不同代理的 agentDir 路径必须唯一，复用同一目录会导致认证和会话数据发生冲突，这是新用户最常见的配置错误。

模型成本控制：子代理通常处理较简单的分解任务，建议配置使用 Sonnet 级别的模型，而不是 Opus，可以显著降低 API 调用费用。

组群聊天触发词：在群组中使用多代理时，可以为每个代理配置独立的触发关键词，避免所有代理同时响应同一条消息。