OpenClaw 多 Agent 踩坑记：Session 路径验证失败解析

作者：CSDN博客
问题背景

在 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
复现步骤：

配置一个次要 Agent（如 `exo`），指定独立的工作空间和会话目录在 Discord 或其他绑定的频道中 @ 该 AgentGateway 日志报错，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：修改路径解析函数（推荐）

// 修改后的代码
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"
    }
  }
}
验证修复

测试步骤

创建测试 Agent：

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

# 添加配置到 openclaw.json

发送测试消息：

# 通过 CLI 测试
openclaw send --agent test-agent "Hello, are you working?"

# 或绑定到测试频道后发送消息

验证日志：

# 检查 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`[ ] 目录权限正确（可读写）[ ] 路径使用绝对路径或正确的相对路径[ ] 避免路径包含特殊字符或空格

影响范围

场景	影响
单 Agent 使用	❌ 不受影响
多 Agent + 默认配置	✅ 受影响（需修复）
多 Agent + 自定义 workspace	✅ 受影响（需修复）
Docker/K8s 部署	✅ 受影响（需确保卷挂载正确）

总结

维度	建议
**紧急修复**	升级到 v2026.2.13+ 或应用补丁
**配置检查**	验证所有非默认 Agent 的 sessionsDir
**长期方案**	建立多 Agent 目录隔离最佳实践

这个 Bug 暴露了多 Agent 场景下的路径管理问题。在设计和实现多 Agent 系统时，每个 Agent 的资源隔离（会话、配置、工作空间）是确保稳定性的关键。

原文地址：https://blog.csdn.net/u011664969/article/details/158182562