第 18 章 — 多 Agent 路由：Bindings、Workspace 隔离与会话分发

agents:
  defaults:
    model: "claude-sonnet-4-20250514"
    workspace: "~/.openclaw/workspace"
  list:
    - id: "main"
      default: true
      name: "通用助手"
    - id: "ops"
      name: "运维 Agent"
      workspace: "~/ops-workspace"
      model: "gpt-4o"
      systemPromptOverride: "你是一个运维专家..."
    - id: "translator"
      name: "翻译 Agent"
      workspace: "~/translator-workspace"
      model: "claude-sonnet-4-20250514"

// src/routing/session-key.ts:92
export function normalizeAgentId(value: string | undefined | null): string {
  const trimmed = (value ?? "").trim();
  if (!trimmed) {
    return DEFAULT_AGENT_ID;  // "main"
  }
  const normalized = normalizeLowercaseStringOrEmpty(trimmed);
  if (VALID_ID_RE.test(trimmed)) {
    return normalized;
  }
  // 非法字符折叠为连字符
  return (
    normalized
      .replace(INVALID_CHARS_RE, "-")
      .replace(LEADING_DASH_RE, "")
      .replace(TRAILING_DASH_RE, "")
      .slice(0, 64) || DEFAULT_AGENT_ID
  );
}

// src/agents/agent-scope-config.ts:82
export function resolveDefaultAgentId(cfg: OpenClawConfig): string {
  const agents = listAgentEntries(cfg);
  if (agents.length === 0) {
    return DEFAULT_AGENT_ID;
  }
  const defaults = agents.filter((agent) => agent?.default);
  if (defaults.length > 1 && !defaultAgentWarned) {
    defaultAgentWarned = true;
    warnMultipleDefaultAgents();
  }
  const chosen = (defaults[0] ?? agents[0])?.id?.trim();
  return normalizeAgentId(chosen || DEFAULT_AGENT_ID);
}

// src/agents/agent-scope-config.ts:154
export function resolveAgentWorkspaceDir(
  cfg: OpenClawConfig,
  agentId: string,
  env: NodeJS.ProcessEnv = process.env,
) {
  const id = normalizeAgentId(agentId);
  // 1. Agent 自己配置了 workspace，直接用
  const configured = resolveAgentConfig(cfg, id)?.workspace?.trim();
  if (configured) {
    return stripNullBytes(resolveUserPath(configured, env));
  }
  const defaultAgentId = resolveDefaultAgentId(cfg);
  const fallback = cfg.agents?.defaults?.workspace?.trim();
  // 2. 默认 Agent，用 defaults.workspace 或系统默认目录
  if (id === defaultAgentId) {
    if (fallback) {
      return stripNullBytes(resolveUserPath(fallback, env));
    }
    return stripNullBytes(resolveDefaultAgentWorkspaceDir(env));
  }
  // 3. 非默认 Agent 且没有显式配置，在 defaults.workspace 或 stateDir 下创建子目录
  if (fallback) {
    return stripNullBytes(path.join(resolveUserPath(fallback, env), id));
  }
  const stateDir = resolveStateDir(env);
  return stripNullBytes(path.join(stateDir, `workspace-${id}`));
}

// src/agents/agent-scope-config.ts:179
export function resolveAgentDir(
  cfg: OpenClawConfig,
  agentId: string,
  env: NodeJS.ProcessEnv = process.env,
) {
  const id = normalizeAgentId(agentId);
  const configured = resolveAgentConfig(cfg, id)?.agentDir?.trim();
  if (configured) {
    return resolveUserPath(configured, env);
  }
  const root = resolveStateDir(env);
  return path.join(root, "agents", id, "agent");
}

// src/config/types.agents.ts:49
export type AgentRouteBinding = {
  type?: "route";
  agentId: string;
  comment?: string;
  match: AgentBindingMatch;
  session?: {
    dmScope?: DmScope;
  };
};

export type AgentBindingMatch = {
  channel: string;         // 渠道：telegram, discord, whatsapp 等
  accountId?: string;      // 账号 ID（同一渠道可能有多个 Bot 账号）
  peer?: { kind: ChatType; id: string };  // 对话对象：direct/group/channel + ID
  guildId?: string;        // Discord 服务器 ID
  teamId?: string;         // Slack 团队 ID
  roles?: string[];        // Discord 角色 ID 列表
};

bindings:
  # 特定 Telegram 群组 -> 运维 Agent
  - agentId: "ops"
    match:
      channel: "telegram"
      accountId: "bot_ops_123"
      peer:
        kind: "group"
        id: "-1001234567890"
 
  # 特定 WhatsApp 私聊 -> 翻译 Agent
  - agentId: "translator"
    match:
      channel: "whatsapp"
      peer:
        kind: "direct"
        id: "8613800138000"
 
  # Discord 特定服务器的管理员角色 -> 运维 Agent
  - agentId: "ops"
    match:
      channel: "discord"
      guildId: "1234567890"
      roles: ["admin-role-id"]
 
  # Discord 特定服务器其他人 -> 通用助手
  - agentId: "main"
    match:
      channel: "discord"
      guildId: "1234567890"

