问题背景：OpenClaw 多Agent会话路径验证失败详解

在OpenClaw v2026.2.12版本中，多Agent架构（Multi-agent setup）隐藏着一个相当不易察觉的会话路径验证Bug。简而言之，当你配置了一个非默认的Agent（我们称之为secondary agent），系统在验证会话文件路径时，会错误地转向主Agent的目录进行检查，最终导致Agent完全无响应。

来看一个典型场景：

• 主Agent: `claw`（默认）
• 次Agent: `exo`（自定义工作空间）
• 问题：通过Discord向`exo`发送消息时，Gateway立即报错，Agent完全没有反应

错误现象与复现步骤

Error: Session file path must be within sessions directory

复现步骤非常直观：

1. 配置一个次要Agent（例如`exo`），为其指定独立的工作空间与专属会话目录
2. 在Discord或其他绑定的频道中@提及该Agent
3. Gateway日志立刻抛出错误，Agent无法加载任何会话文件

根因深入分析

代码定位

问题根源在路径解析模块，我们来详细拆解其代码逻辑：

// dist/paths-*.js 中的问题代码
function resolvePathWithinSessionsDir(filePath) {
  // ❌ 错误：始终使用主 Agent 的 sessionsDir
  const sessionsDir = getMainAgentSessionsDir();
  if (!filePath.startsWith(sessionsDir)) {
    throw new Error('Session file path must be within sessions directory');
  }
  return path.resolve(filePath);
}

架构层面的缺陷

通过示意图可以更清晰地理解：

┌─────────────────────────────────────────────────────────────┐
│                         Gateway                              │
│  ┌─────────────────┐    ┌─────────────────┐                 │
│  │   Main Agent    │    │  Second Agent   │                 │
│  │   ("claw")      │    │   ("exo")       │                 │
│  │                 │    │                 │                 │
│  │  sessionsDir    │    │  sessionsDir    │                 │
│  │  ~/.openclaw/   │    │  ~/.openclaw/   │                 │
│  │    sessions/    │    │    agents/exo/  │                 │
│  │                 │    │      sessions/  │                 │
│  └────────┬────────┘    └────────┬────────┘                 │
│           │                      │                          │
│           │    ❌ 验证失败        │                          │
│           │ <────────────────────│                          │
│           │   检查主目录而不是    │                          │
│           │   exo 自己的目录     │                          │
└───────────┼──────────────────────┼──────────────────────────┘
            │                      │
            ▼                      ▼
    ┌───────────────┐      ┌───────────────┐
    │ 主 Agent 会话 │      │ exo 会话文件  │
    │ 文件存储位置  │      │ 存储位置      │
    └───────────────┘      └───────────────┘

根本原因剖析

本质上，resolvePathWithinSessionsDir和resolveSessionFilePath这两个函数在路径验证时，完全没有传入当前Agent的上下文信息，而是直接使用了主Agent的`sessionsDir`进行检查。这就好比一位保安只认主人家的大门，却从不查看访客的通行证件。

解决方案与修复策略

方案 1：改造路径解析函数（强烈推荐）

最直接的修复方式是让路径解析函数明确感知当前正在处理哪个Agent：

// 修改后的代码
function resolvePathWithinSessionsDir(filePath, agentId = 'default') {
  // ✅ 正确：根据 agentId 获取对应的 sessionsDir
  const sessionsDir = getAgentSessionsDir(agentId);
  // 规范化路径
  const normalizedPath = path.resolve(filePath);
  const normalizedSessionsDir = path.resolve(sessionsDir);
  if (!normalizedPath.startsWith(normalizedSessionsDir)) {
    throw new Error(`Session file path must be within ${agentId}'s sessions directory`);
  }
  return normalizedPath;
}
function getAgentSessionsDir(agentId) {
  if (agentId === 'default' || agentId === config.mainAgentId) {
    return path.join(config.openclawDir, 'sessions');
  }
  // 获取特定 Agent 的配置
  const agentConfig = config.agents[agentId];
  if (agentConfig?.workspace) {
    return path.join(agentConfig.workspace, 'sessions');
  }
  // 默认位置
  return path.join(config.openclawDir, 'agents', agentId, 'sessions');
}

方案 2：通过Agent配置实现目录隔离

在`openclaw.json`中为每个Agent显式配置独立的会话目录，是一种清晰且易于维护的策略：

{
  "agents": {
    "claw": {
      "default": true,
      "sessionsDir": "~/.openclaw/sessions"
    },
    "exo": {
      "sessionsDir": "~/.openclaw/agents/exo/sessions",
      "workspace": "~/.openclaw/agents/exo"
    }
  }
}

方案 3：临时应急方案（Workaround）

如果暂时无法升级版本，以下是一个快速生效的权宜之计：

# 创建符号链接
ln -s ~/.openclaw/agents/exo/sessions ~/.openclaw/sessions/exo
# 修改 Agent 配置，使用主目录下的子目录
# 在 openclaw.json 中:
{
  "agents": {
    "exo": {
      "sessionsDir": "~/.openclaw/sessions/exo"
    }
  }
}

修复验证与测试

测试步骤

1. 创建测试Agent：

# 创建 Agent 配置目录
mkdir -p ~/.openclaw/agents/test-agent/sessions
# 添加配置到 openclaw.json

1. 发送测试消息：

# 通过 CLI 测试
openclaw send --agent test-agent "Hello, are you working?"
# 或绑定到测试频道后发送消息

1. 验证日志：

# 检查 Gateway 日志
tail -f ~/.openclaw/logs/gateway.log | grep -E "(session|test-agent)"
# 应该看到成功加载会话的日志，而不是错误

预期结果

✅ Agent "exo" session loaded from ~/.openclaw/agents/exo/sessions/
✅ Message processed successfully

多Agent最佳实践指南

推荐的目录结构

高效的多Agent目录组织方式如下：

~/.openclaw/
├── sessions/                    # 主 Agent 会话
│   └── ...
├── agents/                      # 其他 Agent
│   ├── exo/
│   │   ├── sessions/           # 各 Agent 独立会话
│   │   ├── config.json
│   │   └── workspace/
│   └── another-agent/
│       └── sessions/
└── config.json

配置检查清单

• [ ] 每个非默认 Agent 都有独立的 `sessionsDir`
• [ ] 目录权限正确（可读写）
• [ ] 路径使用绝对路径或正确的相对路径
• [ ] 避免路径包含特殊字符或空格

影响范围与场景对照

总结与行动建议

这个Bug实际上暴露了多Agent场景下路径管理的深层设计问题。在构建多Agent系统时，每个Agent的资源隔离——包括会话、配置、工作空间——是保障系统稳定性的基本原则。优先做好这件事，后续能省去大量排查和修复的麻烦。