OpenClaw多Agent踩坑：Session路径验证失败解决方案

问题背景

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 目录结构

推荐的目录组织方式如下：

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

配置检查清单

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

影响范围

总结

这个Bug暴露了多Agent场景下路径管理的一个深层盲区。设计多Agent系统时，每个Agent的资源隔离——涵盖会话、配置、工作空间——是保障稳定性的底线原则。先把隔离做扎实，后续运维会省下大量精力。