// src/routing/resolve-route.ts:46
export type ResolvedAgentRoute = {
  agentId: string;
  channel: string;
  accountId: string;
  sessionKey: string;
  mainSessionKey: string;
  lastRoutePolicy: "main" | "session";
  matchedBy:
    | "binding.peer"
    | "binding.peer.parent"
    | "binding.peer.wildcard"
    | "binding.guild+roles"
    | "binding.guild"
    | "binding.team"
    | "binding.account"
    | "binding.channel"
    | "default";
};

// src/routing/resolve-route.ts:731（简化）
const tiers = [
  {
    matchedBy: "binding.peer",
    enabled: Boolean(peer),
    candidates: collectPeerIndexedBindings(bindingsIndex, peer),
    predicate: (c) => c.match.peer.state === "valid",
  },
  {
    matchedBy: "binding.peer.parent",
    enabled: Boolean(parentPeer && parentPeer.id),
    candidates: collectPeerIndexedBindings(bindingsIndex, parentPeer),
    predicate: (c) => c.match.peer.state === "valid",
  },
  // ... 后续 tier 依次降级
];
 
for (const tier of tiers) {
  if (!tier.enabled) continue;
  const matched = tier.candidates.find(
    (c) => tier.predicate(c) && matchesBindingScope(c.match, { ...baseScope, peer: tier.scopePeer })
  );
  if (matched) {
    return choose(matched.binding.agentId, tier.matchedBy);
  }
}
// 全部未命中，返回默认 Agent
return choose(resolveDefaultAgentId(input.cfg), "default");

// src/routing/resolve-route.ts:373（简化）
function buildEvaluatedBindingsIndex(bindings): EvaluatedBindingsIndex {
  const byPeer = new Map();
  const byPeerWildcard = [];
  const byGuildWithRoles = new Map();
  const byGuild = new Map();
  const byTeam = new Map();
  const byAccount = [];
  const byChannel = [];
 
  for (const binding of bindings) {
    if (binding.match.peer.state === "valid") {
      pushToIndexMap(byPeer, peerLookupKeys(...), binding);
    } else if (binding.match.peer.state === "wildcard-kind") {
      byPeerWildcard.push(binding);
    } else if (binding.match.guildId && binding.match.roles) {
      pushToIndexMap(byGuildWithRoles, binding.match.guildId, binding);
    }
    // ... 依次分类
  }
  return { byPeer, byPeerWildcard, byGuildWithRoles, byGuild, byTeam, byAccount, byChannel };
}

agents:
  list:
    - id: "main"
      default: true
      name: "通用助手"
    - id: "product"
      name: "产品助手"
      workspace: "~/product-workspace"
      systemPromptOverride: "你是产品经理的 AI 助手..."
 
bindings:
  # 产品经理的 DM -> 产品助手
  - agentId: "product"
    match:
      channel: "whatsapp"
      peer:
        kind: "direct"
        id: "8613900139000"
    session:
      dmScope: "per-peer"
 
  # 其他 WhatsApp 消息 -> 通用助手（通配符）
  - agentId: "main"
    match:
      channel: "whatsapp"

// src/gateway/agent-list.ts:51
export function listGatewayAgentsBasic(cfg: OpenClawConfig): {
  defaultId: string;
  mainKey: string;
  scope: SessionScope;
  agents: GatewayAgentListRow[];
}

// src/agents/agent-scope-config.ts:15（类型定义，简化）
export type ResolvedAgentConfig = {
  name?: string;
  workspace?: string;
  agentDir?: string;
  systemPromptOverride?: string;
  model?: AgentModelConfig;
  skills?: string[];         // 技能白名单
  memorySearch?: MemorySearchConfig;
  sandbox?: AgentSandboxConfig;
  tools?: AgentToolsConfig;
  subagents?: {
    allowAgents?: string[];  // 允许生成哪些子 Agent
    model?: AgentModelConfig;
    requireAgentId?: boolean;
  };
  // ...
};

// src/agents/agent-scope.ts:245
export function resolveAgentIdsByWorkspacePath(
  cfg: OpenClawConfig,
  workspacePath: string,
): string[] {
  const normalizedWorkspacePath = normalizePathForComparison(workspacePath);
  const ids = listAgentIds(cfg);
  const matches = [];
 
  for (const id of ids) {
    const workspaceDir = normalizePathForComparison(resolveAgentWorkspaceDir(cfg, id));
    if (!isPathWithinRoot(normalizedWorkspacePath, workspaceDir)) {
      continue;
    }
    matches.push({ id, workspaceDir });
  }
  // 最长匹配优先
  matches.sort((left, right) => right.workspaceDir.length - left.workspaceDir.length);
  return matches.map((entry) => entry.id);
}

// src/config/types.agents.ts:61
export type AgentAcpBinding = {
  type: "acp";
  agentId: string;
  match: AgentBindingMatch;
  acp?: {
    mode?: "persistent" | "oneshot";
    label?: string;
    cwd?: string;
    backend?: string;
  };
};

// src/config/bindings.ts:10
export function isRouteBinding(binding: AgentBinding): binding is AgentRouteBinding {
  return normalizeBindingType(binding) === "route";
}
 
export function isAcpBinding(binding: AgentBinding): binding is AgentAcpBinding {
  return normalizeBindingType(binding) === "acp";
}